@godspeedai/cognate-ag-ui

中文文档
0.10.0发布于 2026/11/16Apache-2.0ES Module构建来源已验证近 30 天下载 3279

AG-UI投影和互操作性适配器:出站事件映射,通过本土授权的入站动作,有重联的SSE端点(spec §24). 内部事件从来不是AG-UI的别名.

中文使用文档
文档目录8 节
  1. 安装
  2. 快开始
  3. 入境行动
  4. 继续绘图
  5. 事件报道
  6. 限制
  7. 相关软件包
  8. 许可证

@godspideai/cognate-ag-ui (英语)

AG-UI 1.0 互操作性适配器:将 Cognate 运行的可持久事件流作为SSE上的 schema-valid AG-UI 事件进行项目,并将 AG-UI 的动作(消息、工具结果、批准、取消)映射到运行时间 RuntimeService 与运输认证呼叫器.

何时使用此软件包 : a 一个 乌干达 客户端( 或任何说 AG- UI 事件语法的 SSE 消费者) 应驱动您的 Cognate 代理 。 它是可选的边界——原生的Cognate执行和UI工作没有它的改变,Cognate的内部事件从未被改写为AG-UI的别名. 关于A2A特工,请看 @godspeedai/cognate-a2a。 。 。 .

安装

bun add @godspeedai/cognate-ag-ui

要求数 阿宝 1.4.0. 取决于 @ag-ui/core, (中文(简体) ), @ag-ui/encoder,以及服务类型 @godspeedai/cognate-runtime-api; 配对 @godspeedai/cognate-runtime-bun 对于运行时间本身.

快开始

import { createAgUiHandler } from "@godspeedai/cognate-ag-ui";
import { createRuntime } from "@godspeedai/cognate-runtime-bun";

const runtime = await createRuntime({
  store: "./app.sqlite",
  agents: [/* your AgentDefinitions */],
  policy,
  actions,
});

const handler = createAgUiHandler({
  service: runtime.service,
  defaultAgent: "agent.copilot", // agent started for new user messages
  authenticate: (headers) => myBearerAuth(headers), // Caller | undefined
});

Bun.serve({ port: 3000, fetch: handler });

一个客户端 POST 一个AG-UI RunAgentInput 并读取SSE流:

const response = await fetch("http://127.0.0.1:3000/", {
  method: "POST",
  headers: { "content-type": "application/json", authorization: "Bearer alice", accept: "text/event-stream" },
  body: JSON.stringify({
    threadId: "t-1",
    runId: "r-1",
    messages: [{ id: "m1", role: "user", content: "I was double charged" }],
    tools: [],
    context: [],
    state: {},
    forwardedProps: {},
  }),
});
// response.body streams AG-UI events: RUN_STARTED, TEXT_MESSAGE_*, STATE_*, RUN_FINISHED, ...

未认证的请求获得 HTTP 401; a ServiceError 从入境行动到 RUN_ERROR 带有服务错误代码的事件.

入境行动

处理器从最后一个用户/工具消息读取意向以及从 forwardedProps.cognate数字 :

投入采取的行动
最后一个消息与 role: "user"开始运行 forwardedProps.cognate.agent (或 defaultAgent; 消息文本和 context 成为运行中的输入; 非空 state 种子共享状态
最后一个消息与 role: "tool"解决前端可操作性或远程出价续作 toolCallId 与解析 content
forwardedProps.cognate.resolve解决续作continuationId, (中文(简体) ), action "resume"编号 :"cancel", (中文(简体) ), input选项 expectedVersion(中文(简体) )
forwardedProps.cognate.cancel取消线程当前运行
forwardedProps.cognate.cursor从持久事件位置恢复 SSE 流

所有运行开始为一个 AG-UI 线程共享关联 id, 所以即使服务器重启后, 解析/ 取消/ 重新连接到线程最近的运行 。 未知或已过期的光标触发一个完整的再同步( S)RUN_STARTED, (中文(简体) ), MESSAGES_SNAPSHOT, (中文(简体) ), STATE_SNAPSHOT,然后是新的事件。 断开 HTTP 流不会取消持久运行 .

继续绘图

  • 前端能力延续( U)type: "frontend:<capability>"项目作为 TOOL_CALL_START编号 :ARGS编号 :END 与 toolCallId 设置为继用 id; 客户端的 role: "tool" 消息解决了它.
  • A 类 human_approval 继续项目 CUSTOM 已命名的事件 cognate.continuation,使一个通用客户端能够通过 forwardedProps.cognate.resolve。 。 。 .
  • 没有忠实的AG-UI代表项目的续作 CUSTOM cognate.unsupported_interaction和运行 RUN_FINISHED 报告 status: "waiting_unsupported" 改为 "waiting"。 。 。 .
  • 工艺品(AG-UI 1.0无文物活动)项目 CUSTOM cognate.artifact。 。 。 .

事件报道

matrix 全部记录 31 AG-UI 1.0 EventType 数值,每行一行:输出(RUN_STARTED编号 :RUN_FINISHED编号 :RUN_ERROR, (中文(简体) ), TEXT_MESSAGE_*, (中文(简体) ), TOOL_CALL_*, (中文(简体) ), STATE_SNAPSHOT编号 :STATE_DELTA, (中文(简体) ), MESSAGES_SNAPSHOT, (中文(简体) ), CUSTOM和科格纳特尚不能生产的 _CHUNK 手势, ACTIVITY_*, (中文(简体) ), RAW, (中文(简体) ), STEP_*, (中文(简体) ), REASONING_*, (中文(简体) ), SUBAGENT_*),每个都有原因. ignoredFrameworkEvents 列出有意不投影的Cognate事件类型.

为了直接使用, createProjector({ threadId, runId }) 将命令的持久事件折叠成 AG-UI 事件(push附加时 snapshot()编号 :stateOnly() 用于重新连接),以及 threadCorrelationId(threadId) 给出关联 id 组合一条线程.

限制

  • 一个适配器,一个真理的方向:持久相干事件是源;AG-UI输出是投影. AG-UI 客户端除通过外不发送任何记录 RuntimeService 行动.
  • 模式文本流经 TEXT_MESSAGE_*;没有推理/思考通道,亚剂筑巢,或原始事件传递.
  • TOOL_CALL_ARGS (a) 有效载荷被去除后,即成为 {}。 。 。 .

许可证

阿帕奇 - 2.0

版本与发布记录

@godspeedai/cognate-ag-ui 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.22026/11/152 天前
0.9.12026/11/143 天前
0.9.02026/11/0610 天前
0.8.02026/10/2720 天前
0.7.12026/10/2423 天前

关于 @godspeedai/cognate-ag-ui 的常见问题

@godspeedai/cognate-ag-ui 是什么?

AG-UI投影和互操作性适配器:出站事件映射,通过本土授权的入站动作,有重联的SSE端点(spec §24). 内部事件从来不是AG-UI的别名.

如何安装 @godspeedai/cognate-ag-ui?

在项目目录运行 npm install @godspeedai/cognate-ag-ui,或使用 pnpm add / yarn add / bun add。

@godspeedai/cognate-ag-ui 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/godspeedai__cognate-ag-ui 是否存在。

@godspeedai/cognate-ag-ui 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@godspeedai/cognate-ag-ui 可以商用吗?

@godspeedai/cognate-ag-ui 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@godspeedai/cognate-ag-ui 的下载量有多少?

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

@godspeedai/cognate-ag-ui 还在维护吗?

最新版本 0.10.0 发布于 2026/11/16(今天);至今共发布 20 个版本,其中过去 12 个月发布了 20 个;首次发布于 2026/10/09。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。