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 uno o más objetos AssistantMessage, uno para cada bloque de contenido, como un bloque de texto o una 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 retroalimenta 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 produce un AssistantMessage para cada llamada y devuelve el contenido del archivo.
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 para cada llamada.
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": metadatos de sesión para la ejecución. Cuando un hook SessionStart o Setup se ejecuta durante el inicio de la sesión, sus mensajes del ciclo de vida del hook llegan antes del mensaje init
  • "compact_boundary": se dispara después de compactación
  • "informational": banners de estado de texto sin formato del bucle
  • "worker_shutting_down": el host se está cerrando o Remote Control se desconectó
  En TypeScript, cada subtipo que no sea "init" es su propio tipo en la unión SDKMessage en lugar de un subtipo de SDKSystemMessage.
• AssistantMessage: emitido para cada bloque de contenido en las respuestas de Claude, incluido el final solo de texto. Cada uno lleva un único bloque de contenido, como texto o una llamada de herramienta, y los mensajes de una respuesta comparten un ID de mensaje.
• 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.

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                # Each AssistantMessage carries one content block
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Claude: {block.text}")
                    elif isinstance(block, ToolUseBlock):
                        print(f"Tool call: {block.name}")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      // Each assistant message carries one content block
      for (const block of message.message.content) {
        if (block.type === "text") {
          console.log(`Claude: ${block.text}`);
        } else if (block.type === "tool_use") {
          console.log(`Tool call: ${block.name}`);
        }
      }
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

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 pedir confirmación, salvo las lecturas desde rutas de red. Las herramientas no listadas aún están disponibles, y las llamadas a ellas que necesitan aprobación se transfieren al modo de permisos y a canUseTool.
• 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 cuánta supervisión humana desea. El SDK evalúa el modo activo junto con sus reglas de permitir y denegar en un orden fijo, descrito en Cómo se evalúan los permisos. Vea Modo de permiso para los modos disponibles.

​

Ejecución paralela de herramientas

​

Controlar cómo se ejecuta el bucle

​

Turnos y presupuesto

​

Margen del 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 compactador coincide en intención, así que el encabezado de la sección es de forma libre.
• 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 ordinarias. Vea dispatch commands by name.

# 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

• Usa 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. El contexto del agente principal crece por ese resumen, no por la transcripción completa de la subtarea. Consulta Qué heredan los subagentes para más 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 o ha retrocedido a carga anticipada, 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. Vea Configurar búsqueda de herramientas para las configuraciones donde se aplica el retroceso.
• 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

• Después de un bloqueo de sesión, el resultado final es un error_during_execution cuyos campos de costo pueden estar en cero y cuyo stop_reason es null, y el proceso sale después de emitirlo. Vea Recuperar totales después de un bloqueo de sesión.
• En Python, total_cost_usd, usage y model_usage se escriben como opcionales, así que verifique que no sean None antes de leerlos.

​

Hooks

​

Ponerlo todo junto

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    try:
        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}")
    except Exception as error:
        # A single-shot query() raises after yielding an error result. If the
        # failure was an error result, the error subtype branches above have
        # already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

try {
  for await (const message of query({
    prompt: "Find and fix the bug causing test failures in the auth module",
    options: {
      allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
      settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
      maxTurns: 30, // Prevent runaway sessions
      effort: "high" // Thorough reasoning for complex debugging
    }
  })) {
    // Save the session ID to resume later if needed
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }

    // Handle the final result
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`Done: ${message.result}`);
      } else if (message.subtype === "error_max_turns") {
        // Agent ran out of turns. Resume with a higher limit.
        console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
      } else if (message.subtype === "error_max_budget_usd") {
        console.log("Hit budget limit.");
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
      console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

​

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.
• ¿Implementando como servicio? Vea Alojamiento del Agent SDK para orientación sobre contenedores y sin servidor, y Almacenamiento de sesión para persistir sesiones en su propio backend.