Introdução ao Claude Code Agent SDK — Construa agentes autônomos rapidamente

O que é o Agent SDK?

O Claude Code Agent SDK é um framework para construir agentes autônomos alimentados por modelos Claude. Diferente de simples chamadas de API, um agente recebe um objetivo, seleciona ferramentas por conta própria, avalia resultados e executa um loop de raciocínio multi-etapas para chegar a uma solução.

Chatbots tradicionais funcionam em um único ciclo de solicitação-resposta. Com o Agent SDK, você pode completar workflows complexos — ler arquivos, identificar problemas, aplicar correções, executar testes e reportar resultados — tudo a partir de uma única instrução.

Configuração

Inicialize seu projeto e instale o SDK.

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

Para desenvolvimento com TypeScript, adicione também as definições de tipos.

npm install typescript @types/node --save-dev
npx tsc --init

Configure a variável de ambiente ANTHROPIC_API_KEY e você está pronto.

export ANTHROPIC_API_KEY="sk-ant-..."

Um agente mínimo

Aqui está um agente simples que pode interagir com o sistema de arquivos.

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "Liste todos os comentários TODO no diretório src e ordene por prioridade"
  );
  console.log(result.text);
}

main();

O parâmetro maxTurns limita o número máximo de passos que o agente pode executar. Sempre configure-o como proteção contra loops infinitos.

Definindo ferramentas personalizadas

O verdadeiro poder do Agent SDK está nas ferramentas personalizadas. Ao dar ao agente acesso a APIs externas ou bancos de dados, você desbloqueia uma automação muito mais prática.

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "Buscar uma issue do GitHub",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "Proprietário do repositório" },
      repo: { type: "string", description: "Nome do repositório" },
      number: { type: "number", description: "Número da issue" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

Com essa definição, o agente chama fetch_github_issue quando necessário e decide sua próxima ação com base nas informações obtidas.

Como funciona a execução multi-etapas

Internamente, o Agent SDK executa o seguinte loop:

1. Planejamento — Decompor a instrução do usuário em passos necessários
2. Seleção de ferramenta — Escolher a ferramenta ideal entre as disponíveis
3. Execução — Executar a ferramenta e capturar resultados
4. Avaliação — Verificar se o objetivo foi alcançado
5. Repetir ou completar — Voltar ao passo 1 se incompleto, ou gerar a resposta final

Este loop elimina a necessidade de codificar cada procedimento antecipadamente, permitindo um processamento flexível que se adapta à situação.

Exemplo prático: Agente de revisão automática de PRs

Vamos construir um caso de uso real — um agente de revisão automática de Pull Requests.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `Você é um especialista em revisão de código.
Leia o diff do PR e revise considerando:
- Possíveis bugs
- Riscos de segurança
- Problemas de performance
- Sugestões de melhoria`,
});

const result = await agent.run(
  "Revise o PR #42 e deixe comentários se houver problemas"
);

Ao especificar o papel do agente e os critérios de avaliação no systemPrompt, você obtém revisões consistentes e confiáveis.

Tratamento de erros e retentativas

O tratamento robusto de erros é essencial em ambientes de produção.

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`Erro no passo ${context.turn}:`, error.message);
    if (context.turn >= 3) {
      return "abort"; // Abortar após 3 falhas
    }
    return "retry"; // Tentar novamente caso contrário
  },
});

Resumo e próximos passos

Com o Agent SDK, você pode automatizar tarefas complexas de múltiplas etapas em vez de depender de respostas de IA pontuais. Comece com tarefas pequenas como organização de arquivos ou análise de logs, e gradualmente adicione ferramentas para expandir as capacidades do seu agente.

Para os fundamentos do Claude Code, confira o Guia de início. Para desenvolvimento com APIs, veja o Guia de desenvolvimento de APIs. Para integração CLI, consulte Desenvolvimento de ferramentas CLI.

Para mais detalhes, visite a documentação oficial da Anthropic e o repositório GitHub do Claude Code.