cloudwego / cloudwego/eino-ext
feat: 支持 Eino 原生消息类型与 AG-UI 协议之间的双向转换
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 813
- Forks
- 368
- Avg merge
- 16h 22m
- Merged PRs (30d)
- 13
Description
Is your feature request related to a problem? Please describe.
目前 Eino 框架缺少与 AG-UI(Agent-User Interaction Protocol) 的集成支持。AG-UI 是由 CopilotKit 发起的开放协议,已被 Microsoft Agent Framework、Amazon Bedrock AgentCore 等采纳,正在成为 AI Agent 与前端应用之间实时通信的行业标准。
当前如果要将 Eino Agent 接入任何 AG-UI 兼容的前端(如 CopilotKit React/Angular 客户端),开发者需要手动编写大量的协议转换代码,将 schema.Message / schema.AgenticMessage 与 AG-UI 的 17 种事件类型逐一映射。这不仅工作量大,还容易遗漏边界情况(如流式分片、ToolCall 生命周期管理等)。
Describe the solution you'd like
希望在 eino-ext 中提供一个 AG-UI 协议适配层,实现 Eino 原生消息类型与 AG-UI 协议事件之间的双向转换,使 Eino Agent 能以标准化方式对接任何 AG-UI 兼容的前端应用。
核心能力包括:
1. Eino → AG-UI(Agent 输出转前端事件流)
| Eino 类型 | AG-UI 事件 |
|---|---|
schema.Message (role=assistant) 流式输出 |
TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT (delta) → TEXT_MESSAGE_END |
schema.Message.ToolCalls |
TOOL_CALL_START → TOOL_CALL_ARGS → TOOL_CALL_END |
schema.Message (role=tool) |
TOOL_CALL_RESULT |
schema.AgenticMessage 的 ContentBlock (AssistantGenText) |
TEXT_MESSAGE_* 事件序列 |
schema.AgenticMessage 的 ContentBlock (FunctionToolCall) |
TOOL_CALL_* 事件序列 |
schema.AgenticMessage 的 ContentBlock (FunctionToolResult) |
TOOL_CALL_RESULT |
| Agent Runner 生命周期 | RUN_STARTED / RUN_FINISHED / RUN_ERROR |
2. AG-UI → Eino(前端输入转 Agent 消息)
| AG-UI 输入 | Eino 类型 |
|---|---|
RunAgentInput.messages |
[]*schema.Message 或 []*schema.AgenticMessage |
RunAgentInput.tools |
[]*schema.ToolInfo |
TOOL_CALL_RESULT 事件 |
schema.ToolMessage() |
| Text message (role=user) | schema.UserMessage() / schema.UserAgenticMessage() |
3. 传输层
- 提供基于 SSE(Server-Sent Events)的默认实现
- 支持 HTTP handler 集成,兼容 Hertz / net/http 等框架
- 可选支持 WebSocket 传输
期望的使用方式(伪代码):
import "github.com/cloudwego/eino-ext/protocols/agui"
// 将 Eino Agent 包装为 AG-UI 兼容的 HTTP handler
handler := agui.NewHandler(myEinoAgent, &agui.Config{
// 配置选项
})
// 注册到 HTTP 路由
router.POST("/api/copilotkit", handler.ServeHTTP)
Describe alternatives you've considered
-
手动编写转换代码:在业务层自行实现 Eino 消息到 AG-UI 事件的映射。问题在于每个项目都需要重复编写,且流式场景下的分片拼接、ToolCall 生命周期状态管理等细节容易出错。
-
使用 Eino 自带的 A2UI 方案:Eino quickstart 示例中提供了一套业务层的 A2UI 渲染方案,但它是 Eino 自定义的协议,并非行业标准,无法与 CopilotKit、Microsoft Agent Framework 等生态互通。
-
等待社区 Go AG-UI SDK 成熟后再封装:目前 AG-UI 官方仅提供 TypeScript 和 Python SDK,Go SDK 仍处于社区早期阶段。但 eino-ext 可以不依赖外部 Go SDK,直接按 AG-UI 协议规范实现转换层——协议本身是基于 SSE 的简单 JSON 事件流,实现成本可控。
Additional context
- AG-UI 协议规范:https://docs.ag-ui.com/introduction
- AG-UI GitHub 仓库:https://github.com/ag-ui-protocol/ag-ui
- AG-UI 事件类型详细定义:https://docs.ag-ui.com/concepts/events
- 相关协议生态:AG-UI 定位于 Agent↔User 通信层,与 MCP(Agent↔Tool)和 A2A(Agent↔Agent)互补,三者共同构成完整的 Agent 协议栈。eino-ext 已有 MCP 集成(
components/tool/mcp),AG-UI 的加入将补齐 Agent 面向前端的最后一环。 - 社区 Go SDK 现状:AG-UI 官方目前提供 TypeScript 和 Python SDK,Go 社区 SDK 仍在发展中。eino-ext 提供官方 Go 实现将填补这一空白,对整个 Go Agent 生态也有很大价值。
- 参考:本仓库已有的 A2A 协议讨论 (#468)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing components/tool/mcp integration and the referenced A2A discussion (#468), then read the linked AG-UI protocol and event definitions. Define the conversion scope for Eino messages, tool calls, lifecycle events, and SSE/HTTP handling. Done means the requested bidirectional mappings and default SSE handler are implemented with coverage for the listed streaming and tool-call cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- ai, api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100