Le he pedido a CC que analizase su propia conversación con el API remoto
Ha construido un proxy y ha guardado toda la conversación. Luego le he pedido que la analice:
Cómo funciona la conversación entre Claude Code y la API
Visión general
Cada vez que pulsas Enter en Claude Code, no se envía solo tu mensaje. Se envía un HTTP POST enorme que
contiene el estado completo de toda la conversación. La API es completamente stateless — no recuerda nada
entre llamadas.
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code (cliente) api.anthropic.com │
│ │
│ Turno 1: │
│ POST /v1/messages?beta=true ──────────────────────────────► │
│ { system, tools, messages: [msg0] } │
│ ◄─── SSE │
│ │
│ Turno 2: │
│ POST /v1/messages?beta=true ──────────────────────────────► │
│ { system, tools, messages: [msg0, msg1, msg2, msg3] } │
│ ◄─── SSE │
│ │
│ Turno N: │
│ POST /v1/messages?beta=true ──────────────────────────────► │
│ { system, tools, messages: [msg0 ... msgN-1] } │
│ ◄─── SSE │
└─────────────────────────────────────────────────────────────────┘
---
Estructura del request
{
"model": "claude-sonnet-4-6",
"max_tokens": 32000,
"stream": true,
"system": [ ... ], ← instrucciones permanentes
"tools": [ ... ], ← 28 herramientas disponibles
"messages": [ ... ] ← historial completo de la conversación
}
---
1 — system: las instrucciones permanentes
El system prompt llega dividido en 3 bloques, cada uno con una estrategia de caché diferente:
"system": [
{
"type": "text",
"cache_control": null,
"text": "x-anthropic-billing-header: cc_version=2.1.119.918; cc_entrypoint=sdk-cli; cch=9aaa4;"
},
{
"type": "text",
"cache_control": { "type": "ephemeral", "ttl": "1h" },
"text": "You are a Claude agent, built on Anthropic's Claude Agent SDK."
},
{
"type": "text",
"cache_control": { "type": "ephemeral", "ttl": "1h" },
"text": "You are an interactive agent that helps users with software engineering tasks..."
↑ 26.000 caracteres de instrucciones
}
]
cache_control: ephemeral ttl=1h significa que Anthropic guarda en caché ese bloque durante 1 hora. Si se
repite idéntico en el siguiente request (lo cual siempre ocurre), no se cobra ni se procesa de nuevo — es la
razón por la que Claude Code es más eficiente de lo que parece.
---
2 — tools: las 28 herramientas
Cada herramienta se define una vez y se envía en todos los requests:
{
"name": "Bash",
"description": "Executes a given bash command and returns its output...",
"input_schema": {
"type": "object",
"properties": {
"command": { "type": "string" },
"description": { "type": "string" },
"timeout": { "type": "number" },
"run_in_background": { "type": "boolean" }
},
"required": ["command"]
}
}
Las 28 herramientas en tu instalación: Agent, AskUserQuestion, Bash, CronCreate, CronDelete, CronList, Edit,
EnterPlanMode, EnterWorktree, ExitPlanMode, ExitWorktree, Glob, Grep, Monitor, NotebookEdit,
PushNotification, Read, RemoteTrigger, ScheduleWakeup, Skill, TaskOutput, TaskStop, TodoWrite, WebFetch,
WebSearch, Write, + 2 de Google Drive MCP.
---
3 — messages: el historial
Este es el núcleo. En tu sesión de hoy, al final había 201 mensajes. Hay 5 tipos de partes de mensaje:
Tipo A — Mensaje de usuario (texto simple)
{
"role": "user",
"content": [
{ "type": "text", "text": "me gustaria ver cual es la conversacion..." }
]
}
Tipo B — Respuesta del asistente (solo texto)
{
"role": "assistant",
"content": [
{
"type": "thinking",
"thinking": "",
"signature": "EuQrClsIDRgCKkB+FBBr..." ← bloque de razonamiento interno (cifrado)
},
{
"type": "text",
"text": "Aquí está lo que encontré. La conversación completa se guarda en..."
}
]
}
Tipo C — Asistente solicitando ejecutar una herramienta
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toulu_01Ru3wLkJGi1FFkT2YTA22Hx", ← ID único de esta llamada
"name": "Bash",
"input": {
"command": "ls ~/.claude/projects/-Users-usuario-temp/ | head -10",
"description": "List conversation files for current project"
}
}
]
}
Tipo D — Usuario devolviendo el resultado de la herramienta
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01Ru3wLkJGi1FFkT2YTA22Hx", ← mismo ID
"content":
"3a75ff99-0429-46d5-8f44-22a0cc3efae3.jsonl\nab53faa9-38cc-4ce9-8154-fdc0fad02064.jsonl\nmemory",
"is_error": false
}
]
}
Tipo E — Asistente con texto Y herramienta en el mismo turno
{
"role": "assistant",
"content": [
{ "type": "thinking", "thinking": "", "signature": "..." },
{ "type": "text", "text": "Voy a arrancar el proxy en background..." },
{
"type": "tool_use",
"id": "toulu_011DdmrMpGQXdL7KWMHF8qPz",
"name": "Bash",
"input": { "command": "python3 anthropic_proxy.py &\nsleep 1\necho \"PID=$!\"" }
}
]
}
---
4 — El ciclo completo de un "turno"
Usuario escribe Enter
│
▼
┌───────────────────────────────────────────────┐
│ Request N │
│ messages: [A, B, C, D, ..., Nuevo_msg_user] │
└───────────────────────────────────────────────┘
│ POST → api.anthropic.com
▼
┌───────────────────────────────────────────────┐
│ La API responde (streaming SSE): │
│ ¿Quiere hablar? → devuelve tipo B │
│ ¿Quiere actuar? → devuelve tipo C o E │
└───────────────────────────────────────────────┘
│
├── Si devuelve texto → se muestra en terminal → FIN del turno
│
└── Si devuelve tool_use:
│
▼
Claude Code ejecuta la herramienta localmente
(Bash, Read, Edit, Write...)
│
▼
Request N+1 automático:
messages: [..., msg_user, msg_assistant_tool_use, msg_user_tool_result]
│
└──► vuelve al principio (puede haber 20+ iteraciones)
---
5 — Desglose real de los 201 mensajes
Así quedó distribuida la conversación de hoy (proxy setup session):
95 user → tool_result (Claude Code devolviendo resultados de comandos)
75 asst → tool_use (Claude pidiendo ejecutar algo)
20 asst → text + tool_use (Claude explicando Y pidiendo ejecutar)
5 asst → text (Claude solo respondiendo en texto)
3 user → text (tus mensajes escritos)
3 user → (sistema/transición)
─────
201 total
Es decir: de cada 201 mensajes, solo 3 fueron texto que escribiste tú. El 98% es el protocolo de
herramientas.
---
6 — Qué pasa cuando el contexto se llena
Cuando la conversación se acerca al límite (200K tokens), Claude Code comprime el historial antes de
enviarlo. En el request llegaría esto:
"messages": [
{
"role": "user",
"content": [{
"type": "text",
"text": "<parameter name=\"summary\">Resumen de los primeros 150 mensajes:\n- El usuario pidió ver la
conversación con el modelo\n- Se creó anthropic_proxy.py para interceptar tráfico\n- Se depuró un error SSL
en la versión inicial\n- Se descubrió que OAuth no funciona en /v1/messages directo\n- Se reescribió el
proxy con httpx y se resolvió el gzip...\n</parameter>"
}]
},
{ "role": "assistant", "content": [...] }, ← mensajes recientes, intactos
...
{ "role": "user", "content": [{ "type": "text", "text": "y cuando quiera desactivarlo?" }] }
]
Con el proxy activo esto sería perfectamente visible: el número de mensajes bajaría de golpe (de 180 a 40,
por ejemplo) y aparecería ese bloque <parameter name="summary">.
---
7 — La respuesta (streaming SSE)
La API no devuelve JSON completo sino un stream de eventos:
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking",...}}
data: {"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"..."}}
data: {"type":"content_block_stop","index":0}
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hola"}}
data: {"type":"content_block_stop","index":1}
data: {"type":"message_delta","usage":{"output_tokens":3}}
data: {"type":"message_stop"}
Claude Code va leyendo estos eventos y mostrando el texto en terminal en tiempo real. Cuando detecta un
tool_use block completo, lo ejecuta sin esperar al final del stream.