Migrar para Claude Agent SDK
Guia para migrar os SDKs TypeScript e Python do Claude Code para o Claude Agent SDK
Visão Geral
O Claude Code SDK foi renomeado para o Claude Agent SDK e sua documentação foi reorganizada. Esta mudança reflete as capacidades mais amplas do SDK para construir agentes de IA além de apenas tarefas de codificação.
O Que Mudou
| Aspecto | Antigo | Novo |
|---|---|---|
| Nome do Pacote (TS/JS) | @anthropic-ai/claude-code |
@anthropic-ai/claude-agent-sdk |
| Pacote Python | claude-code-sdk |
claude-agent-sdk |
| Local da Documentação | Documentação do Claude Code | API Guide → Seção Agent SDK |
Etapas de Migração
Para Projetos TypeScript/JavaScript
1. Desinstale o pacote antigo:
npm uninstall @anthropic-ai/claude-code
2. Instale o novo pacote:
npm install @anthropic-ai/claude-agent-sdk
3. Atualize suas importações:
Altere todas as importações de @anthropic-ai/claude-code para @anthropic-ai/claude-agent-sdk:
// Antes
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";
// Depois
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
4. Atualize as dependências do package.json:
Se você tiver o pacote listado em seu package.json, atualize-o:
Antes:
{
"dependencies": {
"@anthropic-ai/claude-code": "^0.0.42"
}
}
Depois:
{
"dependencies": {
"@anthropic-ai/claude-agent-sdk": "^0.2.0"
}
}
Pronto! Nenhuma outra alteração de código é necessária.
Para Projetos Python
1. Desinstale o pacote antigo:
pip uninstall claude-code-sdk
2. Instale o novo pacote:
pip install claude-agent-sdk
3. Atualize suas importações:
Altere todas as importações de claude_code_sdk para claude_agent_sdk:
# Antes
from claude_code_sdk import query, ClaudeCodeOptions
# Depois
from claude_agent_sdk import query, ClaudeAgentOptions
4. Atualize os nomes dos tipos:
Altere ClaudeCodeOptions para ClaudeAgentOptions:
# Antes
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7")
# Depois
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7")
5. Revise mudanças significativas
Faça as alterações de código necessárias para concluir a migração.
Mudanças significativas
Python: ClaudeCodeOptions renomeado para ClaudeAgentOptions
O que mudou: O tipo ClaudeCodeOptions do SDK Python foi renomeado para ClaudeAgentOptions.
Migração:
# ANTES (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions
options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
# DEPOIS (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")
Por que isso mudou: O nome do tipo agora corresponde à marca "Claude Agent SDK" e fornece consistência nas convenções de nomenclatura do SDK.
Prompt do sistema não é mais padrão
O que mudou: O SDK não usa mais o prompt do sistema do Claude Code por padrão.
Migração:
// ANTES (v0.0.x) - Usava o prompt do sistema do Claude Code por padrão
const result = query({ prompt: "Hello" });
// DEPOIS (v0.1.0) - Usa prompt do sistema mínimo por padrão
// Para obter o comportamento antigo, solicite explicitamente a predefinição do Claude Code:
const result = query({
prompt: "Hello",
options: {
systemPrompt: { type: "preset", preset: "claude_code" }
}
});
// Ou use um prompt do sistema personalizado:
const result = query({
prompt: "Hello",
options: {
systemPrompt: "You are a helpful coding assistant"
}
});
# ANTES (v0.0.x) - Usava o prompt do sistema do Claude Code por padrão
async for message in query(prompt="Hello"):
print(message)
# DEPOIS (v0.1.0) - Usa prompt do sistema mínimo por padrão
# Para obter o comportamento antigo, solicite explicitamente a predefinição do Claude Code:
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
system_prompt={"type": "preset", "preset": "claude_code"} # Use a predefinição
),
):
print(message)
# Ou use um prompt do sistema personalizado:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
):
print(message)
Por que isso mudou: Fornece melhor controle e isolamento para aplicações SDK. Você agora pode construir agentes com comportamento personalizado sem herdar as instruções focadas em CLI do Claude Code.
Padrão de fontes de configurações
Este padrão foi brevemente alterado em v0.1.0 e depois revertido, portanto nenhuma ação de migração é necessária.
Comportamento atual: Omitir settingSources em query() carrega configurações de usuário, projeto e sistema de arquivos local, correspondendo ao CLI. Isso inclui ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, arquivos CLAUDE.md e comandos personalizados.
Para executar isolado das configurações do sistema de arquivos, passe uma matriz vazia:
const result = query({
prompt: "Hello",
options: {
settingSources: [] // Nenhuma configuração do sistema de arquivos carregada
}
});
// Ou carregue apenas fontes específicas:
const result = query({
prompt: "Hello",
options: {
settingSources: ["project"] // Apenas configurações do projeto
}
});
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(setting_sources=[]), # Nenhuma configuração do sistema de arquivos carregada
):
print(message)
# Ou carregue apenas fontes específicas:
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
setting_sources=["project"] # Apenas configurações do projeto
),
):
print(message)
O isolamento é especialmente importante para pipelines CI/CD, aplicações implantadas, ambientes de teste e sistemas multi-tenant onde personalizações locais não devem vazar.
Por Que a Renomeação?
O Claude Code SDK foi originalmente projetado para tarefas de codificação, mas evoluiu para um framework poderoso para construir todos os tipos de agentes de IA. O novo nome "Claude Agent SDK" reflete melhor suas capacidades:
- Construir agentes de negócios (assistentes jurídicos, consultores financeiros, suporte ao cliente)
- Criar agentes de codificação especializados (bots SRE, revisores de segurança, agentes de revisão de código)
- Desenvolver agentes personalizados para qualquer domínio com uso de ferramentas, integração MCP e muito mais
Obtendo Ajuda
Se você encontrar algum problema durante a migração:
Para TypeScript/JavaScript:
- Verifique se todas as importações foram atualizadas para usar
@anthropic-ai/claude-agent-sdk - Verifique se seu package.json tem o novo nome do pacote
- Execute
npm installpara garantir que as dependências sejam atualizadas
Para Python:
- Verifique se todas as importações foram atualizadas para usar
claude_agent_sdk - Verifique se seu requirements.txt ou pyproject.toml tem o novo nome do pacote
- Execute
pip install claude-agent-sdkpara garantir que o pacote seja instalado
Próximas Etapas
- Explore a Visão Geral do Agent SDK para aprender sobre os recursos disponíveis
- Confira a Referência do SDK TypeScript para documentação detalhada da API
- Revise a Referência do SDK Python para documentação específica do Python
- Aprenda sobre Ferramentas Personalizadas e Integração MCP