Construindo agentes de IA com o Claude Agent SDK: um guia pratico

O Claude Agent SDK oferece acesso programatico ao mesmo agent loop que alimenta o Claude Code. Seus agentes podem ler arquivos, executar comandos shell, pesquisar na web, editar codigo, chamar APIs externas atraves de servidores MCP e orquestrar sub-agentes - tudo com poucas linhas de TypeScript ou Python.

Diferentemente do Client SDK padrao da Anthropic, onde voce constroi seu proprio tool loop, o Agent SDK gerencia internamente a execucao de tools, o gerenciamento de contexto, os retries e a orquestracao. Voce descreve o que quer, fornece as ferramentas, e o agente cuida do resto.

Arquitetura

O SDK segue um loop simples: coletar contexto, agir, verificar, repetir.

O ponto de entrada principal e query(), que retorna um iterador assincrono que transmite mensagens em streaming enquanto o agente trabalha. Cada mensagem indica o que o agente esta fazendo: raciocinando, chamando um tool, recebendo um resultado ou entregando a saida final.

Primeiros passos

Instalacao

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Voce precisa de uma chave de API da Anthropic configurada como ANTHROPIC_API_KEY no seu ambiente.

Seu primeiro agente

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

So isso. O agente vai usar Glob para encontrar arquivos, Grep para buscar padroes TODO, Read para inspecionar as correspondencias e retornar um resumo estruturado. Voce nao escreve a logica de orquestracao - o SDK cuida disso.

Equivalente em Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Tools integrados

O SDK inclui os mesmos tools disponiveis no Claude Code:

Voce controla quais tools o agente pode usar atraves de allowedTools. Se um tool nao esta na lista, o agente nao pode chama-lo.

Modos de permissao

Como os agentes executam comandos reais em sistemas reais, as permissoes importam.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Para uso em producao, sempre execute agentes em ambientes sandbox (containers, VMs) e use o modo de permissao mais restritivo que ainda permita ao agente realizar seu trabalho.

Criando tools personalizados com MCP

O verdadeiro poder do SDK esta em estender os agentes com suas proprias ferramentas. Os tools personalizados sao definidos como servidores MCP in-process - sem gerenciamento de subprocessos, sem overhead de rede.

Exemplo: tool meteorologico

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Os tools personalizados seguem a convencao de nomenclatura mcp__{nome_servidor}__{nome_tool}. Voce pode usar curingas em allowedTools: "mcp__weather__*" habilita todos os tools do servidor meteorologico.

Exemplo: tool de consulta ao banco de dados

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Conectando servidores MCP externos

Alem dos tools in-process, voce pode se conectar a qualquer servidor MCP existente - os mesmos servidores que funcionam com Claude Desktop, Cursor e outros clientes MCP.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Voce pode combinar varios servidores MCP. O agente enxerga todos os tools de todos os servidores conectados e os utiliza conforme necessario.

Orquestracao multi-agente

Para workflows complexos, voce pode definir sub-agentes especializados aos quais o agente principal delega. Cada sub-agente tem seu proprio prompt, seus proprios tools e sua area de atuacao.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Inclua "Agent" nos allowedTools do pai para habilitar a delegacao. Os sub-agentes executam com seus proprios tools e nao podem acessar os do pai, a menos que isso seja explicitamente concedido.

Sessoes e continuidade

Os agentes podem manter o contexto entre multiplas consultas usando sessoes. Capture o session_id da primeira interacao e passe-o em resume para as consultas seguintes.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Se voce nao quer hospedar a infraestrutura dos agentes, os Claude Managed Agents (lancados em abril de 2026) oferecem um servico na nuvem totalmente gerenciado. A Anthropic cuida dos containers, do scaling e disponibiliza uma API em streaming.

A diferenca fundamental: com o Agent SDK, voce executa o agent loop na sua propria infraestrutura. Com os Managed Agents, a Anthropic hospeda e executa o agente por voce. Voce interage atraves de uma API baseada em sessoes e recebe eventos via Server-Sent Events.

Precos:

• Agent SDK: apenas as tarifas padrao por token da API do Claude. A hospedagem fica por sua conta.
• Managed Agents: tarifas por token mais US$ 0,08 por hora de sessao (cobrado por milissegundo).

Boas praticas para producao

1. Sempre use sandbox

Nunca execute agentes com permissoes ilimitadas em uma maquina de producao. Use containers (Docker, Fly.io, Modal) ou ambientes sandbox (E2B, Vercel Sandbox).

2. Limite o acesso aos tools

Siga o principio do menor privilegio. Um agente que gera relatorios nao precisa de Bash ou Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Use hooks como guardrails

Os hooks permitem interceptar chamadas a tools antes e depois da execucao. Use-os para logging, validacao e rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Trate erros adequadamente

O agent loop pode produzir erros - falhas de tools, limites de taxa da API, estouro da janela de contexto. Sempre verifique os tipos de mensagem.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Monitore o consumo de tokens

Os agent loops podem consumir uma quantidade significativa de tokens, especialmente com codebases grandes. O SDK inclui compactacao automatica de contexto, mas voce ainda deve monitorar o uso.

Conclusao

O Claude Agent SDK transforma um LLM de uma maquina de responder perguntas em algo mais proximo de um desenvolvedor junior. Seus agentes podem ler, escrever, executar, verificar e iterar - o mesmo workflow que um ser humano segue.

Comece pequeno: construa um agente com alguns tools integrados. Depois adicione tools MCP personalizados para o seu dominio especifico. Escale para a orquestracao multi-agente quando seus workflows exigirem especializacao.

O agent loop e o mesmo que alimenta o Claude Code. Se ele consegue criar software, seus agentes tambem conseguem.

Checklist para comecar:

• Instalar o SDK (npm install @anthropic-ai/claude-agent-sdk)
• Configurar ANTHROPIC_API_KEY no seu ambiente
• Construir um agente simples com os tools integrados (Read, Glob, Grep)
• Adicionar um tool personalizado via servidor MCP in-process
• Conectar um servidor MCP externo (GitHub, PostgreSQL, etc.)
• Implementar a orquestracao multi-agente com sub-agentes
• Configurar um ambiente sandbox para producao
• Adicionar hooks para logging e guardrails