Skip to main content
Use o Agent SDK para construir um agente de IA que leia seu código, encontre bugs e os corrija, tudo sem intervenção manual. O que você fará:
  1. Configurar um projeto com o Agent SDK
  2. Criar um arquivo com código com bugs
  3. Executar um agente que encontra e corrige os bugs automaticamente

Pré-requisitos

  • Node.js 18+ ou Python 3.10+
  • Uma conta Anthropic. Se você não tiver uma, inscreva-se aqui.

Configuração

1

Criar uma pasta de projeto

Crie um novo diretório para este início rápido:
Para seus próprios projetos, você pode executar o SDK de qualquer pasta; ele terá acesso aos arquivos nesse diretório e seus subdiretórios por padrão.
2

Instalar o SDK

Instale o pacote Agent SDK para sua linguagem:
Definir "type": "module" em package.json permite que seu script de agente use await de nível superior, e tsx executa arquivos TypeScript diretamente. npm imprime added N packages quando a instalação é bem-sucedida.
Tanto o SDK TypeScript quanto o Python agrupam um binário nativo Claude Code, portanto a maioria das instalações não precisa de uma instalação separada do Claude Code. Algumas instalações não têm binário agrupado:
  • Se pip instalar a distribuição de código-fonte do SDK Python em vez de uma wheel de plataforma, por exemplo em ARM64 Windows, nenhum binário é agrupado. Instale Claude Code nativamente. O SDK Python o encontra em seu PATH.
  • O SDK TypeScript instala seu binário através de dependências opcionais npm, portanto uma instalação que as ignora, por exemplo npm ci --omit=optional, não obtém binário mesmo em uma plataforma suportada. Reinstale sem ignorar dependências opcionais, ou instale Claude Code nativamente e defina pathToClaudeCodeExecutable para seu caminho.
3

Defina sua chave de API

Obtenha uma chave de API no Claude Console, depois defina-a como uma variável de ambiente no shell onde você executará seu agente:
O SDK lê a chave do ambiente do processo que executa seu agente; ele não carrega arquivos .env automaticamente. Se você mantiver a chave em um arquivo .env, carregue-a você mesmo, por exemplo com o pacote dotenv, antes de chamar o SDK.O SDK também suporta autenticação através de provedores de API de terceiros:
  • Amazon Bedrock: defina a variável de ambiente CLAUDE_CODE_USE_BEDROCK=1 e configure as credenciais AWS
  • Claude Platform on AWS: defina CLAUDE_CODE_USE_ANTHROPIC_AWS=1 e ANTHROPIC_AWS_WORKSPACE_ID, depois configure as credenciais AWS
  • Google Cloud’s Agent Platform: defina a variável de ambiente CLAUDE_CODE_USE_VERTEX=1 e configure as credenciais Google Cloud
  • Microsoft Foundry: defina a variável de ambiente CLAUDE_CODE_USE_FOUNDRY=1 e configure as credenciais Azure
Consulte os guias de configuração para Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, ou Microsoft Foundry para detalhes.
A menos que previamente aprovado, a Anthropic não permite que desenvolvedores terceirizados ofereçam login claude.ai ou rate limits para seus produtos, incluindo agentes construídos no Claude Agent SDK. Em vez disso, use os métodos de autenticação de chave de API descritos neste documento.

Criar um arquivo com bugs

Este início rápido o orienta na construção de um agente que pode encontrar e corrigir bugs no código. Primeiro, você precisa de um arquivo com alguns bugs intencionais para o agente corrigir. Crie utils.py no diretório my-agent e cole o seguinte código:
Este código tem dois bugs:
  1. calculate_average([]) falha com divisão por zero
  2. get_user_name(None) falha com um TypeError

Construir um agente que encontra e corrige bugs

Crie agent.py se estiver usando o SDK Python, ou agent.ts para TypeScript. Use agent.mts em vez disso se seu projeto existente usar CommonJS:
Este código tem três partes principais:
  1. query: o ponto de entrada principal que cria o loop agentic. Ele retorna um iterador assíncrono, então você usa async for para transmitir mensagens enquanto Claude trabalha. Veja a API completa na referência do SDK Python ou TypeScript.
  2. prompt: o que você quer que Claude faça. Claude descobre quais ferramentas usar com base na tarefa.
  3. options: configuração para o agente. Este exemplo usa allowedTools para pré-aprovar Read, Edit e Glob, e permissionMode: "acceptEdits" para auto-aprovar alterações de arquivo. Outras opções incluem systemPrompt, mcpServers e muito mais. Veja todas as opções para Python ou TypeScript.
O loop async for continua executando enquanto Claude pensa, chama ferramentas, observa resultados e decide o que fazer a seguir. Cada iteração produz uma mensagem: o raciocínio de Claude, uma chamada de ferramenta, um resultado de ferramenta ou o resultado final. O SDK lida com a orquestração, execução de ferramentas, gerenciamento de contexto e tentativas, para que você apenas consuma o fluxo. O loop termina quando Claude conclui a tarefa ou encontra um erro. O tratamento de mensagens dentro do loop filtra a saída legível por humanos. Sem filtragem, você veria objetos de mensagem brutos, incluindo inicialização do sistema e estado interno, o que é útil para depuração, mas barulhento caso contrário.
Este exemplo usa streaming para mostrar o progresso em tempo real. Se você não precisar de saída ao vivo (por exemplo, para trabalhos em segundo plano ou pipelines de CI), você pode coletar todas as mensagens de uma vez. Veja Streaming vs. modo de turno único para detalhes.

Execute seu agente

Seu agente está pronto. Execute-o com o seguinte comando:
Se você nomeou seu script como agent.mts, execute npx tsx agent.mts em vez disso.
Conforme funciona, o agente imprime seu raciocínio e cada ferramenta que chama, terminando com Done: success. Após executar, verifique utils.py. Você verá código defensivo tratando listas vazias e usuários nulos. Seu agente autonomamente:
  1. Leu utils.py para entender o código
  2. Analisou a lógica e identificou casos extremos que causariam falhas
  3. Editou o arquivo para adicionar tratamento de erros apropriado
Isto é o que torna o Agent SDK diferente: Claude executa ferramentas diretamente em vez de pedir que você as implemente.
Se você vir um erro de autenticação como Not logged in ou Invalid API key, certifique-se de que definiu a variável de ambiente ANTHROPIC_API_KEY no shell onde você executa seu agente. O SDK não carrega arquivos .env automaticamente.Para as causas e correções por trás desses e outros erros de autenticação, veja Erros de autenticação na referência de Erro.

Tente outros prompts

Agora que seu agente está configurado, tente alguns prompts diferentes:
  • "Add docstrings to all functions in utils.py"
  • "Add type hints to all functions in utils.py"
  • "Create a README.md documenting the functions in utils.py"

Personalize seu agente

Você pode modificar o comportamento do seu agente alterando as opções. Aqui estão alguns exemplos: Adicionar capacidade de busca na web:
Dê a Claude um prompt de sistema personalizado:
Execute comandos no terminal:
Com Bash ativado, tente: "Write unit tests for utils.py, run them, and fix any failures" Cada um desses trechos define campos no mesmo objeto de opções. Para mais informações, veja Configure seu agente.

Conceitos-chave

Ferramentas controlam o que seu agente pode fazer: Modos de permissão controlam quanto de supervisão humana você deseja. O SDK avalia o modo ativo junto com suas regras de permissão e negação em uma ordem fixa, descrita em Como as permissões são avaliadas. Para a lista completa de modos, seu comportamento e quando usar cada um, veja Modo de permissão em Como o loop do agente funciona.

Próximos passos

Agora que você criou seu primeiro agente, aprenda como estender suas capacidades e adaptá-lo ao seu caso de uso:
  • Configure seu agente: componha o objeto de opções e encontre a página que cobre cada configuração
  • Permissões: controle o que seu agente pode fazer e quando precisa de aprovação
  • Hooks: execute código personalizado antes ou depois de chamadas de ferramenta
  • Sessões: construa agentes multi-turno que mantêm contexto
  • Servidores MCP: conecte-se a bancos de dados, navegadores, APIs e outros sistemas externos
  • Hospedagem: implante agentes no Docker, nuvem e CI/CD
  • Agentes de exemplo: veja exemplos completos: assistente de email, agente de pesquisa e muito mais
  • Troubleshooting: corrija erros quando a CLI falha ao iniciar ou sair, ou um resultado chega sem saída estruturada