trpc-group/trpc-agent-go · 上手攻略

• 仓库：trpc-group/trpc-agent-go
• 链接：https://github.com/trpc-group/trpc-agent-go
• 分类：ai · agent-framework · golang
• 作者：Tom
• 更新：2026-08-09

是什么

tRPC-Agent-Go 是一个 Go 原生的生产级 AI Agent 开发框架，GitHub 星标约 1647（截至 2026-08-09，周增 +21），Apache-2.0 许可证，最近一次提交 2026-08-08（高度活跃）。

核心定位：让 AI Agent 应用符合 Go 服务的要求——并发安全、可观测、易部署，同时支持 A2A、AG-UI、MCP 等主流协议。

一句话类比：LangGraph 的 Go 版本，提供类型安全的图工作流 + 多 Agent 协作 + 工具调用 + 记忆管理 + 自进化 + 评测 + OpenTelemetry 可观测性，在同一个 Go 技术栈内闭环。

同系列还有 trpc-agent-python（Python 版）、trpc-a2a-go（A2A 协议 Go 实现）、trpc-go（tRPC 底层 RPC 框架）。

⚠️ 本框架有大量子包（graph/agent/evaluation/evolution 等），完整目录结构见 GitHub 仓库；安装时按需引入，不需要全量依赖。

解决什么问题

痛点：在 Go 服务里集成 AI Agent 能力缺乏统一框架——现有方案多为 Python（LangChain/LangGraph），与 Go 微服务集成时需要跨语言调用、复杂度高、难以保证并发安全。

解决：提供从单 Agent 到多 Agent 协作、从工具调用到图工作流、从记忆管理到评测迭代的完整 Go 原生框架，与现有 Go 微服务天然亲和，无需额外语言运行时。

快速安装

# 方式一：模块安装（按需引入子包）
go get github.com/trpc-group/trpc-agent-go@latest

# 方式二：clone 示例直接跑
git clone https://github.com/trpc-group/trpc-agent-go.git
cd trpc-agent-go
cd examples && ls   # 查看可用示例

# 查看完整包列表（按需引入）
go list ./... -m

⚠️ 本框架为 monorepo 结构，各子包独立引入，不需要全量安装。例如只需要 GraphAgent 时：

import "github.com/trpc-group/trpc-agent-go/graph"

前提条件： - Go ≥ 1.21（未标注，建议实测） - LLM API（OpenAI / Claude / 本地模型）——框架不绑定特定模型，通过 model 接口抽象

核心用法

1. 创建一个最简单的 LLM Agent

import (
    "github.com/trpc-group/trpc-agent-go/agent"
    "github.com/trpc-group/trpc-agent-go/agent/llmagent"
    "github.com/trpc-group/trpc-agent-go/agent/model"
    "github.com/trpc-group/trpc-agent-go/agent/runner"
)

// 定义一个工具函数
func calculate(expr string) string {
    // 实际业务逻辑
    return "42"
}

// 注册为工具
calculatorTool := function.NewFunctionTool(
    calculate,
    function.WithName("calculator"),
    function.WithDescription("Perform math operations"),
)

// 创建 Agent
myAgent := llmagent.New("assistant",
    llmagent.WithTools(calculatorTool),
    llmagent.WithModel(openAIModel),
)

// 通过 Runner 运行
myRunner := runner.NewRunner("app", myAgent)
events, err := myRunner.Run(ctx, "user-1", "session-1",
    model.NewUserMessage("What is 10 + 32?"),
)

2. 多 Agent 链式编排（Chain）

// 链式执行：analyzer → processor → reporter
pipeline := chainagent.New("pipeline",
    chainagent.WithSubAgents([]agent.Agent{
        analyzer,   // 分析 Agent
        processor,  // 处理 Agent
        reporter,   // 报告 Agent
    }),
)

// Runner 运行链式流程
runner := runner.NewRunner("app", pipeline)
events, _ := runner.Run(ctx, "user-1", "session-1",
    model.NewUserMessage("分析Q2销售数据并生成报告"),
)

3. 并行 Agent 执行

parallel := parallelagent.New("concurrent",
    parallelagent.WithSubAgents(tasks),
)
runner := runner.NewRunner("app", parallel)

4. GraphAgent（图工作流，LangGraph 等效）

GraphAgent 提供类型安全的 DAG（有向无环图）工作流，支持多条件路由：

import "github.com/trpc-group/trpc-agent-go/graph"

g := graph.New("my-workflow")
g.AddNode("start", startNode)
g.AddNode("process", processNode)
g.AddNode("end", endNode)
g.AddEdge("start", "process")
g.AddEdge("process", "end")
// 支持条件路由
g.AddConditionalEdge("process", routeFn, []string{"continue", "abort"})

⚠️ GraphAgent 功能与 LangGraph Python 版对标，但 Go 版 API 细节请以实际代码为准（框架迭代较快，README 示例可能滞后于最新版本）。

5. 记忆与会话状态

// 内存记忆服务
memory := memorysvc.NewInMemoryService()

myAgent := llmagent.New("assistant",
    llmagent.WithTools(memory.Tools()),
    llmagent.WithModel(model),
)

myRunner := runner.NewRunner("app", myAgent,
    runner.WithMemoryService(memory),
)
// Runner 层面注入记忆服务，Agent 自动跨 session 记住上下文

6. Agent Skills（SKILL.md 工作流复用）

import (
    "github.com/trpc-group/trpc-agent-go/skill/skilltool"
    "github.com/trpc-group/trpc-agent-go/skill"
    "github.com/trpc-group/trpc-agent-go/plugin/codeexecutor/localexec"
)

// 加载本地 skills 目录
repo, _ := skill.NewFSRepository("./skills")

// 通过 Skill 工具让 Agent 按需加载和执行 SKILL.md 工作流
tools := []tool.Tool{
    skilltool.NewLoadTool(repo),    // 加载 skill
    skilltool.NewRunTool(repo, localexec.New()),  // 执行 skill
}

Skills 目录结构：

skills/
├── skill-A/
│   └── SKILL.md    # 定义工作流步骤
└── skill-B/
    └── SKILL.md

7. MCP 协议集成（连接外部工具服务器）

import "github.com/trpc-group/trpc-agent-go/plugin/mcptool"

// 连接 MCP 服务器（stdio 或 HTTP）
mcpTool := mcptool.New(serverConn)  // serverConn 为 MCP 协议连接

myAgent := llmagent.New("assistant",
    llmagent.WithTools(mcpTool),
    llmagent.WithModel(model),
)

8. Agent 自进化（Self-Evolution）

import "github.com/trpc-group/trpc-agent-go/evolution"

evo := evolution.NewService(reviewerModel,
    evolution.WithManagedSkillsDir("./managed_skills"),
    evolution.WithSkillRepository(repo),
)
defer evo.Close()

runner := runner.NewRunner("app", myAgent,
    runner.WithEvolutionService(evo),
)
// 完成后自动异步 review session，质量过关的发布为可复用 SKILL

9. 评测（Evaluation）

import "github.com/trpc-group/trpc-agent-go/evaluation"

evaluator, _ := evaluation.New("app", runner,
    evaluation.WithNumRuns(3),  // 每个 case 跑 3 次
)
defer evaluator.Close()

result, _ := evaluator.Evaluate(ctx, "math-basic")
_ = result.OverallStatus  // PASS/FAIL/...

10. OpenTelemetry 可观测性 + Langfuse

import (
    "github.com/trpc-group/trpc-agent-go/plugin/langfuse"
    "go.opentelemetry.io/otel/attribute"
)

clean, _ := langfuse.Start(ctx)
defer clean(ctx)

runner := runner.NewRunner("app", myAgent)
events, _ := runner.Run(ctx, "user-1", "session-1",
    model.NewUserMessage("Hello"),
    agent.WithSpanAttributes(
        attribute.String("langfuse.user.id", "user-1"),
        attribute.String("langfuse.session.id", "session-1"),
    ),
)

⚠️ langfuse.Start API 以实际代码为准，README 示例可能在框架演进中变化。

核心包速查

典型适用场景

坑与注意

1. 版本稳定性：框架高度活跃（1906 commits，2026-08-08 仍有更新），API 在快速迭代；生产项目建议锁定 minor 版本，不用 @latest。
2. 模型抽象层需自行实现：model 包是抽象接口，连接具体 LLM（OpenAI/Claude/本地）需要实现相应 adapter，未提供开箱即用的实现（需参考 examples/）。
3. evolution 自进化是实验性功能：依赖 reviewerModel（额外的 LLM）进行 session 评审；生产环境使用前建议充分评估质量门槛的有效性。
4. Prompt Caching 标注 90% 节省：README 称"automatic cost optimization with 90% savings"，但该数字高度依赖具体模型和 prompt 结构，不同场景差异可能很大，请以实测为准，不要当确定性数字使用。
5. SKILL.md 路径支持 HTTP URL：NewFSRepository 支持 HTTP(S) URL（zip/tar.gz），会自动下载并缓存；但企业内部使用建议走本地路径，避免外网依赖和安全审计问题。
6. langfuse 集成方式：langfuse.Start 等 API 以实际代码为准，README 可能滞后；建议跑通 examples/langfuse 后再接入。
7. Go Agent 框架竞争：同类还有 go-agent（Alex不好意思，内容太短）、gohire 等；trpc-agent-go 的差异化在于图工作流 + A2A/MCP/AG-UI 协议全家桶，适合协议互操作性有需求的企业。
8. 文档质量：README 功能描述详尽，但具体 API 参数细节需读各子包 GoDoc；/examples/ 目录是最可靠的用法参考。

与同类对比

一句话推荐结论

Go 服务接入 AI Agent 的首选生产级框架——如果你已有 Go 微服务，想引入 Agent 能力（无论是单 Agent 工具调用、多 Agent 协作还是图工作流），trpc-agent-go 以 Go 原生姿态提供了目前最完整的方案，同时内置 A2A/MCP/AG-UI 协议支持；但注意框架迭代快、模型抽象层需自实现，生产锁定版本并充分测试后再上线。