tRPC-Agent-Go 教程：用 Go 构建可运行、可观测、可评测的生产级 Agent 系统

tRPC-Agent-Go 更接近 Go 服务团队真正需要的 Agent 运行时，而不是“又一个聊天机器人脚手架”。它把 LLM Agent、Graph 工作流、工具调用、Session/Memory、Knowledge、Evaluation、OpenTelemetry、A2A、AG-UI、MCP 放进同一套 Go-native 结构里，讨论的是 Agent 如何作为后端服务长期运行。

tRPC-Agent-Go 的价值不在于把 LangChain 的概念翻译成 Go，而在于它把 Agent 当成生产服务来设计。Go 团队关心的不是 demo 能不能回答问题，而是取消、超时、流式事件、会话存储、并发、可观测性、协议边界、工具权限和评测闭环能不能进入工程体系。这也是它比普通 Agent demo 更接近生产框架的原因。

为什么它适合进入工程视野

很多 Agent 框架的入门路径是：定义一个 prompt，接一个模型，注册几个工具，然后演示一段对话。问题是，真实业务不会停在这里。客户支持、DevOps 自动化、数据分析助手、企业流程机器人都会很快遇到同样的问题：一次运行怎么取消？多轮状态存哪里？工具执行过程怎么审计？前端怎么接事件流？另一个 Agent 怎么调用我？质量下降怎么发现？

tRPC-Agent-Go 的 README 和文档树显示，它把这些问题直接作为一等模块处理：runner、session、memory、graph、tool、server/a2a、server/agui、evaluation、telemetry、skill、knowledge 都是独立包。最新 release v1.10.0 还继续强化了 OpenTelemetry 消息属性、GraphAgent trace、tool result 对齐、prompt iteration、case-level rubrics、distributed cancel 等生产细节。

快速判断：你是不是它的目标用户

你主要用 Go 写后端服务，希望 Agent 逻辑和已有服务部署、监控、context cancellation 保持一致。
你需要的不只是单 Agent 对话，而是多步骤工作流、工具调用、并行/串行 Agent 协作或图编排。
你希望前端能通过 AG-UI 接收流式事件，也可能通过 A2A 把 Agent 暴露给其他系统。
你关心长期质量：评测集、指标、trace、session、memory，而不是只跑一次 demo。
你接受框架复杂度。这个项目覆盖面很宽，小工具或一次性脚本未必需要它。

最小模型：Agent、Runner、Event

理解 tRPC-Agent-Go，先抓住三个对象。Agent 描述“会做什么”；Runner 负责把用户、会话、消息和 Agent 执行串起来；Event 是运行过程的输出单位。这个拆分非常 Go：Agent 不直接变成全局黑盒，Runner 承担生命周期和会话边界，事件流则让 CLI、HTTP、AG-UI 前端都能消费同一套执行过程。

modelInstance := openai.New("gpt-4o-mini")

llmAgent := llmagent.New(
    "support-agent",
    llmagent.WithModel(modelInstance),
    llmagent.WithDescription("A support assistant with tools."),
    llmagent.WithInstruction("Use tools when facts must be checked."),
    llmagent.WithTools([]tool.Tool{calculatorTool, timeTool}),
)

r := runner.NewRunner(
    "support-app",
    llmAgent,
    runner.WithSessionService(sessioninmemory.NewSessionService()),
)

events, err := r.Run(ctx, "user-1", "session-1", model.NewUserMessage("help me"))
for ev := range events {
    if ev.Error != nil { /* handle */ }
    if ev.Done { break }
}

这段结构的重点不是代码长短，而是边界清楚：模型可以换，SessionService 可以从内存换成 Redis/MySQL/Postgres，工具可以是函数、MCP、OpenAPI 或自定义服务，事件消费端也可以从终端换成 Web 前端。

工具层：不要把工具调用当成魔法

tRPC-Agent-Go 支持 Function Tool、MCP Tool、文件、代码执行、Web fetch、OpenAPI 等工具形态。教程里最应该强调的是权限和过滤，而不是“模型能调用工具了”。官方示例里 MCP toolset 会显式配置 transport、server URL、timeout、tool filter 和 retry，这比把一个工具服务器整包暴露给模型安全得多。

stdioToolSet := mcp.NewMCPToolSet(
    mcp.ConnectionConfig{
        Transport: "stdio",
        Command:   "go",
        Args:      []string{"run", "./stdioserver/main.go"},
        Timeout:   10 * time.Second,
    },
    mcp.WithToolFilterFunc(tool.NewIncludeToolNamesFilter("echo", "add")),
)
_ = stdioToolSet.Init(ctx)

生产建议很直接：只暴露任务需要的工具；给远程 MCP 设置超时和重试；高风险工具做审批或沙箱；把工具参数、结果和错误纳入 trace。Agent 出错时，很多时候不是模型差，而是工具边界太松。

GraphAgent：适合把工作流从 prompt 里拿出来

如果一个流程有明确阶段，就不要全部塞进 system prompt。tRPC-Agent-Go 的 GraphAgent 把节点、边、条件路由、中断、checkpoint、resume 做成图工作流。它的意义类似 LangGraph，但目标是 Go 服务：类型、context、并发、可观测性和部署方式更贴近后端团队。

客服场景：分类 → 查知识库 → 必要时查订单 → 生成答复 → 人工复核。
DevOps 场景：读取告警 → 拉取指标 → 判断影响面 → 生成变更建议 → 等待审批 → 执行回滚。
数据分析场景：理解问题 → 生成 SQL → 执行 → 校验结果 → 输出报告。

Graph 的好处是每一步都能测试、记录和复用。它不会让业务复杂度消失，但会避免复杂度躲在一段越来越长的 prompt 里。

AG-UI、A2A、MCP：三条边界不要混

这个项目同时支持多个协议，很容易看花。可以这样区分：MCP 是工具协议，让 Agent 调外部工具；AG-UI 是前端事件协议，让用户界面实时看到 Agent 运行；A2A 是 Agent 间互操作协议，把一个 Agent 暴露成另一个 Agent 能调用的服务。三者不是互相替代，而是位于不同边界。

MCP：解决“我能调用哪些工具”。
AG-UI：解决“用户界面如何接收流式过程、历史和取消”。
A2A：解决“另一个 Agent 如何发现并调用我”。

tRPC-Agent-Go 的 A2A 文档还特别强调：A2A 原本是黑盒协作协议，内部工具调用、reasoning、code execution 这些 trace 信息应通过扩展能力谨慎暴露。这一点很成熟，因为企业多 Agent 协作最怕把内部执行细节无边界地传给外部系统。

评测和可观测性：Agent 上线后的主战场

Agent 系统上线后，最难的不是第一次跑通，而是持续知道它有没有变坏。tRPC-Agent-Go 把 Evaluation、Metrics、OpenTelemetry、Langfuse 示例放进框架，是它比普通 demo 框架更值得关注的地方。你可以为关键任务建 eval set，做多次运行，比较整体 status、case-level rubric 和 trace。

实际落地时，我建议把评测分三层：第一层是工具契约测试，确保工具参数和返回稳定；第二层是任务级 eval，覆盖典型用户问题；第三层是线上 trace 抽检，关注取消、超时、工具失败、上下文过长和 session summary。没有这三层，Agent 很容易在一次模型升级或 prompt 改动后悄悄退化。

落地路线

第一步：只做一个 Runner + LLMAgent + 两三个只读工具，跑通 session 和事件处理。
第二步：把关键工具接入 MCP 或 function tool，并加超时、过滤、日志和错误处理。
第三步：把确定性流程迁移到 GraphAgent，不要继续堆 prompt。
第四步：接 AG-UI 或自有 SSE/WebSocket 前端，支持取消和历史。
第五步：用 Evaluation 固化验收集，用 OpenTelemetry/Langfuse 观察真实运行。
第六步：需要跨 Agent 协作时再引入 A2A，不要一开始就把协议面铺太大。

风险和取舍

tRPC-Agent-Go 的覆盖面很大，这既是优点也是成本。团队需要理解 Agent、Runner、Session、Tool、Graph、Protocol、Evaluation 之间的边界，否则容易把框架当成一个万能黑盒。另一个取舍是生态：Python/TypeScript Agent 框架的第三方教程更多，Go 生态则胜在服务化和并发模型。

我的判断是：如果你要做的是长期运行、需要审计、需要和后端服务深度集成的 Agent 系统，tRPC-Agent-Go 值得认真评估。如果只是做一个内容生成脚本、内部小助手或概念验证，它可能偏重。

结论

tRPC-Agent-Go 有价值的地方，是把 Agent 从“会聊天的 demo”拉回到“可运行的软件服务”。它关心工具边界、会话、事件、取消、图工作流、评测、观测和协议互操作。这些东西不酷，但它们决定了 Agent 能不能真的进入生产。对于 Go 团队来说，这比再多一个 prompt 模板库更重要。