O que é o Claude Agent SDK? Guia completo para criar agentes de IA

"Não seria ótimo dar uma instrução para a IA e ela pensar e trabalhar sozinha?" É exatamente isso que os agentes de IA tornam possível. O Claude Agent SDK da Anthropic é um framework que permite criar agentes de IA alimentados pelo Claude usando Python ou TypeScript. É a mesma tecnologia que opera nos bastidores do Claude Code, a CLI oficial da Anthropic.

Neste artigo, apresentamos o Claude Agent SDK de forma abrangente: dos conceitos fundamentais à implementação e casos de uso práticos.

O que é um agente de IA?

Os agentes de IA são fundamentalmente diferentes da IA tradicional de "pergunta e resposta". Sua principal característica é a capacidade de decompor tarefas de forma autônoma, usar ferramentas, avaliar resultados e decidir o próximo passo.

Por exemplo, se você pedir a um agente para "corrigir o bug em auth.py", ele seguirá estas etapas:

1. Ler o arquivo para entender o código
2. Buscar arquivos relacionados para compreender o contexto geral
3. Identificar a causa raiz do bug
4. Aplicar a correção
5. Executar os testes para verificar a solução
6. Relatar os resultados

O agente conduz todo esse fluxo por conta própria, sem intervenção humana a cada etapa. Esse é o verdadeiro poder dos agentes.

Visão geral do Claude Agent SDK

O Claude Agent SDK é o framework oficial de desenvolvimento de agentes da Anthropic. Ele dá acesso programático ao mesmo motor que alimenta o Claude Code.

Suas principais características são:

Dos três modos do Claude — Chat, Cowork e Code, o Agent SDK é a tecnologia por trás do Claude Code (o modo Code).

Como funciona o loop do agente

O coração do Agent SDK é o loop do agente — um ciclo automatizado onde o Claude pensa, usa ferramentas, verifica resultados e pensa novamente.

O fluxo passo a passo é o seguinte:

1. Receber o prompt: a instrução do usuário é enviada ao Claude
2. Claude raciocina: analisa a instrução e determina as ações necessárias
3. Executar ferramentas: ferramentas como Bash, Edit e Read são chamadas para realizar o trabalho
4. Processar resultados: a saída das ferramentas é devolvida ao Claude
5. Continuar ou finalizar: se ainda há trabalho pendente, volta ao passo 2. Caso contrário, retorna uma resposta de texto

O ponto-chave é que o loop termina quando não há mais chamadas de ferramentas. Quando o Claude determina que não precisa mais de nenhuma ferramenta, ele retorna a resposta final em texto.

Primeiros passos: instalação e código básico

Instalação

O SDK está disponível para Python e TypeScript.

# Python
pip install claude-agent-sdk

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

Agente mínimo (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Find and fix the bug in src/auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            print(f"Cost: ${message.total_cost_usd:.4f}")

asyncio.run(main())

Agente mínimo (TypeScript)

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

for await (const message of query({
  prompt: "Find and fix the bug in src/auth.py",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Com apenas esse código, você já tem um agente que lê arquivos, procura bugs, aplica correções e reporta resultados de forma completamente autônoma.

Ferramentas integradas

O Agent SDK inclui um amplo conjunto de ferramentas prontas para uso, sem necessidade de escrever código adicional.

Basta especificar as ferramentas a habilitar com allowed_tools e elas estarão prontas. Não é preciso escrever o código de tratamento das ferramentas por conta própria.

Como criar ferramentas personalizadas

Quando as ferramentas integradas não são suficientes, você pode criar as suas. Vamos construir uma ferramenta personalizada que se conecta a uma API de clima.

Python

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "Get the current weather for a given city",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # In practice, call an actual API
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"Weather in {city}: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

TypeScript

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

const getWeather = tool(
  "get_weather",
  "Get the current weather for a given city",
  { city: z.string().describe("City name") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `Weather in ${args.city}: ${data}` }]
    };
  }
);

As ferramentas personalizadas são criadas como servidores MCP e conectadas ao agente. Quando ocorrem erros, retorne isError: true em vez de lançar uma exceção. Assim o loop do agente continua funcionando e o Claude pode tentar novamente ou adotar uma abordagem diferente.

Processamento paralelo com subagentes

Para tarefas grandes, dividir o trabalho entre subagentes e executá-los em paralelo é muito mais eficiente. Os subagentes lidam com tarefas especializadas sem poluir o contexto (memória) do agente principal.

Quando usar subagentes

• Suítes de testes extensas: mesmo que os logs de teste sejam enormes, eles não afetam o contexto do agente principal
• Pesquisa paralela: investigar vários módulos simultaneamente e coletar os resultados
• Separar trabalhos especializados: atribuir "revisão de código" e "execução de testes" a agentes diferentes

Subagentes personalizados no Claude Code

No Claude Code (CLI), você pode definir subagentes personalizados simplesmente colocando arquivos Markdown no diretório .claude/agents/.

# .claude/agents/reviewer.md
---
name: code-reviewer
description: A sub-agent specialized in code review
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer.
Review code for quality, security,
and best practices.

Ao limitar o acesso a ferramentas (neste exemplo, apenas leitura), você evita que o revisor modifique o código acidentalmente.

Agent SDK vs Client SDK vs Claude Code

O Claude oferece três interfaces para desenvolvedores. Cada uma tem pontos fortes distintos, então escolha de acordo com suas necessidades.

Guia rápido de decisão:

• Trabalho de desenvolvimento diário → Claude Code CLI
• Construir sistemas automatizados → Agent SDK
• Criar seu próprio app com IA → Client SDK

Casos de uso práticos

Automação do desenvolvimento de código

Este é o caso de uso mais comum. Diga ao agente "implemente esta funcionalidade" e ele explorará a estrutura de arquivos, escreverá o código e executará os testes.

# Automated bug fixing
async for msg in query(
    prompt="The auth module tests are failing. Investigate and fix the issue",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # Cost cap: $2
    ),
):
    pass

Integração em pipelines CI/CD

Integre com GitHub Actions ou ferramentas similares para criar fluxos de trabalho que revisem automaticamente o código a cada PR ou tentem correções automáticas quando os testes falharem.

Análise de dados e pesquisa

Tarefas de pesquisa com múltiplas etapas, como "analisar os padrões de erro nos logs do último mês", podem ser delegadas a um agente. Combine com a ferramenta WebSearch para obter também informações atualizadas.

Melhores práticas

1. Defina sempre controles de custos

Como os agentes trabalham em loop, podem consumir mais tokens do que o esperado. Configure sempre max_budget_usd e max_turns.

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # Stop at $5
    max_turns=30,           # Stop after 30 turns
    effort="medium",        # Reasoning depth (low/medium/high/max)
)

2. Use apenas as ferramentas necessárias

Habilitar ferramentas desnecessárias desperdiça espaço na janela de contexto. Conceda apenas as ferramentas que a tarefa realmente precisa através de allowed_tools.

3. Use isError para tratamento de erros

Se uma ferramenta personalizada lança uma exceção, o loop inteiro do agente para. Retorne isError: true em vez disso, e o Claude tentará se recuperar.

4. Delegue tarefas pesadas para subagentes

Atribua tarefas com saídas volumosas, como execução de testes ou análise de logs, a subagentes. Isso evita que o contexto do agente principal fique sobrecarregado.

5. Seja específico nos seus prompts

Em vez de "melhore o código", diga "adicione limitação de taxa à função de login em auth.py e escreva testes para isso". Instruções específicas geram resultados muito mais eficientes.

Resumo

O Claude Agent SDK reduz drasticamente a barreira para criar agentes de IA. Com o mesmo motor que alimenta o Claude Code, ele permite construir agentes autônomos que executam tarefas em Python ou TypeScript.

Uma boa abordagem é começar usando o Claude Code de forma interativa para experimentar como os agentes funcionam, e depois migrar para o Agent SDK quando precisar de automação — uma transição gradual e natural.

Para mais informações sobre os conceitos básicos do Claude, confira também Comparação das três abas do Claude: Chat, Cowork e Code.