Pular para o conteúdo principal
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

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.
O SDK TypeScript agrupa um binário nativo Claude Code para sua plataforma como uma dependência opcional, portanto você não precisa instalar Claude Code separadamente.
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 Azure: 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 limites de taxa para seus produtos, incluindo agentes construídos no Agent SDK Claude. 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, 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 “API key not found”, 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. Veja o guia completo de solução de problemas para mais ajuda.

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"

Conceitos-chave

Ferramentas controlam o que seu agente pode fazer: Modos de permissão controlam quanto de supervisão humana você deseja: O exemplo acima usa o modo acceptEdits, que auto-aprova operações de arquivo para que o agente possa executar sem prompts interativos. Se você quiser solicitar aprovação dos usuários, use o modo default e forneça um callback canUseTool que coleta entrada do usuário. Para mais controle, veja Permissões.

Próximos passos

Agora que você criou seu primeiro agente, aprenda como estender suas capacidades e adaptá-lo ao seu caso de uso:
  • 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