Agent SDK

把 Claude Code 的 Agent 能力嵌入你自己的应用——安装、query()、多轮对话、自定义工具与 Subagents

概述

Claude Agent SDK 把 Claude Code 的 agent loop、内置工具（Read / Edit / Bash 等）和上下文管理打包成一个可嵌入的库。底层会启动 Claude Code 子进程，SDK 自带 CLI 二进制，无需单独安装 Claude Code。

简单说就是——你在终端里用 Claude Code 能做的事，现在可以用几行代码在自己的应用里做了。

它和其他东西有什么区别？

	定位	一句话总结
Claude Code CLI	终端交互工具	在命令行里直接和 Claude 对话写代码
Agent SDK	嵌入式 Agent 库	把 Claude Code 的全部能力封装成 Python / TypeScript API
Client SDK（`@anthropic-ai/sdk`）	API 客户端	直接调 Messages API，tool loop 要自己实现
Managed Agents	云端托管服务	Anthropic 托管的 Agent，2026-04 公测

安装

Python

pip install claude-agent-sdk

需要 Python 3.10+。

TypeScript

npm install @anthropic-ai/claude-agent-sdk

需要 Node.js 18+。

认证

SDK 通过环境变量读取 API 密钥：

export ANTHROPIC_API_KEY="sk-ant-..."

也支持 Amazon Bedrock、Google Vertex AI 和 Foundry 等替代认证方式。

快速开始

核心入口是 query() 函数。它返回一个异步迭代器，需要用 async for / for await 逐条消费消息。

Python

from claude_agent_sdk import query

async for message in query(
    prompt="查找所有 TODO 并修复",
    options={"allowedTools": ["Read", "Edit", "Bash"]}
):
    if message.type == "assistant":
        print(message.content)

TypeScript

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

for await (const message of query({
  prompt: '查找所有 TODO 并修复',
  options: { allowedTools: ['Read', 'Edit', 'Bash'] }
})) {
  if (message.type === 'assistant') {
    console.log(message.content);
  }
}

注意：query() 不是 await 一次拿到完整结果，而是流式返回 AsyncIterator[Message]。每条 message 有 type 字段区分角色。

多轮对话

如果需要在同一个会话里连续提问（保持上下文），用 ClaudeSDKClient：

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(ClaudeAgentOptions(...)) as client:
    await client.connect()

    response = await client.query("这个项目用了什么框架？")
    messages = await client.receive_response()

    # 继续追问，上下文自动保留
    response = await client.query("帮我找到所有 API 路由")
    messages = await client.receive_response()

    await client.disconnect()

自定义工具

用 @tool 注册工具

@tool 装饰器需要三个参数：工具名称、描述和 input_schema（JSON Schema 格式）：

from claude_agent_sdk import tool

@tool("get_weather", "获取天气信息", {
    "type": "object",
    "properties": {"city": {"type": "string", "description": "城市名"}},
    "required": ["city"]
})
def get_weather(city: str) -> str:
    return f"{city}: 晴天 25°C"

注意：不能写裸的 @tool——name、description、input_schema 三个参数缺一不可。

用 create_sdk_mcp_server 暴露工具

把注册好的工具打包成 MCP 服务器，SDK 会自动管理进程通信：

from claude_agent_sdk import create_sdk_mcp_server

server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[get_weather]
)

这种方式比手动跑外部 MCP 服务器更轻量——无需单独管理子进程，单进程内完成一切。

自定义 Subagents

Subagents 是运行在独立上下文中的专门化 AI 助手。

方式一：Markdown 文件

在 .claude/agents/ 下创建 .md 文件：

---
name: code-reviewer
description: 专门审查代码质量和安全性的 Agent
model: sonnet
tools:
  - Read
  - Glob
  - Grep
maxTurns: 10
permissionMode: plan
---

你是一个代码审查专家。审查代码时关注：
1. 安全漏洞（SQL 注入、XSS 等）
2. 性能问题
3. 代码规范

方式二：交互式创建

在 Claude Code 中输入 /agents，通过引导式设置创建。

Subagent 配置字段

字段	说明
`name`	Agent 名称（必需）
`description`	Agent 描述（必需）
`model`	模型别名：sonnet / opus / haiku / fable / inherit，或完整模型 ID
`tools`	可用工具列表
`disallowedTools`	禁用工具列表
`maxTurns`	最大交互轮次
`permissionMode`	权限模式
`mcpServers`	MCP 服务器配置
`hooks`	生命周期钩子
`skills`	启动时预加载的 Skills
`memory`	持久记忆（user/project/local）
`effort`	推理 effort 级别
`background`	是否后台运行
`isolation`	worktree 隔离
`color`	在 UI 中显示的颜色
`initialPrompt`	作为主会话 agent 运行时的初始提示

内置 Subagents

Agent	模型	用途
Explore	Haiku	只读，快速代码搜索
Plan	继承	计划模式研究
General-purpose	继承	完整工具，复杂任务

Agent SDK

概述

它和其他东西有什么区别？

安装

Python

TypeScript

认证

快速开始

Python

TypeScript

多轮对话

自定义工具

用 @tool 注册工具

用 create_sdk_mcp_server 暴露工具

自定义 Subagents

方式一：Markdown 文件

方式二：交互式创建

Subagent 配置字段

内置 Subagents

相关概念

Tool Runner

Managed Agents

On this page