智能代理示例 #

本文档中引用的文件

目录 #

  1. 简介
  2. 项目结构概览
  3. 基础代理创建
  4. ReAct Agent 思考-行动循环
  5. Supervisor 多代理协调
  6. Swarm 代理群协作
  7. 工具系统详解
  8. 状态管理模式
  9. 架构对比与选择指南
  10. 最佳实践与故障排除
  11. 总结

简介 #

LangGraphGo 是一个强大的框架，用于构建智能代理系统。本教程将通过四个核心示例：create_agent、react_agent、supervisor 和 swarm，深入讲解不同类型智能代理的创建和使用方法。这些示例涵盖了从基础代理创建到复杂的多代理协作的各种场景。

智能代理的核心思想是让 AI 系统能够自主思考、采取行动、观察结果并不断改进。通过本教程，您将学会如何根据具体需求选择合适的代理架构，并掌握构建高效智能系统的技能。

项目结构概览 #

LangGraphGo 的智能代理示例分布在以下目录结构中：

graph TD
A[examples/] --> B[create_agent/]
A --> C[react_agent/]
A --> D[supervisor/]
A --> E[swarm/]
F[prebuilt/] --> G[create_agent.go]
F --> H[react_agent.go]
F --> I[supervisor.go]
F --> J[tool_executor.go]
K[graph/] --> L[schema.go]
K --> M[messages_graph.go]
N[tool/] --> O[tool.go]
B --> P[main.go]
C --> Q[main.go]
D --> R[main.go]
E --> S[main.go]
style A fill:#e1f5fe
style F fill:#f3e5f5
style K fill:#e8f5e8
style N fill:#fff3e0

图表来源

每个示例都专注于特定的代理类型和应用场景：

章节来源

基础代理创建 #

核心概念 #

基础代理创建是构建智能系统的第一步。CreateAgent 函数提供了一个灵活且可扩展的框架，其设计灵感来源于 LangChain 1.0，支持函数式选项来配置代理的行为。

主要特性 #

  1. 函数式选项模式: 使用可选参数来配置代理，使 API 更加整洁
  2. 系统消息定制: 可以设置代理的行为规范和角色定义
  3. 状态修改器: 允许在消息发送给 LLM 之前进行拦截和修改
  4. 工具集成: 支持多种外部工具的无缝集成

架构设计 #

classDiagram
class CreateAgentOptions {
+string SystemMessage
+func StateModifier
+CheckpointStore Checkpointer
}
class CreateAgent {
+model llms.Model
+inputTools []tools.Tool
+opts []CreateAgentOption
+CreateAgent() StateRunnable
}
class ToolExecutor {
+tools map[string]tools.Tool
+Execute() string
+ExecuteMany() []string
+ToolNode() interface
}
class StateGraph {
+AddNode()
+AddEdge()
+SetEntryPoint()
+Compile() StateRunnable
}
CreateAgent --> CreateAgentOptions : "uses"
CreateAgent --> ToolExecutor : "creates"
CreateAgent --> StateGraph : "builds"
ToolExecutor --> StateGraph : "executes in"

图表来源

实现流程 #

基础代理的创建遵循以下步骤：

  1. 初始化 LLM: 创建语言模型实例
  2. 定义工具: 创建代理可以使用的工具列表
  3. 配置选项: 使用函数式选项设置系统消息和状态修改器
  4. 创建代理: 调用 CreateAgent 函数构建完整的代理图
  5. 执行调用: 使用初始用户消息运行代理

关键组件分析 #

系统消息配置 #

系统消息决定了代理的基本行为和角色定位。通过 WithSystemMessage 选项，可以轻松设置代理的专业领域和行为准则。

状态修改器 #

状态修改器是一个强大的功能，允许在消息发送给 LLM 之前对其进行动态修改。这对于实现高级提示工程技术非常有用。

工具执行流程 #

代理通过工具执行器来处理外部工具调用。工具执行器负责：

章节来源

ReAct Agent 思考-行动循环 #

ReAct 模型原理 #

ReAct (Reasoning and Acting) 是构建智能 Agent 的基础模式，其核心思想是让模型通过推理、行动、观察和迭代来解决问题。

四阶段循环 #

flowchart TD
A[用户查询] --> B[LLM 分析问题]
B --> C{需要工具调用?}
C --> |是| D[调用相应工具]
C --> |否| E[生成最终答案]
D --> F[获取工具结果]
F --> G[观察执行结果]
G --> B
E --> H[返回最终结果]
style A fill:#e3f2fd
style E fill:#e8f5e8
style H fill:#e8f5e8

图表来源

核心组件 #

Agent 节点 #

Agent 节点是 ReAct 循环的核心，负责：

工具节点 #

工具节点专门处理 Agent 节点发起的工具调用：

条件边 #

条件边决定了 ReAct 循环的流向：

实现细节 #

ReAct Agent 的实现采用了简洁而高效的架构：

  1. 状态管理: 使用消息列表来维护对话历史
  2. 工具集成: 自动将可用工具转换为模型可理解的格式
  3. 循环控制: 通过条件边实现智能的执行流程控制
  4. 错误处理: 提供完善的错误处理和异常恢复机制

应用场景 #

ReAct Agent 特别适合以下场景：

章节来源

Supervisor 多代理协调 #

Supervisor 架构概述 #

Supervisor 模式实现了一个中央协调者来管理多个专门的 Worker Agent。这种架构适用于需要明确分工和协调的复杂任务场景。

系统组成 #

graph TB
subgraph "Supervisor 系统"
A[Supervisor Agent] --> B[Math Expert]
A --> C[General Assistant]
A --> D[Writer]
B --> E[数学计算]
C --> F[通用问答]
D --> G[文档写作]
A -.-> H[决策逻辑]
H -.-> A
end
style A fill:#ffeb3b
style B fill:#4caf50
style C fill:#2196f3
style D fill:#ff9800

图表来源

核心机制 #

成员管理 #

Supervisor 系统通过成员映射来管理各个 Worker Agent：

路由决策 #

Supervisor 使用强化学习或规则引擎来做出路由决策：

协作流程 #

sequenceDiagram
participant U as 用户
participant S as Supervisor
participant M as Math Expert
participant G as General Assistant
U->>S : 提交复杂任务
S->>S : 分析任务需求
S->>M : 路由到数学专家
M->>M : 执行数学计算
M->>S : 返回计算结果
S->>G : 路由到通用助手
G->>G : 处理通用问题
G->>S : 返回处理结果
S->>U : 汇总最终答案

图表来源

实现特点 #

状态共享 #

所有 Agent 共享相同的消息历史，确保上下文连续性：

边界控制 #

通过条件边实现精确的流程控制：

错误恢复 #

完善的错误处理机制：

章节来源

Swarm 代理群协作 #

Swarm 模型原理 #

Swarm 模式借鉴了 OpenAI Swarm 框架的设计理念，实现了去中心化的多 Agent 协作。与 Supervisor 模式不同，Swarm 允许 Agent 直接相互移交控制权，模拟真实的专家团队协作方式。

去中心化协作 #

graph LR
subgraph "Swarm 协作网络"
A[Researcher] < --> B[Writer]
A < --> C[Analyst]
B < --> D[Editor]
C < --> D
E[User Query] --> A
A --> F[Research Results]
F --> B
B --> G[Final Report]
style A fill:#4caf50
style B fill:#2196f3
style C fill:#ff9800
style D fill:#9c27b0
end

图表来源

核心机制 #

Handoff 工具 #

Handoff 工具是 Swarm 模式的核心创新，它允许 Agent 之间直接移交控制权：

var HandoffTool = llms.Tool{
    Type: "function",
    Function: &llms.FunctionDefinition{
        Name:        "handoff",
        Description: "Hand off control to another agent.",
        Parameters: map[string]interface{}{
            "type": "object",
            "properties": map[string]interface{}{
                "to": map[string]interface{}{
                    "type": "string",
                    "enum": []string{"Researcher", "Writer"},
                },
            },
            "required": []string{"to"},
        },
    },
}

路由机制 #

Swarm 使用条件边来实现智能路由：

状态管理 #

Swarm 采用共享状态模式：

实现细节 #

Agent 节点处理 #

每个 Agent 节点都需要处理 Handoff 工具调用：

flowchart TD
A[Agent 执行] --> B{发现 Handoff?}
B --> |是| C[解析目标 Agent]
B --> |否| D[正常响应]
C --> E[创建工具调用消息]
E --> F[添加工具响应消息]
F --> G[设置 next 字段]
G --> H[返回状态更新]
D --> I[返回正常响应]
style C fill:#ffeb3b
style G fill:#ffeb3b

图表来源

流程控制 #

Swarm 的流程控制通过路由器函数实现：

应用优势 #

Swarm 模式特别适合以下场景：

章节来源

工具系统详解 #

工具接口设计 #

LangGraphGo 的工具系统基于统一的接口设计，确保各种工具能够无缝集成到代理系统中。

标准接口 #

classDiagram
class Tool {
<<interface>>
+Name() string
+Description() string
+Call(ctx Context, input string) (string, error)
}
class WeatherTool {
+Name() string
+Description() string
+Call(ctx Context, input string) (string, error)
}
class CalculatorTool {
+Name() string
+Description() string
+Call(ctx Context, input string) (string, error)
}
Tool <|.. WeatherTool
Tool <|.. CalculatorTool

图表来源

工具执行器 #

工具执行器是工具系统的核心组件，负责工具的查找、调用和结果处理。

执行流程 #

sequenceDiagram
participant A as Agent
participant TE as ToolExecutor
participant T as Tool
A->>TE : Execute(invocation)
TE->>TE : 查找工具
TE->>T : Call(ctx, input)
T->>T : 执行业务逻辑
T->>TE : 返回结果
TE->>A : 格式化结果

图表来源

多工具支持 #

工具执行器支持多种调用模式：

工具节点 #

工具节点是图执行器中的专用组件，负责处理工具调用消息。

消息处理 #

工具节点能够处理来自 LLM 的工具调用消息：

章节来源

状态管理模式 #

状态架构 #

LangGraphGo 的状态管理系统提供了灵活且强大的状态更新机制，支持复杂的状态演进和数据管理。

状态模式 #

classDiagram
class StateSchema {
<<interface>>
+Init() interface
+Update(current, new) interface
}
class MapSchema {
+Reducers map[string]Reducer
+EphemeralKeys map[string]bool
+RegisterReducer()
+Update()
}
class Reducer {
<<function>>
+current interface
+new interface
+return interface
}
StateSchema <|.. MapSchema
MapSchema --> Reducer : "uses"

图表来源

Reducer 类型 #

内置 Reducers #

  1. AppendReducer: 将新元素追加到列表末尾
  2. OverwriteReducer: 用新值替换旧值（默认行为）
  3. SumReducer: 对数值进行累加

自定义 Reducer #

开发者可以创建自定义 Reducer 来满足特定需求：

func SetReducer(current interface{}, new interface{}) (interface{}, error) {
    // 实现集合去重逻辑
    set := make(map[string]bool)
    // 合并当前值和新值
    // 返回去重后的结果
}

状态更新流程 #

flowchart TD
A[节点返回部分状态] --> B[Schema 检查 Reducer]
B --> C{是否有自定义 Reducer?}
C --> |是| D[执行自定义逻辑]
C --> |否| E[使用默认行为]
D --> F[合并状态]
E --> F
F --> G[更新全局状态]
style D fill:#ffeb3b
style F fill:#e8f5e8

图表来源

应用场景 #

状态管理模式适用于各种复杂场景：

章节来源

架构对比与选择指南 #

架构特性对比 #

特性 CreateAgent ReactAgent Supervisor Swarm
架构类型 单一代理 单一代理 中央协调 去中心化
工具集成 原生支持 原生支持 通过成员支持 通过工具支持
协作模式 自主决策 自主决策 中央调度 直接移交
复杂度 低 中等 中等 高
适用场景 简单工具调用 复杂推理任务 明确分工 动态协作

选择决策树 #

flowchart TD
A[开始选择代理架构] --> B{任务复杂度}
B --> |简单| C{需要工具调用?}
B --> |复杂| D{需要多Agent协作?}
C --> |否| E[CreateAgent]
C --> |是| F[ReactAgent]
D --> |否| G{需要中央协调?}
D --> |是| H{需要明确分工?}
G --> |否| I[ReactAgent]
G --> |是| J[Supervisor]
H --> |是| K[Supervisor]
H --> |否| L[Swarm]
style E fill:#e8f5e8
style F fill:#e8f5e8
style I fill:#e8f5e8
style J fill:#e3f2fd
style K fill:#e3f2fd
style L fill:#fff3e0

场景推荐 #

CreateAgent 场景 #

ReactAgent 场景 #

Supervisor 场景 #

Swarm 场景 #

性能考虑 #

不同架构的性能特征：

  1. CreateAgent: 最高性能，最小开销
  2. ReactAgent: 中等性能，适合推理密集型任务
  3. Supervisor: 中等性能，适合协调密集型任务
  4. Swarm: 较低性能，适合协作密集型任务

最佳实践与故障排除 #

开发最佳实践 #

1. 工具设计原则 #

2. 状态管理 #

3. 错误处理 #

常见问题与解决方案 #

1. 工具调用失败 #

问题: 工具执行过程中出现错误 解决方案:

2. 状态不一致 #

问题: 多 Agent 协作时状态同步问题 解决方案:

3. 性能瓶颈 #

问题: 大规模部署时性能下降 解决方案:

调试技巧 #

1. 日志记录 #

// 启用详细日志
log.SetLevel(log.DebugLevel)

2. 状态检查 #

// 检查中间状态
fmt.Printf("Intermediate state: %+v\n", state)

3. 工具测试 #

// 单独测试工具
result, err := tool.Call(ctx, input)
if err != nil {
    log.Printf("Tool error: %v", err)
}

总结 #

LangGraphGo 提供了构建智能代理系统的完整解决方案，通过四个核心示例展示了不同的代理架构和应用场景。

核心收获 #

  1. 基础代理创建: 学会了使用 CreateAgent 构建灵活的智能代理
  2. ReAct 思考-行动循环: 掌握了 ReAct 模式的实现和应用
  3. 多代理协调: 理解了 Supervisor 模式的中央协调机制
  4. 去中心化协作: 学会了 Swarm 模式的代理群协作模式

技术要点 #

应用指导 #

选择合适的代理架构需要考虑：

通过本教程的学习，您已经掌握了构建智能代理系统的核心技能，可以根据具体需求选择最适合的架构模式，创造出高效、智能的代理应用。