Claude Code SDK

 (docs.anthropic.com)
1 pontos por GN⁺ 2025-05-20 | 1 comentários | Compartilhar no WhatsApp
  • O Claude Agent SDK permite controlar a execução de ferramentas, o loop de agente e o gerenciamento de contexto do Claude Code a partir de código Python e TypeScript, automatizando leitura de arquivos, execução de comandos, busca na web e edição de código
  • Ele oferece como ferramentas básicas Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, permitindo lidar desde a exploração de codebases até perguntas de confirmação ao usuário sem uma camada de execução separada
  • Ao combinar hooks, subagentes, MCP, permissões e sessões, é possível montar configurações como logs de auditoria de alterações em arquivos, subagentes dedicados a code review, automação de navegador baseada em Playwright e agentes de análise somente leitura
  • A instalação é feita com @anthropic-ai/claude-agent-sdk ou claude-agent-sdk; Python exige 3.10 ou superior, e o SDK TypeScript inclui como dependência opcional o binário nativo do Claude Code para a plataforma
  • Diferentemente do Anthropic Client SDK, no qual é preciso implementar diretamente o loop de ferramentas, o Agent SDK oferece execução de ferramentas integrada e roda no processo e na infraestrutura do usuário, não na infraestrutura da Anthropic como os Managed Agents

Escopo do Claude Agent SDK

  • O Claude Agent SDK disponibiliza em Python e TypeScript as ferramentas, o loop de agente e o gerenciamento de contexto que impulsionam o Claude Code
  • O agente pode ler arquivos, executar comandos, pesquisar na web e editar código
  • Como inclui execução de ferramentas integrada, o agente pode começar a trabalhar sem que o usuário precise criar uma camada separada de execução de ferramentas
  • O exemplo básico permite as ferramentas Read, Edit e Bash para encontrar e corrigir um bug em auth.py

Instalação e fluxo de autenticação

  • A instalação é feita por pacotes específicos de cada linguagem
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • O pacote Python exige Python 3.10 ou superior
    • Se aparecer o erro No matching distribution found for claude-agent-sdk, o interpretador pode estar em uma versão anterior à 3.10
    • No macOS ou Linux, confira com python3 --version; no Windows, com py --version
  • O SDK TypeScript inclui como dependência opcional o binário do Claude Code nativo para a plataforma, portanto não é necessário instalar o Claude Code separadamente
  • A chave de API deve ser emitida no Console e configurada na variável de ambiente ANTHROPIC_API_KEY
  • Também há suporte à autenticação em provedores de API de terceiros
    • Amazon Bedrock: configure CLAUDE_CODE_USE_BEDROCK=1 e depois as credenciais da AWS
    • Claude Platform on AWS: configure CLAUDE_CODE_USE_ANTHROPIC_AWS=1 e ANTHROPIC_AWS_WORKSPACE_ID, depois as credenciais da AWS
    • Google Vertex AI: configure CLAUDE_CODE_USE_VERTEX=1 e depois as credenciais do Google Cloud
    • Microsoft Azure: configure CLAUDE_CODE_USE_FOUNDRY=1 e depois as credenciais do Azure
  • A Anthropic não permite que desenvolvedores terceiros ofereçam login via claude.ai ou rate limits em produtos baseados no Claude Agent SDK sem aprovação prévia

Ferramentas básicas e recursos de agente

  • O SDK permite manipular por código os principais recursos do Claude Code
    • Ferramentas integradas
    • Hooks
    • Subagentes
    • MCP
    • Permissões
    • Sessões
  • As principais ferramentas integradas cumprem os seguintes papéis
    • Read: ler arquivos dentro do diretório de trabalho
    • Write: criar novos arquivos
    • Edit: aplicar edições precisas a arquivos existentes
    • Bash: executar comandos de terminal, scripts e operações git
    • Monitor: monitorar scripts em segundo plano e reagir a cada linha de saída como um evento
    • Glob: encontrar arquivos por padrões como **/*.ts e src/**/*.py
    • Grep: pesquisar conteúdo de arquivos com expressões regulares
    • WebSearch: pesquisar informações recentes na web
    • WebFetch: obter e fazer parsing do conteúdo de páginas web
    • AskUserQuestion: fazer perguntas de confirmação ao usuário com opções de múltipla escolha
  • O agente de exemplo permite Read, Glob e Grep para encontrar e resumir comentários TODO na codebase

Hooks, subagentes e MCP

  • Hooks executam código do usuário em pontos importantes do ciclo de vida do agente
    • Com funções de callback, é possível validar, registrar, bloquear ou transformar o comportamento do agente
    • Os hooks disponíveis incluem PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit e outros
    • O exemplo detecta operações Edit|Write em PostToolUse e registra alterações de arquivos em audit.log
  • Subagentes são agentes especializados que lidam com subtarefas focadas
    • O agente principal delega uma tarefa e o subagente retorna o resultado
    • Agentes customizados são definidos por descrição, prompt e ferramentas a serem usadas
    • A chamada de subagente é feita por meio da ferramenta Agent, portanto, para aprovação automática, é preciso incluir Agent em allowedTools
    • Mensagens dentro do contexto do subagente incluem o campo parent_tool_use_id, permitindo rastrear a qual execução de subagente pertencem
  • Com o Model Context Protocol (MCP), é possível conectar sistemas externos como bancos de dados, navegadores e APIs

Gerenciamento de permissões e sessões

  • As configurações de permissão limitam as ferramentas que o agente pode usar
    • É possível permitir operações seguras, bloquear operações perigosas e exigir aprovação para ações sensíveis
    • O exemplo pré-aprova apenas Read, Glob e Grep para montar um agente somente leitura que analisa código sem modificá-lo
  • A ferramenta AskUserQuestion e prompts interativos de aprovação são usados em conjunto no fluxo de processamento de entrada do usuário
  • Sessões mantêm o contexto ao longo de várias trocas
    • Claude lembra os arquivos lidos, as análises realizadas e o histórico da conversa
    • Depois, é possível retomar a mesma sessão ou fazer um fork para explorar outra abordagem
    • O exemplo obtém um session_id na primeira consulta e, na segunda, continua com o mesmo contexto usando resume=session_id

Suporte às configurações do Claude Code

  • O SDK oferece suporte às configurações baseadas em sistema de arquivos do Claude Code
  • Nas opções padrão, ele carrega configurações de .claude/ no diretório de trabalho e de ~/.claude/
  • Para restringir as fontes de configuração a carregar, use a opção setting_sources em Python e settingSources em TypeScript
  • Os recursos e locais com suporte são os seguintes
    • Skills: recursos especializados que Claude usa automaticamente ou chama com /name, em .claude/skills/*/SKILL.md
    • Commands: comandos customizados em formato legado, em .claude/commands/*.md
    • Memory: contexto e instruções do projeto, em CLAUDE.md ou .claude/CLAUDE.md
    • Plugins: extensões de skills, agents, hooks e MCP servers, configuradas programaticamente pela opção plugins

Diferenças em relação a outras ferramentas Claude

  • O Anthropic Client SDK oferece acesso direto à API; o usuário envia prompts e implementa diretamente a execução de ferramentas
  • No Agent SDK, Claude executa o processamento de ferramentas de forma autônoma
    • No Client SDK, o usuário implementa o loop de ferramentas
    • O Agent SDK oferece a Claude execução de ferramentas integrada
  • Os critérios de escolha por uso são os seguintes
    • Desenvolvimento interativo: CLI
    • Pipelines de CI/CD: SDK
    • Aplicações customizadas: SDK
    • Tarefas pontuais: CLI
    • Automação em produção: SDK
  • Muitas equipes usam a CLI no desenvolvimento cotidiano e o SDK em produção, e os workflows podem ser transferidos diretamente entre eles
  • Managed Agents é uma API REST hospedada na qual a Anthropic executa o agente e o sandbox
  • O Agent SDK é uma biblioteca que executa o loop do agente dentro do processo do usuário
    • Local de execução: o Agent SDK roda no processo e na infraestrutura do usuário; Managed Agents roda na infraestrutura gerenciada pela Anthropic
    • Interface: o Agent SDK é uma biblioteca Python ou TypeScript; Managed Agents é uma API REST
    • Alvo do trabalho: o Agent SDK atua sobre arquivos na infraestrutura do usuário; Managed Agents usa um sandbox gerenciado por sessão
    • Estado da sessão: o Agent SDK usa JSONL no sistema de arquivos; Managed Agents usa logs de eventos hospedados pela Anthropic
    • Ferramentas customizadas: no Agent SDK, são funções Python ou TypeScript dentro do processo; em Managed Agents, Claude aciona a ferramenta e o usuário retorna o resultado da execução
    • Casos indicados: o Agent SDK é adequado para prototipagem local e agentes com acesso direto ao sistema de arquivos e serviços; Managed Agents é indicado para agentes em produção sem operar infraestrutura de sandbox ou sessão e para sessões longas e assíncronas
  • O caminho comum é criar um protótipo local com o Agent SDK e depois migrar para Managed Agents em produção

Changelog, reporte de bugs e branding

  • Atualizações do SDK, correções de bugs e novos recursos podem ser conferidos no changelog de cada repositório
  • Bugs ou issues devem ser reportados no GitHub
  • Quando parceiros integram o Claude Agent SDK, o uso da marca Claude é opcional
    • Permitido: “Claude Agent”, “Claude”, “Powered by Claude”
    • Proibido: “Claude Code”, “Claude Code Agent”, ASCII art da marca Claude Code ou elementos visuais que imitem o Claude Code
    • O produto deve manter sua própria marca e não deve parecer o Claude Code nem um produto da Anthropic
  • O uso do Claude Agent SDK está sujeito aos Termos Comerciais de Serviço da Anthropic
    • A exceção é quando um componente ou dependência específico declara uma licença diferente no arquivo LICENSE desse componente

Leituras relacionadas

1 comentários

 
GN⁺ 2025-05-20
Opiniões no Hacker News

  • A direção que o Claude Code está mirando bate exatamente com o que eu quero em uma ferramenta de codificação agentic, e também gosto da filosofia de “ferramenta no estilo Unix”
    Venho usando desde o início do preview público e já dava para ver a direção. Para mim, o estado final ideal de um agente de codificação é você passar uma solicitação de funcionalidade, como um ticket do Jira, e ele criar um PR para ser revisado e receber feedback. Nesse sentido, ferramentas centradas em editores locais como Cursor e Windsurf ficam próximas de um beco sem saída, porque não conseguem rodar dentro de CI. Se você vai preparar a codebase para IA com regras, MCP etc., deveria mirar em uma tecnologia que possa chegar até o uso headless. O Claude Code é fácil de usar como parte de uma automação por meio de ferramentas, então agora virou meu padrão ao pensar em agentes de codificação, e o pacote npm do Codex é parecido. Dito isso, como trabalho ajudando empresas a preparar suas codebases para o uso de agentes, posso ter um viés por ferramentas fáceis de configurar

    • Tenho dificuldade em concordar com esse “estado final ideal”. O que eu quero é estar em uma sala cercado por várias telas, com agentes de IA codificando, projetando e testando, enquanto eu fico no centro definindo a direção e aplicando minhas preferências
      Espero que tudo aconteça por conversa, de um jeito em que 99% do tempo eu não precise encostar no teclado
    • Acho que não. O estado final “ideal” de um agente de codificação é um agente de codificação livre e open source rodando no meu computador ou em uma máquina que eu escolher
      Imagine pagar dinheiro toda vez que você executa comandos como ls, ps ou kill no terminal — não faz sentido. Com LLMs é a mesma coisa. Não estou dizendo que LLMs proprietários devam ser proibidos, mas as ferramentas principais dos hackers de antigamente deveriam ser livres e open source
    • A Anthropic também anunciou hoje em beta um recurso numa direção parecida: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • Também tentei fazer esse tipo de trabalho com Cursor e MCP. Depois de mais ou menos um dia, bati no limite de uso e caí para o modelo mais lento e burro
      Também tentei com Claude, mas esgotei o limite rapidamente. Só em uns 25% dos casos o PR fica num nível em que dá para “seguir em frente” de cara, e muitas vezes é mais rápido simplesmente fazer direito por conta própria do que descobrir onde a IA estragou tudo
    • Entendo a ideia de dar uma solicitação de funcionalidade e ele gerar um PR para revisão, mas aí só sobra a parte mais corrosiva para a alma no trabalho de software: os tickets do Jira. É deprimente

  • Claude Code é a forma de usar LLMs para programação de que mais gosto
    Mas acho que o que realmente precisamos é de uma versão open source em que seja possível plugar qualquer modelo e também comparar respostas de vários modelos. Aider e outras alternativas não parecem tão agradáveis de usar quanto o Claude Code. Do ponto de vista da Anthropic, eles não iriam querer isso, porque o fosso defensivo desapareceria; mas, do ponto de vista do consumidor, eu só quero usar o melhor modelo sem ficar preso a um ecossistema específico. Provavelmente é isso que mais assusta os provedores de modelos de LLM

    • O OpenAI Codex provavelmente é a alternativa mais próxima. É open source e pode usar o modelo de qualquer provedor
      No momento ainda não é tão bom quanto o Claude Code, mas acho que vai alcançar rapidamente. https://github.com/openai/codex/tree/main
    • O projeto OpenCode pode ser do seu interesse: https://github.com/opencode-ai/opencode
      Ainda está em desenvolvimento, mas parece promissor
    • Fico curioso para saber o que o Claude Code faz melhor que o Aider
    • Tenho feito autopromoção demais recentemente, mas, vendo comentários anteriores, eu tenho um serviço que criei em Go. Ele mira exatamente essa necessidade
    • Concordo, mas outros modelos também não precisariam ser treinados para saber como trabalhar com servidores MCP? Ou isso não é um problema?

  • O Aider há muito tempo dá suporte a Python e scripting de shell [0]
    No processo recente de adicionar suporte a 130 novas linguagens de programação, também fiz um screencast usando o Aider para scripting Bash na hora [1]. Isso dá uma ideia de como essa abordagem pode ser poderosa.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Gosto muito do Aider. O suporte a MCP também deve chegar em breve, e estou testando o branch de desenvolvimento
      Com isso, dá para fazer desenvolvimento de ponta a ponta por meio de PRs, tickets etc., usando o modelo em que você confia
    • Fico curioso para saber o quão perto dá para deixar o Aider do Claude Code. A experiência de usuário do Claude Code foi boa, mas não uso porque prefiro o Gemini 2.5 Pro
      Não faço muita questão de ele criar commits; gosto principalmente da sensação de uso do Claude Code
    • O Aider poderia melhorar bastante com um workflow do GitHub Actions bem polido
      Bastaria adicionar um único arquivo ao repositório para poder conversar com qualquer modelo por meio de issues

  • O que a equipe do Claude Code abordou com mais detalhes: http://latent.space/p/claude-code
    Dá para só passar os olhos pela transcrição, mas, pessoalmente, achei marcante o fato de funcionários da Anthropic usarem Claude ilimitado e ainda assim gastarem em média cerca de US$ 6 por dia; a visão do Claude Code headless como um utilitário “Linux” utilizável em qualquer CI; a ideia dele como uma plataforma extensível pelos usuários; o fato de sandboxing, branching e funcionalidades de planejamento estarem no roadmap futuro; e a visão do Sonnet 3.7 como um modelo de agente persistente

    • O link diz que, entre os engenheiros internos da Anthropic, houve até alguém que gastou mais de US$ 1.000 em um dia
      Fico curioso para saber quais são os valores P50, P75 e P95 de gasto por funcionário
    • Talvez eu esteja usando errado, mas se eu usar Claude Code por 2 horas, facilmente passa de US$ 20
      Parei de usar em projetos pessoais porque é caro demais
    • Tenho curtido muito o podcast latent space ultimamente. Acho que há poucas pessoas ou podcasts que mantenham uma relação sinal-ruído tão alta com um volume geral de produção desse nível
      É impressionante ver que, no último semestre ou nos últimos anos, mesmo enquanto desenvolvem vários negócios, a quantidade e o valor do trabalho público continuam crescendo. Seria bom se outras pessoas também conseguissem encontrar uma curva de produtividade parecida. Eles até compartilham, em linhas gerais, o que funciona bem, mas não é fácil reproduzir. Me vêm à mente simonw e gwern
    • Fico me perguntando quão neutro foi esse podcast, ou se foi simplesmente promoção com viés comercial desse produto

  • Se eu fosse criar um assistente de código com IA, prender o produto a um provedor de modelo-base específico seria a última coisa que eu faria
    Para este produto ter sucesso, é preciso pressupor que o desempenho dos modelos acabou de atingir um platô, que todos os modelos-base vão convergir para praticamente o mesmo desempenho e as mesmas capacidades, e que integradores vão escolher com base em pequenas conveniências, como um SDK familiar

    • Tirando comandos e argumentos, não há muita coisa que prenda alguém. No fim, é só entrada e saída
      Basta trocar por outra coisa ou colocar um wrapper. Não há muita complexidade nisso aqui
    • Neste momento, o Claude Code é o elemento de diferenciação de software na área de codificação agentiva
      Estou construindo algo relacionado a assistentes de código com IA, e a primeira coisa que eu estava hackeando era como integrar o Claude Code. É a primeira coisa sobre a qual queríamos construir. Ainda é cedo demais para se preocupar com lock-in; precisamos do melhor, então vamos construir apenas em torno do melhor

  • O Claude Code já podia ser usado em modo não interativo e, portanto, integrado a outros apps como qualquer outro utilitário de linha de comando Unix
    Este SDK parece oferecer suporte apenas ao uso via linha de comando por enquanto; então não é a mesma coisa que já existia? Não entendo o que de fato há de novo. O que estou deixando passar?

    • Também não sei. Para mim, é estranho que quase ninguém pareça falar sobre esse ponto

  • Também recomendo o Codebuff (https://www.codebuff.com/). É um excelente assistente de código via CLI, parecido com o Claude Code, e pode economizar muito em custo de tokens
    Não tenho relação com o projeto, sou apenas usuário

  • Os termos dizem que o serviço não pode ser usado “para desenvolver produtos ou serviços que concorram com o Serviço, para desenvolver ou treinar algoritmos ou modelos de inteligência artificial ou machine learning, nem para revender o Serviço”
    Fico me perguntando o que exatamente seria um produto ou serviço de software que não concorra com inteligência geral. Eles vendem inteligência e, se interpretado estritamente, estão anexando uma cláusula legal que basicamente diz para não usar em lugar nenhum. É tão vago que se torna inexequível? Se não se pode usar para competir com inteligência geral, como é que se possui o output? É aquela ideia de que “ninguém liga para termos legais”? Se ninguém liga, por que colocar uma proibição ampla sobre o uso do serviço? Tenho muitas dúvidas sobre se é para aceitar até responsabilidade por derrota em processo para receber esse tipo de resultado

    • É isso que acontece quando se deixa advogados escreverem à vontade
    • Trocaram “artificial” por “general”, então obviamente o significado muda

  • Ter lock-in de modelo é uma grande desvantagem para o uso. Se alguém lançar o mais novo modelo de melhor desempenho e você já tiver investido nessa infraestrutura, fica preso
    Mesmo que abram isso depois, é provável que o modelo em questão tenha sido treinado especificamente para essa CLI, então talvez não funcione bem. Basta olhar para o Codex CLI: dá para usar Gemini 2.5 Pro, mas, em comparação com os modelos da OpenAI, ele para aleatoriamente ou falha com muito mais frequência

  • A nova GitHub Action é exatamente a funcionalidade que eu estava procurando: https://docs.anthropic.com/en/docs/claude-code/github-action...
    Mas não parece haver uma forma de usá-la com o plano Max do Claude Code. Pelo que vejo, ela parece aceitar apenas uma chave de API