中文 | English

tRPC-Agent-Go

一款功能强大的 Go 框架，用于构建智能代理系统，彻底改变您创建 AI 应用的方式。轻松构建能够思考、记忆、协作并采取行动的自主代理。

为什么选择 tRPC-Agent-Go？

• 智能推理：先进的分层规划器和多代理编排
• 丰富的工具生态：与外部 API、数据库和服务无缝集成
• 持久化内存：长期状态管理和上下文感知能力
• 多代理协作：链式、并行和基于图的代理工作流
• GraphAgent：类型安全的图工作流，支持多条件路由，功能上等同于 Go 语言中的 LangGraph
• 代理技能：可重用的 SKILL.md 工作流，具备安全执行机制
• 工件管理：对代理和工具生成的文件进行版本化存储
• 提示缓存：自动优化成本，缓存内容可节省 90% 的费用
• 评估与基准测试：提供评估集和指标，以衡量随时间推移的质量变化
• UI 和服务器集成：AG-UI（代理-用户交互）以及代理间互操作性（A2A）
• 生产就绪：内置遥测、追踪和企业级可靠性
• 高性能：针对可扩展性和低延迟进行了优化

使用场景

非常适合用于构建：

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

核心特性

// 将代理串联起来以实现复杂的工作流
pipeline := chainagent.New("pipeline",
    chainagent.WithSubAgents([]agent.Agent{
        analyzer, processor, reporter,
    }))

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

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

// 在运行器级别管理的内存服务
runner := runner.NewRunner("app", agent,
    runner.WithMemoryService(memory))

// 代理可以在不同会话之间记住上下文

// 任何函数都可以成为工具
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"),
    ))

// 技能是以 SKILL.md 规范定义的文件夹。
repo, _ := skill.NewFSRepository("./skills")

// 让代理按需加载和运行技能。
tools := []tool.Tool{
    skilltool.NewLoadTool(repo),
    skilltool.NewRunTool(repo, localexec.New()),
}

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

目录

• tRPC-Agent-Go
  • 使用场景
  • 关键特性
    • 多智能体编排
    • 高级记忆系统
    • 丰富的工具集成
    • 生产环境可观测性
    • 智能体技能
    • 评估与基准测试
  • 目录
  • 文档
  • 快速入门
    • 先决条件
    • 运行示例
    • 基本用法
    • 停止/取消运行
  • 示例
    • 1. 工具使用
    • 2. 纯LLM智能体
    • 3. 多智能体运行器
    • 4. 图形化智能体
    • 5. 记忆
    • 6. 知识
    • 7. 遥测与追踪
    • 8. MCP集成
    • 9. AG-UI演示
    • 10. 评估
    • 11. 智能体技能
    • 12. 构建产物
    • 13. A2A互操作
    • 14. 网关服务器
  • 架构概览
    • 执行流程
  • 使用内置智能体
    • 多智能体协作示例
  • 贡献
    • 贡献方式
    • 快速贡献设置
  • 致谢
    • 企业级验证
    • 开源灵感
  • 星标历史
  • 许可证
    • 在GitHub上关注我们 • 报告问题 • 参与讨论

文档

准备好深入探索tRPC-Agent-Go了吗？我们的文档涵盖了从基础概念到高级技术的方方面面，助您自信地构建强大的AI应用。无论您是AI智能体的新手还是经验丰富的开发者，都能在这里找到详尽的指南、实用的示例以及最佳实践，加速您的开发之旅。

快速入门

亲眼见证其运作：【演示GIF占位符——展示智能体推理及工具使用】

先决条件

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

运行示例

只需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. 运行您的第一个智能体！
cd examples/runner
go run . -model="gpt-4o-mini" -streaming=true

您将看到：

• 与AI智能体的交互式对话
• 实时流式响应
• 工具使用（计算器+时间工具）
• 多轮对话并具备记忆功能

您可以尝试提问：“现在几点了？然后计算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() {
    // 创建模型。
    modelInstance := openai.New("deepseek-chat",
        openai.WithVariant(openai.VariantDeepSeek),
    )

    // 创建工具。
    calculatorTool := function.NewFunctionTool(
        calculator,
        function.WithName("calculator"),
        function.WithDescription("执行加、减、乘、除运算。"+
            "参数：a、b为数值，op取值为add/sub/mul/div；"+
            "返回结果为计算结果。"),
    )

    // 启用流式输出。
    genConfig := model.GenerationConfig{
        Stream: true,
    }

    // 创建智能体。
    agent := llmagent.New("assistant",
        llmagent.WithModel(modelInstance),
        llmagent.WithTools([]tool.Tool{calculatorTool}),
        llmagent.WithGenerationConfig(genConfig),
    )

    // 创建运行器。
    runner := runner.NewRunner("calculator-app", agent)

    // 执行对话。
    ctx := context.Background()
    events, err := runner.Run(ctx,
        "user-001",
        "session-001",
        model.NewUserMessage("计算2加3等于多少"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // 处理事件流。
    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("无效操作：%s", req.Op)
    }
    return calculatorRsp{Result: result}, nil
}

type calculatorReq struct {
    A  float64 `json:"A"  jsonschema:"description=第一个整数操作数，必填"`
    B  float64 `json:"B"  jsonschema:"description=第二个整数操作数，必填"`
    Op string  `json:"Op" jsonschema:"description=运算类型，枚举值为add、sub、mul、div，必填"`
}

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

每次请求动态创建智能体

有时您的智能体需要根据每次请求来创建（例如：不同的提示词、模型、工具、沙箱实例）。在这种情况下，可以让运行器为每一次Run(...)构建一个新的智能体：

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

events, err := r.Run(ctx,
    "user-001",
    "session-001",
    model.NewUserMessage("你好"),
    agent.WithInstruction("你是一个乐于助人的助手。"),
)
_ = events
_ = err

停止/取消运行

如果您想中断正在运行的代理，建议取消传递给 Runner.Run 的上下文。这样做可以安全地停止模型调用和工具调用，并让运行器进行清理。

重要提示：不要只是简单地“中断”事件循环就退出——代理协程可能会继续运行，并阻塞在通道写入操作上。务必先取消上下文，然后持续从事件通道中读取数据，直到通道被关闭。

选项 A：Ctrl+C（终端程序）

将 Ctrl+C 转换为上下文取消：

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 {
    // 持续读取，直到运行器停止（上下文被取消或运行完成）。
}

选项 B：从代码中取消

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)

更多详细信息（包括分离式取消、恢复以及服务器端取消流程），请参阅 docs/mkdocs/en/runner.md 和 docs/mkdocs/en/agui.md。

示例

examples 目录包含可运行的演示，涵盖了所有主要功能。

1. 工具使用

• examples/agenttool — 将代理封装为可调用工具。
• examples/multitools — 多工具编排。
• examples/duckduckgo — 集成网络搜索工具。
• examples/filetoolset — 将文件操作封装为工具。
• examples/fileinput — 提供文件作为输入。
• examples/agenttool 展示了流式与非流式模式。

2. 仅使用 LLM 的代理

示例：examples/llmagent

• 可以将任何聊天补全模型封装为 LLMAgent。
• 配置系统指令、温度、最大令牌数等参数。
• 在模型流式输出时，接收增量式的 event.Event 更新。

3. 多代理运行器

示例：examples/multiagent

• ChainAgent — 子代理的线性流水线。
• ParallelAgent — 并发运行子代理并合并结果。
• CycleAgent — 循环执行，直到满足终止条件。

4. 图形化代理

示例：examples/graph

• GraphAgent — 使用 graph 和 agent/graph 包展示如何构建和执行复杂的条件工作流。它演示了如何构造基于图的代理、安全地管理状态、实现条件路由，以及通过运行器编排执行过程。

  多条件分支路由示例：

  // 返回多个分支键和并行执行的目标。
  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"}, // 路径映射或终点映射
  )
  sg.SetFinishPoint("A").SetFinishPoint("B")
  

5. 内存

示例：examples/memory

• 提供内存和 Redis 内存服务，支持 CRUD 操作、搜索及工具集成。
• 展示如何配置、调用工具以及自定义提示词。

6. 知识库

示例：examples/knowledge

• 基本的 RAG 示例：加载数据源、嵌入向量存储并进行检索。
• 讲解如何利用对话上下文，以及调整加载和并发选项。

7. 链路追踪与遥测

示例：examples/telemetry

• 在模型、工具和运行器层集成 OpenTelemetry 钩子。
• 将追踪数据导出到 OTLP 端点，以便进行实时分析。

8. MCP 集成

示例：examples/mcptool

• 提供围绕 trpc-mcp-go 的封装工具，它是 模型上下文协议 (MCP) 的一种实现。
• 支持遵循 MCP 规范的结构化提示、工具调用、资源消息和会话消息。
• 实现动态工具执行以及代理与 LLM 之间的丰富上下文交互。

9. AG-UI 演示

示例：examples/agui

• 通过 AG-UI（代理-用户交互）协议暴露运行器。
• 内置 Server-Sent Events (SSE) 服务器，并提供客户端示例（例如 CopilotKit 和 TDesign Chat）。

10. 评估

示例：examples/evaluation

• 使用可重复的评估集和可插拔的指标来评估代理。
• 包括本地文件驱动的运行和内存中的运行。

11. 代理技能

示例：examples/skillrun、examples/skillfind

• 技能是以 SKILL.md 规范文件为核心，并可选包含文档或脚本的文件夹。
• 内置工具包括：skill_load、skill_list_docs、skill_select_docs、skill_run，以及（当执行器支持交互式会话时）skill_exec、skill_write_stdin、skill_poll_session、skill_kill_session。
• skill_run 是默认的一次性命令执行器，运行于隔离的工作空间中。
• skill_exec 和会话相关工具用于处理交互式的标准输入/TTY 流程，而无需将完整脚本内联到提示中。这些工具仅在代码执行器暴露 InteractiveProgramRunner 接口时注册（或回退到本地引擎实现该接口时）。
• skill.NewFSRepository(...) 可以扫描多个根目录，例如共享的技能目录和用户私有的目录。在长期运行的进程中，安装或移除技能后，请调用 (*skill.FSRepository).Refresh() 方法刷新仓库。
• 建议仅将 skill_run 用于所选技能文档中明确要求的命令，而不应用于通用的 Shell 探索任务。
• 当 LLMAgent 使用 WithCodeExecutor(...) 仅为了支持 skill_run 时，可通过 llmagent.WithEnableCodeExecutionResponseProcessor(false) 禁用响应中的代码执行处理器。以技能为中心的示例（如 examples/skill、examples/skillrun、examples/skilldynamicschema 和 examples/structuredoutputskills）均遵循此模式，从而避免助手文本中嵌入的代码块自动执行。
• examples/skillfind 展示了一个完整的端到端发现流程：模型使用内置的 skill-find 技能搜索公共网络，将一个公开的 GitHub 技能安装到用户私有目录中，刷新仓库，并在同一对话中使用新技能。默认情况下，本地执行功能是关闭的，只有在需要运行已安装技能时才可显式启用。

12. 艺术品

示例：examples/artifact

• 保存并检索由工具生成的版本化文件（图像、文本、报告等）。
• 支持多种后端存储（内存、S3、COS 等）。

13. A2A 互操作

示例：examples/a2aadk

• 与 ADK Python A2A 服务器进行代理间互操作。
• 演示跨运行时的流式传输、工具调用和代码执行。

14. 网关服务器

示例：openclaw

• 一个极简的 OpenClaw 风格网关服务器。
• 提供稳定的会话 ID 和每会话序列化功能。
• 具备基础的安全控制机制：白名单 + 提及过滤。
• 类似 OpenClaw 的实现（Telegram + 网关）：openclaw

其他值得关注的示例：

• examples/humaninloop – 人机协作。
• examples/codeexecution – 安全的代码执行。

有关使用细节，请参阅每个示例文件夹中的 README.md 文件。

架构概览

架构

执行流程

1. Runner 协调整个执行流水线，并管理会话。
2. Agent 使用多个专用组件处理请求。
3. Planner 确定最优策略和工具选择。
4. Tools 执行特定任务（API 调用、计算、网络搜索等）。
5. Memory 维护上下文信息，并从交互中学习。
6. Knowledge 提供基于 RAG 的文档理解能力。

关键包：

使用内置代理

对于大多数应用场景，您无需自行实现 agent.Agent 接口。框架已经提供了若干开箱即用的代理，您可以像搭积木一样自由组合：

多代理协作示例

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

// 2. 创建另一个具有不同指令的 LLM 代理。
translator := llmagent.New(
    "translator",
    llmagent.WithInstruction("将所有内容翻译成法语"),
    llmagent.WithModel(openai.New("gpt-3.5-turbo")),
)

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

// 4. 通过 Runner 运行会话并进行遥测。
run := runner.NewRunner("demo-app", pipeline)
events, _ := run.Run(ctx, "user-1", "sess-1",
    model.NewUserMessage("你好！"))
for ev := range events { /* ... */ }

组合 API 允许您嵌套链式、循环式或并行式代理，从而构建复杂的流程，而无需编写底层的管道逻辑。

贡献

我们非常欢迎贡献！加入我们不断壮大的开发者社区，共同构建人工智能代理的未来。

贡献方式

• 通过 Issues 报告问题或提出功能建议
• 改进文档——帮助更多人更快上手
• 提交 Pull Request（PR）——修复 bug、添加新功能或示例
• 分享你的使用场景——用你的代理应用启发他人

快速贡献设置

# 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 等众多优秀框架的启发。站在巨人的肩膀上，我们才能走得更远！

星标历史

许可证

本项目采用 Apache 2.0 许可证 许可——详情请参阅 LICENSE 文件。

tRPC-Agent-Go 快速上手指南

tRPC-Agent-Go 是一个强大的 Go 语言框架，专为构建智能体（Agent）系统设计。它支持多智能体协作、持久化记忆、丰富的工具集成以及生产级的可观测性，帮助开发者轻松打造能思考、能记忆、能协作的 AI 应用。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Go 版本：Go 1.21 或更高版本。
• LLM API Key：需要准备一个大模型提供商的 API Key（如 OpenAI、DeepSeek 等）。
• 网络环境：确保能够访问 GitHub 及对应的 LLM 服务接口。

安装步骤

1. 克隆项目

首先，将仓库克隆到本地并进入示例目录：

git clone https://github.com/trpc-group/trpc-agent-go.git
cd trpc-agent-go

2. 配置环境变量

设置您的 LLM 提供商密钥。以 OpenAI 或兼容接口（如 DeepSeek）为例：

export OPENAI_API_KEY="your-api-key-here"
export OPENAI_BASE_URL="your-base-url-here"  # 可选，如果是非官方端点需配置此项

提示：国内开发者若使用 DeepSeek 等国内模型，请将 OPENAI_BASE_URL 指向相应的国内服务地址。

3. 运行首个示例

运行内置的交互式 Agent 示例，体验实时流式响应和工具调用能力：

cd examples/runner
go run . -model="gpt-4o-mini" -streaming=true

启动后，您可以尝试输入：“现在几点了？然后计算 15 * 23 + 100"，观察 Agent 如何调用时间工具和计算器工具。

基本使用

以下是一个最小化的代码示例，展示如何创建一个带有自定义工具（计算器）的 Agent 并执行对话。

代码示例

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() {
    // 1. 创建模型实例 (以 DeepSeek 为例)
    modelInstance := openai.New("deepseek-chat",
        openai.WithVariant(openai.VariantDeepSeek),
    )

    // 2. 定义工具 (计算器)
    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."),
    )

    // 3. 启用流式输出配置
    genConfig := model.GenerationConfig{
        Stream: true,
    }

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

    // 5. 创建 Runner
    runner := runner.NewRunner("calculator-app", agent)

    // 6. 执行对话
    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)
    }

    // 7. 处理事件流
    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"`
}

核心步骤解析

1. 初始化模型：通过 openai.New 连接大模型服务。
2. 注册工具：使用 function.NewFunctionTool 将 Go 函数转换为 Agent 可调用的工具。
3. 构建 Agent：组合模型与工具，创建智能体实例。
4. 运行会话：通过 runner.Run 发起请求，并遍历返回的事件流获取流式回复。

更多高级功能（如多智能体编排、记忆系统、GraphAgent 工作流等）请参考官方文档或查看 examples 目录下的完整案例。