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

Flash-LHR · 2025-09-18T06:32:42Z

No description provided.

codecov · 2025-09-18T06:33:52Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.94735%. Comparing base (d286d8d) to head (2fa5e13).
⚠️ Report is 190 commits behind head on main.

Additional details and impacted files

@@                 Coverage Diff                  @@
##                main        #379          +/-   ##
====================================================
+ Coverage   58.42422%   74.94735%   +16.52313%     
====================================================
  Files             97         142          +45     
  Lines          12286       21367        +9081     
====================================================
+ Hits            7178       16014        +8836     
+ Misses          4608        4457         -151     
- Partials         500         896         +396

Flag	Coverage Δ
unittests	`74.94735% <ø> (+16.52313%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

sandyskies · 2025-09-18T06:59:34Z

server/agui/go.mod

@@ -0,0 +1,37 @@
+module trpc.group/trpc-go/trpc-agent-go/server/agui
+
+go 1.24.4


注意下go 版本

AGUI GO SDK 使用了 go1.24.4，因此给 agui 打了个 gomod
https://github.com/ag-ui-protocol/ag-ui/pull/339/files#diff-5b94013923af92d1340c95388546e1783d73fdc13ca8d17b6f5e7e05e0d2b0ba

sandyskies · 2025-09-21T01:43:15Z

server/agui/runner/runner.go

+}
+
+// New wraps a trpc-agent-go runner with AG-UI specific translation logic.
+func New(r trunner.Runner, opt ...Option) Runner {


这个还要单独封装一个runner吗，如果用户自己创建runner，并添加memory和session，这个和用户的不是有冲突？
是不是反过来，和memory，session一样，通过runner传入

这里封装的 AGUI Runner 不会和用户自定义的 Runner 产生冲突，原因：

New 接收用户自定义的 Runner，memory/session 逻辑由用户在自己的 Runner 中实现，AG-UI Runner 相当于 Wrap 了自定义 Runner，只做事件翻译，不会覆盖 memory/session 逻辑。

AGUI Runner 与 Runner 的 Option 类型不互通，不支持传入 memory/session

之所以抽象出 AGUI Runner 接口，是为了让用户根据需要换成本地实现（例如 mock AGUI 事件输出）。

sandyskies · 2025-09-25T09:33:13Z

examples/agui/client/bubbletea/ui.go

+	"github.com/charmbracelet/bubbles/spinner"
+	"github.com/charmbracelet/bubbles/textinput"
+	"github.com/charmbracelet/bubbles/viewport"
+	tea "github.com/charmbracelet/bubbletea"


这个是什么，会不会有点不好理解

bubbletea是 CLI 开发框架，这个 example 演示了 client 如何自己解析 AGUI 协议。
另外，还使用 CopilotKit 开发了一个 web ui 作为 client，在另一个 example。

UPDATE：移除了 bubbletea，提供了最小样例

sandyskies · 2025-09-25T09:35:56Z

examples/agui/server/default/main.go

+	if err != nil {
+		log.Fatalf("failed to create AG-UI server: %v", err)
+	}
+	if err := server.Serve(context.Background()); err != nil {


ip port要如何设置、

~~通过 WithAddress 和 WithPath 设置，在 example 中显式写出来了~~

UPDATE
address(ipport)在http.ListenAndServe(*address, server.Handler())中指定，见最新的 server example

WineChord · 2025-09-26T01:30:07Z

server/agui/event/event.go

+}
+
+// NewBridge creates a new event bridge.
+func NewBridge(threadID, runID string) Bridge {


Bridge 这些相关的看上去可以放到 internal

agui 有一种 custom event 类型，抽象出 Bridge interface 可以让用户自行处理自定义 event 的转换

WineChord · 2025-09-26T01:32:03Z

server/agui/agui.go

+}
+
+// New creates a AG-UI server instance.
+func New(agent agent.Agent, opt ...Option) (*Server, error) {


除了这个 agui.New 之外，service package 和 runner package 这些是不是都可以放到 internal？

agui 协议没有规定 transport，框架提供了 sse 实现，也可以有 websocket/私有协议实现，所以抽象出 service interface，支持协议扩展。

WineChord · 2025-09-26T01:33:43Z

server/agui/options.go

+}
+
+// WithSessionService sets the session service.
+func WithSessionService(svc session.Service) Option {


这里不太好，trpc-agent-go 的 runner 还有其他 option，不只有 session service 的 option，你要在这里一一复刻一遍吗？

去除WithSessionService了，使用WithRunnerOptions统一设置 runner 的 option

为什么不考虑在原来的runner里面去传入ag-ui相关的东西？

AGUI要启动一个服务，如果通过通过 runner 传递的话，拿不到 HTTP handler

AGUI 与 A2A/DebugServer 类似，都是向外提供服务，放在 server 下面，使用方法应该相近

WineChord · 2025-09-26T01:36:42Z

server/agui/service/sse/sse.go

+}
+
+// Serve starts the SSE service and listens on the address.
+func (s *sse) Serve(ctx context.Context) error {


serve 这里可以考虑监听 ctx.Done 来对 server 做 shutdown 操作

否则传入的 ctx 就没有什么用了

刚才更新了，去除了 Serve/Close 方法，改用 Handler 方法，能够让用户显式与 trpc 结合

WineChord · 2025-09-26T01:39:15Z

examples/agui/server/default/main.go

+		llmagent.WithGenerationConfig(generationConfig),
+		llmagent.WithInstruction("You are a helpful assistant."),
+	)
+	server, err := agui.New(agent, agui.WithPath(*path))


除了 example 这里用户会使用到的导出方法以外，其他的都要考虑下是否可以放到 internal 中

导出符号整理如下：

package agui

DefaultNewService 变量：service 创建的工厂函数，用于匿名导入覆盖；

package adapter

RunAgentInput 结构体：AG-UI 协议的请求包，自定义 UserIDResolver/TranslatorFactory 时需要用到

package runner

Options 结构体、NewOptions 工厂函数、WithUserIDResolver、WithTranslatorFactory Option。

package service

Service 接口：用于自定义通信协议；

Options 结构体、WithPath Option

package sse

New 方法：用于创建 sse 服务

package translate

Translator 接口与 New 构造器：用于自定义翻译器。

WineChord · 2025-09-26T02:36:29Z

server/agui/service/sse/sse.go

+		o(&opts)
+	}
+	s := &sse{
+		path:   opts.Path,


opts.Path 需要判空兜底默认 /，否则 HandleFunc 那里会 panic

done，默认使用"/"

WineChord · 2025-09-26T02:37:00Z

server/agui/service/sse/sse.go

+}
+
+// handle handles an AG-UI run request.
+func (s *sse) handle(w http.ResponseWriter, r *http.Request) {


需要过滤下 http method，只支持 GET POST

以及 OPTIONS（给 CORS 用）

WineChord · 2025-09-26T02:40:05Z

examples/agui/README.md

+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/bubblecopilotkittea/README.md).


这个路径和实际的不符

This reverts commit afec996.

sandyskies · 2025-09-27T11:53:55Z

server/agui/translator/translator.go

+}
+
+// New creates a new event translator.
+func New(threadID, runID string) Translator {


threadID 指的是啥，go 又没thread

RunAgentInput 是 AGUI协议规定的请求包格式，这些字段都是 AGUI 协议规定的。
其中，ThreadID和RunID分别对应了框架的SessionID和InvcationID

sandyskies · 2025-09-27T11:56:13Z

server/agui/adapter/adapter.go

+// RunAgentInput represents the parameters for an AG-UI run request.
+type RunAgentInput struct {
+	// ThreadID is the ID of the conversation thread, which is the session ID.
+	ThreadID string `json:"threadId"`


为啥不叫session id

RunAgentInput 是 AGUI协议规定的请求包格式，这些字段都是 AGUI 协议规定的。
其中，ThreadID和RunID分别对应了框架的SessionID和InvcationID

sandyskies · 2025-09-27T11:59:59Z

examples/agui/server/default/main.go

+		llmagent.WithModel(modelInstance),
+		llmagent.WithGenerationConfig(generationConfig),
+		llmagent.WithInstruction("You are a helpful assistant."),
+	)


这里有个问题，如果要传入session，或者memory，要怎么做呢？

通过 WithRunnerOptions 传入，例如:

// 创建 AG-UI 服务 server, err := agui.New( agent, agui.WithPath("/agui"), // 指定 HTTP 路由 agui.WithRunnerOptions(runner.WithSessionService(sessionService)), // 注入 Session Service )

文档新增了 Runner 示例

sandyskies · 2025-09-28T10:56:40Z

docs/mkdocs/zh/agui.md

+// 创建 Agent
+agent := newAgent()
+// 创建 AG-UI 服务，指定 HTTP 路由
+server, err := agui.New(agent, agui.WithPath("/agui"))


debugserver：https://github.com/trpc-group/trpc-agent-go/blob/main/server/debug/server.go#L47 New的是server，传入了runner

agui.New 改成了传入 runner

sandyskies · 2025-09-29T07:36:21Z

server/agui/options.go

+)
+
+// options holds the options for the AG-UI server.
+type options struct {


这些还需要保留吗

sandyskies · 2025-09-29T07:40:15Z

server/agui/runner/options.go

+//
+//
+
+package runner


这个还要保留吗

需要的，用户自定义事件需要用到 option，所以要导出。倘若把 Runner option 放到 agui option中，则会有循环依赖的问题。
暂时没有自定义 Runner 实现的需求，所以 Runner 接口定义放到 internal/runner 了。

feat: support agui

d50af9e

Flash-LHR changed the title ~~{server/agui, examples}: support agui~~ [WIP] {server/agui, examples}: support agui Sep 18, 2025

sandyskies reviewed Sep 18, 2025

View reviewed changes

Flash-LHR added 3 commits September 19, 2025 11:48

refactor

c4ec52f

Merge branch 'main' into support-agui

f6d0c59

fix

067afd5

sandyskies reviewed Sep 21, 2025

View reviewed changes

Flash-LHR added 4 commits September 22, 2025 17:13

feat: support DefaultNewService

b83f997

Merge branch 'main' into support-agui

d1bf559

feat: adapter

ba011eb

feat: support non-stream message

dc7c5af

sandyskies reviewed Sep 25, 2025

View reviewed changes

Flash-LHR added 8 commits September 25, 2025 20:10

fix

b939e00

example: add copilokit

dad2ebf

docs

376680b

doc

8f7861d

front

e1214a4

doc

e5bdc2d

doc

2d90ab0

Merge branch 'main' into support-agui

e9a15c6

WineChord reviewed Sep 26, 2025

View reviewed changes

feat: use Handler

6b246c2

WineChord reviewed Sep 26, 2025

View reviewed changes

Flash-LHR added 8 commits September 26, 2025 12:13

refactor

5361c06

only post

d05620b

fix

cbe1424

test

13f40ec

fix

5e2e01e

doc

3113f81

Merge branch 'main' into support-agui

a31d209

typo

be3e701

Flash-LHR changed the title ~~[WIP] {server/agui, examples}: support agui~~ {server/agui, examples}: support agui Sep 26, 2025

Flash-LHR changed the title ~~{server/agui, examples}: support agui~~ {server/agui, examples, docs}: support agui Sep 26, 2025

Flash-LHR added 5 commits September 26, 2025 20:46

fix

6333979

docs

a4cd818

fix

e95347d

refactor: runner

afec996

Revert "refactor: runner"

f5fa1a4

This reverts commit afec996.

sandyskies reviewed Sep 27, 2025

View reviewed changes

Flash-LHR added 3 commits September 28, 2025 11:04

docs

613c887

doc

390ccce

example

783b880

sandyskies reviewed Sep 28, 2025

View reviewed changes

Flash-LHR added 2 commits September 28, 2025 22:54

refactor: runner instead of agent

2a3ed72

test

2fa5e13

sandyskies reviewed Sep 29, 2025

View reviewed changes

server/agui/options.go

)

// options holds the options for the AG-UI server.

type options struct {

Copy link

Contributor

sandyskies Sep 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这些还需要保留吗

sandyskies reviewed Sep 29, 2025

View reviewed changes

sandyskies approved these changes Sep 29, 2025

View reviewed changes

sandyskies merged commit 087c82f into trpc-group:main Sep 29, 2025
7 checks passed

github-actions bot locked and limited conversation to collaborators Sep 29, 2025

		@@ -0,0 +1,37 @@
		module trpc.group/trpc-go/trpc-agent-go/server/agui

		go 1.24.4

Uh oh!

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

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

Uh oh!

Conversation

Flash-LHR commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Flash-LHR Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Flash-LHR Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Flash-LHR commented Sep 18, 2025 •

edited

Loading

codecov bot commented Sep 18, 2025 •

edited

Loading

Flash-LHR Sep 25, 2025 •

edited

Loading

Flash-LHR Sep 26, 2025 •

edited

Loading