Guia de Início Rápido

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 (inscreva-se aqui)

Configuração

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:

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 do 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())

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 restringir Claude a Read, Edit e Glob, e permissionMode: "acceptEdits" para aprovar automaticamente as 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 para 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 de outra forma.

Executar seu agente

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

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

Isso é 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"
)

Dar ao 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:

Modos de permissão controlam quanto de supervisão humana você deseja:

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