cloudwego / cloudwego/eino-ext

feat: 支持 Eino 原生消息类型与 AG-UI 协议之间的双向转换

Open
#881 1 comment 0 reactions 0 assignees View on GitHub

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_STARTTEXT_MESSAGE_CONTENT (delta) → TEXT_MESSAGE_END
schema.Message.ToolCalls TOOL_CALL_STARTTOOL_CALL_ARGSTOOL_CALL_END
schema.Message (role=tool) TOOL_CALL_RESULT
schema.AgenticMessageContentBlock (AssistantGenText) TEXT_MESSAGE_* 事件序列
schema.AgenticMessageContentBlock (FunctionToolCall) TOOL_CALL_* 事件序列
schema.AgenticMessageContentBlock (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

  1. 手动编写转换代码:在业务层自行实现 Eino 消息到 AG-UI 事件的映射。问题在于每个项目都需要重复编写,且流式场景下的分片拼接、ToolCall 生命周期状态管理等细节容易出错。

  2. 使用 Eino 自带的 A2UI 方案:Eino quickstart 示例中提供了一套业务层的 A2UI 渲染方案,但它是 Eino 自定义的协议,并非行业标准,无法与 CopilotKit、Microsoft Agent Framework 等生态互通。

  3. 等待社区 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.