O Claude Code Agent SDK dá-lhe um loop de agente programável. Essa é a boa notícia.
A notícia mais importante é aquilo que ele não lhe dá.
Não dá ao seu agente a camada de capacidades do mundo real de que a maioria dos fluxos de trabalho em produção precisa: pesquisa em tempo real, geração de imagens, geração de vídeo, armazenamento de artefactos e publicação. O SDK dá-lhe a camada de shell e orquestração. Se quiser um agente mais forte, continua a precisar do runtime por trás dele.
Esta distinção importa porque muitos guias de SDK ficam pelo “aqui está como lançar um agente”. As equipas de produção preocupam-se com a pergunta seguinte: será que esse agente consegue mesmo terminar o trabalho?
Este guia cobre ambos os lados: o que o Claude Code Agent SDK faz bem e onde entra um runtime de capacidades como o AnyCap quando precisa que o agente faça mais do que ler ficheiros e executar bash.
O que é o Claude Code Agent SDK?
O Claude Code Agent SDK é o toolkit em Python e TypeScript da Anthropic para incorporar comportamento de agente ao estilo Claude Code nas suas próprias aplicações.
Pense assim:
- Modelo Claude = raciocínio
- Agent SDK = loop de agente programável
- Runtime de capacidades = a camada de execução em falta para media, pesquisa, armazenamento e publicação
O SDK trata do trabalho central de orquestração que, de outra forma, teria de construir por si:
- planeamento e execução iterativa
- acesso e edição de ficheiros
- execução de shell
- chamadas de ferramentas
- integração com MCP
- padrões de subagentes
Isto já substitui muito código de ligação personalizado. Mas continua a ser apenas uma parte da stack de produção.
O que o torna diferente da API bruta do Claude
| Funcionalidade | Claude API | Claude Code Agent SDK |
|---|---|---|
| Loop do agente | Constrói você | Incluído |
| Acesso a ficheiros | Nenhum | Incluído |
| Execução de shell | Nenhuma | Incluída |
| Orquestração de ferramentas | Manual | Incluída |
| Suporte MCP | Manual | Incluído |
| Padrões de subagentes | Manual | Mais fácil de implementar |
Se está a construir um worker de revisão de código, uma automatização de CI ou um assistente de repositório, o SDK é uma grande melhoria face a montar o loop manualmente.
Mas continua a ser importante perceber o seu limite: não se transforma magicamente num runtime completo de capacidades só porque tem uma interface de ferramentas.
Instalação e configuração
Pré-requisitos
- Python 3.10+ ou Node.js 20+
- Chave de API da Anthropic ou acesso ao Claude Code
- Claude Code CLI instalada como superfície de runtime
Instalar o Claude Code CLI
npm install -g @anthropic-ai/claude-code
Instalar o Agent SDK
Python
pip install claude-agent-sdk
TypeScript
npm install @anthropic-ai/claude-agent-sdk
Autenticação
claude login
O seu primeiro agente
from claude_agent_sdk import Agent, tool
@tool
def read_file(path: str) -> str:
with open(path, "r") as f:
return f.read()
@tool
def list_files(directory: str = ".") -> list:
import os
return os.listdir(directory)
agent = Agent(
system_prompt="You are a careful code reviewer.",
tools=[read_file, list_files],
model="claude-sonnet-4-20250514"
)
result = agent.run("Review ./src for security issues")
print(result.output)
É aqui que o SDK brilha. Define ferramentas, passa uma tarefa e deixa o loop do agente tratar da exploração e da iteração.
Conceitos principais
1. O loop do agente
Tarefa → Plano → Chamada de ferramenta → Observação → Replanear → Resposta final
Este loop é o verdadeiro valor do SDK. Elimina a necessidade de ligar manualmente cada passo.
2. Subagentes
Os subagentes permitem decompor o trabalho em vez de enfiar tudo num único contexto longo.
agent = Agent(
system_prompt="You are a tech lead reviewing a codebase.",
tools=["task"]
)
Use-os para revisões paralelas de diretórios, investigações divididas e bases de código grandes.
3. Suporte MCP
O SDK pode comunicar com ferramentas compatíveis com MCP, o que é útil para APIs internas, bases de dados ou serviços especializados.
agent = Agent(
mcp_servers=[
{
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
"env": {"ALLOWED_DIRECTORIES": "/project"}
}
]
)
Mas այստեղ há uma nuance que muitos guias falham: MCP é a camada de protocolo, não a estratégia completa de capacidades. Se o seu agente precisa de uma superfície de ferramentas mais ampla e transversal, normalmente quer um runtime de capacidades, não cinco integrações pontuais sem relação entre si.
Considerações para produção
Controlo de custos
Use modelos de menor custo para trabalho rotineiro, defina max_turns e empurre trabalho paralelo amplo para subagentes em vez de uma sessão única e inchada.
Gestão de contexto
Mantenha os prompts enxutos, evite carregar ficheiros desnecessários e resuma resultados intermédios quando a sessão ficar longa.
Permissões
Restrinja o acesso a ficheiros e as integrações externas do agente ao âmbito mínimo necessário.
Erros comuns e como os corrigir
OverloadedError
Tente novamente com exponential backoff.
import time
from claude_agent_sdk import OverloadedError
def run_with_retry(agent, prompt, max_retries=3):
for attempt in range(max_retries):
try:
return agent.run(prompt)
except OverloadedError:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
ContextLengthExceededError
Divida o trabalho em subtarefas e use subagentes em vez de uma execução monolítica.
MaxTurnsReached
Aumente max_turns apenas se a tarefa estiver bem delimitada. Caso contrário, decomponha o fluxo de trabalho.
Erros de permissão
Expanda apenas os diretórios e integrações de que o seu agente realmente precisa.
O que o Agent SDK continua sem lhe dar
Esta é a parte mais importante para fluxos de trabalho em produção.
O Claude Code Agent SDK pode:
- ler e editar ficheiros
- executar comandos de shell
- orquestrar chamadas de ferramentas
- gerir loops iterativos de agente
Aquilo que não lhe dá por si só é a camada de capacidades em falta para:
- pesquisa na Web em tempo real
- geração de imagens
- geração de vídeo
- armazenamento na cloud e partilha
- publicação na Web
É por isso que muitas equipas acabam com agentes impressionantes em demos, mas incompletos na prática. O agente consegue raciocinar muito bem sobre uma página de lançamento, mas não consegue gerar a hero image, guardar os artefactos finais nem publicar o entregável sem infraestrutura extra.
Onde o AnyCap entra
Aqui, o AnyCap é melhor entendido como o runtime de capacidades através do qual o seu agente baseado em Claude pode executar.
A arquitetura fica mais limpa quando separa as camadas:
- Modelo Claude → pensa
- Claude Code Agent SDK → orquestra
- AnyCap CLI → executa capacidades transversais
- Skill AnyCap → ensina o agente a usar essa CLI de forma eficaz
Instalar o runtime de capacidades
curl -fsSL https://anycap.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
anycap login
Adicionar a camada de skill
npx -y skills add anycap-ai/anycap -a claude-code
Depois disso, o seu agente pode usar uma superfície consistente de capacidades para:
anycap search "latest competitor pricing"
anycap image generate "product hero image"
anycap video generate "10-second launch teaser"
anycap drive upload ./report.pdf
anycap page publish ./launch-brief.md
Essa é a diferença entre “construí um loop de agente” e “construí um agente que consegue realmente terminar trabalho”.
Quando usar o Agent SDK
Use o Agent SDK quando precisar de:
- um agente programático dentro do seu produto ou automatização
- um worker repetível de revisão de código
- um assistente de repositório dentro de CI/CD
- uma tarefa em segundo plano que precise de um loop iterativo de agente
Use um runtime de capacidades em conjunto quando o agente também precisar de pesquisar, gerar media, entregar ficheiros ou publicar resultados.
Conclusão
O Claude Code Agent SDK é poderoso porque resolve o problema da orquestração. Dá aos programadores uma versão programável do loop do Claude Code em vez de os obrigar a construir uma de raiz.
Mas continua a ser apenas a camada de shell e coordenação.
Se o seu agente precisa de interagir com o mundo real — pesquisar informação atual, gerar ativos criativos, guardar resultados, publicar entregas — também precisa da camada de capacidades em falta.
Este é o modelo mental que evita que as equipas sobrestimem aquilo que o SDK faz por si só.
O SDK torna o agente programável.
Um runtime de capacidades torna o agente útil para além do código.