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 é uma biblioteca que permite criar agentes de IA alimentados pelo Claude usando Python ou TypeScript. Ele coloca nos seus próprios programas as mesmas ferramentas, o mesmo loop de agente e o mesmo gerenciamento de contexto que fazem o Claude Code, o agente de programação oficial da Anthropic, funcionar.

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 é a biblioteca oficial da Anthropic para criar agentes. A documentação oficial o descreve como uma biblioteca que executa o binário do Claude Code. Ou seja, a direção é o SDK aciona o Claude Code, e não o contrário. Os SDKs de Python e TypeScript já trazem esse binário, então na maioria dos ambientes não é preciso instalar o Claude Code separadamente.

Suas principais características são:

O Agent SDK serve para levar o agente que roda no Code (Claude Code) do Claude para os seus próprios aplicativos e scripts, fora dessa interface.

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

É preciso ter Node.js 18 ou superior, ou Python 3.10 ou superior (guia de início rápido oficial).

Autenticação: use uma chave de API (não o login do claude.ai)

O SDK funciona com a chave de API da variável de ambiente ANTHROPIC_API_KEY. Para usar via Amazon Bedrock, Google Cloud (a versão operada pelo Google) ou Microsoft Foundry, defina CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1 ou CLAUDE_CODE_USE_FOUNDRY=1 e configure as credenciais dessa nuvem. O SDK não carrega arquivos .env automaticamente, então defina a variável no shell onde o agente roda. A configuração e os preços do Claude no Google Cloud estão explicados em Claude no Vertex AI.

Atenção ao login do claude.ai (assinaturas Pro, Max e similares). Salvo aprovação prévia, a documentação oficial não permite que desenvolvedores terceiros ofereçam em seus produtos o login ou os limites de uso do claude.ai, incluindo agentes criados com o Agent SDK. Os aplicativos que você cria com o SDK devem se autenticar com uma chave de API.

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)
            if message.total_cost_usd is not None:
                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. Mas atenção: allowed_tools não é a lista de ferramentas que o Claude pode usar, e sim a lista de ferramentas aprovadas automaticamente, sem perguntar. Como este exemplo inclui Bash, os comandos de shell que o Claude escolher rodam sem confirmação (exceto algumas ações, como certas exclusões, que nenhuma configuração aprova automaticamente). Como este exemplo não define permission_mode, o modo vem de permissions.defaultMode nos seus arquivos de configuração ou, na falta dele, do padrão embutido, que desde a v2.1.285 era auto nas sessões que não buscam feature flags, como com um provedor de terceiros (Bedrock, Google Cloud, Microsoft Foundry) ou com a telemetria desativada (documentação oficial). Porém, a partir da v2.1.302 (16 de outubro de 2026), sessões do Agent SDK e de claude -p que não definem um modo de permissão começam em default, inclusive por meio de provedores de terceiros. Para usar o auto, é preciso defini-lo explicitamente (na CLI, --permission-mode auto; veja o histórico de atualizações, consultado em 18 de outubro de 2026). O modo auto descarta regras de permissão amplas como Bash; por isso, se você depende do comportamento acima, passe permission_mode="default" (TS: permissionMode: "default") explicitamente (documentação oficial). Teste em um diretório de trabalho que você não se importe de estragar. A próxima seção mostra como restringir de fato as ferramentas.

Ferramentas integradas

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

Você não precisa escrever código de tratamento para usar as ferramentas integradas. O ponto importante é que "quais ferramentas o Claude vê" e "quais ferramentas rodam sem perguntar" são configurações diferentes. Veja como a documentação oficial as descreve:

Por exemplo, combinar allowed_tools=["Read"] com permission_mode="bypassPermissions" aprova tudo, inclusive Bash, Write e Edit, que não estão na lista (a documentação oficial alerta expressamente sobre essa combinação). Para deixar uma ferramenta fora de alcance, remova-a com tools ou disallowed_tools. Para trabalhar só com um conjunto fixo, combine allowed_tools com permission_mode="dontAsk", que nega tudo o que, de outra forma, pediria confirmação.

Mais um detalhe: no macOS, no Linux e no WSL, Glob e Grep não fazem parte das ferramentas padrão (no Windows, fazem). Nesses sistemas o Claude busca com find e grep pelo Bash. Citar qualquer uma das duas em tools ou allowed_tools as traz de volta (referência oficial de ferramentas).

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 passadas ao agente com mcp_servers (TS: mcpServers). O nome completo de cada ferramenta passa a ser mcp__nome-do-servidor__nome-da-ferramenta; para que ela rode sem perguntar, inclua esse nome em allowed_tools:

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

Se a sua ferramenta lançar uma exceção, o loop do agente não para. O servidor MCP do SDK captura a exceção e entrega ao Claude a mensagem dela, sem alterações, como resultado de erro. Se você mesmo capturar o erro e retornar "is_error": True (TypeScript: isError: true), pode escrever a mensagem que o Claude lê: qual requisição falhou e o que tentar no lugar. Em ambos os casos o Claude pode tentar de novo, usar outra ferramenta ou explicar a falha (documentação oficial: ferramentas personalizadas).

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.

Permissões, hooks e sessões

Esses três recursos são os que mais pesam quando um agente vai para produção. A documentação oficial os inclui entre os recursos do Claude Code disponíveis no SDK.

Permissões: cada chamada é avaliada em uma ordem fixa

Quando o Claude solicita uma ferramenta, o SDK avalia hooks → regras de negação → regras de consulta → modo de permissão → regras de permissão → o callback can_use_tool, nessa ordem. Uma chamada que corresponde a uma regra de negação (vinda de disallowed_tools, por exemplo) é bloqueada mesmo no modo bypassPermissions. Uma exceção: um mod (um plugin cujos hooks são funções) também roda nas sessões do Agent SDK que o carregam (documentação oficial), e um mod que responde a tool.check pode aprovar uma chamada que uma regra de negação recusou, exceto em máquinas com configurações gerenciadas ou com login em um plano Team ou Enterprise (documentação oficial). Instale apenas mods de autores em quem você confia; veja mais em Mods do Claude Code. O modo é escolhido com permission_mode (segundo a documentação oficial em setembro de 2026):

Hooks: rode seu próprio código em momentos-chave

Hooks são callbacks disparados por eventos como antes de uma ferramenta rodar (PreToolUse), depois (PostToolUse) ou quando a execução para (Stop). Eles rodam antes da avaliação de permissões, então uma ação que você quer bloquear em qualquer modo deve ficar aqui. Este exemplo, resumido da documentação oficial, bloqueia a escrita em arquivos .env:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Sessões: retomar de onde parou ou ramificar

O SDK salva automaticamente em disco o histórico da conversa (prompts, chamadas de ferramentas, resultados e respostas) como uma sessão. Guarde o session_id da mensagem de resultado e passe-o para resume no próximo query(): o agente continua levando em conta os arquivos que já leu e as decisões que já tomou. Para retomar a sessão mais recente, use continue_conversation=True (TS: continue: true); para testar outra abordagem sem mexer na original, fork_session=True (TS: forkSession: true). As sessões guardam só a conversa; alterações em arquivos não são desfeitas (documentação oficial: sessões).

Além disso, as skills, os comandos e a memória em .claude/ do seu projeto e em ~/.claude/ são carregados automaticamente, como no Claude Code. Plugins, que reúnem skills, agentes, hooks e servidores MCP, podem ser carregados a partir de um caminho local.

Agent SDK vs Client SDK vs Claude Code

A comparação oficial lista quatro formas de construir com o Claude: Agent SDK, Claude Code CLI, Client SDK e Managed Agents. Vamos começar pelas três que você roda na sua própria máquina ou nos seus servidores.

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
• Delegar também a operação do loop e do sandbox → Managed Agents (um agente hospedado pela Anthropic que roda as sessões em um sandbox na nuvem gerenciado pela Anthropic ou em um sandbox próprio, usado pelo SDK da sua linguagem, pela CLI ant ou pela API REST)

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/xhigh/max)
)

xhigh é tratado como high nos modelos que não o suportam. Quando um limite encerra a execução, a mensagem de resultado final traz subtype igual a "error_max_budget_usd" para max_budget_usd ou "error_max_turns" para max_turns, e result fica vazio (None). Verifique subtype para saber por que o agente parou.

Lembre-se de que o valor é uma estimativa que o SDK calcula com uma tabela de preços embutida, não a sua fatura real. O orçamento conta apenas o gasto daquela chamada; o que já foi gasto em uma sessão retomada com resume não entra. Para valores exatos, use a página Usage do Claude Console ou a Usage and Cost API (documentação oficial: acompanhamento de custos).

2. Use apenas as ferramentas necessárias

Para que o Claude não veja ferramentas desnecessárias, liste apenas as que você precisa em tools ou remova-as pelo nome em disallowed_tools. allowed_tools só dispensa a confirmação; não reduz as ferramentas disponíveis. Mantenha também a lista de aprovação automática no mínimo que a tarefa exige.

3. Informe erros de ferramentas com is_error

Uma exceção em uma ferramenta personalizada não para o loop do agente: o SDK passa a mensagem da exceção ao Claude como resultado de erro. Mas uma mensagem de exceção crua nem sempre basta para o Claude decidir o próximo passo. Capture-a você mesmo e retorne "is_error": True (TypeScript: isError: true) com o que falhou e o que tentar no lugar, e o Claude se recupera com mais facilidade.

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.

Se você prefere não gerenciar por conta própria o loop, o sandbox e o estado, a alternativa totalmente gerenciada da Anthropic é o Claude Managed Agents.

Para mais informações sobre os conceitos básicos do Claude, confira também Chat, Cowork e Code do Claude.