@godspeedai/cognate-ag-ui

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

AG-UI projection and interoperability adapter: outbound event mapping, inbound actions through native authorization, SSE endpoint with reconnect (spec §24). Internal events are never AG-UI aliases.

原始使用文档
文档目录8 节
  1. Installation
  2. Quick start
  3. Inbound actions
  4. Continuation mapping
  5. Event coverage
  6. Limitations
  7. Related packages
  8. License

@godspeedai/cognate-ag-ui

AG-UI 1.0 interoperability adapter: projects a Cognate run's durable event stream as schema-valid AG-UI events over SSE, and maps inbound AG-UI actions (messages, tool results, approvals, cancellation) onto the runtime's RuntimeService with the transport-authenticated caller.

When to use this package: an AG-UI client (or any SSE consumer speaking the AG-UI event grammar) should drive your Cognate agent. It is an optional boundary — native Cognate execution and UIs work unchanged without it, and Cognate's internal events are never rewritten as AG-UI aliases. For A2A agents see @godspeedai/cognate-a2a.

Installation

bun add @godspeedai/cognate-ag-ui

Requires Bun >= 1.4.0. Depends on @ag-ui/core, @ag-ui/encoder, and the service types from @godspeedai/cognate-runtime-api; pair it with @godspeedai/cognate-runtime-bun for the runtime itself.

Quick start

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 });

A client POSTs an AG-UI RunAgentInput and reads the SSE stream:

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, ...

Unauthenticated requests get HTTP 401; a ServiceError from an inbound action arrives as a RUN_ERROR event carrying the service error code.

Inbound actions

The handler reads intent from the last user/tool message and from forwardedProps.cognate:

InputAction taken
last message with role: "user"starts a run of forwardedProps.cognate.agent (or defaultAgent); message text and context become the run input; a non-empty state seeds shared state
last message with role: "tool"resolves the frontend-capability or remote-offer continuation addressed by toolCallId with the parsed content
forwardedProps.cognate.resolveresolves a continuation (continuationId, action "resume"/"cancel", input, optional expectedVersion)
forwardedProps.cognate.cancelcancels the thread's current run
forwardedProps.cognate.cursorresumes the SSE stream from a durable event position

All runs started for one AG-UI thread share a correlation id, so resolve/cancel/reconnect route to the thread's most recent run even after a server restart. An unknown or expired cursor triggers a full resync (RUN_STARTED, MESSAGES_SNAPSHOT, STATE_SNAPSHOT, then newer events). Disconnecting the HTTP stream never cancels the durable run.

Continuation mapping

  • A frontend-capability continuation (type: "frontend:<capability>") projects as TOOL_CALL_START/ARGS/END with toolCallId set to the continuation id; the client's role: "tool" message resolves it.
  • A human_approval continuation projects as a CUSTOM event named cognate.continuation, self-sufficient for a generic client to resolve via forwardedProps.cognate.resolve.
  • Continuation kinds with no faithful AG-UI representation project as CUSTOM cognate.unsupported_interaction, and the run's RUN_FINISHED reports status: "waiting_unsupported" instead of "waiting".
  • Artifacts (AG-UI 1.0 has no artifact event) project as CUSTOM cognate.artifact.

Event coverage

matrix documents all 31 AG-UI 1.0 EventType values, one row each: which are produced outbound (RUN_STARTED/RUN_FINISHED/RUN_ERROR, TEXT_MESSAGE_*, TOOL_CALL_*, STATE_SNAPSHOT/STATE_DELTA, MESSAGES_SNAPSHOT, CUSTOM) and which Cognate cannot produce yet (the _CHUNK shorthands, ACTIVITY_*, RAW, STEP_*, REASONING_*, SUBAGENT_*), each with the reason. ignoredFrameworkEvents lists the Cognate event types deliberately not projected.

For direct use, createProjector({ threadId, runId }) folds ordered durable events into AG-UI events (push, plus snapshot()/stateOnly() for reconnects), and threadCorrelationId(threadId) gives the correlation id grouping a thread's runs.

Limitations

  • One adapter, one direction of truth: durable Cognate events are the source; AG-UI output is a projection. Nothing an AG-UI client sends writes history except through RuntimeService actions.
  • Model text streaming arrives via TEXT_MESSAGE_*; there is no reasoning/thinking channel, subagent nesting, or raw event passthrough.
  • TOOL_CALL_ARGS for a completed invocation carries the recorded invocation input; after that payload is erased it becomes {}.

License

Apache-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 projection and interoperability adapter: outbound event mapping, inbound actions through native authorization, SSE endpoint with reconnect (spec §24). Internal events are never AG-UI aliases.

如何安装 @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 和提交记录判断。