Pular para o conteúdo principal

​
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

AspectoAntigoNovo
Nome do Pacote (TS/JS)@anthropic-ai/claude-code@anthropic-ai/claude-agent-sdk
Pacote Pythonclaude-code-sdkclaude-agent-sdk
Local da DocumentaçãoDocumentação do Claude CodeAPI Guide → Seção Agent SDK
Mudanças na Documentação: A documentação do Agent SDK foi movida da documentação do Claude Code para o API Guide em uma seção dedicada Agent SDK. A documentação do Claude Code agora se concentra na ferramenta CLI e recursos de automação.

​
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

Para melhorar o isolamento e a configuração explícita, o Claude Agent SDK v0.1.0 introduz mudanças significativas para usuários que migram do Claude Code SDK. Revise esta seção cuidadosamente antes de migrar.

​
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"
  }
});
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
  }
});
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.
O SDK v0.1.0 brevemente padronizou para nenhuma configuração carregada; isso foi revertido em versões subsequentes. Python SDK 0.1.59 e anteriores tratavam uma lista vazia da mesma forma que omitir a opção, portanto atualize antes de confiar em setting_sources=[]. Veja O que settingSources não controla para entradas que são lidas mesmo quando settingSources é [].

​
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:
  1. Verifique se todas as importações foram atualizadas para usar @anthropic-ai/claude-agent-sdk
  2. Verifique se seu package.json tem o novo nome do pacote
  3. Execute npm install para garantir que as dependências sejam atualizadas
Para Python:
  1. Verifique se todas as importações foram atualizadas para usar claude_agent_sdk
  2. Verifique se seu requirements.txt ou pyproject.toml tem o novo nome do pacote
  3. Execute pip install claude-agent-sdk para garantir que o pacote seja instalado

​
Próximas Etapas