About the author
Gonzalo Gomez
AI & Automation Specialist
I design AI-powered communication systems. My work focuses on voice agents, WhatsApp chatbots, AI assistants, and workflow automation built primarily on Twilio, n8n, and modern LLMs like OpenAI and Claude. Over the past 7 years, I've shipped 30+ automation projects handling 250k+ monthly interactions.
Subscribe to my newsletter
If you enjoy the content that I make, you can subscribe and receive insightful information through email. No spam is going to be sent, just updates about interesting posts or specialized content that I talk about.
Introducción
Cada prueba que hacés contra el API de Anthropic mientras desarrollás un agente conversacional te cuesta plata. Ajustás el system prompt, mandás 40 mensajes de prueba, algo no te cierra, volvés a ajustar, otros 40 mensajes. Todo eso es facturación por tokens antes de tener un solo usuario real.
Si tenés suscripción de Claude (Pro o Max), hay una alternativa que casi nadie usa para esto: el modo headless de Claude Code. Le pasás el prompt y el mensaje del usuario, te devuelve la respuesta en texto plano, y el consumo sale de tu suscripción, no del API. Este PDF es la implementación de principio a fin, con los casos de uso donde tiene sentido y el límite donde deja de tenerlo.
Qué vas a encontrar en este PDF
El comando base para un agente: salida estructurada con --output-format json, tu system prompt con --append-system-prompt y control de herramientas con --allowedTools.
La implementación completa con Python: el wrapper que invoca claude -p y el endpoint que recibe el webhook de tu canal, sea WhatsApp o un chat web.
Cómo mantener el hilo de la conversación con --resume y el mapeo de usuario a session_id, sin armar el historial a mano.
Streaming con stream-json para mostrar la respuesta a medida que se genera.
Los casos de uso donde brilla: iterar el system prompt sin que el medidor del API se mueva, suites de regresión de prompts, demos a clientes y prototipos internos.
El límite, que es importante: por qué esto es para desarrollo y pruebas locales, y cuándo corresponde migrar al API con el Anthropic SDK.
Para quién es
Para desarrolladores que están armando un agente conversacional y queman la mayor parte de sus requests justo en la etapa donde el agente todavía no funciona. El modo headless te saca el costo de esa etapa. La etapa donde el agente ya funciona es la que tiene que pagar su propio API.
Descargá el PDF con el botón de arriba y tenés el comando, el código y los flags en tres páginas, listos para adaptar a tu proyecto.
