@ag-ui/claude-agent-sdk (英语)
为Anthropic Claude Agent SDK(TypeScript)执行AG-UI协议.
安装
npm install @ag-ui/claude-agent-sdk @anthropic-ai/claude-agent-sdk zod
使用量
适配器在内部管理 SDK 生命周期——只要拨打 adapter.run(input)数字 :
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 |
运行示例
# 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(剧本)"
链接
内容和国家保全
适配器为所支持的工具结果介质发布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区块排序探测器使用合成本地主机提供者(无模型)
全权证书或外部推论:
pnpm exec tsx integrations/claude-agent-sdk/typescript/scripts/probe-assistant-blocks.mjs
它检查两个文本块和文本,然后是本地工具呼叫,每个都使用 部分信件启用并禁用, 与最后信件快照相对应 .
不支持的待处理批次
一旦观察到多次延期,适配器就坚持诊断 元数据先确认钩子。 并联悬钩写作被连载. 因此,在终端 SDK 结果之前, 流例外或取消 当一个新的适配器装入装入绑定物时,将确认的批次屏蔽.
如果在获得结果之前推迟了几次通话,适配器将保存
所有观察到的原始身份、姓名和参数
SessionBinding.unsupportedPendingTools,保留SDK的 pending 电话,和
发射 RUN_ERROR。在自定义约束商店中坚持这个可选字段。 一个新的
适配器/进程拒绝恢复此绑定 。 对于更古老的单子捆绑,
适配器在续作前读取原生历史并保留未解决的内容
当拯救的召唤来临的时候, 已完成的本地成果,包括:
空洞的结果,被排除在诊断之外。 失败历史读取失败
运行而不是跳过支票.
这是故障控制,不是批量回收: 没有兄弟会的结果 伪造的,没有重写本体记录,也没有提交答复或下一个 用户消息在拒绝时发送到 SDK 。 打电话的人必须拒绝 输入。 不清除诊断字段或独立重放每个兄弟 绕过警卫 现有批次需要上游SDK回收支持; 缺少历史呼叫或结果不能由这个适配器重建. 见SDK的 单项延期限制。 。 。 .
没有自动更改提供者配置 。 信任的部署可能 为未来回合配置相继生成,但必须验证实际 提供者要求和尊重组织政策。 这种预防没有 修复现有批次。 单调续作仍需要原件 会话、工具配置、结果所有权和批准检查.
未解决的儿童电话
父母完成、代理启动结果和任务完成通知
没有解决儿童的工具呼叫。 适配器跟踪观察到的儿童工具用途
直到本地结果同时匹配工具ID和 parent_tool_use_id时
父完成、 未解决的呼叫保留在 unsupportedPendingTools
其原始身份、名称、输入和 parentToolUseId; 运行输出
RUN_ERROR保持这个领域不变。 冷续作在之前就被拒绝了
启动SDK,即使只有一个孩子的电话没有解决。 儿童身份
从未被曝光为可诉家长会批准.
SDK 文档 子代理续作 通过新的快速命名代理, 但这不是一个核实准确的呼叫 推迟重播合同。 因此这个适配器不尝试孩子 恢复、综合结果或修改记录誊本。 已经丢失的诊断 在旧装订书中,单靠父母完成无法重建.