Official rename

Claude Agent SDK Developer Guide

The Claude Code SDK was officially renamed to Claude Agent SDK, offering a more complete AI Agent building experience. This guide covers Python/TypeScript quickstarts, core concepts, and enterprise best practices.

Python & TypeScript Formerly Claude Code SDK QCode.cc Compatible

Updated 2026-09-21

What is Claude Agent SDK

Official rename

Claude Code SDK Claude Agent SDK

The official migration guide also reorganized the docs; both names refer to the same SDK (checked 2026-09-21).

Why rename

The official reason is scope: the library is for building AI agents beyond coding tasks (checked 2026-09-21).

Unified Tool Interface

Shares the same tool system and Agent loop as Claude Code, enabling seamless switching between local and cloud deployments.

Production Ready

Built-in error retry, session management, streaming output and other enterprise features work out of the box.

Multi-language Support

Official Python and TypeScript SDKs with symmetric API design and comprehensive documentation.

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, fully compatible with QCode.cc proxy.

Step 1: Install SDK

python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk

Step 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-sdk

Step 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 cloud-hosted
Scaling	Manual instance management	Auto elastic scaling
Use case	Prototyping, highly custom scenarios	Enterprise production Agent deployment

Managed Agents guide

Using via QCode.cc

Point ANTHROPIC_BASE_URL at the QCode.cc endpoint to use the Agent SDK directly from China, no VPN required; see /models for what is callable. Managed Agents has Anthropic host the agent (official docs fetched 2026-09-22); we have not verified that path here and make no promise about it.

.env

# 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",
    },
)

All Claude models (Fable 5 / Opus 4.8 / Sonnet 4.6 / Haiku 4.5) available

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

Create account View Pricing Partner program →