O que é Claude Agent SDK?
O Claude Agent SDK permite que um programa em Python ou TypeScript rode o mesmo loop de agente, as mesmas ferramentas e o mesmo gerenciamento de contexto que movem o Claude Code. Antes ele se chamava Claude Code SDK. A biblioteca inicia um binário do Claude Code embutido e troca mensagens com ele, então um agente construído sobre ela já consegue ler, escrever e editar arquivos, rodar comandos de shell e buscar na web.
query() executa uma tarefa pontual como fluxo assíncrono; o ClaudeSDKClient mantém uma sessão bidirecional e acrescenta ferramentas próprias, escritas como funções comuns de Python e servidas como servidores MCP no mesmo processo, além de hooks que rodam o seu código em pontos do ciclo de vida do agente. Subagentes, sessões que podem ser retomadas ou ramificadas, modos de permissão, skills, plugins e a memória do projeto das pastas .claude/ vêm do Claude Code.
O pacote de Python exige Python 3.10 ou mais recente. A versão 0.2.178 saiu em 4 de novembro de 2026 com o Claude Code 2.1.318 embutido; o pacote de TypeScript é publicado como @anthropic-ai/claude-agent-sdk.
Claude Agent SDK vale a pena?
O valor do Agent SDK é que as partes difíceis já estão escritas. Edição de arquivos, acesso ao shell, compactação de contexto, subagentes e pedidos de permissão vêm do Claude Code, que a Anthropic atualiza a cada poucos dias, então uma chamada de query() de dez linhas resulta em um agente capaz de corrigir um bug em um repositório real. Frameworks rivais como o OpenAI Agents SDK ou o LangGraph entregam peças para montar; este entrega um ambiente pronto que precisa ser restringido.
Essa inversão molda o modelo de segurança. Por padrão o Claude tem todo o conjunto de ferramentas do Claude Code, incluindo Bash e Write. allowed_tools só aprova automaticamente as ferramentas listadas; não remove as demais, que caem no modo de permissão e no seu callback can_use_tool. Para remover uma ferramenta é preciso usar disallowed_tools. Quem embute o SDK em um serviço deve ler o guia de permissões antes do quickstart e rodar o processo em um contêiner se as entradas não forem confiáveis.
O rótulo de código aberto precisa de uma nota de rodapé. O wrapper de Python tem licença MIT, mas o trabalho acontece no binário do Claude Code embutido, e a documentação diz que o uso do SDK segue os Commercial Terms da Anthropic. O repositório de TypeScript está marcado com todos os direitos reservados. Não dá para fazer fork do loop do agente, só configurá-lo.
O ritmo de versões acompanha o do Claude Code: 25 versões de Python entre 15 de setembro e 4 de novembro de 2026, de 0.2.153 a 0.2.178, ainda abaixo de 1.0. O repositório tem cerca de 8.440 estrelas e 616 issues e pull requests abertos. A documentação proíbe produtos de terceiros de oferecer login do claude.ai ou os limites dos planos sem aprovação, então um produto feito com o SDK cobra por chaves de API; na máquina de um desenvolvedor, o uso com login consome o plano do Claude dele. Um crédito mensal para o SDK anunciado para 15 de junho de 2026 foi suspenso no mesmo dia.
Onde ele se destaca
Um engenheiro de plataforma em uma empresa com 100 desenvolvedores
Rodar um bot interno que faça triagem de jobs de CI com falha e proponha patches
Chame query() a partir do runner de CI com cwd no checkout, disallowed_tools para tudo fora do repositório e um hook PreToolUse que bloqueie comandos de rede; o uso é cobrado em uma chave de API da Console com limite de gasto próprio.
Uma start-up que adiciona um agente a um produto de gestão de documentos
Deixar clientes pedirem a um agente que reorganize e resuma os arquivos deles
Exponha as ações do próprio produto como ferramentas com o decorador @tool e create_sdk_mcp_server, para que rodem no mesmo processo; cada sessão de cliente roda no próprio contêiner, e a cobrança passa por chaves de API porque o login do claude.ai não é permitido.
Uma desenvolvedora autônoma automatizando tarefas no próprio notebook
Automatizar refatorações repetidas sem escrever um loop de agente
Um script curto de Python com ClaudeSDKClient e o modo acceptEdits faz as edições; com o plano pessoal do Claude conectado, ele consome os limites desse plano em vez de gerar uma conta à parte.
Antes de decidir
- Configuração
- pip install claude-agent-sdk no Python 3.10+ (ou npm install @anthropic-ai/claude-agent-sdk), defina uma chave de API, e o agente de correção de bugs do quickstart roda em minutos; não é preciso instalar o Claude Code à parte.
- Integrações
- Servidores MCP, ferramentas próprias no mesmo processo, hooks, subagentes, skills e plugins das pastas .claude/; Claude API, Amazon Bedrock, Google Cloud e Microsoft Foundry para acesso aos modelos.
- Dados e privacidade
- Roda localmente com as permissões do seu processo e envia prompts e conteúdo de arquivos ao Claude conforme os termos da API ou do plano da conta; o conjunto padrão de ferramentas pode ler, escrever e executar em qualquer lugar onde o processo possa.
- Custo em escala
- O SDK é gratuito; o custo são os tokens do Claude a preços de API, e loops de agente com muitas chamadas de ferramentas multiplicam os tokens por tarefa. Os planos Max, Ultra e Team incluem créditos mensais de API utilizáveis com uma chave da Console vinculada.
- Limites
- Só modelos Claude; API abaixo de 1.0 com versões frequentes; regras de marca proíbem chamar um produto de Claude Code; o loop do agente em si não pode ser alterado.
O que é bom
- As ferramentas de arquivos, shell e web do Claude Code prontas para uso
- Ferramentas próprias como servidores MCP no mesmo processo, sem processo separado
- Hooks, subagentes, sessões e plugins herdados
- O mesmo motor na API, no Bedrock, no Google Cloud e no Foundry
- Versões frequentes no ritmo do Claude Code
O que não é
- O binário central é fechado e segue os Commercial Terms da Anthropic
- Todas as ferramentas disponíveis por padrão; allowed_tools não restringe
- Só modelos Claude
- Abaixo de 1.0, com versões a cada poucos dias
- Produtos não podem oferecer login do claude.ai aos usuários
Ideal para
Desenvolvedores que querem um agente de código ou de trabalho com arquivos no nível do Claude Code dentro do próprio produto e já escolheram o Claude.
Alternativas ao Claude Agent SDK
Claude Agent SDK: perguntas frequentes
- Claude Agent SDK vale a pena?
- Não há caminho mais rápido para um agente que já sabe editar arquivos e rodar comandos, desde que você aceite o Claude Code como um motor fechado lá dentro. Damos nota 4.2 de 5.
- Quanto custa Claude Agent SDK?
- O wrapper de Python é gratuito sob a licença MIT; o binário do Claude Code embutido e o pacote de TypeScript seguem os Commercial Terms da Anthropic. Você paga pelo uso da Claude API ou consome os limites do seu próprio plano do Claude.
- Quais são as desvantagens de Claude Agent SDK?
- O binário central é fechado e segue os Commercial Terms da Anthropic; todas as ferramentas disponíveis por padrão; allowed_tools não restringe; só modelos Claude; abaixo de 1.0, com versões a cada poucos dias; produtos não podem oferecer login do claude.ai aos usuários.
- Para quem Claude Agent SDK é indicado?
- Desenvolvedores que querem um agente de código ou de trabalho com arquivos no nível do Claude Code dentro do próprio produto e já escolheram o Claude.
- Quanto custa Claude Agent SDK para uma equipe ou em produção?
- O SDK é gratuito; o custo são os tokens do Claude a preços de API, e loops de agente com muitas chamadas de ferramentas multiplicam os tokens por tarefa. Os planos Max, Ultra e Team incluem créditos mensais de API utilizáveis com uma chave da Console vinculada.
- Claude Agent SDK é seguro para dados da empresa?
- Roda localmente com as permissões do seu processo e envia prompts e conteúdo de arquivos ao Claude conforme os termos da API ou do plano da conta; o conjunto padrão de ferramentas pode ler, escrever e executar em qualquer lugar onde o processo possa.
- Quais são as melhores alternativas ao Claude Agent SDK?
- As alternativas mais próximas que analisamos são OpenAI Agents SDK, Pydantic AI, LangGraph e Google Agent Development Kit (ADK).
Respostas verificadas em 6 de nov. de 2026.
Você faz o Claude Agent SDK? Mostre esta nota no seu site
