Claude Code Agent SDK: O guia completo para desenvolvedores (2026)

O Agent SDK da Anthropic transforma o Claude Code de um assistente de terminal em um agente de IA programável e automatizável que você pode incorporar aos seus próprios fluxos de trabalho. Este guia cobre tudo: instalação, o ciclo do agente, integração de ferramentas, servidores MCP, orquestração de subagentes e as lacunas de capacidade que você precisa preencher para uso em produção.

O que é o Claude Code Agent SDK?

O Claude Code Agent SDK também chamado de Claude Agent SDK ou Claude Code SDK é a biblioteca Python e TypeScript da Anthropic para construir agentes de IA autônomos movidos por Claude. Ele encapsula o mesmo ciclo do agente, o sistema de ferramentas e o ambiente de execução em sandbox que alimentam o Claude Code como CLI, tornando isso disponível como um SDK que você pode chamar do seu próprio código.

O SDK foi lançado no início de 2026 como parte do esforço da Anthropic para tornar agentes de IA programáveis, e não apenas interativos.

O que o torna diferente de usar a API do Claude diretamente

Se você hoje usa a API do Claude e escreve seu próprio ciclo de agente com tratamento manual de ferramentas, o Agent SDK substitui centenas de linhas de boilerplate.

Instalação e configuração

Pré-requisitos

• Python 3.10+ ou TypeScript/Node.js 20+
• Chave de API da Anthropic ou assinatura Claude Code Pro/Max/Enterprise
• Claude Code CLI instalado, porque o SDK o usa como runtime

Passo 1: Instalar o Claude Code CLI

npm install -g @anthropic-ai/claude-code

Ou use o instalador nativo em claude.ai/download.

Passo 2: Instalar o Agent SDK

Python:

pip install claude-agent-sdk

TypeScript:

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

Passo 3: Autenticar

claude login

Siga o fluxo OAuth. Sua chave de API fica salva localmente e é usada automaticamente pelo SDK.

Seu primeiro agente: caçador de bugs

Aqui está um agente Python mínimo que varre um diretório em busca de bugs:

from claude_agent_sdk import Agent, tool

@tool
def read_file(path: str) -> str:
    """Ler um arquivo e retornar seu conteúdo."""
    with open(path, 'r') as f:
        return f.read()

@tool  
def list_files(directory: str = ".") -> list:
    """Listar todos os arquivos em um diretório."""
    import os
    return os.listdir(directory)

agent = Agent(
    system_prompt="Você é um revisor de código. Encontre bugs e sugira correções.",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("Revise o código em ./src em busca de problemas de segurança")
print(result.output)

O que acontece por baixo dos panos

1. O agente recebe a tarefa e lê seu prompt de sistema
2. Ele chama list_files("./src") para descobrir a base de código
3. Ele chama read_file(path) para cada arquivo de origem
4. Ele analisa o código usando o raciocínio do Claude
5. Ele retorna descobertas com números de linha e sugestões de correção

O SDK cuida de todo o ciclo — você não precisa escrever a lógica de planejar-agir-observar.

Conceitos principais

O ciclo do agente

Tarefa → Planejar → Chamada de ferramenta → Observar resultado → Replanejar → ... → Resposta final

Em cada iteração:

1. O Claude decide o que fazer a seguir
2. Ele chama ferramentas conforme necessário
3. Ele recebe a saída das ferramentas
4. Ele decide se continua ou termina

O SDK gerencia automaticamente os limites da janela de contexto por meio de compactação, ou seja, resumindo turnos antigos, e delegação a subagentes.

Ferramentas e o decorador tool

Ferramentas são funções que você expõe ao agente. O SDK fornece várias ferramentas embutidas:

# Operações de arquivo embutidas, disponíveis automaticamente
agent = Agent(
    tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)

Ferramentas personalizadas usam o decorador @tool:

from claude_agent_sdk import tool

@tool
def search_docs(query: str, max_results: int = 5) -> str:
    """Pesquisar documentação interna para uma consulta específica."""
    # Sua implementação de busca
    return results

agent = Agent(tools=[search_docs])

Subagentes: processamento em paralelo

Os subagentes permitem que você crie instâncias independentes do Claude para trabalho paralelo:

agent = Agent(
    system_prompt="Você é um tech lead revisando uma base de código.",
    tools=["task"]  # habilita a criação de subagentes
)

result = agent.run("""
    Revise ./frontend/ e ./backend/ em paralelo.
    Use subagentes para cada diretório e depois combine os achados.
""")

Subagentes executam em contextos isolados e retornam resultados independentemente. É assim que o próprio Claude Code lida com operações em grande escala.

Integração com servidor MCP

O SDK oferece suporte a servidores Model Context Protocol, ou seja, serviços externos que expõem ferramentas ao seu agente:

agent = Agent(
    mcp_servers=[
        {
            "command": "npx",
            "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
            "env": {"ALLOWED_DIRECTORIES": "/project"}
        }
    ]
)

Servidores MCP podem adicionar acesso a banco de dados, integrações de API, serviços de terceiros e muito mais.

O que o Agent SDK não consegue fazer e como preencher as lacunas

O Claude Code Agent SDK dá aos seus agentes acesso a arquivos, execução de shell e manipulação de código. Mas ele tem cinco grandes lacunas de capacidade:

1. Geração de imagens

Seu agente pode escrever código que chama APIs de imagem, mas não consegue gerar nem ver imagens diretamente. Para um agente que constrói UI, prototipa design ou cria documentação, isso é uma limitação real.

Solução: Dê ao seu agente um runtime de capacidades que cuide da geração de imagens. Com uma única linha de configuração, seu agente pode gerar imagens a partir de texto, iterar em designs e incorporar os resultados.

2. Geração de vídeo

Vídeo está ainda mais fora de alcance. Seu agente pode escrever comandos ffmpeg, mas não consegue gerar novo conteúdo de vídeo.

3. Busca na web com resultados fundamentados

Os agentes Claude Code podem usar curl ou APIs fetch, mas não conseguem fazer busca semântica na web com resultados fundamentados e citados. Isso importa para agentes de pesquisa, agentes de conteúdo e qualquer fluxo de trabalho que precise de informação atualizada.

4. Armazenamento em nuvem e compartilhamento de arquivos

O acesso ao sistema de arquivos do SDK é apenas local. Para agentes que precisam armazenar saídas, compartilhar arquivos com humanos ou manter dados entre sessões, você precisa de armazenamento em nuvem.

5. Publicação e deployment

Seu agente cria o artefato, mas colocá-lo online — uma página web, um relatório compartilhável ou um app implantado — exige infraestrutura separada.

A correção em um comando

Em vez de configurar cinco servidores MCP separados, cada um com sua própria chave de API, esforço de manutenção e overhead de tokens, você pode usar um runtime de capacidades — uma única ferramenta CLI que reúne geração de imagens, vídeo, busca na web, armazenamento em nuvem e publicação atrás de um único endpoint.

Por exemplo, a AnyCap dá aos agentes cinco capacidades em uma única CLI — geração de imagens, vídeo, busca na web, armazenamento em nuvem e publicação de páginas — para que você gaste minutos configurando, e não horas.

Considerações de produção

Gerenciamento da janela de contexto

O Agent SDK lida automaticamente com a compactação de contexto, mas para agentes de longa duração, com mais de 100 turnos, você deve:

• Usar subagentes para tarefas paralelas grandes em vez de processamento sequencial
• Manter prompts de sistema concisos — cada token no prompt de sistema é overhead em cada turno
• Evitar carregar arquivos grandes para o contexto quando as ferramentas puderem retornar resumos

Controle de custos

Uma sessão típica de agente com o SDK custa de US$ 0,50 a US$ 3,00, dependendo da complexidade da tarefa. Para controlar custos:

• Defina max_turns para evitar loops sem fim
• Use Haiku para subagentes simples e Sonnet para o agente principal
• Monitore o uso pelo painel da console da Anthropic

Segurança

O SDK executa comandos em sandbox, mas você ainda deve:

• Restringir o acesso ao sistema de arquivos com ALLOWED_DIRECTORIES
• Nunca dar a agentes de produção acesso a credenciais ou arquivos .env
• Revisar as ações do agente em modo não interativo

Claude Code SDK vs Claude Agent SDK: qual é a diferença?

Esses termos são frequentemente usados de forma intercambiável, mas existe uma distinção:

Na prática, a maioria dos desenvolvedores usa o Agent SDK como ponto de entrada. As APIs de nível mais baixo são para casos avançados, como gerenciamento de sessão personalizado.

Quando usar o Agent SDK em vez do Claude Code CLI

A regra prática é simples: se você está digitando comandos, use a CLI. Se você está escrevendo código que precisa chamar o Claude, use o SDK.

Resumo

O Claude Code Agent SDK transforma o Claude de um companheiro de terminal em um runtime de agente programável. Com operações de arquivo embutidas, acesso a shell, orquestração de subagentes e suporte a servidor MCP, ele assume o trabalho pesado da infraestrutura de agentes.

Mas um agente que só consegue ler arquivos e rodar bash é apenas meio agente. Para construir agentes que pesquisem na web, gerem imagens e vídeo, armazenem saídas na nuvem e publiquem resultados, você precisa de uma camada de capacidade. O SDK dá ao seu agente o cérebro; um runtime de capacidade como o AnyCap dá olhos, mãos e voz.