{server/agui, examples, docs}: support agui

.gitignore

@@ -5,6 +5,8 @@
 
 .vscode/
 .idea/
+node_modules/
+.next/
 *.out
 *.log
 coverage.out
@@ -24,3 +26,4 @@ CLAUDE.md
 *test*.py
 *.db
 .codex
+pnpm-lock.yaml

docs/mkdocs.yml

@@ -24,6 +24,7 @@ nav:
       - Planner: planner.md
       - Event: event.md
   - Debug: debugserver.md
+  - AG-UI: agui.md
   - Observability: observability.md
   - A2A: a2a.md
   - Ecosystem: ecosystem.md
@@ -61,6 +62,7 @@ plugins:
                 - Graph: graph.md
                 - Event: event.md
             - 调试: debugserver.md
+            - AG-UI: agui.md
             - 可观测: observability.md
             - A2A: a2a.md
             - 生态: ecosystem.md

docs/mkdocs/en/agui.md

@@ -0,0 +1,114 @@
+# AG-UI Guide
+
+The AG-UI (Agent-User Interaction) protocol is maintained by the open-source community at [AG-UI Protocol](https://github.com/ag-ui-protocol/ag-ui). It enables agents implemented in different languages, frameworks, and execution environments to deliver the outputs generated during a run to user interfaces through a unified event stream. The protocol tolerates loosely-matched event formats and supports multiple transports including SSE and WebSocket.
+
+`tRPC-Agent-Go` integrates with the AG-UI protocol and provides an SSE server implementation by default. It also supports switching to other communication protocols such as WebSocket through custom `service.Service`, as well as custom extended event translation logic.
+
+## Getting Started
+
+If you already have an agent, you can expose it via AG-UI and start an HTTP service as follows:
+
+```go
+import (
+    "net/http"
+
+    "trpc.group/trpc-go/trpc-agent-go/server/agui"
+)
+
+// Create your agent.
+agent := newAgent()
+// Create the AG-UI server and mount it onto an HTTP route.
+server, err := agui.New(agent, agui.WithPath("/agui"))
+if err != nil {
+    log.Fatalf("create agui server failed: %v", err)
+}
+// Start the HTTP server.
+if err := http.ListenAndServe("127.0.0.1:8080", server.Handler()); err != nil {
+    log.Fatalf("server stopped with error: %v", err)
+}
+```
+
+See the full example at [examples/agui/server/default](https://github.com/trpc-group/trpc-agent-go/tree/main/examples/agui/server/default).
+
+On the client side you can pair this with frameworks such as [CopilotKit](https://github.com/CopilotKit/CopilotKit), which provides React/Next.js components and built-in SSE subscriptions for AG-UI streams.
+
+[examples/agui/client/copilotkit](https://github.com/trpc-group/trpc-agent-go/tree/main/examples/agui/client/copilotkit) uses CopilotKit to build a Web UI interface and communicate with the Agent through the AG-UI protocol. The effect is shown in the figure below.
+
+![copilotkit](../assets/img/agui/copilotkit.png)
+
+## Advanced Usage
+
+### Custom transport (`service.Service`)
+
+The AG-UI protocol does not mandate a specific transport. This framework uses SSE as the default. If you want to switch to WebSocket or other protocols, implement the `service.Service` interface yourself:
+
+```go
+import "trpc.group/trpc-go/trpc-agent-go/server/agui"
+
+type wsService struct{}
+
+func (s *wsService) Handler() http.Handler { /* register WebSocket and stream events */ }
+
+server, _ := agui.New(agent, agui.WithService(&wsService{}))
+```
+
+### Custom translator
+
+The default `translator.New` converts internal events into the canonical AG-UI events. To augment the stream while keeping the default behaviour, implement the `translator.Translator` interface and use AG-UI `Custom` events to carry extra information:
+
+```go
+import (
+    aguievents "github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events"
+    agentevent "trpc.group/trpc-go/trpc-agent-go/event"
+    "trpc.group/trpc-go/trpc-agent-go/server/agui"
+    "trpc.group/trpc-go/trpc-agent-go/server/agui/adapter"
+    aguirunner "trpc.group/trpc-go/trpc-agent-go/server/agui/runner"
+    "trpc.group/trpc-go/trpc-agent-go/server/agui/translator"
+)
+
+type customTranslator struct {
+    inner translator.Translator
+}
+
+func (t *customTranslator) Translate(evt *agentevent.Event) ([]aguievents.Event, error) {
+    out, err := t.inner.Translate(evt)
+    if err != nil {
+        return nil, err
+    }
+    if payload := buildCustomPayload(evt); payload != nil {
+        out = append(out, aguievents.NewCustomEvent("trace.metadata", aguievents.WithValue(payload)))
+    }
+    return out, nil
+}
+
+func buildCustomPayload(evt *agentevent.Event) map[string]any {
+    if evt == nil || evt.Response == nil {
+        return nil
+    }
+    return map[string]any{
+        "object":    evt.Response.Object,
+        "timestamp": evt.Response.Timestamp,
+    }
+}
+
+factory := func(input *adapter.RunAgentInput) translator.Translator {
+    return &customTranslator{inner: translator.New(input.ThreadID, input.RunID)}
+}
+
+server, _ := agui.New(agent, agui.WithAGUIRunnerOptions(aguirunner.WithTranslatorFactory(factory)))
+```
+
+### Custom `UserIDResolver`
+
+By default every request maps to the fixed session `"user"`. Override `UserIDResolver` to derive the user ID from `RunAgentInput`:
+
+```go
+resolver := func(ctx context.Context, input *adapter.RunAgentInput) (string, error) {
+    if user, ok := input.ForwardedProps["userId"].(string); ok && user != "" {
+        return user, nil
+    }
+    return "anonymous", nil
+}
+
+server, _ := agui.New(agent, agui.WithAGUIRunnerOptions(aguirunner.WithUserIDResolver(resolver)))
+```

docs/mkdocs/zh/agui.md

@@ -0,0 +1,114 @@
+# AG-UI 使用指南
+
+AG-UI（Agent-User Interaction）协议由开源社区 [AG-UI Protocol](https://github.com/ag-ui-protocol/ag-ui) 维护，旨在让不同语言、不同框架、不同执行环境的智能体，都能够通过统一的事件流把一次执行过程中产生的内容传递给用户界面，允许松散的事件格式匹配，支持 SSE 和 WebSocket 等多种通信协议。
+
+`tRPC-Agent-Go` 接入了 AG-UI 协议，默认提供 SSE 服务端实现，同时也支持通过自定义 `service.Service` 切换到 WebSocket 等其他通信协议，以及自定义扩展事件翻译逻辑。
+
+## 快速上手
+
+假设你已经实现了一个 Agent，可以如下所示接入 AG-UI 协议并启动服务：
+
+```go
+import (
+    "net/http"
+
+    "trpc.group/trpc-go/trpc-agent-go/server/agui"
+)
+
+// 创建 Agent
+agent := newAgent()
+// 创建 AG-UI 服务，指定 HTTP 路由
+server, err := agui.New(agent, agui.WithPath("/agui"))
+if err != nil {
+    log.Fatalf("create agui server failed: %v", err)
+}
+// 启动 HTTP 服务
+if err := http.ListenAndServe("127.0.0.1:8080", server.Handler()); err != nil {
+    log.Fatalf("server stopped with error: %v", err)
+}
+```
+
+完整代码示例参见 [examples/agui/server/default](https://github.com/trpc-group/trpc-agent-go/tree/main/examples/agui/server/default)。
+
+在前端侧，可以配合 [CopilotKit](https://github.com/CopilotKit/CopilotKit) 等支持 AG-UI 协议的客户端框架，它提供 React/Next.js 组件并内置 SSE 订阅能力。
+
+[examples/agui/client/copilotkit](https://github.com/trpc-group/trpc-agent-go/tree/main/examples/agui/client/copilotkit) 使用 CopilotKit 搭建了 Web UI 界面，通过 AG-UI 协议与 Agent 通信，效果如下图所示。
+
+![copilotkit](../assets/img/agui/copilotkit.png)
+
+## 进阶用法
+
+### 自定义传输层（`service.Service`）
+
+AG-UI 协议未强制规定通信协议，框架使用 SSE 作为 AG-UI 的默认通信协议，如果希望改用 WebSocket 等其他协议，可以实现 `service.Service` 接口：
+
+```go
+import "trpc.group/trpc-go/trpc-agent-go/server/agui"
+
+type wsService struct{}
+
+func (s *wsService) Handler() http.Handler { /* 注册 WebSocket 并写入事件 */ }
+
+server, _ := agui.New(agent, agui.WithService(&wsService{}))
+```
+
+### 自定义 Translator
+
+默认的 `translator.New` 会把内部事件翻译成协议里定义的标准事件集。若想在保留默认行为的基础上追加自定义信息，可以实现 `translator.Translator` 接口，并借助 AG-UI 的 `Custom` 事件类型携带扩展数据：
+
+```go
+import (
+    aguievents "github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events"
+    agentevent "trpc.group/trpc-go/trpc-agent-go/event"
+    "trpc.group/trpc-go/trpc-agent-go/server/agui"
+    "trpc.group/trpc-go/trpc-agent-go/server/agui/adapter"
+    aguirunner "trpc.group/trpc-go/trpc-agent-go/server/agui/runner"
+    "trpc.group/trpc-go/trpc-agent-go/server/agui/translator"
+)
+
+type customTranslator struct {
+    inner translator.Translator
+}
+
+func (t *customTranslator) Translate(evt *agentevent.Event) ([]aguievents.Event, error) {
+    out, err := t.inner.Translate(evt)
+    if err != nil {
+        return nil, err
+    }
+    if payload := buildCustomPayload(evt); payload != nil {
+        out = append(out, aguievents.NewCustomEvent("trace.metadata", aguievents.WithValue(payload)))
+    }
+    return out, nil
+}
+
+func buildCustomPayload(evt *agentevent.Event) map[string]any {
+    if evt == nil || evt.Response == nil {
+        return nil
+    }
+    return map[string]any{
+        "object":    evt.Response.Object,
+        "timestamp": evt.Response.Timestamp,
+    }
+}
+
+factory := func(input *adapter.RunAgentInput) translator.Translator {
+    return &customTranslator{inner: translator.New(input.ThreadID, input.RunID)}
+}
+
+server, _ := agui.New(agent, agui.WithAGUIRunnerOptions(aguirunner.WithTranslatorFactory(factory)))
+```
+
+### 自定义 `UserIDResolver`
+
+默认所有请求都会归到固定的 `"user"` 会话，可以通过自定义 `UserIDResolver` 从 `RunAgentInput` 中提取 `UserID`：
+
+```go
+resolver := func(ctx context.Context, input *adapter.RunAgentInput) (string, error) {
+    if user, ok := input.ForwardedProps["userId"].(string); ok && user != "" {
+        return user, nil
+    }
+    return "anonymous", nil
+}
+
+server, _ := agui.New(agent, agui.WithAGUIRunnerOptions(aguirunner.WithUserIDResolver(resolver)))
+```

examples/agui/README.md

@@ -0,0 +1,26 @@
+# AG-UI Examples
+
+This folder collects runnable demos that showcase how to integrate the `tRPC-Agent-Go` AG-UI server and various clients.
+
+- [`client/`](client/) – Client-side samples.
+- [`server/`](server/) – Server-side samples.
+
+## Quick Start
+
+1. Start the default AG-UI server:
+
+```bash
+go run ./server/default
+```
+
+2. In another terminal start the CopilotKit client:
+
+```bash
+cd ./client/copilotkit
+pnpm install
+pnpm dev
+```
+
+3. Ask a question such as `Calculate 2*(10+11)` and watch the live event stream in the terminal. A full transcript example is documented in [`client/copilotkit/README.md`](client/copilotkit/README.md).
+
+See the individual README files under `client/` and `server/` for more background and configuration options.

examples/agui/client/README.md

@@ -0,0 +1,8 @@
+# AG-UI Clients
+
+This directory collects runnable clients that can talk to the AG-UI SSE server examples.
+
+## Available Clients
+
+- [copilotkit/](copilotkit/) – Next.js web UI powered by CopilotKit.
+- [bubbletea/](bubbletea/) – Terminal interface built with Bubble Tea.

examples/agui/client/bubbletea/README.md

@@ -0,0 +1,54 @@
+# Bubble Tea AG-UI Client
+
+This sample uses [Bubble Tea](https://github.com/charmbracelet/bubbletea) to present a terminal chat UI that consumes the AG-UI SSE stream exposed by the example server. Events are rendered as soon as they arrive so you can watch the agent reason step by step.
+
+## Run the Client
+
+From `examples/agui`:
+
+```bash
+go run ./client/bubbletea/
+```
+
+You can customise the endpoint with `--endpoint` if the server is hosted elsewhere.
+
+## Sample Output
+
+The client streams every AG-UI event. Submitting `calculate 1.2+3.5` produces output like the following (truncated IDs for clarity):
+
+```text
+Simple AG-UI Client. Press Ctrl+C to quit.
+You> calculate 1.2+3.5
+Agent> [RUN_STARTED]
+Agent> [TEXT_MESSAGE_START]
+Agent> [TEXT_MESSAGE_CONTENT] 我来
+Agent> [TEXT_MESSAGE_CONTENT] 帮
+Agent> [TEXT_MESSAGE_CONTENT] 您
+Agent> [TEXT_MESSAGE_CONTENT] 计算
+Agent> [TEXT_MESSAGE_CONTENT] 1
+Agent> [TEXT_MESSAGE_CONTENT] .
+Agent> [TEXT_MESSAGE_CONTENT] 2
+Agent> [TEXT_MESSAGE_CONTENT]  +
+Agent> [TEXT_MESSAGE_CONTENT] 3
+Agent> [TEXT_MESSAGE_CONTENT] .
+Agent> [TEXT_MESSAGE_CONTENT] 5
+Agent> [TEXT_MESSAGE_CONTENT] 。
+Agent> [TOOL_CALL_START] tool call 'calculator' started, id: call_...
+Agent> [TOOL_CALL_ARGS] tool args: {"a":1.2,"b":3.5,"operation":"plus"}
+Agent> [TOOL_CALL_END] tool call completed, id: call_...
+Agent> [TOOL_CALL_RESULT] tool result: {"result":4.7}
+Agent> [TEXT_MESSAGE_START]
+Agent> [TEXT_MESSAGE_CONTENT] 1
+Agent> [TEXT_MESSAGE_CONTENT] .
+Agent> [TEXT_MESSAGE_CONTENT] 2
+Agent> [TEXT_MESSAGE_CONTENT]  +
+Agent> [TEXT_MESSAGE_CONTENT] 3
+Agent> [TEXT_MESSAGE_CONTENT] .
+Agent> [TEXT_MESSAGE_CONTENT] 5
+Agent> [TEXT_MESSAGE_CONTENT]  =
+Agent> [TEXT_MESSAGE_CONTENT] 4
+Agent> [TEXT_MESSAGE_CONTENT] .
+Agent> [TEXT_MESSAGE_CONTENT] 7
+Agent> [TEXT_MESSAGE_END]
+Agent> [RUN_FINISHED]
+```