- Configurar um projeto com o Agent SDK
- Criar um arquivo com código com bugs
- Executar um agente que encontra e corrige os bugs automaticamente
Pré-requisitos
- Node.js 18+ ou Python 3.10+
- Uma conta Anthropic (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
- TypeScript (novo projeto)
- TypeScript (projeto existente)
- Python (uv)
- Python (pip)
"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
- macOS / Linux
- Windows (PowerShell)
.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=1e configure as credenciais AWS - Claude Platform on AWS: defina
CLAUDE_CODE_USE_ANTHROPIC_AWS=1eANTHROPIC_AWS_WORKSPACE_ID, depois configure as credenciais AWS - Google Cloud’s Agent Platform: defina a variável de ambiente
CLAUDE_CODE_USE_VERTEX=1e configure as credenciais Google Cloud - Microsoft Azure: defina a variável de ambiente
CLAUDE_CODE_USE_FOUNDRY=1e configure as credenciais Azure
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. Crieutils.py no diretório my-agent e cole o seguinte código:
calculate_average([])falha com divisão por zeroget_user_name(None)falha com um TypeError
Construir um agente que encontra e corrige bugs
Crieagent.py se estiver usando o SDK Python, ou agent.ts para TypeScript. Use agent.mts em vez disso se seu projeto existente usar CommonJS:
-
query: o ponto de entrada principal que cria o loop agentic. Ele retorna um iterador assíncrono, então você usaasync forpara transmitir mensagens enquanto Claude trabalha. Veja a API completa na referência do SDK Python ou TypeScript. -
prompt: o que você quer que Claude faça. Claude descobre quais ferramentas usar com base na tarefa. -
options: configuração para o agente. Este exemplo usaallowedToolspara pré-aprovarRead,EditeGlob, epermissionMode: "acceptEdits"para auto-aprovar alterações de arquivo. Outras opções incluemsystemPrompt,mcpServerse muito mais. Veja todas as opções para Python ou TypeScript.
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:- TypeScript
- Python (uv)
- Python (pip)
agent.mts, execute npx tsx agent.mts em vez disso.Done: success. Após executar, verifique utils.py. Você verá código defensivo tratando listas vazias e usuários nulos. Seu agente autonomamente:
- Leu
utils.pypara entender o código - Analisou a lógica e identificou casos extremos que causariam falhas
- Editou o arquivo para adicionar tratamento de erros apropriado
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: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