# Claude Code Agent SDK API 参考速查

> TypeScript 和 Python Agent SDK 的安装、query、ClaudeSDKClient、工具函数、session API、settings 解析、迁移和版本差异。

URL: https://docs.passion8.cc/docs/claude-code/sdk-api-reference
Language: zh-CN
Publisher: Passion8

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

如果你要看 custom tools、streaming、structured output、tool search 和用户审批,看 [Agent SDK 运行时模式](https://docs.passion8.cc/docs/claude-code/sdk-runtime-patterns)。如果你要做多租户和生产部署,看 [Agent SDK 生产部署](https://docs.passion8.cc/docs/claude-code/sdk-production)。

## 覆盖的官方页面

| 官方页面 | 本页覆盖重点 |
| --- | --- |
| 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 的替代路线 |

## 安装





### TypeScript


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

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




### Python


```bash
pip install claude-agent-sdk
```

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







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

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Passion8 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()` 最小例子





### TypeScript


```typescript
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://passion8.cc",
      ANTHROPIC_AUTH_TOKEN: process.env.PASSION8_API_KEY ?? ""
    }
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}
```




### Python


```python
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://passion8.cc",
            "ANTHROPIC_AUTH_TOKEN": "sk-你的 Passion8 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:

```typescript
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 生产部署](https://docs.passion8.cc/docs/claude-code/sdk-production) 的 `SessionStore`。

## Settings 解析

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

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

多租户产品建议默认:

```typescript
{
  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,设置:

```typescript
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 生产部署](https://docs.passion8.cc/docs/claude-code/sdk-production)。

## 官方参考

- [Agent SDK overview](https://code.claude.com/docs/en/agent-sdk/overview.md)
- [Agent SDK quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart.md)
- [TypeScript reference](https://code.claude.com/docs/en/agent-sdk/typescript.md)
- [Python reference](https://code.claude.com/docs/en/agent-sdk/python.md)
- [Migration guide](https://code.claude.com/docs/en/agent-sdk/migration-guide.md)
- [TypeScript V2 session API removed](https://code.claude.com/docs/en/agent-sdk/typescript-v2-preview.md)