Cómo funciona el bucle del agente

​

El bucle de un vistazo

1. Recibir prompt. Claude recibe su prompt, junto con el prompt del sistema, las definiciones de herramientas e historial de conversación. El SDK produce un SystemMessage con subtipo "init" que contiene metadatos de sesión.
2. Evaluar y responder. Claude evalúa el estado actual y determina cómo proceder. Puede responder con texto, solicitar una o más llamadas de herramientas, o ambas. El SDK produce un AssistantMessage que contiene el texto y cualquier solicitud de llamada de herramienta.
3. Ejecutar herramientas. El SDK ejecuta cada herramienta solicitada y recopila los resultados. Cada conjunto de resultados de herramientas se devuelve a Claude para la siguiente decisión. Puede usar hooks para interceptar, modificar o bloquear llamadas de herramientas antes de que se ejecuten.
4. Repetir. Los pasos 2 y 3 se repiten como un ciclo. Cada ciclo completo es un turno. Claude continúa llamando a herramientas y procesando resultados hasta que produce una respuesta sin llamadas de herramientas.
5. Devolver resultado. El SDK produce un AssistantMessage final con la respuesta de texto (sin llamadas de herramientas), seguido de un ResultMessage con el texto final, uso de tokens, costo e ID de sesión.

​

Turnos y mensajes

1. Turno 1: Claude llama a Bash para ejecutar npm test. El SDK produce un AssistantMessage con la llamada de herramienta, ejecuta el comando, luego produce un UserMessage con la salida (tres fallos).
2. Turno 2: Claude llama a Read en auth.ts y auth.test.ts. El SDK devuelve el contenido del archivo y produce un AssistantMessage.
3. Turno 3: Claude llama a Edit para arreglar auth.ts, luego llama a Bash para volver a ejecutar npm test. Las tres pruebas pasan. El SDK produce un AssistantMessage.
4. Turno final: Claude produce una respuesta solo de texto sin llamadas de herramientas: “Arreglé el error de autenticación, las tres pruebas pasan ahora.” El SDK produce un AssistantMessage final con este texto, luego un ResultMessage con el mismo texto más costo y uso.

​

Tipos de mensajes

• SystemMessage: eventos del ciclo de vida de la sesión. El campo subtype los distingue: "init" es el primer mensaje (metadatos de sesión), y "compact_boundary" se dispara después de compactación. En TypeScript, el límite de compactación es su propio tipo SDKCompactBoundaryMessage en lugar de un subtipo de SDKSystemMessage.
• AssistantMessage: emitido después de cada respuesta de Claude, incluida la final solo de texto. Contiene bloques de contenido de texto y bloques de llamadas de herramientas de ese turno.
• UserMessage: emitido después de cada ejecución de herramienta con el contenido del resultado de la herramienta enviado de vuelta a Claude. También se emite para cualquier entrada de usuario que transmita a mitad del bucle.
• StreamEvent: solo se emite cuando los mensajes parciales están habilitados. Contiene eventos de transmisión de API sin procesar (deltas de texto, fragmentos de entrada de herramientas). Vea Respuestas de transmisión.
• ResultMessage: marca el final del bucle del agente. Contiene el resultado de texto final, uso de tokens, costo e ID de sesión. Verifique el campo subtype para determinar si la tarea tuvo éxito o alcanzó un límite. Un pequeño número de eventos del sistema finales, como prompt_suggestion, pueden llegar después, así que itere el flujo hasta completarse en lugar de romper en el resultado. Vea Manejar el resultado.

​

Manejar mensajes

• Solo resultados finales: maneje ResultMessage para obtener la salida, el costo y si la tarea tuvo éxito o alcanzó un límite.
• Actualizaciones de progreso: maneje AssistantMessage para ver qué está haciendo Claude en cada turno, incluidas las herramientas que llamó.
• Transmisión en vivo: habilite mensajes parciales (include_partial_messages en Python, includePartialMessages en TypeScript) para obtener mensajes StreamEvent en tiempo real. Vea Respuestas de transmisión en tiempo real.

• Python: verifique los tipos de mensajes con isinstance() contra clases importadas de claude_agent_sdk (por ejemplo, isinstance(message, ResultMessage)).
• TypeScript: verifique el campo de cadena type (por ejemplo, message.type === "result"). AssistantMessage y UserMessage envuelven el mensaje de API sin procesar en un campo .message, por lo que los bloques de contenido están en message.message.content, no en message.content.

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

Ejecución de herramientas

​

Herramientas integradas

• Conectar servicios externos con servidores MCP (bases de datos, navegadores, APIs)
• Definir herramientas personalizadas con manejadores de herramientas personalizadas
• Cargar skills del proyecto a través de fuentes de configuración para flujos de trabajo reutilizables

​

Permisos de herramientas

• allowed_tools / allowedTools aprueba automáticamente las herramientas listadas. Un agente de solo lectura con ["Read", "Glob", "Grep"] en su lista de herramientas permitidas ejecuta esas herramientas sin solicitar. Las herramientas no listadas aún están disponibles pero requieren permiso.
• disallowed_tools / disallowedTools bloquea las herramientas listadas, independientemente de otras configuraciones. Vea Permisos para el orden en que se verifican las reglas antes de que se ejecute una herramienta.
• permission_mode / permissionMode controla qué sucede con las herramientas que no están cubiertas por reglas de permitir o denegar. Vea Modo de permiso para los modos disponibles.

​

Ejecución paralela de herramientas

​

Controlar cómo se ejecuta el bucle

​

Turnos y presupuesto

​

Nivel de esfuerzo

​

Modo de permiso

​

Modelo

​

La ventana de contexto

​

Qué consume contexto

​

Compactación automática

• Instrucciones de resumen en CLAUDE.md: El compactador lee su CLAUDE.md como cualquier otro contexto, así que puede incluir una sección diciéndole qué preservar al resumir. El encabezado de la sección es de forma libre (no una cadena mágica); el compactador coincide en intención.
• Hook PreCompact: Ejecute lógica personalizada antes de que ocurra la compactación, por ejemplo para archivar la transcripción completa. El hook recibe un campo trigger (manual o auto). Vea hooks.
• Compactación manual: Envíe /compact como una cadena de prompt para activar la compactación bajo demanda. Los comandos enviados de esta manera son entradas de SDK, no atajos solo de CLI. Vea slash commands en el SDK.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

​

Mantener el contexto eficiente

• Use subagentes para subtareas. Cada subagente comienza con una conversación nueva (sin historial de mensajes anterior, aunque carga su propio prompt del sistema y contexto a nivel de proyecto como CLAUDE.md). No ve los turnos del padre, y solo su respuesta final regresa al padre como resultado de herramienta. El contexto del agente principal crece por ese resumen, no por la transcripción completa de subtarea. Vea Qué heredan los subagentes para detalles.
• Sea selectivo con herramientas. Cada definición de herramienta toma espacio de contexto. Use el campo tools en AgentDefinition para limitar subagentes al conjunto mínimo que necesitan.
• Observe costos de servidor MCP. Búsqueda de herramientas MCP difiere esquemas de herramientas MCP por defecto y los carga bajo demanda. Cuando la búsqueda de herramientas está desactivada, en Vertex AI, o detrás de una ANTHROPIC_BASE_URL que no sea de primera parte, cada servidor MCP agrega todos sus esquemas de herramientas a cada solicitud, así que algunos servidores con muchas herramientas pueden consumir contexto significativo antes de que el agente haga ningún trabajo.
• Use esfuerzo más bajo para tareas rutinarias. Establezca esfuerzo a "low" para agentes que solo necesitan leer archivos o listar directorios. Esto reduce el uso de tokens y el costo.

​

Sesiones y continuidad

​

Manejar el resultado

​

Hooks

​

Ponerlo todo junto

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    async for message in query(
        prompt="Find and fix the bug causing test failures in the auth module",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read",
                "Edit",
                "Bash",
                "Glob",
                "Grep",
            ],  # Listing tools here auto-approves them (no prompting)
            setting_sources=[
                "project"
            ],  # Load CLAUDE.md, skills, hooks from current directory
            max_turns=30,  # Prevent runaway sessions
            effort="high",  # Thorough reasoning for complex debugging
        ),
    ):
        # Handle the final result
        if isinstance(message, ResultMessage):
            session_id = message.session_id  # Save for potential resumption

            if message.subtype == "success":
                print(f"Done: {message.result}")
            elif message.subtype == "error_max_turns":
                # Agent ran out of turns. Resume with a higher limit.
                print(f"Hit turn limit. Resume session {session_id} to continue.")
            elif message.subtype == "error_max_budget_usd":
                print("Hit budget limit.")
            else:
                print(f"Stopped: {message.subtype}")
            if message.total_cost_usd is not None:
                print(f"Cost: ${message.total_cost_usd:.4f}")


asyncio.run(run_agent())

​

Próximos pasos

• ¿Aún no ha ejecutado un agente? Comience con el inicio rápido para obtener el SDK instalado y ver un ejemplo completo ejecutándose de principio a fin.
• ¿Listo para conectarse a su proyecto? Cargue CLAUDE.md, skills y hooks del sistema de archivos para que el agente siga automáticamente las convenciones de su proyecto.
• ¿Construyendo una interfaz de usuario interactiva? Habilite transmisión para mostrar texto en vivo y llamadas de herramientas a medida que se ejecuta el bucle.
• ¿Necesita control más ajustado sobre lo que el agente puede hacer? Bloquee el acceso a herramientas con permisos y use hooks para auditar, bloquear o transformar llamadas de herramientas antes de que se ejecuten.
• ¿Ejecutando tareas largas o costosas? Descargue trabajo aislado a subagentes para mantener su contexto principal delgado.