Agent SDK API 参考速查

这一页把官方 TypeScript/Python API 参考压缩成工程速查。完整 API 仍以官方参考为准,但日常选型通常只需要先判断:一次性 query()、长连接 client、custom tools、session 管理、settings 解析和迁移差异。

如果你要看 custom tools、streaming、structured output、tool search 和用户审批,看 Agent SDK 运行时模式。如果你要做多租户和生产部署,看 Agent SDK 生产部署。

覆盖的官方页面

官方页面	本页覆盖重点
Agent SDK overview	SDK 定位、能力和与 CLI/API 的差异
Quickstart	安装、最小 agent、权限模式
TypeScript reference	query()、startup()、tool()、session API、resolveSettings()
Python reference	query()、ClaudeSDKClient、@tool、session API
Migration guide	包名、system prompt、setting sources 和 breaking changes
TypeScript V2 preview removed	已移除 API 的替代路线

安装

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

TypeScript 包通常通过 optional dependency 带平台对应 binary。生产镜像里仍要确认 binary 存在,并保留 PATH。

pip install claude-agent-sdk

Python 需要 3.10 或更新版本。持续会话优先用 ClaudeSDKClient,一次性任务用 query()。

接 Gushen888 时,关键仍是子进程环境:

export ANTHROPIC_BASE_URL="https://api.gushen888.cloud"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Gushen888 API Key"

TypeScript env 选项会替换子进程环境。传自定义 env 时通常要展开 ...process.env。

选择入口

需求	TypeScript	Python	说明
一次性任务	query()	query()	最简单,流结束后进程退出
持续聊天	continue: true 或保存 session ID	ClaudeSDKClient	同一上下文多轮交互
流式输入	AsyncIterable<SDKUserMessage>	AsyncIterable[dict]	适合 WebSocket 或后台队列
自定义工具	tool()	@tool	用 in-process MCP server 暴露函数
列出本地 session	listSessions()	list_sessions()	可做历史列表和恢复入口
解析 settings	resolveSettings()	参考 Python options 行为	适合宿主应用展示有效配置

query() 最小例子

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

for await (const message of query({
  prompt: "解释这个仓库的入口文件",
  options: {
    cwd: process.cwd(),
    maxTurns: 5,
    permissionMode: "dontAsk",
    allowedTools: ["Read", "Grep", "Glob"],
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://api.gushen888.cloud",
      ANTHROPIC_AUTH_TOKEN: process.env.GUSHEN888_API_KEY ?? ""
    }
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, query

async def main() -> None:
    options = ClaudeAgentOptions(
        cwd=".",
        max_turns=5,
        permission_mode="dontAsk",
        allowed_tools=["Read", "Grep", "Glob"],
        env={
            "ANTHROPIC_BASE_URL": "https://api.gushen888.cloud",
            "ANTHROPIC_AUTH_TOKEN": "sk-你的 Gushen888 API Key",
        },
    )

    async for message in query(prompt="解释这个仓库的入口文件", options=options):
        if getattr(message, "type", None) == "result":
            print(message.result)

asyncio.run(main())

Python query() 与 ClaudeSDKClient

项目	query()	ClaudeSDKClient
会话	默认新 session	同一个 client 复用 session
多轮	需要 continue_conversation 或 resume	自动保持上下文
连接	自动创建和关闭	由你打开和关闭
Interrupt	不适合	支持
用途	job、CI、一次性后台任务	聊天 UI、IDE 面板、长会话

如果你的产品是“用户打开一个 agent 面板连续对话”,Python 优先用 ClaudeSDKClient。如果是“队列里每条任务跑一次”,用 query() 更简单。

常用函数

函数	语言	作用
query()	TS/Python	启动 agent loop 并返回消息流
startup()	TS	提前初始化子进程,降低首条消息延迟
tool() / @tool	TS/Python	定义 custom tool
createSdkMcpServer() / create_sdk_mcp_server()	TS/Python	把 custom tools 包装为 in-process MCP server
listSessions() / list_sessions()	TS/Python	列出本地 session
getSessionMessages() / get_session_messages()	TS/Python	读取 transcript 消息
getSessionInfo() / get_session_info()	TS/Python	查单个 session 元数据
renameSession() / rename_session()	TS/Python	重命名 session
tagSession() / tag_session()	TS/Python	给 session 打标签
resolveSettings()	TS	解析 settings 生效结果和 provenance

Permission mode 速查

模式	行为	适合
default	未被规则覆盖的工具会触发审批 callback	自定义审批 UI
acceptEdits	自动批准文件编辑和常见文件系统命令	人监督的开发流
plan	只读探索,编辑会走审批	大改前规划
dontAsk	不提示,未 allow 的动作直接拒绝	受限 headless agent
auto	TypeScript 可用,用 classifier 判断	半自治任务
bypassPermissions	大部分动作直接执行	只用于强隔离 sandbox

allowedTools 是预批准列表,不是工具全集限制。要移除工具定义,使用 disallowedTools 或缩小 tools。

Session API

字段	含义
sessionId / session_id	UUID,恢复或查看历史时使用
summary	自动或手动标题
lastModified	最近更新时间
cwd	session 结束时所在目录
gitBranch	结束时 Git branch
tag	用户设置标签

常见 UI:

const sessions = await listSessions({ dir: "/repo", limit: 50 });
const current = await getSessionInfo(sessions[0].sessionId, { dir: "/repo" });
const messages = await getSessionMessages(sessions[0].sessionId, { dir: "/repo", limit: 100 });

不要把本地 transcript 当唯一可靠存储。跨主机恢复看 Agent SDK 生产部署 的 SessionStore。

Settings 解析

TypeScript resolveSettings() 适合宿主应用在启动前展示“最终哪些配置生效”。

选项	用途
cwd	按哪个目录解析 project/local settings
settingSources	选择 user、project、local,传 [] 可跳过文件系统 settings
managedSettings	宿主应用提供更严格的 policy-tier settings
serverManagedSettings	宿主传入服务端 settings snapshot

多租户产品建议默认:

{
  settingSources: [],
  env: {
    ...process.env,
    CLAUDE_CONFIG_DIR: `/srv/claude-config/${tenantId}`,
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"
  }
}

从旧 SDK 迁移

旧	新
@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
claude-code-sdk	claude-agent-sdk
Python ClaudeCodeOptions	ClaudeAgentOptions
默认 Claude Code system prompt	需要显式设置 claude_code preset
隐式 settings 行为	要认真确认 settingSources
TS V2 session API	已移除,改用当前 query()、session API 或 Python client

如果你从 CLI 迁移,并希望行为像 Claude Code CLI,设置:

systemPrompt: {
  type: "preset",
  preset: "claude_code"
}

缓存影响

变化	5m/1h cache 影响
改 systemPrompt	改变前缀,通常导致 miss
改 settingSources	可能增减 CLAUDE.md、skills、hooks 和 settings
改 tools/MCP	工具 schema 变化会改变前缀
query() 新 session	历史为空,只复用稳定 system/tools 前缀
continue / resume	延续历史,更可能命中同一前缀
ENABLE_PROMPT_CACHING_1H=1	可选请求 1 小时 TTL,写入成本更高,适合反复调用同一 agent 配置

观测字段见 Agent SDK 生产部署。

官方参考

• Agent SDK overview
• Agent SDK quickstart
• TypeScript reference
• Python reference
• Migration guide
• TypeScript V2 session API removed