SDK de agente

Guia de 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

Instalar Claude Code
O Agent SDK usa Claude Code como seu tempo de execução. Instale-o para sua plataforma:
Após instalar Claude Code em sua máquina, execute claude em seu terminal e siga os prompts para autenticar. O SDK usará essa autenticação automaticamente.
Para mais informações sobre a instalação do Claude Code, consulte configuração do Claude Code.
Criar uma pasta de projeto
Crie um novo diretório para este guia de 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:
Definir sua chave de API
Se você já autenticou Claude Code (executando claude em seu terminal), o SDK usa essa autenticação automaticamente.
Caso contrário, você precisa de uma chave de API, que pode obter no Console Anthropic.
Crie um arquivo .env em seu diretório de projeto e armazene a chave de API lá:
ANTHROPIC_API_KEY=your-api-key
Usando Amazon Bedrock, Google Vertex AI ou Microsoft Azure? Consulte os guias de configuração para Bedrock, Vertex AI ou Azure AI Foundry.
A menos que previamente aprovado, não permitimos 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 guia de 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 zero
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:

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ê usa async for para transmitir mensagens enquanto Claude trabalha. Consulte 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 usa allowedTools para restringir Claude a Read, Edit e Glob, e permissionMode: "acceptEdits" para aprovar automaticamente alterações de arquivo. Outras opções incluem systemPrompt, mcpServers e muito mais. Consulte todas as opções para Python ou .

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. Consulte Streaming vs. modo de turno único para detalhes.

Executar seu agente

Seu agente está pronto. Execute-o com o seguinte comando:

python3 agent.py

Após executar, verifique utils.py. Você verá código defensivo tratando listas vazias e usuários nulos. Seu agente autonomamente:

Leu utils.py para entender o código
Analisou a lógica e identificou casos extremos que causariam falhas
Editou o arquivo para adicionar tratamento de erros adequado

Isto é o que torna o Agent SDK diferente: Claude executa ferramentas diretamente em vez de pedir que você as implemente.

Se você vir "Claude Code not found", instale Claude Code e reinicie seu terminal. Para "API key not found", defina sua chave de API. Consulte 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"

Personalizar 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"
)

Dar 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."
)

Executar comandos no terminal:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="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`	Aprova automaticamente edições de arquivo, pede outras ações	Fluxos de trabalho de desenvolvimento confiáveis
`bypassPermissions`	Executa sem prompts	Pipelines de CI/CD, automação
`default`	Requer um callback `canUseTool` para lidar com aprovação	Fluxos de aprovação personalizados

O exemplo acima usa o modo acceptEdits, que aprova automaticamente operações de arquivo para que o agente possa ser executado sem prompts interativos. Se você quiser solicitar aprovação aos usuários, use o modo default e forneça um callback canUseTool que coleta entrada do usuário. Para mais controle, consulte Permissões.

Próximas etapas

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

SDK de agente

Guia de 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

Instalar Claude Code
O Agent SDK usa Claude Code como seu tempo de execução. Instale-o para sua plataforma:
Após instalar Claude Code em sua máquina, execute claude em seu terminal e siga os prompts para autenticar. O SDK usará essa autenticação automaticamente.
Para mais informações sobre a instalação do Claude Code, consulte configuração do Claude Code.
Criar uma pasta de projeto
Crie um novo diretório para este guia de 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:
Definir sua chave de API
Se você já autenticou Claude Code (executando claude em seu terminal), o SDK usa essa autenticação automaticamente.
Caso contrário, você precisa de uma chave de API, que pode obter no Console Anthropic.
Crie um arquivo .env em seu diretório de projeto e armazene a chave de API lá:
ANTHROPIC_API_KEY=your-api-key
Usando Amazon Bedrock, Google Vertex AI ou Microsoft Azure? Consulte os guias de configuração para Bedrock, Vertex AI ou Azure AI Foundry.
A menos que previamente aprovado, não permitimos 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

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 zero
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:

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ê usa async for para transmitir mensagens enquanto Claude trabalha. Consulte 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 usa allowedTools para restringir Claude a Read, Edit e Glob, e permissionMode: "acceptEdits" para aprovar automaticamente alterações de arquivo. Outras opções incluem systemPrompt, mcpServers e muito mais. Consulte todas as opções para Python ou .

Executar seu agente

Seu agente está pronto. Execute-o com o seguinte comando:

python3 agent.py

Após executar, verifique utils.py. Você verá código defensivo tratando listas vazias e usuários nulos. Seu agente autonomamente:

Leu utils.py para entender o código
Analisou a lógica e identificou casos extremos que causariam falhas
Editou o arquivo para adicionar tratamento de erros adequado

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"

Personalizar 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"
)

Dar 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."
)

Executar comandos no terminal:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="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`	Aprova automaticamente edições de arquivo, pede outras ações	Fluxos de trabalho de desenvolvimento confiáveis
`bypassPermissions`	Executa sem prompts	Pipelines de CI/CD, automação
`default`	Requer um callback `canUseTool` para lidar com aprovação	Fluxos de aprovação personalizados

Próximas etapas

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