基础代理创建 #

本文档中引用的文件

目录 #

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 函数式选项模式
  7. 状态图结构
  8. 与 CreateReactAgent 对比
  9. 性能考虑
  10. 故障排除指南
  11. 结论

简介 #

LangGraphGo 的 prebuilt.CreateAgent 函数提供了一个强大而灵活的基础智能代理创建框架。该函数采用函数式选项模式（Functional Options Pattern），允许开发者通过可选参数轻松配置代理的行为，包括系统消息、状态修改器等关键特性。

本文档将深入探讨如何使用 CreateAgent 函数创建基础智能代理，解释函数式选项模式的设计优势，展示从初始化 LLM 到构建并调用代理的完整流程，并说明代理内部的状态图结构及其与 CreateReactAgent 的区别。

项目结构 #

LangGraphGo 项目采用模块化架构，核心功能分布在以下关键目录中：

graph TD
A[LangGraphGo 项目] --> B[prebuilt/]
A --> C[examples/]
A --> D[graph/]
B --> E[create_agent.go]
B --> F[react_agent.go]
B --> G[tool_executor.go]
C --> H[create_agent/]
H --> I[main.go]
H --> J[README.md]
D --> K[schema.go]
D --> L[graph.go]
E --> M[CreateAgent 函数]
E --> N[函数式选项]
E --> O[状态管理]
F --> P[CreateReactAgent 函数]
F --> Q[简化版本]

图表来源

章节来源

核心组件 #

CreateAgentOptions 结构体 #

CreateAgentOptions 是 CreateAgent 函数的核心配置结构体，定义了代理创建时可用的所有选项：

classDiagram
class CreateAgentOptions {
+string SystemMessage
+StateModifier StateModifier
+CheckpointStore Checkpointer
}
class CreateAgentOption {
<<function>>
+Apply(options *CreateAgentOptions)
}
class StateModifier {
<<function>>
+Modify(messages []MessageContent) []MessageContent
}
CreateAgentOptions --> StateModifier : "包含"
CreateAgentOption --> CreateAgentOptions : "配置"

图表来源

主要配置选项 #

配置项 类型 描述 默认值
SystemMessage string 系统提示消息，定义代理行为 “”
StateModifier func 消息状态修改器，用于预处理消息历史 nil
Checkpointer CheckpointStore 检查点存储器，用于状态持久化 nil

章节来源

架构概览 #

CreateAgent 函数构建了一个基于状态图的智能代理系统，该系统包含以下核心组件：

graph TB
subgraph "代理架构"
A[LLM 模型] --> B[代理节点]
B --> C{条件边判断}
C --> |有工具调用| D[工具节点]
C --> |无工具调用| E[结束]
D --> B
F[工具列表] --> D
G[状态管理] --> B
G --> D
end
subgraph "状态流"
H[初始状态] --> B
B --> D
D --> B
B --> E
end

图表来源

章节来源

详细组件分析 #

CreateAgent 函数实现 #

CreateAgent 函数是整个代理系统的核心入口点，负责：

  1. 选项处理: 应用所有传入的函数式选项
  2. 工具执行器创建: 初始化工具执行器
  3. 状态图构建: 创建并配置状态图
  4. 节点定义: 定义代理节点和工具节点
  5. 边路由: 设置条件边和普通边
sequenceDiagram
participant Client as "客户端"
participant CA as "CreateAgent"
participant TE as "ToolExecutor"
participant LLM as "LLM模型"
participant SG as "StateGraph"
Client->>CA : 调用 CreateAgent(model, tools, options)
CA->>CA : 处理选项参数
CA->>TE : 创建工具执行器
CA->>SG : 创建状态图
CA->>SG : 添加代理节点
CA->>SG : 添加工具节点
CA->>SG : 设置入口点
CA->>SG : 添加条件边
CA->>SG : 添加普通边
CA->>SG : 编译图
SG-->>CA : 返回 StateRunnable
CA-->>Client : 返回编译后的代理

图表来源

代理节点实现 #

代理节点是系统的核心推理引擎，负责：

  1. 工具定义转换: 将工具列表转换为 LLM 可识别的格式
  2. 消息预处理: 应用系统消息和状态修改器
  3. LLM 调用: 发送消息并处理响应
  4. 结果封装: 将 LLM 响应封装为标准格式
flowchart TD
A[接收状态输入] --> B[提取消息列表]
B --> C[转换工具定义]
C --> D[应用系统消息]
D --> E[应用状态修改器]
E --> F[调用 LLM]
F --> G{是否有工具调用?}
G --> |是| H[封装工具调用]
G --> |否| I[封装文本响应]
H --> J[返回 AI 消息]
I --> J

图表来源

工具节点实现 #

工具节点负责执行 LLM 调用的工具请求：

flowchart TD
A[接收状态输入] --> B[提取最后一条消息]
B --> C{是否为 AI 消息?}
C --> |否| D[错误：非 AI 消息]
C --> |是| E[遍历消息部分]
E --> F{是否为工具调用?}
F --> |否| G[跳过]
F --> |是| H[解析参数]
H --> I[执行工具]
I --> J[创建工具响应]
J --> K[收集所有工具响应]
K --> L[返回工具消息]

图表来源

章节来源

函数式选项模式 #

设计优势 #

函数式选项模式（Functional Options Pattern）是 CreateAgent 函数的核心设计理念，具有以下优势：

  1. 可读性: 通过命名函数清晰表达配置意图
  2. 可扩展性: 易于添加新的配置选项
  3. 向后兼容: 新增选项不会破坏现有代码
  4. 类型安全: 编译时检查选项类型

核心选项函数 #

WithSystemMessage #

classDiagram
class WithSystemMessage {
+message string
+CreateAgentOption
+apply(options *CreateAgentOptions)
}
class CreateAgentOptions {
+SystemMessage string
}
WithSystemMessage --> CreateAgentOptions : "配置"

图表来源

WithStateModifier #

状态修改器提供了强大的消息预处理能力：

flowchart LR
A[原始消息历史] --> B[状态修改器函数]
B --> C[修改后的消息历史]
subgraph "修改器功能"
D[日志记录]
E[消息过滤]
F[动态提示工程]
G[上下文压缩]
end
B -.-> D
B -.-> E
B -.-> F
B -.-> G

图表来源

章节来源

状态图结构 #

内部状态图 #

CreateAgent 创建的状态图包含两个主要节点和相应的边：

stateDiagram-v2
[*] --> agent : 启动
agent --> tools : 有工具调用
agent --> [*] : 无工具调用
state agent {
[*] --> 接收输入
接收输入 --> 处理消息
处理消息 --> 调用LLM
调用LLM --> [*]
}
state tools {
[*] --> 解析调用
解析调用 --> 执行工具
执行工具 --> [*]
}

图表来源

条件边路由逻辑 #

条件边决定了代理的执行流程：

flowchart TD
A[代理节点完成] --> B{最后消息包含工具调用?}
B --> |是| C[路由到工具节点]
B --> |否| D[路由到结束]
C --> E[工具节点执行]
E --> F[返回 AI 响应]
F --> A
D --> G[代理终止]

图表来源

状态 Schema #

代理使用 MapSchema 和 AppendReducer 来管理消息历史：

字段名 类型 用途 Reducer
messages []MessageContent 存储对话历史 AppendReducer

章节来源

与 CreateReactAgent 对比 #

功能对比表 #

特性 CreateAgent CreateReactAgent
灵活性 ✅ 高度可配置 ⚠️ 基础配置
函数式选项 ✅ 支持 ❌ 不支持
系统消息 ✅ 支持 ❌ 不支持
状态修改器 ✅ 支持 ❌ 不支持
检查点支持 ✅ 计划中 ❌ 不支持
扩展性 ✅ 易于扩展 ⚠️ 有限扩展

实现差异 #

graph LR
subgraph "CreateAgent"
A1[函数式选项] --> A2[灵活配置]
A2 --> A3[高级功能]
end
subgraph "CreateReactAgent"
B1[固定配置] --> B2[简单易用]
B2 --> B3[基础功能]
end
A3 --> C[更适合复杂场景]
B3 --> D[更适合快速原型]

图表来源

章节来源

性能考虑 #

优化策略 #

  1. 消息缓存: 合理使用状态修改器避免重复计算
  2. 工具并发: 在实际实现中可以考虑工具执行的并发处理
  3. 内存管理: 注意消息历史的增长控制
  4. LLM 调用优化: 合理设置工具数量和消息长度

最佳实践 #

故障排除指南 #

常见问题及解决方案 #

1. 系统消息未生效 #

问题: 设置了系统消息但未被使用

解决方案: 确保正确使用 WithSystemMessage 选项，并检查状态修改器是否移除了系统消息

2. 工具调用失败 #

问题: LLM 调用了不存在的工具

解决方案: 检查工具名称匹配和工具定义格式

3. 状态修改器异常 #

问题: 状态修改器导致程序崩溃

解决方案: 添加适当的错误处理和边界检查

章节来源

结论 #

prebuilt.CreateAgent 函数提供了一个强大而灵活的基础智能代理创建框架。通过函数式选项模式，开发者可以轻松配置代理的各种行为，包括系统消息、状态修改器等高级特性。

与 CreateReactAgent 相比，CreateAgent 提供了更高的灵活性和扩展性，特别适合需要复杂配置和定制化的应用场景。其基于状态图的架构设计确保了代理执行的可预测性和可调试性。

通过合理使用这些功能，开发者可以构建出功能丰富、性能优异的智能代理系统，满足各种复杂的业务需求。