Claude Agent SDK Developer Guide
The Claude Code SDK has been officially renamed to the Claude Agent SDK, with broader capabilities for building AI agents beyond coding tasks. This guide covers Python/TypeScript quickstarts, core concepts, the comparison with Managed Agents, and setup via QCode.
Updated 2026-10-20
What is Claude Agent SDK
Official rename
The official migration guide shows the docs were reorganized alongside the rename, and the install package names changed as well; both names refer to the same SDK (checked 2026-10-20).
Why rename
The official reason is scope: the library is for building AI agents beyond coding tasks (checked 2026-10-20).
Unified Tool Interface
Provides the same tools, agent loop and context management that power Claude Code, embedded as a library in your own Python or TypeScript application and run in a process you operate.
Production Ready
Built-in tools for reading, writing and editing files, running commands and searching the web, plus sessions, permissions, hooks, subagents and MCP integration.
Multi-language Support
Officially maintained in two packages: claude-agent-sdk for Python and @anthropic-ai/claude-agent-sdk for TypeScript, both kept up to date.
Core Concepts
Tools
Functions callable by the Agent, declared with decorators that auto-generate JSON Schema for Claude to understand and invoke.
Agent Loop
Claude thinks → selects tool → executes → observes result → continues thinking, until the task is complete.
Memory / Context
Unified management of in-session short-term memory (conversation history) and cross-session long-term memory (file/database persistence).
Permissions
Fine-grained permission control: filesystem, network, code execution, and external API access scopes can all be configured independently.
Python Quickstart
Build your first Claude Agent in three steps; on QCode you only configure the QCode key and the Anthropic endpoint.
Step 1: Install SDK
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdkStep 2: Create Agent
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
system_prompt="You are an expert Python developer",
permission_mode="acceptEdits",
)
async for message in query(
prompt="Create a Python web server", options=options
):
print(message)
asyncio.run(main())Step 3: Define Custom Tools
import asyncio
from typing import Any
from claude_agent_sdk import (
ClaudeAgentOptions, create_sdk_mcp_server, query, tool
)
@tool("get_weather", "Get current weather for a city", {"city": str})
async def get_weather(args: dict[str, Any]) -> dict[str, Any]:
return {
"content": [
{"type": "text",
"text": f"Weather in {args['city']}: 22 C, sunny"}
]
}
weather_server = create_sdk_mcp_server(
name="weather",
version="1.0.0",
tools=[get_weather],
)
options = ClaudeAgentOptions(
mcp_servers={"weather": weather_server},
allowed_tools=["mcp__weather__get_weather"],
)
async def main():
async for message in query(
prompt="What's the weather in Beijing and Shanghai?",
options=options,
):
print(message)
asyncio.run(main())TypeScript Quickstart
Claude Agent development in Node.js / Bun with full type support.
Step 1: Install SDK
npm install @anthropic-ai/claude-agent-sdkStep 2: Create Agent
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Create a Python web server",
options: { systemPrompt: "You are an expert Python developer" },
})) {
console.log(message);
}Step 3: Full Example
import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
const getTemperature = tool(
"get_temperature",
"Get the current temperature at a location",
{
latitude: z.number().describe("Latitude coordinate"),
longitude: z.number().describe("Longitude coordinate")
},
async (args) => {
return {
content: [{ type: "text", text: `Temperature at ${args.latitude}` }]
};
}
);
const weatherServer = createSdkMcpServer({
name: "weather",
version: "1.0.0",
tools: [getTemperature]
});
for await (const message of query({
prompt: "What's the temperature in Beijing?",
options: {
mcpServers: { weather: weatherServer },
allowedTools: ["mcp__weather__get_temperature"]
}
})) {
console.log(message);
}Agent SDK vs Managed Agents
| Aspect |
Agent SDK
|
Managed Agents
|
|---|---|---|
| Runtime | Self-hosted (local / own server) | Anthropic hosts the agent loop; sessions can run in an Anthropic-managed cloud sandbox or a sandbox on your own infrastructure. |
| Scaling | Manual instance management | Auto elastic scaling |
| Use case | Prototyping, highly custom scenarios | Enterprise production Agent deployment |
Using via QCode.cc
Point ANTHROPIC_BASE_URL at https://api.qcode.cc/api and call the Agent SDK with your QCode key; see /models for what is callable. Managed Agents has Anthropic host the agent loop, with sessions in an Anthropic-managed cloud sandbox or a sandbox on your own infrastructure (official docs fetched 2026-10-20); we have not verified that path and make no promise about it.
# Python SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_API_KEY=your-qcode-api-key
# TypeScript SDK
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_API_KEY=your-qcode-api-key
# Point the endpoint at your own gateway: the SDK reads it from env
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
env={
"ANTHROPIC_BASE_URL": "https://api.qcode.cc/api",
},
)Claude models Fable 5 / Opus 4.8 / Sonnet 4.6 are callable on QCode; whether Haiku 4.5 and other models are callable follows /models (checked 2026-10-20).
Full tool calling (Function Calling) support
Streaming output support
Same shape as the official Messages API — the Agent SDK only needs ANTHROPIC_BASE_URL
Start Building AI Agents Today
Register at QCode.cc for stable Claude API access within China, supporting all Agent SDK features.