# @godspeedai/cognate-ag-ui 中文文档

规范地址：https://npmcn.com/package/%40godspeedai/cognate-ag-ui/

版本：0\.10\.0
npm 元数据更新时间：2026-11-16T03:36:15.877Z
中文译文更新时间：2026-11-16T18:01:09.490Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：55.6 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：5 个
- 首次发布：2026-10-09T02:26:35.032Z
- 最新版本发布：2026-11-16T03:36:15.472Z
- 近 30 天下载量：3279（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

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

## 安装

```sh
npm install @godspeedai/cognate-ag-ui
```

也可以使用：`pnpm add @godspeedai/cognate-ag-ui`、`yarn add @godspeedai/cognate-ag-ui`、`bun add @godspeedai/cognate-ag-ui`

## README

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

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

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

## 安装

```sh
bun add @godspeedai/cognate-ag-ui
```

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

## 快开始

```ts
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流:

```ts
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) 有效载荷被去除后,即成为 `{}`。 。 。 .

## 相关软件包

-   [`@godspeedai/cognate-react`](https://www.npmjs.com/package/@godspeedai/cognate-react) 财务报告和审定财务报表 [`@godspeedai/cognate-ui-astryx`](https://www.npmjs.com/package/@godspeedai/cognate-ui-astryx) ——无头反应约束和参考UI对同一份客户合同.
-   [`@godspeedai/cognate-a2a`](https://www.npmjs.com/package/@godspeedai/cognate-a2a) ——A2A协议适配器.
-   [`@godspeedai/cognate-profile-copilot`](https://www.npmjs.com/package/@godspeedai/cognate-profile-copilot) ——基于此端点的由构成的交互式聊天应用程序.
-   [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) SDK伞.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @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 和提交记录判断。

