tRPC-Agent-Go

English | 中文

---

tRPC-Agent-Go 是一个用于构建生产级 Agent 系统的 Go 框架。 它把 LLM Agent、图工作流、工具调用、Session/Memory 状态、知识检索、 Agent 自进化、评测与 OpenTelemetry 可观测性整合到一套 Go-native 技术栈中。

如果你希望 Agent 应用天然适配 Go 服务开发、并发执行、可观测部署，并能接入 A2A、AG-UI、MCP 等协议，tRPC-Agent-Go 可以作为底层框架。

为什么选择 tRPC-Agent-Go？

• Go-Native Agent Runtime：流式 Runner、context cancel 和服务友好的 API
• GraphAgent：类型安全的图工作流，支持多条件路由，功能对标 LangGraph 的 Go 实现
• 多 Agent 协作：Chain、Parallel 和 Cycle 工作流
• 丰富的 Tool 生态系统：Function Tool、MCP Tool、Web 搜索、代码执行和自定义服务
• 持久化状态：Session、Memory、Artifacts 与知识检索
• Agent Skills：可复用的 SKILL.md 工作流，支持安全执行
• Agent 自进化：Hermes-style 会话复盘，自动提取、门禁校验并发布可复用 SKILL.md 工作流
• Prompt Caching：自动优化成本，缓存内容最高可节省 90%
• 评测与基准：EvalSet + Metric 用于长期质量度量
• 协议集成：AG-UI 对接前端、A2A 实现 Agent 互通、MCP 接入工具生态
• 生产可观测性：OpenTelemetry tracing、metrics 与 Langfuse 示例

使用场景

非常适合构建：

• 客户支持机器人 - 理解上下文并解决复杂查询的智能 agent
• 数据分析助手 - 查询数据库、生成报告并提供洞察的 agent
• DevOps 自动化 - 智能部署、监控和事件响应系统
• 业务流程自动化 - 具有 human-in-the-loop 能力的多步骤工作流
• 研究与知识管理 - 基于 RAG 的文档分析和问答 agent

核心特性

// Chain agent 构建复杂工作流
pipeline := chainagent.New("pipeline",
    chainagent.WithSubAgents([]agent.Agent{
        analyzer, processor, reporter,
    }))

// 或者并行运行
parallel := parallelagent.New("concurrent",
    parallelagent.WithSubAgents(tasks))

// 带搜索的持久化 memory
memory := memorysvc.NewInMemoryService()
agent := llmagent.New("assistant",
    llmagent.WithTools(memory.Tools()),
    llmagent.WithModel(model))

// Memory service 在 runner 层管理
runner := runner.NewRunner("app", agent,
    runner.WithMemoryService(memory))

// Agent 在会话间记住上下文

// 任何函数都可以成为 tool
calculator := function.NewFunctionTool(
    calculate,
    function.WithName("calculator"),
    function.WithDescription("数学运算"))

// MCP 协议支持
mcpTool := mcptool.New(serverConn)

// 启动 Langfuse 集成
clean, _ := langfuse.Start(ctx)
defer clean(ctx)

runner := runner.NewRunner("app", agent)
// 运行并添加 Langfuse 属性
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"),
    ))

// Skills 是一个包含 SKILL.md 的文件夹。
repo, _ := skill.NewFSRepository("./skills")

// 让 agent 按需加载并执行 skills。
tools := []tool.Tool{
    skilltool.NewLoadTool(repo),
    skilltool.NewRunTool(repo, localexec.New()),
}

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

runner := runner.NewRunner("app", agent,
    runner.WithEvolutionService(evo))

evaluator, _ := evaluation.New("app", runner, evaluation.WithNumRuns(3))
defer evaluator.Close()
result, _ := evaluator.Evaluate(ctx, "math-basic")
_ = result.OverallStatus

目录

• tRPC-Agent-Go
  • 使用场景
  • 核心特性
    • 多 Agent 编排
    • 先进的 Memory 系统
    • 丰富的 Tool 集成
    • 生产可观测性
    • Agent Skills
    • Agent 自进化
    • 评测与基准
  • 目录
  • 文档
    • 博客
  • 快速开始
    • 前置条件
    • 运行示例
    • 基本用法
    • 中断 / 取消一次运行
  • 示例
    • 1. Tool 用法
    • 2. 仅 LLM 的 Agent
    • 3. 多 Agent Runner
    • 4. Graph Agent
    • 5. Memory
    • 6. Knowledge
    • 7. Telemetry 与 Tracing
    • 8. MCP 集成
    • 9. AG-UI Demo
    • 10. 评测（Evaluation）
    • 11. Agent Skills
    • 12. Agent 自进化
    • 13. Artifacts
    • 14. A2A 互通
    • 15. Gateway 服务
  • 架构概览
    • 执行流程
  • 使用内置 Agents
    • 多 Agent 协作示例
  • 贡献
    • 贡献方式
    • 快速贡献设置
  • 致谢
    • 企业验证
    • 开源灵感
  • Star 历史
  • 许可证
    • GitHub 仓库 • 报告问题 • 加入讨论

文档

准备好深入了解 tRPC-Agent-Go 了吗？我们的文档涵盖从基础概念到高级技巧的一切，帮助你自信地构建强大的 AI 应用。无论你是 AI agent 新手还是有经验的开发者，都能在其中找到详细指南、实用示例和最佳实践，加速你的开发旅程。

博客

这些博客围绕框架全景、核心能力与工程实践展开，可按需阅读：

• 构建智能 AI 应用的 Go 语言 Agent 框架
• GraphAgent 让 AI 工作流与 Agent 无缝融合
• 快速构建基于 AG-UI 的 Agent 服务
• Anthropic Agent Skills 规范的 Go 原生实现
• 打造企业级安全可控的 OpenClaw Runtime
• AI Agent 自动化评估范式与工程实践全解析
• AI Agent 提示词自动迭代与工程实践全解析

快速开始

上面的 Demo 展示了 tRPC-Agent-Go 服务将 Agent 事件流式输出到 AG-UI 客户端，Agent 在执行过程中完成规划、工具调用并更新界面。

前置条件

• Go 1.21 或更高版本
• LLM 提供商 API 密钥（OpenAI、DeepSeek 等）
• 5 分钟构建您的第一个智能 agent

运行示例

3 个简单步骤开始：

# 1. 克隆和设置
git clone https://github.com/trpc-group/trpc-agent-go.git
cd trpc-agent-go

# 2. 配置您的 LLM
export OPENAI_API_KEY="your-api-key-here"
export OPENAI_BASE_URL="your-base-url-here"  # 可选

# 3. 运行您的第一个 agent！
cd examples/runner
go run . -model="gpt-4o-mini" -streaming=true

您将看到：

• 与您的 AI agent 互动聊天
• 实时流式响应
• Tool 使用（计算器 + 时间工具）
• 带 memory 的多轮对话

试着问问："现在几点了？然后计算 15 * 23 + 100"

基本用法

package main

import (
    "context"
    "fmt"
    "log"

    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/model"
    "trpc.group/trpc-go/trpc-agent-go/model/openai"
    "trpc.group/trpc-go/trpc-agent-go/runner"
    "trpc.group/trpc-go/trpc-agent-go/tool"
    "trpc.group/trpc-go/trpc-agent-go/tool/function"
)

func main() {
    // Create model.
    modelInstance := openai.New("deepseek-chat",
        openai.WithVariant(openai.VariantDeepSeek),
    )

    // Create tool.
    calculatorTool := function.NewFunctionTool(
        calculator,
        function.WithName("calculator"),
        function.WithDescription("Execute addition, subtraction, multiplication, and division. "+
            "Parameters: a, b are numeric values, op takes values add/sub/mul/div; "+
            "returns result as the calculation result."),
    )

    // Enable streaming output.
    genConfig := model.GenerationConfig{
        Stream: true,
    }

    // Create Agent.
    agent := llmagent.New("assistant",
        llmagent.WithModel(modelInstance),
        llmagent.WithTools([]tool.Tool{calculatorTool}),
        llmagent.WithGenerationConfig(genConfig),
    )

    // Create Runner.
    runner := runner.NewRunner("calculator-app", agent)

    // Execute conversation.
    ctx := context.Background()
    events, err := runner.Run(ctx,
        "user-001",
        "session-001",
        model.NewUserMessage("Calculate what 2+3 equals"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Process event stream.
    for event := range events {
        if event.Object == "chat.completion.chunk" {
            fmt.Print(event.Response.Choices[0].Delta.Content)
        }
    }
    fmt.Println()
}

func calculator(ctx context.Context, req calculatorReq) (calculatorRsp, error) {
    var result float64
    switch req.Op {
    case "add", "+":
        result = req.A + req.B
    case "sub", "-":
        result = req.A - req.B
    case "mul", "*":
        result = req.A * req.B
    case "div", "/":
        result = req.A / req.B
	default:
		return calculatorRsp{}, fmt.Errorf("invalid operation: %s", req.Op)
	}
    return calculatorRsp{Result: result}, nil
}

type calculatorReq struct {
    A  float64 `json:"A"  jsonschema:"description=First integer operand,required"`
    B  float64 `json:"B"  jsonschema:"description=Second integer operand,required"`
    Op string  `json:"Op" jsonschema:"description=Operation type,enum=add,enum=sub,enum=mul,enum=div,required"`
}

type calculatorRsp struct {
    Result float64 `json:"result"`
}

每次请求动态创建 Agent

有些场景下，你希望 Agent 按请求创建（例如：不同的提示词、模型、工具集、沙箱实例）。 这时可以让 Runner 在每次 Run(...) 时动态构建一个新的 Agent：

r := runner.NewRunnerWithAgentFactory(
    "my-app",
    "assistant",
    func(ctx context.Context, ro agent.RunOptions) (agent.Agent, error) {
        // 通过 ro 构建本次请求使用的 Agent。
        a := llmagent.New("assistant",
            llmagent.WithInstruction(ro.Instruction),
        )
        return a, nil
    },
)

events, err := r.Run(ctx,
    "user-001",
    "session-001",
    model.NewUserMessage("Hello"),
    agent.WithInstruction("You are a helpful assistant."),
)
_ = events
_ = err

中断 / 取消一次运行

如果你希望“中断正在运行的 agent”（停止本次模型调用 / 工具调用），推荐做法是： 取消你传给 Runner.Run 的 context.Context。

特别注意：不要只是在消费事件的 for range 里 break 然后直接返回。 如果你不再读取事件通道，但 agent 还在后台写事件，可能会阻塞并造成 goroutine 泄漏。正确姿势是：先 cancel，再把事件通道读到关闭为止。

方式 A：Ctrl+C（命令行程序）

把 Ctrl+C 转成 ctx cancel：

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

events, err := r.Run(ctx, userID, sessionID, message)
if err != nil {
    return err
}
for range events {
    // 一直读到通道关闭：要么 ctx 被取消，要么 run 正常结束。
}

方式 B：代码里主动 cancel

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

events, err := r.Run(ctx, userID, sessionID, message)
if err != nil {
    return err
}

go func() {
    time.Sleep(2 * time.Second)
    cancel()
}()

for range events {
    // 一直读到通道关闭。
}

方式 C：按 requestID 取消（适合服务端 / 后台任务）

requestID := "req-123"
events, err := r.Run(ctx, userID, sessionID, message,
    agent.WithRequestID(requestID),
)

mr := r.(runner.ManagedRunner)
_ = mr.Cancel(requestID)

更完整的说明（包含 detached cancel、resume、以及 AG-UI 的取消路由）见 docs/mkdocs/zh/runner.md 与 docs/mkdocs/zh/agui.md。

示例

examples 目录包含涵盖各主要功能的可运行 Demo。

如果你还不确定从哪里开始，可以按目标选择：

• 第一个多轮 Agent：examples/runner
• 可控图工作流：examples/graph
• Agent 前端或流式 UI：examples/agui
• A2A 互通：examples/a2aagent
• RAG 与知识检索：examples/knowledge
• 评测与提示词迭代：examples/evaluation
• Skills 与本地自动化：examples/skillrun

1. Tool 用法

• examples/agenttool – 将 agent 封装为可调用的 tool。
• examples/multitools – 多工具编排。
• examples/duckduckgo – Web 搜索工具集成。
• examples/fileinput – 以文件作为输入。
• examples/agenttool 展示了流式与非流式模式。

2. 仅 LLM 的 Agent

示例：examples/llmagent

• 将任意 chat-completion 模型封装为 LLMAgent。
• 配置 system 指令、temperature、max tokens 等。
• 在模型流式输出时接收增量 event.Event 更新。

3. 多 Agent Runner

示例：examples/multiagent

• ChainAgent – 子 agent 的线性流水线。
• ParallelAgent – 并发执行子 agent 并合并结果。
• CycleAgent – 迭代执行直到满足终止条件。

4. Graph Agent

示例：examples/graph

• GraphAgent – 展示如何使用 graph 与 agent/graph 包来构建并执行复杂的、带条件的工作流。展示了如何构建基于图的 agent、安全管理状态、实现条件路由，并通过 Runner 进行编排执行。

• 多条件扇出路由（一次返回多个分支并行执行）：

// 返回多个分支键，分别触发目标节点并行执行。
sg := graph.NewStateGraph(schema)
sg.AddNode("router", func(ctx context.Context, s graph.State) (any, error) {
    return nil, nil
})
sg.AddNode("A", func(ctx context.Context, s graph.State) (any, error) {
    return graph.State{"a": 1}, nil
})
sg.AddNode("B", func(ctx context.Context, s graph.State) (any, error) {
    return graph.State{"b": 1}, nil
})
sg.SetEntryPoint("router")
sg.AddMultiConditionalEdges(
    "router",
    func(ctx context.Context, s graph.State) ([]string, error) {
        return []string{"goA", "goB"}, nil
    },
    map[string]string{"goA": "A", "goB": "B"}, // 可用 PathMap 或 Ends
)
sg.SetFinishPoint("A").SetFinishPoint("B")

5. Memory

示例：examples/memory

• 提供内存与 Redis memory 服务，包含 CRUD、搜索与 tool 集成。
• 如何进行配置、调用工具以及自定义 prompts。

6. Knowledge

示例：examples/knowledge

• 基础 RAG 示例：加载数据源、向量化到 vector store，并进行搜索。
• 如何使用对话上下文以及调节加载/并发选项。

7. Telemetry 与 Tracing

示例：examples/telemetry

• 在 model、tool 与 runner 层面的 OpenTelemetry hooks。
• 将 traces 导出到 OTLP endpoint 进行实时分析。

8. MCP 集成

示例：examples/mcptool

• 围绕 trpc-mcp-go 的封装工具，这是 Model Context Protocol (MCP) 的一个实现。
• 提供遵循 MCP 规范的 structured prompts、tool 调用、resource 与 session 消息。
• 使 agent 与 LLM 之间能够进行动态工具执行与上下文丰富的交互。

9. AG-UI Demo

示例：examples/agui

• 通过 AG-UI（Agent-User Interaction）协议对外暴露 Runner。
• 默认提供 Server-Sent Events（SSE）服务端实现，并提供客户端示例（例如 CopilotKit、TDesign Chat）。

10. 评测（Evaluation）

示例：examples/evaluation

• 通过可复用的 EvalSet 与可插拔的 Metric 对 agent 进行评测。
• 包含本地文件（local）与内存（inmemory）两种模式。

11. Agent Skills

示例：examples/skillrun

• Skill 是一个包含 SKILL.md 规范的文件夹，可附带 docs/scripts。
• 内置工具：skill_load、skill_list_docs、skill_select_docs、skill_run（在隔离工作空间里执行命令）。
• 建议 skill_run 尽量只用于执行所选 Skill 文档里要求的命令，而不是用于通用的 Shell 探查。
• 如果 LLMAgent 配置 WithCodeExecutor(...) 的目的只是支持 skill_run，建议关闭响应阶段的代码执行处理器： llmagent.WithEnableCodeExecutionResponseProcessor(false)。当前 examples/skill、examples/skillrun、examples/skilldynamicschema 与 examples/structuredoutputskills 都采用了这种配置，避免自动执行 assistant 文本里的围栏代码块。

12. Agent 自进化

示例：examples/evolution

• 在后台复盘已完成会话，并提取可复用的 SKILL.md 工作流。
• 支持 revision 存储、质量门禁、人工审批，以及技能在后续运行中的 warm-start。
• Runner 集成只需要一个选项：runner.WithEvolutionService(...)。

13. Artifacts

示例：examples/artifact

• 保存并读取工具产出的版本化文件（图片、文本、报告等）。
• 支持多种后端（in-memory、S3、COS）。

14. A2A 互通

示例：examples/a2aadk

• Agent-to-Agent（A2A）与 ADK Python A2A Server 的互通示例。
• 演示跨运行时的流式输出、工具调用与代码执行。

15. Gateway 服务

示例：openclaw

• 一个最小的 OpenClaw-like gateway 服务。
• 稳定的 session id，以及同一 session 串行执行。
• 基础安全控制：allowlist + mention gating。
• OpenClaw-like 实现（Telegram + gateway）：openclaw

其他值得关注的示例：

• examples/humaninloop – Human-in-the-loop。
• examples/codeexecution – 代码执行。

关于使用详情，请参阅各示例文件夹中的 README.md。

架构概览

架构图

执行流程

1. Runner 通过会话管理编排整个执行管道
2. Agent 使用多个专门组件处理请求
3. Planner 确定最优策略和 tool 选择
4. Tools 执行特定任务（API 调用、计算、web 搜索）
5. Memory 维护上下文并从交互中学习
6. Knowledge 为文档理解提供 RAG 能力
7. Evolution 复盘已完成会话，并把可复用过程沉淀为托管技能

关键包：

使用内置 Agents

对于大多数应用，你不需要自己实现 agent.Agent 接口。框架已经提供了若干可直接使用的 agent，你可以像搭积木一样组合：

多 Agent 协作示例

// 1. 创建一个基础的 LLM agent。
base := llmagent.New(
    "assistant",
    llmagent.WithModel(openai.New("gpt-4o-mini")),
)

// 2. 创建第二个具有不同指令的 LLM agent。
translator := llmagent.New(
    "translator",
    llmagent.WithInstruction("Translate everything to French"),
    llmagent.WithModel(openai.New("gpt-3.5-turbo")),
)

// 3. 将它们组合成一个 chain。
pipeline := chainagent.New(
    "pipeline",
    chainagent.WithSubAgents([]agent.Agent{base, translator}),
)

// 4. 通过 runner 运行以获得会话与 telemetry。
run := runner.NewRunner("demo-app", pipeline)
events, _ := run.Run(ctx, "user-1", "sess-1",
    model.NewUserMessage("Hello!"))
for ev := range events { /* ... */ }

组合式 API 允许你将 chain、cycle 或 parallel 进行嵌套，从而在无需底层管线处理的情况下构建复杂工作流。

贡献

我们热爱贡献！加入我们不断壮大的开发者社区，共同构建 AI agent 的未来。

贡献方式

• 报告 bug 或通过 Issues 建议新功能
• 改进文档 - 帮助他人更快学习
• 提交 PR - bug 修复、新功能或示例
• 分享您的用例 - 用您的 agent 应用启发他人

快速贡献设置

# Fork 并克隆仓库
git clone https://github.com/YOUR_USERNAME/trpc-agent-go.git
cd trpc-agent-go

# 运行测试确保一切正常
go test ./...
go vet ./...

# 进行您的更改并提交 PR！

请阅读 CONTRIBUTING.md 了解详细指南和编码标准。

致谢

企业验证

特别感谢腾讯各业务单元，包括腾讯元宝、腾讯视频、腾讯新闻、IMA 和 QQ 音乐的宝贵支持和生产环境验证推动框架发展

开源灵感

感谢优秀的开源框架如 ADK、Agno、CrewAI、AutoGen 等的启发。站在巨人的肩膀上！

Star 历史

许可证

遵循 Apache 2.0 许可证 - 详见 LICENSE 文件。