​
Visão Geral

O Claude Code SDK foi renomeado para 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
Localização da DocumentaçãoDocumentos Claude Code → seção SDKGuia da API → seção Agent SDK
Mudanças na Documentação: A documentação do Agent SDK foi movida dos documentos do Claude Code para o Guia da API sob uma seção dedicada Agent SDK. Os documentos do Claude Code agora focam na ferramenta CLI e recursos de automação.

​
Passos 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: Mude 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ê tem o pacote listado no seu package.json, atualize-o: 
// Antes
{
  "dependencies": {
    "@anthropic-ai/claude-code": "^1.0.0"
  }
}

// Depois
{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
  }
}
É isso! Nenhuma outra mudança 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: Mude 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 nomes de tipos: Mude ClaudeCodeOptions para ClaudeAgentOptions: 
# Antes
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5"
)

# Depois
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5"
)
5. Revise mudanças que quebram compatibilidade Faça quaisquer mudanças de código necessárias para completar a migração.

​
Mudanças que quebram compatibilidade

Para melhorar o isolamento e configuração explícita, o Claude Agent SDK v0.1.0 introduz mudanças que quebram compatibilidade para usuários migrando 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 (v0.0.x)
from claude_agent_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(
    model="claude-sonnet-4-5",
    permission_mode="acceptEdits"
)

# DEPOIS (v0.1.0)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-sonnet-4-5",
    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: "Olá" });

// DEPOIS (v0.1.0) - Usa prompt do sistema vazio por padrão
// Para obter o comportamento antigo, solicite explicitamente o preset do Claude Code:
const result = query({
  prompt: "Olá",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Ou use um prompt do sistema personalizado:
const result = query({
  prompt: "Olá",
  options: {
    systemPrompt: "Você é um assistente de codificação útil"
  }
});
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.

​
Fontes de Configurações Não São Mais Carregadas por Padrão

O que mudou: O SDK não lê mais configurações do sistema de arquivos (CLAUDE.md, settings.json, comandos slash, etc.) por padrão. Migração: 
// ANTES (v0.0.x) - Carregava todas as configurações automaticamente
const result = query({ prompt: "Olá" });
// Leria de:
// - ~/.claude/settings.json (usuário)
// - .claude/settings.json (projeto)
// - .claude/settings.local.json (local)
// - arquivos CLAUDE.md
// - Comandos slash personalizados

// DEPOIS (v0.1.0) - Nenhuma configuração carregada por padrão
// Para obter o comportamento antigo:
const result = query({
  prompt: "Olá",
  options: {
    settingSources: ["user", "project", "local"]
  }
});

// Ou carregue apenas fontes específicas:
const result = query({
  prompt: "Olá",
  options: {
    settingSources: ["project"]  // Apenas configurações do projeto
  }
});
Por que isso mudou: Garante que aplicações SDK tenham comportamento previsível independente de configurações locais do sistema de arquivos. Isso é especialmente importante para:
  • Ambientes CI/CD - Comportamento consistente sem personalizações locais
  • Aplicações implantadas - Sem dependência de configurações do sistema de arquivos
  • Testes - Ambientes de teste isolados
  • Sistemas multi-inquilino - Prevenir vazamento de configurações entre usuários
Compatibilidade com versões anteriores: Se sua aplicação dependia de configurações do sistema de arquivos (comandos slash personalizados, instruções CLAUDE.md, etc.), adicione settingSources: ['user', 'project', 'local'] às suas opções.

​
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 mais

​
Obtendo Ajuda

Se você encontrar problemas 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
Veja o guia de Solução de Problemas para problemas comuns.

​
Próximos Passos