O Modelo Mental do Claude Agent SDK
O Claude Agent SDK é a biblioteca da Anthropic para construir agentes de IA de produção em Python ou TypeScript.
Ele foi renomeado de "Claude Code SDK" em 2025, e esse renomeio é a maneira mais rápida de entender o que ele realmente é.
Claude Code, o agente de codificação de linha de comando, é construído sobre os mesmos primitivos que este SDK expõe para você: um loop de uso de ferramentas, um conjunto de ferramentas integradas, subagentes, sessões e suporte a cliente MCP.
Aprender este SDK é aprender como o Claude Code funciona internamente, e então poder direcionar essa mesma maquinaria para qualquer problema que você esteja resolvendo, em vez de apenas engenharia de software.
Esta página constrói o modelo mental que o restante da seção assume: o que o loop realmente faz em cada turno, como as ferramentas integradas e os subagentes se encaixam nele, e onde as sessões e os servidores MCP se conectam.
Resumo
- Ideia Central: O SDK envolve uma chamada de modelo em um loop de uso de ferramentas, entrega a esse loop um conjunto escopado de ferramentas (integradas, subagente ou MCP) e permite que o loop rode até que o agente produza uma resposta final ou atinja uma condição de parada.
- Por que Importa: Uma única chamada de prompt-resposta não pode ler um arquivo, executar um comando ou delegar uma subtarefa; o loop é o que transforma um modelo de linguagem em algo que pode realmente agir em uma base de código ou sistema.
- Conceitos Chave: loop de uso de ferramentas, ferramentas integradas, subagentes, sessões, pontos de verificação de intervenção humana (human-in-the-loop checkpoints), cliente MCP.
- Quando Usar: Qualquer tarefa que precise que o modelo leia/escreva arquivos, execute comandos, navegue na web ou coordene múltiplos fluxos de trabalho independentes, não apenas gere texto.
- Limitações / Trade-offs: Mais capacidade significa mais área de superfície para proteger; cada ferramenta que você habilita é algo que o loop pode fazer agora sem um humano observando cada passo, a menos que você adicione pontos de verificação.
- Tópicos Relacionados: noções básicas de query(), escopo de ferramentas, delegação de subagentes, persistência de sessão, servidores MCP.
Fundamentos
Na sua forma mais simples, chamar um modelo de linguagem é uma requisição e uma resposta.
Você envia um prompt, o modelo retorna texto, e nada no mundo muda como resultado.
O Claude Agent SDK existe porque a maior parte do trabalho real não tem essa forma.
Trabalho real geralmente significa "olhe este arquivo, decida o que mudar, faça a mudança, verifique se funcionou" - uma sequência de ações, não um único palpite.
A resposta do SDK para essa lacuna é o loop de uso de ferramentas: você o inicia com uma chamada do tipo query(), e em vez de retornar após uma resposta, o loop continua rodando enquanto o modelo continuar decidindo que precisa chamar uma ferramenta.
A cada turno, o modelo produz uma resposta final ou pede para invocar uma ferramenta, o SDK executa essa ferramenta e devolve o resultado, e o modelo tem mais um turno com essa nova informação disponível.
Uma analogia simples é um empreiteiro trabalhando a partir de uma planta baixa versus um que apenas descreve a casa por telefone.
Uma chamada de modelo bruta é a descrição por telefone: detalhada, mas nada é construído.
O loop de uso de ferramentas é o empreiteiro pegando ferramentas, usando-as e verificando o resultado antes de decidir o que fazer a seguir.
O SDK envia várias categorias de capacidade que se conectam a este loop, e entender para que serve cada categoria é a maior parte do que você precisa antes de escrever seu primeiro agente.
Ferramentas integradas cobrem edição de arquivos, execução de bash, pesquisa na web e busca na web, prontas para uso, sem necessidade de fiação de terceiros.
Subagentes são agentes filhos com seu próprio contexto isolado para o qual um agente pai pode delegar trabalho, útil quando uma tarefa se divide em peças independentes.
Sessões permitem que o histórico de conversas e chamadas de ferramentas de um agente persista entre execuções de processos, para que uma segunda invocação possa retomar em vez de começar do zero.
Suporte a cliente MCP amplia o que o loop pode alcançar sem que você precise escrever código de ferramenta personalizado; através do Model Context Protocol.
Mecânicas e Interações
A forma básica do loop é sempre a mesma: decidir, agir, observar, repetir.
O passo "decidir" é o modelo escolhendo, com base na conversa e nos resultados anteriores das ferramentas até agora, se deve chamar uma ferramenta ou produzir uma resposta final.
O passo "agir" é o SDK executando de fato o que o modelo pediu, seja uma ferramenta integrada, uma invocação de subagente ou uma chamada de ferramenta MCP.
O passo "observar" alimenta o resultado dessa ação de volta na conversa como novo contexto, que é o que torna o próximo passo de "decidir" mais informado do que o último.
Isso é exatamente o loop que o Claude Code executa quando edita um arquivo para você no terminal: ler, decidir, editar, verificar a diferença, decidir novamente.
Onde as categorias interagem é em como cada uma muda o que "agir" pode fazer.
Ferramentas integradas são as mãos padrão do loop: a edição de arquivos dá a ele a capacidade de mudar o que está no disco, o bash dá a ele um shell, a pesquisa na web e a busca na web dão a ele uma maneira de puxar informações além de seus dados de treinamento.
Nenhuma dessas é obrigatória; um agente de produção normalmente habilita apenas o subconjunto que a tarefa realmente precisa, porque cada ferramenta habilitada é algo que o loop pode invocar sem perguntar primeiro, a menos que você adicione um ponto de verificação.
from claude_agent_sdk import query, AgentOptions
options = AgentOptions(
allowed_tools=["file_edit", "bash"], # escopado, não "tudo ativado"
permission_mode="default", # loop pausa antes de ações arriscadas
)
result = query("Corrija o teste que falhou em tests/test_orders.py", options=options)Subagentes mudam a forma de "agir" de "executar uma ferramenta" para "entregar esta subtarefa inteira a um agente separado e esperar pelo seu resultado."
Cada subagente recebe sua própria janela de contexto e seu próprio acesso a ferramentas, o que significa que um agente pai trabalhando em uma tarefa grande pode distribuir o trabalho para vários subagentes que não poluem o contexto uns dos outros ou pisam nos raciocínios intermediários uns dos outros.
Esse isolamento também é a principal razão para buscar um subagente em vez de apenas adicionar outra chamada de ferramenta: fluxos de trabalho independentes permanecem independentes, e você pode executá-los em paralelo.
Pontos de verificação de intervenção humana (human-in-the-loop checkpoints) se conectam especificamente ao passo "agir", não ao loop inteiro.
Um ponto de verificação pausa a execução logo antes de uma ferramenta específica ser chamada, tipicamente uma marcada como destrutiva ou irreversível (excluir arquivos, enviar para um remoto, gastar dinheiro), e espera por aprovação antes de permitir que "agir" prossiga.
Sessões operam entre invocações de loop em vez de dentro de uma única.
Um ID de sessão captura o histórico de conversas e resultados de ferramentas no ponto em que uma execução termina, e passar esse ID para uma chamada query() posterior retoma o loop a partir daí em vez de começar do zero, o que é importante para tarefas de agente de longa duração ou multi-etapas que não cabem em um único processo.
Suporte a cliente MCP amplia o que "agir" pode alcançar sem que você escreva código de ferramenta personalizado.
Um servidor MCP, seja um processo stdio local ou um endpoint HTTP remoto, expõe ferramentas com a mesma forma das ferramentas integradas, então, uma vez que você registra uma, o loop pode chamá-la exatamente como chama edição de arquivo ou bash.
Considerações Avançadas e Aplicações
O modelo mental acima se mantém bem até você começar a compor peças, e é aí que a maioria das decisões de design de produção realmente vive.
Um agente pai com subagentes ainda é um único loop de uso de ferramentas no topo: cada invocação de subagente é apenas outra chamada de ferramenta da perspectiva do pai, e o subagente executa seu próprio loop interno por baixo, com seu próprio ciclo decidir-agir-observar e seu próprio escopo de ferramentas.
Esse aninhamento é por que subagentes compõem de forma limpa com pontos de verificação e sessões: um ponto de verificação no pai não se aplica automaticamente dentro de um subagente, e um subagente tipicamente não herda a sessão do pai, a menos que você configure isso explicitamente.
O escopo de ferramentas interage com pontos de verificação de uma maneira que é fácil de entender errado: o escopo decide o que o loop é capaz de chamar, enquanto os pontos de verificação decidem quais dessas chamadas permitidas ainda precisam que um humano diga sim.
Um agente com escopo estreito e sem pontos de verificação pode ser mais seguro do que um agente com escopo amplo e com pontos de verificação apenas nas ações mais obviamente destrutivas, porque o escopo fecha classes inteiras de ação em vez de depender de capturar todas as arriscadas no momento da aprovação.
A forma de implantação muda o que sessões e pontos de verificação significam na prática.
Executar o binário CLI empacotado localmente mantém tudo, incluindo aprovações de pontos de verificação, em uma máquina com um humano no teclado; um modelo de execução hospedado geralmente precisa que as aprovações de pontos de verificação sejam roteadas por algum outro canal (uma fila, um webhook, um painel) já que não há terminal para solicitar.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Agente único, apenas ferramentas integradas | Simples de raciocinar e depurar | Sem paralelismo, uma janela de contexto para tudo | Tarefas pequenas e autocontidas |
| Agente único + servidores MCP | Estende o alcance sem código de ferramenta personalizado | Adiciona uma dependência externa e seus próprios modos de falha | Tarefas que precisam de sistemas que o SDK não cobre nativamente |
| Pai + subagentes | Paraleliza trabalho independente, isola contexto | Mais partes móveis, mais difícil de rastrear de ponta a ponta | Tarefas grandes que se dividem em peças independentes claras |
| Qualquer um dos acima + pontos de verificação | Adiciona um veto humano antes de ações irreversíveis | Adiciona latência e uma dependência operacional de um revisor | Qualquer coisa que toque dados de produção, dinheiro ou exclusão |
Conceitos Errôneos Comuns
- "query() apenas envia um prompt e recebe uma resposta." Ele inicia um loop; a resposta que você recebe é o resultado após o modelo ter potencialmente chamado ferramentas, observado resultados e decidido novamente, possivelmente muitas vezes.
- "Habilitar uma ferramenta integrada significa que o agente pode fazer qualquer coisa com ela." O acesso a ferramentas pode ser escopado para ferramentas e caminhos específicos permitidos; habilitar "file edit" não precisa significar acesso irrestrito ao sistema de arquivos.
- "Subagentes são apenas uma maneira de economizar tokens." O isolamento de contexto é o benefício principal; a capacidade de executar subagentes independentes em paralelo e manter seus raciocínios intermediários de lotar o contexto do pai importa tanto quanto qualquer economia de tokens.
- "Sessões e pontos de verificação são o mesmo mecanismo de segurança." Sessões são sobre continuidade de contexto entre execuções; pontos de verificação são sobre pausar para aprovação antes de uma ação específica. Nenhum substitui o outro.
- "MCP é apenas para conectar a APIs remotas." Servidores MCP podem rodar localmente via stdio tão facilmente quanto via HTTP; o protocolo não se importa se a ferramenta vive em sua máquina ou através da rede.
FAQs
O Claude Agent SDK é a mesma coisa que o Claude Code?
- Não, mas eles compartilham os mesmos primitivos subjacentes.
- Claude Code é um produto CLI específico construído sobre esses primitivos, voltado para engenharia de software.
- O Agent SDK expõe esses primitivos diretamente para que você possa construir um agente para qualquer domínio, não apenas codificação.
O que realmente acontece quando eu chamo query()?
Ele inicia um loop de uso de ferramentas: o modelo raciocina sobre sua solicitação, opcionalmente chama uma ou mais ferramentas, observa cada resultado e repete até produzir uma resposta final ou uma condição de parada (como um limite de etapas) ser atingida.
Eu tenho que habilitar as ferramentas file edit, bash e web toda vez?
Não. O acesso a ferramentas é opt-in e escopado; você escolhe quais ferramentas integradas um agente pode usar para uma determinada tarefa, até operações específicas permitidas, em vez de conceder tudo por padrão.
Quando devo usar um subagente em vez de apenas adicionar outra ferramenta?
- Quando uma subtarefa é genuinamente independente e, de outra forma, lotaria o contexto do pai com etapas intermediárias irrelevantes.
- Quando você deseja paralelizar múltiplos fluxos de trabalho independentes.
- Não para toda pequena ação auxiliar; uma única chamada de ferramenta bem escopada é frequentemente mais simples.
O que é um ponto de verificação de intervenção humana (human-in-the-loop checkpoint), mecanicamente?
É uma pausa que o SDK insere logo antes que uma ferramenta específica seja executada, tipicamente uma marcada como destrutiva ou irreversível, que bloqueia até que um humano a aprove ou rejeite antes que o passo "agir" do loop prossiga.
As sessões persistem para sempre?
As sessões persistem pelo tempo que você escolher armazenar o identificador da sessão e seu histórico associado; o SDK fornece o mecanismo para retomar, mas a retenção e o armazenamento são responsabilidade da sua aplicação.
Como o MCP difere de uma ferramenta integrada?
Ferramentas integradas (edição de arquivos, bash, web) vêm com o próprio SDK. Ferramentas MCP vivem em um servidor separado, local ou remoto, que você registra; uma vez registrado, o loop as chama da mesma forma que chama ferramentas integradas.
Um subagente pode usar ferramentas diferentes de seu pai?
Sim. Cada subagente tem seu próprio escopo de ferramentas, que é uma das principais razões para usá-lo: você pode entregar ao subagente apenas o que ele precisa para sua parte específica da tarefa.
O que impede o loop de uso de ferramentas de rodar para sempre?
O loop termina quando o modelo produz uma resposta final em vez de outra chamada de ferramenta, ou quando uma condição de parada configurada (como um número máximo de turnos) é atingida.
Adicionar mais ferramentas torna um agente mais inteligente?
Não diretamente. Mais ferramentas ampliam o que o agente pode agir, mas o modelo ainda tem que decidir corretamente quando cada ferramenta se aplica; acesso a ferramentas não escopado e excessivo principalmente amplia o raio de explosão de uma decisão errada.
Python ou TypeScript é o SDK "real"?
Ambos são pacotes de primeira classe para o mesmo SDK subjacente. Esta seção usa Python como padrão para seus exemplos, mas os mesmos conceitos, loop, ferramentas, subagentes e sessões se aplicam em TypeScript.
Relacionados
- Noções Básicas do Claude Agent SDK - instale o pacote e execute sua primeira query()
- Habilitando Ferramentas de Edição de Arquivos, Bash e Web no Agent SDK - escopando ferramentas integradas na prática
- Delegando Trabalho para Subagentes no Claude Agent SDK - o modelo de isolamento em mais detalhes
- Adicionando Pontos de Verificação de Intervenção Humana a um Fluxo de Trabalho do Agent SDK - pausando o loop antes de ações irreversíveis
- Persistindo Sessões Entre Execuções com o Claude Agent SDK - retomando o contexto entre execuções de processos
- Conectando o Claude Agent SDK a Servidores MCP - ampliando o alcance do loop com ferramentas externas
Versões da Pilha: Escrito contra a linha de modelos Claude atual a partir de ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o Claude Agent SDK (última versão, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.