Como o loop do agente funciona

​

O loop em um relance

1. Receber prompt. Claude recebe seu prompt, junto com o prompt do sistema, definições de ferramentas e histórico de conversa. O SDK produz uma SystemMessage com subtipo "init" contendo metadados da sessão.
2. Avaliar e responder. Claude avalia o estado atual e determina como proceder. Pode responder com texto, solicitar uma ou mais chamadas de ferramentas, ou ambos. O SDK produz uma AssistantMessage contendo o texto e quaisquer solicitações de chamadas de ferramentas.
3. Executar ferramentas. O SDK executa cada ferramenta solicitada e coleta os resultados. Cada conjunto de resultados de ferramentas retorna para Claude para a próxima decisão. Você pode usar hooks para interceptar, modificar ou bloquear chamadas de ferramentas antes de serem executadas.
4. Repetir. Os passos 2 e 3 se repetem como um ciclo. Cada ciclo completo é uma volta. Claude continua chamando ferramentas e processando resultados até produzir uma resposta sem chamadas de ferramentas.
5. Retornar resultado. O SDK produz uma AssistantMessage final com a resposta de texto (sem chamadas de ferramentas), seguida por uma ResultMessage com o texto final, uso de tokens, custo e ID da sessão.

​

Voltas e mensagens

1. Volta 1: Claude chama Bash para executar npm test. O SDK produz uma AssistantMessage com a chamada de ferramenta, executa o comando, então produz uma UserMessage com a saída (três falhas).
2. Volta 2: Claude chama Read em auth.ts e auth.test.ts. O SDK retorna o conteúdo dos arquivos e produz uma AssistantMessage.
3. Volta 3: Claude chama Edit para corrigir auth.ts, então chama Bash para executar novamente npm test. Todos os três testes passam. O SDK produz uma AssistantMessage.
4. Volta final: Claude produz uma resposta apenas com texto sem chamadas de ferramentas: “Corrigi o bug de autenticação, todos os três testes passam agora.” O SDK produz uma AssistantMessage final com este texto, então uma ResultMessage com o mesmo texto mais custo e uso.

​

Tipos de mensagens

• SystemMessage: eventos do ciclo de vida da sessão. O campo subtype os distingue: "init" é a primeira mensagem (metadados da sessão), e "compact_boundary" dispara após compactação. Em TypeScript, o limite de compactação é seu próprio tipo SDKCompactBoundaryMessage em vez de um subtipo de SDKSystemMessage.
• AssistantMessage: emitida após cada resposta do Claude, incluindo a final apenas com texto. Contém blocos de conteúdo de texto e blocos de chamadas de ferramentas dessa volta.
• UserMessage: emitida após cada execução de ferramenta com o conteúdo do resultado da ferramenta enviado de volta para Claude. Também emitida para quaisquer entradas do usuário que você transmita no meio do loop.
• StreamEvent: emitida apenas quando mensagens parciais estão habilitadas. Contém eventos brutos de streaming da API (deltas de texto, pedaços de entrada de ferramentas). Veja Respostas de streaming.
• ResultMessage: marca o fim do loop do agente. Contém o resultado de texto final, uso de tokens, custo e ID da sessão. Verifique o campo subtype para determinar se a tarefa foi bem-sucedida ou atingiu um limite. Um pequeno número de eventos de sistema finais, como prompt_suggestion, pode chegar após ele, então itere o fluxo até a conclusão em vez de quebrar no resultado. Veja Lidar com o resultado.

​

Lidar com mensagens

• Apenas resultados finais: lide com ResultMessage para obter a saída, custo e se a tarefa foi bem-sucedida ou atingiu um limite.
• Atualizações de progresso: lide com AssistantMessage para ver o que Claude está fazendo a cada volta, incluindo quais ferramentas chamou.
• Streaming ao vivo: habilite mensagens parciais (include_partial_messages em Python, includePartialMessages em TypeScript) para obter mensagens StreamEvent em tempo real. Veja Respostas de streaming em tempo real.

• Python: verifique tipos de mensagens com isinstance() contra classes importadas de claude_agent_sdk (por exemplo, isinstance(message, ResultMessage)).
• TypeScript: verifique o campo de string type (por exemplo, message.type === "result"). AssistantMessage e UserMessage envolvem a mensagem bruta da API em um campo .message, então blocos de conteúdo estão em message.message.content, não em 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}")

​

Execução de ferramentas

​

Ferramentas integradas

• Conectar serviços externos com servidores MCP (bancos de dados, navegadores, APIs)
• Definir ferramentas personalizadas com manipuladores de ferramentas personalizadas
• Carregar skills do projeto via fontes de configuração para fluxos de trabalho reutilizáveis

​

Permissões de ferramentas

• allowed_tools / allowedTools aprova automaticamente ferramentas listadas. Um agente somente leitura com ["Read", "Glob", "Grep"] em sua lista de ferramentas permitidas executa essas ferramentas sem avisar. Ferramentas não listadas ainda estão disponíveis, mas exigem permissão.
• disallowed_tools / disallowedTools bloqueia ferramentas listadas, independentemente de outras configurações. Veja Permissões para a ordem em que as regras são verificadas antes de uma ferramenta ser executada.
• permission_mode / permissionMode controla o que acontece com ferramentas que não são cobertas por regras de permissão ou negação. Veja Modo de permissão para os modos disponíveis.

​

Execução paralela de ferramentas

​

Controlar como o loop é executado

​

Voltas e orçamento

​

Nível de esforço

​

Modo de permissão

​

Modelo

​

A janela de contexto

​

O que consome contexto

​

Compactação automática

• Instruções de sumarização em CLAUDE.md: O compactador lê seu CLAUDE.md como qualquer outro contexto, então você pode incluir uma seção dizendo a ele o que preservar ao resumir. O cabeçalho da seção é livre (não uma string mágica); o compactador corresponde à intenção.
• Hook PreCompact: Execute lógica personalizada antes da compactação ocorrer, por exemplo para arquivar a transcrição completa. O hook recebe um campo trigger (manual ou auto). Veja hooks.
• Compactação manual: Envie /compact como uma string de prompt para acionar compactação sob demanda. Comandos enviados desta forma são entradas SDK, não atalhos apenas CLI. Veja slash commands no 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

​

Manter contexto eficiente

• Use subagentes para subtarefas. Cada subagente começa com uma conversa fresca (sem histórico de mensagens anterior, embora carregue seu próprio prompt do sistema e contexto de nível de projeto como CLAUDE.md). Ele não vê as voltas do pai, e apenas sua resposta final retorna ao pai como resultado de ferramenta. O contexto do agente principal cresce por esse resumo, não pela transcrição completa da subtarefa. Veja O que subagentes herdam para detalhes.
• Seja seletivo com ferramentas. Cada definição de ferramenta ocupa espaço de contexto. Use o campo tools em AgentDefinition para escopo subagentes ao conjunto mínimo que precisam.
• Observe custos de servidor MCP. MCP tool search adia esquemas de ferramentas MCP por padrão e carrega-os sob demanda. Quando a busca de ferramentas está desativada, no Vertex AI, ou atrás de um ANTHROPIC_BASE_URL não de primeira parte, cada servidor MCP adiciona todos os seus esquemas de ferramentas a cada requisição, então alguns servidores com muitas ferramentas podem consumir contexto significativo antes do agente fazer qualquer trabalho.
• Use esforço mais baixo para tarefas rotineiras. Defina esforço para "low" para agentes que apenas precisam ler arquivos ou listar diretórios. Isso reduz uso de tokens e custo.

​

Sessões e continuidade

​

Lidar com o resultado

​

Hooks

​

Juntar tudo

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 passos

• Ainda não executou um agente? Comece com o quickstart para obter o SDK instalado e ver um exemplo completo sendo executado de ponta a ponta.
• Pronto para conectar ao seu projeto? Carregue CLAUDE.md, skills e hooks do sistema de arquivos para que o agente siga suas convenções de projeto automaticamente.
• Construindo uma UI interativa? Habilite streaming para mostrar texto ao vivo e chamadas de ferramentas conforme o loop é executado.
• Precisa de controle mais apertado sobre o que o agente pode fazer? Bloqueie o acesso a ferramentas com permissões e use hooks para auditar, bloquear ou transformar chamadas de ferramentas antes de serem executadas.
• Executando tarefas longas ou caras? Descarregue trabalho isolado para subagentes para manter seu contexto principal enxuto.