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

O Agent SDK da Anthropic transforma o Claude Code de um assistente de terminal num agente de IA programável e automatizável que pode ser integrado nos 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 capacidades que precisa de colmatar para uso em produção.

O que é o Claude Code Agent SDK?

O Claude Code Agent SDK (também chamado Claude Agent SDK ou Claude Code SDK) é a biblioteca Python e TypeScript da Anthropic para criar agentes de IA autónomos alimentados por Claude. Envolve o mesmo ciclo do agente, o mesmo sistema de ferramentas e o mesmo ambiente de execução isolado que alimentam o Claude Code como CLI, disponibilizando-os como um SDK que pode chamar a partir 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 os agentes de IA programáveis, e não apenas interativos.

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

Se atualmente usa a API do Claude e escreve o seu próprio ciclo de agente com tratamento manual de ferramentas, o Agent SDK substitui centenas de linhas de código repetitivo.

Instalação e configuração

Pré-requisitos

• Python 3.10+ ou TypeScript/Node.js 20+
• Chave de API da Anthropic ou subscrição Claude Code Pro/Max/Enterprise
• Claude Code CLI instalado, porque o SDK usa-o 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. A sua chave de API é guardada localmente e usada automaticamente pelo SDK.

O seu primeiro agente: detetor de bugs

Aqui está um agente Python minimalista que analisa um diretório à procura de bugs:

from claude_agent_sdk import Agent, tool

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

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

agent = Agent(
    system_prompt="És um revisor de código. Encontra bugs e sugere correções.",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("Revê o código em ./src à procura de problemas de segurança")
print(result.output)

O que acontece por baixo do capô

1. O agente recebe a tarefa e lê o seu prompt do sistema
2. Chama list_files("./src") para descobrir a base de código
3. Chama read_file(path) para cada ficheiro fonte
4. Analisa o código usando o raciocínio do Claude
5. Devolve conclusões com números de linha e sugestões de correção

O SDK trata de todo o ciclo — não precisa de escrever a lógica planear-agir-observar.

Conceitos centrais

O ciclo do agente

Tarefa → Planear → Chamada de ferramenta → Observar resultado → Replanear → ... → Resposta final

Em cada iteração:

1. O Claude decide o que fazer a seguir
2. Chama ferramentas conforme necessário
3. Recebe os resultados das ferramentas
4. Decide se continua ou termina

O SDK gere automaticamente os limites da janela de contexto através de compactação, ou seja, sumarização de turnos antigos, e delegação a subagentes.

Ferramentas e o decorador tool

As ferramentas são funções que expõe ao agente. O SDK fornece várias ferramentas incorporadas:

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

As 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 dada."""
    # A sua implementação de pesquisa
    return results

agent = Agent(tools=[search_docs])

Subagentes: processamento em paralelo

Os subagentes permitem-lhe lançar instâncias independentes do Claude para trabalho em paralelo:

agent = Agent(
    system_prompt="És um tech lead a rever uma base de código.",
    tools=["task"]  # ativa o lançamento de subagentes
)

result = agent.run("""
    Revê ./frontend/ e ./backend/ em paralelo.
    Usa subagentes para cada diretório e depois combina os resultados.
""")

Os subagentes executam em contextos isolados e devolvem resultados de forma independente. É assim que o próprio Claude Code lida com operações em grande escala.

Integração com servidores MCP

O SDK suporta 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"}
        }
    ]
)

Os servidores MCP podem acrescentar acesso a bases de dados, integrações de API, serviços de terceiros e muito mais.

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

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

1. Geração de imagens

O 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 uma interface, prototipa um design ou cria documentação, isto é uma limitação real.

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

2. Geração de vídeo

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

3. Pesquisa na web com resultados fundamentados

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

4. Armazenamento na cloud e partilha de ficheiros

O acesso ao sistema de ficheiros do SDK é apenas local. Para agentes que precisam de guardar resultados, partilhar ficheiros com humanos ou manter dados entre sessões, precisa de armazenamento na cloud.

5. Publicação e deployment

O seu agente cria o artefacto, mas colocá-lo online — uma página web, um relatório partilhável ou uma aplicação implementada — requer infraestrutura separada.

A solução de um comando

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

Por exemplo, o AnyCap dá aos agentes cinco capacidades numa só CLI — geração de imagens, vídeo, pesquisa web, armazenamento na cloud e publicação de páginas — para que passe minutos a configurar, e não horas.

Considerações de produção

Gestão da janela de contexto

O Agent SDK trata automaticamente da compactação do contexto, mas para agentes de longa duração, com mais de 100 turnos, deve:

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

Controlo de custos

Uma sessão típica de agente com o SDK custa entre 0,50 e 3,00 dólares, dependendo da complexidade da tarefa. Para controlar custos:

• Defina max_turns para evitar ciclos sem fim
• Use Haiku para subagentes simples e Sonnet para o agente principal
• Monitorize o uso através do painel da consola Anthropic

Segurança

O SDK executa comandos numa sandbox, mas ainda assim deve:

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

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

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

Na prática, a maioria dos programadores usa o Agent SDK como ponto de entrada. As APIs do SDK de nível inferior destinam-se a casos avançados, como gestão personalizada de sessões.

Quando usar o Agent SDK em vez da Claude Code CLI

A regra prática é simples: se estiver a escrever comandos, use a CLI. Se estiver a escrever código que precisa de chamar o Claude, use o SDK.

Resumo

O Claude Code Agent SDK transforma o Claude de um companheiro de terminal num runtime de agente programável. Com operações de ficheiros incorporadas, acesso ao shell, orquestração de subagentes e suporte a servidores MCP, trata do trabalho pesado da infraestrutura de agentes.

Mas um agente que só consegue ler ficheiros e executar bash é apenas meio agente. Para construir agentes que pesquisem na web, gerem imagens e vídeo, guardem resultados na cloud e publiquem resultados, precisa de uma camada de capacidades. O SDK dá ao seu agente o cérebro; um runtime de capacidades como o AnyCap dá-lhe olhos, mãos e voz.