TokenMix Research Lab · 2026-04-24

Claude Agent SDK 2026: Migration From Claude Code SDK Guide

Claude Agent SDK 2026: Migration From Claude Code SDK Guide

Last Updated: 2026-04-30
Author: TokenMix Research Lab
Data checked: 2026-04-30

Claude Code SDK was renamed to Claude Agent SDK. The migration is mostly package names, imports, and option types.

Anthropic's Agent SDK overview says the Claude Code SDK has been renamed to Claude Agent SDK and now gives developers the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. The current install commands are pip install claude-agent-sdk for Python and npm install @anthropic-ai/claude-agent-sdk for TypeScript. Do not copy old examples that import claude_code_sdk, ClaudeCodeOptions, or @anthropic-ai/claude-code as the SDK package.

Table of Contents

Quick Verdict

Question Direct answer
What replaced Claude Code SDK? Claude Agent SDK
New TypeScript package @anthropic-ai/claude-agent-sdk
New Python package claude-agent-sdk
Main Python entry points query() and ClaudeSDKClient
Main TypeScript entry point query()
What changed in imports? ClaudeCodeOptions becomes ClaudeAgentOptions in Python
Is this just Messages API? No, it includes the agent loop and built-in tools
Should every app use it? No, use it when you need autonomous file/tool workflows

Migration Snapshot

Area Old Claude Code SDK New Claude Agent SDK
TypeScript package @anthropic-ai/claude-code @anthropic-ai/claude-agent-sdk
Python package claude-code-sdk claude-agent-sdk
TypeScript import from "@anthropic-ai/claude-code" from "@anthropic-ai/claude-agent-sdk"
Python import from claude_code_sdk import ... from claude_agent_sdk import ...
Python options type ClaudeCodeOptions ClaudeAgentOptions
Documentation Old Claude Code SDK section Agent SDK section in Claude docs
Scope Coding-oriented naming Broader agent-building naming

The old article version claimed a stable major-version API. I would not keep that claim. The current official migration docs show examples around package versions such as ^0.2.0, and the overview notes Opus 4.7 requires Agent SDK v0.2.111 or later. The practical guidance is: pin a tested package version and watch release notes.

What The Agent SDK Does

The Agent SDK is not a thin text-generation wrapper. It gives you Claude Code-style execution from Python or TypeScript.

Capability What it means
Agent loop Claude can decide which tool to use next and continue until done
Built-in file tools Read, Write, Edit, Glob, Grep for codebase work
Command execution Bash and related process tools for tests, scripts, and git operations
Web tools WebSearch and WebFetch where allowed
Hooks Validate, log, block, or transform behavior at lifecycle points
Subagents Delegate focused work to specialized agents
MCP Connect external tools and systems through Model Context Protocol
Permissions Restrict which tools an agent can use
Sessions Resume context across multiple exchanges

Use the Agent SDK when you want an agent to work inside your infrastructure. Use the normal Anthropic Client SDK when you only need a prompt/response API and want to implement your own tool loop.

Install Matrix

Runtime Install command Notes
Python pip install claude-agent-sdk Official Python SDK package
TypeScript npm install @anthropic-ai/claude-agent-sdk Official TS/JS SDK package
API key ANTHROPIC_API_KEY=... Use Console API key auth
Bedrock CLAUDE_CODE_USE_BEDROCK=1 Configure AWS credentials
Vertex AI CLAUDE_CODE_USE_VERTEX=1 Configure Google Cloud credentials
Microsoft Foundry CLAUDE_CODE_USE_FOUNDRY=1 Configure Azure credentials

Minimal Python example:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find TODO comments and summarize them.",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        print(message)

asyncio.run(main())

Minimal TypeScript example:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List the files in this project and identify the test command.",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Bash"],
  },
})) {
  console.log(message);
}

Python: query vs ClaudeSDKClient

The Python SDK has two patterns. Pick based on session needs.

Pattern Best for Tradeoff
query() One-off tasks and simple automation New session each time
ClaudeSDKClient Continuous conversations and session reuse More lifecycle control
Need Use
Single bug-fix job query()
CI job that runs one review query()
Chat-like app with follow-ups ClaudeSDKClient
Long-running worker ClaudeSDKClient
Interrupt support ClaudeSDKClient
Manual connection control ClaudeSDKClient

The mistake to avoid: using query() for a multi-turn workflow and expecting it to remember prior context unless you explicitly resume or manage sessions.

TypeScript SDK Shape

The TypeScript reference centers on query(), plus helper functions and types.

TS SDK item Use case
query() Stream agent messages as the agent works
tool() Define custom tools
createSdkMcpServer() Create SDK-backed MCP servers
listSessions() Inspect sessions
AgentDefinition Define subagents
PermissionMode / permission types Control tool permissions
Hook types Add lifecycle validation and logging
McpServerConfig Attach MCP servers

If you are migrating from old TS imports, the official path is simple:

// Before
import { query } from "@anthropic-ai/claude-code";

// After
import { query } from "@anthropic-ai/claude-agent-sdk";

Capabilities Matrix

Capability Good default Use carefully
Read, Glob, Grep Safe analysis and code search Large repos can still cost tokens
Edit, Write Controlled code changes Require tests and review
Bash Test runs, build scripts, git status Block destructive shell commands
WebSearch, WebFetch Current info and docs lookup Watch data leakage and prompt injection
Hooks Audit logs, policy checks, cost tracking Do not log secrets
Subagents Specialized review, research, testing More agents can mean more cost and complexity
MCP servers Databases, browsers, SaaS APIs Treat each server as a permissions boundary
Sessions Long workflows Need cleanup and storage policy

Agent SDK vs Client SDK vs Claude Code CLI

Need Best choice Why
Daily interactive coding Claude Code CLI Fastest official developer workflow
App-level autonomous agent Agent SDK Runs in your process with tools and sessions
Basic LLM request Anthropic Client SDK Lower complexity
Custom tool loop Client SDK You keep execution control
CI/CD agent Agent SDK Scriptable and automatable
Hosted sandbox with less infra Managed Agents Anthropic runs more of the infrastructure
Multi-provider API routing Gateway layer outside core SDK path Keep provider routing separate from SDK migration

Many teams should use both Claude Code and Agent SDK. Claude Code is for developers. Agent SDK is for products and automation.

Authentication And Policy Boundary

The Agent SDK is for API-key and approved enterprise/cloud authentication paths, not for reselling Claude.ai consumer login access.

Topic Guidance
API key Use ANTHROPIC_API_KEY from Claude Console
Claude.ai login Do not offer third-party login/rate limits unless Anthropic approved it
Bedrock/Vertex/Foundry Use documented environment flags and cloud credentials
TokenMix.ai Use it for broader model cost/routing strategy; only route SDK traffic through a gateway after protocol compatibility testing
Secrets Keep keys in env or secret manager, not code
Logs Redact prompts, tool inputs, and file paths where needed

This matters for TokenMix.ai positioning. TokenMix.ai is strongest for OpenAI-compatible API routing, fallback, model comparison, and cost control. The Claude Agent SDK is strongest when you specifically need Claude Code-style agents with Anthropic-supported auth.

Production Checklist

Check Why it matters
Pin SDK version Agent SDK is moving quickly
Define allowed tools Prevent unnecessary file writes or shell commands
Add hook-based audit logs Track edits and command execution
Add cost tracking Agents can loop longer than expected
Separate dev/prod permissions Local convenience is not production policy
Use MCP allowlists External tools expand blast radius
Test rollback behavior Agents can make multi-file changes
Monitor model/version requirements Opus 4.7 requires recent SDK versions

Final Recommendation

If you used Claude Code SDK, migrate to Claude Agent SDK now. Change package names and imports first, then revisit permissions, hooks, sessions, and MCP.

Do not treat migration as a search-and-replace only if the agent touches files, runs shell commands, or connects to external tools. That is production infrastructure.

FAQ

What replaced Claude Code SDK?

Claude Agent SDK replaced Claude Code SDK. Anthropic says the rename reflects broader agent-building capabilities beyond coding tasks.

What is the new Python package?

The new Python package is claude-agent-sdk. Install it with pip install claude-agent-sdk.

What is the new TypeScript package?

The new TypeScript package is @anthropic-ai/claude-agent-sdk. Install it with npm install @anthropic-ai/claude-agent-sdk.

Is Claude Agent SDK the same as the Messages API?

No. The Messages API is lower level. Agent SDK includes the agent loop, built-in tools, sessions, permissions, hooks, MCP, and Claude Code-style behavior.

Should I use query() or ClaudeSDKClient in Python?

Use query() for one-off tasks. Use ClaudeSDKClient for continuous conversations, session reuse, interrupts, and more lifecycle control.

Can I use Claude.ai Pro or Max login through my own SDK app?

Do not assume that. Anthropic's docs say third-party developers cannot offer claude.ai login or rate limits for Agent SDK products unless previously approved.

Does Agent SDK support MCP?

Yes. The docs include MCP server configuration and SDK-backed MCP server support.

Where does TokenMix.ai fit?

Use TokenMix.ai for model pricing, OpenAI-compatible API routing, and provider fallback. Keep Agent SDK authentication on documented Claude paths unless you have tested a compatible gateway path.

Related Articles

Sources