# @ag-ui/claude-agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40ag-ui/claude-agent-sdk/

版本：0\.0\.8
npm 元数据更新时间：2026-10-21T07:03:12.414Z
中文译文更新时间：2026-11-06T00:55:23.833Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ag-ui/claude-agent-sdk
原文对照：https://npmcn.com/package/%40ag-ui/claude-agent-sdk/?lang=original
项目主页：https://github.com/ag-ui-protocol/ag-ui#readme
源码仓库：https://github.com/ag-ui-protocol/ag-ui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：473 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：zod \>=3\.0\.0，@ag-ui/core \>=1\.0\.0，@ag-ui/client \>=1\.0\.0，@anthropic-ai/sdk \>=0\.50\.0，@anthropic-ai/claude-agent-sdk 0\.3\.296
- 首次发布：2026-04-24T20:05:18.339Z
- 最新版本发布：2026-10-21T07:03:12.034Z
- 近 30 天下载量：7672（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

AG-UI 用于Anthropic Claude Agent SDK的整合

## 安装

```sh
npm install @ag-ui/claude-agent-sdk
```

也可以使用：`pnpm add @ag-ui/claude-agent-sdk`、`yarn add @ag-ui/claude-agent-sdk`、`bun add @ag-ui/claude-agent-sdk`

## README

# @ag-ui/claude-agent-sdk (英语)

为Anthropic Claude Agent SDK(TypeScript)执行AG-UI协议.

## 安装

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

## 使用量

适配器在内部管理 SDK 生命周期——只要拨打 `adapter.run(input)`数字 :

```typescript
import { ClaudeAgentAdapter } from "@ag-ui/claude-agent-sdk";

const adapter = new ClaudeAgentAdapter({
  agentId: "my_agent",
  model: "claude-haiku-4-5",
  systemPrompt: "You are helpful",
});

const events$ = adapter.run(input);
events$.subscribe({
  next: (event) => sendEvent(event),
  complete: () => res.end(),
});
```

## 特征

-   **全面生命周期管理** - 处理信件提取、选项构建和SDK内部查询
-   **中断支持** - 打电话 `adapter.interrupt()` 停止运行中的查询
-   **动态前端工具** - 作为MCP服务器自动添加客户端提供的工具
-   **前端工具停止** - 前端工具调用客户端执行后流起暂停(即人行)
-   **流出工具参数** 实时 TOOL CALL ARGS 作为 JSON 参数流在
-   **双向状态同步** - 通过 ag ui update 状态工具共享状态管理
-   **上下文注射** - 环境和状态被注入宣传剂的提示
-   **事件清理** - 挂起事件(工具呼叫、推理块)
-   **可观察模式** - RxJS 可观察事件流
-   **通过 MCP 自定义工具** - 使用 Claude SDK 工具定义自定义工具
-   **转发道具** - 用安全白名单覆盖每个运行选项

## 实例

整合包括5个实例:

| 路线 | 说明 | 特征 |
| --- | --- | --- |
| `/agentic_chat` | 基本谈话助理 | 简单聊天 |
| `/backend_tool_rendering` | 天气工具( 后端 MCP) | 后端工具执行, 工具渲染 |
| `/shared_state` | 食谱合作 | 双向状态同步, ag ui update state |
| `/human_in_the_loop` | 经核准的任务规划 | 前端工具、步骤跟踪、核准工作流程 |
| `/tool_based_generative_ui` | 前端工具渲染 | 动态前端工具, 基因UI |

## 运行示例

```bash
# Install dependencies
cd integrations/claude-agent-sdk/typescript
pnpm install

# Start server (port 8889)
ANTHROPIC_API_KEY=sk-ant-xxx npx tsx examples/server.ts

# Start Dojo (in another terminal)
cd apps/dojo
pnpm dev
```

访问 **http://localhost:3:00 (英语)** 选择 **"克劳德特工SDK(剧本)"**

## 链接

-   [克劳德探员SDK](https://platform.claude.com/docs/en/agent-sdk/typescript)
-   [AG-UI 文档](https://docs.ag-ui.com/)
-   [国家管理部门](https://docs.ag-ui.com/concepts/state)

## 内容和国家保全

适配器为所支持的工具结果介质发布AG-UI 1.0的内容部分. 它按顺序保留了每个块,包括字节和MIME类型;每个被预测的部分保留了原始的SDK块 `metadata.claude.block`没有AG-UI等同物的部件保留其JSON有效载荷和明确 `metadata.claude.unsupportedType`. 工具结果事件和最后消息快照使用相同的投影和出错指示. 单一的纯文本结果仍为字符串,包括它们的原白空间.

这个 `claude:assistant_content` 自定义事件保留了从 SDK 收到的完整的助手块,包括文本记录无法代表的推理/签名和更丰富的块. 它的值包含 `messageId`,SDK记录 `uuid` 可用时, `parentToolUseId`,以及 `content`。流出消息ID在提供时使用本地消息ID。 仅 `mcp__ag_ui__` 工具名称映射到前端名称; 外部 MCP 名称仍然具有避免相撞的资格.

输入上传仍然在其中 `RUN_STARTED.input` 及其原始元数据。 将图像和PDF数据/URL转发给克洛德;内置 UTF-8 `text/plain` 文档从基数64解码,文档 `metadata.filename` 改为文件标题。 音频/视频输入和未解决的提供者文件手柄发出 `claude:unsupported_input` 诊断,并省略出模型提示。 记录这些上传与模型理解是分开的. 原生的SDK文字记录并不一定保留每个AG-UI元数据字段.

`input.state` 是运行开始时的完整状态。 这个 `ag_ui_update_state` 工具浅相 `state_updates` 对象键; 嵌入式对象和数组替换该键的上个值。 适配器发出完整的合并 `STATE_SNAPSHOT`,且无效的更新保留了先前状态。 本地状态工具的结果是承认,而不是保存完整的状态快照. 仅部分更新的本地语录无法确定缺少初始状态 .

前端工具代理需要配备一个结果解析器,用于被延迟工具/会话恢复集成的原始工具调用. 解析器将真正的前端结果返回到该调用中;没有解析就明显失败,而不是保存占位符. 字符串保留其字节;所支持的结构化结果成为了MCP的内容. 这种内容的改变必须同PNI-659的生命周期伴航. 它不修复历史占位结果或使任意的历史批准可以恢复.

协议回归测试进行合成SDK流和代理回调,没有模型调用. 它们没有建立释放支持,在重启或从端到端的情报重放过程中的本土持久性;这些需要生命周期伴生和产品验证.

### 恢复会议(PNI-659,未释放)

使用 `sessionRecovery: { store, profile, resolveProfile, deferTools? }` 保留 整个适配器的线程到 SDK 会话绑定 . `store.load(threadId)` 返回时 `{ sessionId, profile, pending?: { id, name, input } }`· ; `store.save` 在解决问题之前,必须坚持不懈地履行这一记录. `resolveProfile(profile)` 返回信任的 SDK 选项,包括原始 `cwd`,当地 `sessionStore` (如果使用),工具/MCP配置,许可模式和证书环境. 存储一个配置密钥, 而不是证书或序列式召回 。 默认 内膜绑定无法在重新启动的进程中存活.

对于导入的会话,主机必须解决导入的线程ID到 原始 UUID 和执行配置文件,包括确认保存的推迟 现相. 丢失的进口记录必须扔出而不是返回 `undefined` (意思是新线程). 永远不要推断未完成的批准 `tool_use` 或等待死亡过程的召回 PNI-657拥有本地人 历史取出与出行. 具有会话约束力的访问要求同一个租户 并授权边界作为本地记录。 序列化横穿 带有应用程序锁的复制件; 适配器只排除重叠的本地 运行。 在保存中断后对本地存储调节绑定 在公布未决决定之前,先进行SDK分机外活动.

使用 `deferTools: ["Read"]` (准确的本地名称)用于本地审批政策. A 类 已确认本地延迟发射 `RUN_FINISHED.outcome = { type: "interrupt", interrupts: [...] }`答复 `resume: [{ interruptId: originalCallId, status: "resolved", payload: { behavior: "allow" | "deny", message?, updatedInput? } }]`· ; `status: "cancelled"` 拒绝电话 适配器恢复 原UUID 不伪造,保留原调用ID,然后离开 实际执行/结果的持久性。 现有的主机钩仍然适用; 不为同一呼叫配置第二个无条件的推迟钩.

测试的基准是SDK特工 **0.3.296 (中文(简体) )**,其捆绑的CLI **2.1.296 (中文(简体) )**,以及 乌干达 **1.0 国家**. 恢复需要国家领导才能 `--await-initialize` 障碍,其中 恢复前的适配器设定,所以在被保存的调用执行之前,SDK钩存在. A hold, 空的输入流避免为额外的用户/ 模型转动排队 。 自定义 超过2.1.261的CLI二进制不支持这一障碍。 本地笔录 寻找,设置相同 `CLAUDE_CONFIG_DIR` 在主机进程和查询环境中. 缺少记录/配置和没有工具作为运行错误表面; 新的会议不会倒退.

前端推迟 `mcp__ag_ui__` 使用经认证的回环 HTTP MCP 端点,与 `alwaysLoad` 在本地重播之前。 终点 仅用于查询,然后关闭。 装订器还存储 初始前端工具声明( e)`frontendTools` 在类型脚本中, `frontend_tools` 在 Python 中);这些字段保持不变,因此仅是三角形 `ToolMessage` 与 `tools: []` 可以在重新启动后恢复原调用. 工具出错保留其本土失败旗. 其他主机提供的流程中 SDK MCP的延期仍然受到注意,因为这些服务器的登记太迟,无法重播. 持久推迟支持 **一次一个工具呼叫**,而不是平行的电话.

重点测试包括绑定还原,允许/拒绝映射,缺失会话, 身份不匹配和召回历史的拒绝。 运行 `pnpm exec tsx scripts/probe-durable-resume.mjs` 重复为 `--allow` 从 此软件包用于对本地主机假冒进行两个 SDK 程序 提供和一次性合成本地文件。 探测器检查了原始UUID, 拨打ID,本地/AG-UI结果平等,总共有两个模式要求. 这是合成适配器的验证 远程商店 生产证书, 情报/浏览器重放,六行产品矩阵仍未验证.

前端探测器( U)`scripts/probe-frontend-resume.mjs`,可选 `--error`, (中文(简体) ), 在类型脚本中; `scripts/probe_frontend_resume.py` 在 Python 中进行额外检查 带有省略工具定义的原会话前端结果, 本地保存 结果, 和一个新的SDK历史读取。 它使用同样的孤立的假提供者 设为本土审批探针. 真正的SDK区块排序探测器使用合成本地主机提供者(无模型) 全权证书或外部推论:

```sh
pnpm exec tsx integrations/claude-agent-sdk/typescript/scripts/probe-assistant-blocks.mjs
```

它检查两个文本块和文本,然后是本地工具呼叫,每个都使用 部分信件启用并禁用, 与最后信件快照相对应 .

#### 不支持的待处理批次

一旦观察到多次延期,适配器就坚持诊断 元数据先确认钩子。 并联悬钩写作被连载. 因此,在终端 SDK 结果之前, 流例外或取消 当一个新的适配器装入装入绑定物时,将确认的批次屏蔽.

如果在获得结果之前推迟了几次通话,适配器将保存 所有观察到的原始身份、姓名和参数 `SessionBinding.unsupportedPendingTools`,保留SDK的 `pending` 电话,和 发射 `RUN_ERROR`。在自定义约束商店中坚持这个可选字段。 一个新的 适配器/进程拒绝恢复此绑定 。 对于更古老的单子捆绑, 适配器在续作前读取原生历史并保留未解决的内容 当拯救的召唤来临的时候, 已完成的本地成果,包括: 空洞的结果,被排除在诊断之外。 失败历史读取失败 运行而不是跳过支票.

这是故障控制,不是批量回收: 没有兄弟会的结果 伪造的,没有重写本体记录,也没有提交答复或下一个 用户消息在拒绝时发送到 SDK 。 打电话的人必须拒绝 输入。 不清除诊断字段或独立重放每个兄弟 绕过警卫 现有批次需要上游SDK回收支持; 缺少历史呼叫或结果不能由这个适配器重建. 见SDK的 [单项延期限制](https://code.claude.com/docs/en/hooks#defer-a-tool-call-for-later)。 。 。 .

没有自动更改提供者配置 。 信任的部署可能 为未来回合配置相继生成,但必须验证实际 提供者要求和尊重组织政策。 这种预防没有 修复现有批次。 单调续作仍需要原件 会话、工具配置、结果所有权和批准检查.

#### 未解决的儿童电话

父母完成、代理启动结果和任务完成通知 没有解决儿童的工具呼叫。 适配器跟踪观察到的儿童工具用途 直到本地结果同时匹配工具ID和 `parent_tool_use_id`时 父完成、 未解决的呼叫保留在 `unsupportedPendingTools` 其原始身份、名称、输入和 `parentToolUseId`; 运行输出 `RUN_ERROR`保持这个领域不变。 冷续作在之前就被拒绝了 启动SDK,即使只有一个孩子的电话没有解决。 儿童身份 从未被曝光为可诉家长会批准.

SDK 文档 [子代理续作](https://code.claude.com/docs/en/agent-sdk/subagents#resume-subagents) 通过新的快速命名代理, 但这不是一个核实准确的呼叫 推迟重播合同。 因此这个适配器不尝试孩子 恢复、综合结果或修改记录誊本。 已经丢失的诊断 在旧装订书中,单靠父母完成无法重建.

## 常见问题

### @ag-ui/claude-agent-sdk 是什么？

AG-UI 用于Anthropic Claude Agent SDK的整合

### 如何安装 @ag-ui/claude-agent-sdk？

在项目目录运行 npm install @ag-ui/claude-agent-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（\>=3\.0\.0）、@ag-ui/core（\>=1\.0\.0）、@ag-ui/client（\>=1\.0\.0）、@anthropic-ai/sdk（\>=0\.50\.0）、@anthropic-ai/claude-agent-sdk（0\.3\.296）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ag-ui/claude-agent-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ag-ui/claude-agent-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ag-ui/claude-agent-sdk 可以商用吗？

@ag-ui/claude-agent-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ag-ui/claude-agent-sdk 的下载量有多少？

根据 npm 官方下载统计，@ag-ui/claude-agent-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 7,672 次，日均约 256 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ag-ui/claude-agent-sdk 还在维护吗？

最新版本 0\.0\.8 发布于 2026/10/21（17 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/04/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。