Início Rápido
Comece com o Agent SDK Python ou TypeScript para construir agentes de IA que funcionam autonomamente
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á:
- 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
Criar uma pasta de projeto
Crie um novo diretório para este início rápido:
mkdir my-agent && cd my-agent
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.
Instalar o SDK
Instale o pacote Agent SDK para sua linguagem:
npm install @anthropic-ai/claude-agent-sdk
uv Python package manager é um gerenciador de pacotes Python rápido que lida com ambientes virtuais automaticamente:
uv init && uv add claude-agent-sdk
Crie um ambiente virtual primeiro, depois instale:
python3 -m venv .venv && source .venv/bin/activate
pip3 install claude-agent-sdk
Defina sua chave de API
Obtenha uma chave de API no Claude Console, depois crie um arquivo .env no diretório do seu projeto:
ANTHROPIC_API_KEY=your-api-key
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 - Google Vertex AI: 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
Consulte os guias de configuração para Bedrock, Vertex AI, ou Azure AI Foundry para detalhes.
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:
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()
Este código tem dois bugs:
calculate_average([])falha com divisão por zeroget_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:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
# Agentic loop: streams messages as Claude works
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # Tools Claude can use
permission_mode="acceptEdits", # Auto-approve file edits
),
):
# Print human-readable output
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # Tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # Final result
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Tools Claude can use
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}
Este código tem três partes principais:
-
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.
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.
Execute seu agente
Seu agente está pronto. Execute-o com o seguinte comando:
python3 agent.py
npx tsx agent.ts
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
Isto é o que torna o Agent SDK diferente: Claude executa ferramentas diretamente em vez de pedir que você as implemente.
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:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};
Dê a Claude um prompt de sistema personalizado:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};
Execute comandos no terminal:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};
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:
| Ferramentas | O que o agente pode fazer |
|---|---|
Read, Glob, Grep |
Análise somente leitura |
Read, Edit, Glob |
Analisar e modificar código |
Read, Edit, Bash, Glob, Grep |
Automação completa |
Modos de permissão controlam quanto de supervisão humana você deseja:
| Modo | Comportamento | Caso de uso |
|---|---|---|
acceptEdits |
Auto-aprova edições de arquivo e comandos comuns do sistema de arquivos, pede outras ações | Fluxos de trabalho de desenvolvimento confiáveis |
dontAsk |
Nega qualquer coisa não em allowedTools |
Agentes headless bloqueados |
auto (apenas TypeScript) |
Um classificador de modelo aprova ou nega cada chamada de ferramenta | Agentes autônomos com proteções de segurança |
bypassPermissions |
Executa cada ferramenta sem prompts | CI em sandbox, ambientes totalmente confiáveis |
default |
Requer um callback canUseTool para lidar com aprovação |
Fluxos de aprovação personalizados |
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.
Solução de problemas
Erro de API thinking.type.enabled não é suportado para este modelo
Claude Opus 4.7 substitui thinking.type.enabled por thinking.type.adaptive. Versões mais antigas do Agent SDK falham com o seguinte erro de API quando você seleciona claude-opus-4-7:
API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}
Atualize para Agent SDK v0.2.111 ou posterior para usar Opus 4.7.
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