Skip to Content
WASPWASP

Lead Agent

🧠

Lead Agent 是每个 DeerFlow 线程中的主要推理和编排单元。它决定要做什么、调用工具、委派子 Agent，并返回产出物。

Lead Agent 是 DeerFlow 线程中的核心执行者。每个对话、任务和工作流都通过它进行。理解它的工作方式有助于你有效地配置它，并在需要时扩展它。

Lead Agent 的职责

Lead Agent 负责：

  • 接收用户消息并维护对话状态
  • 推断接下来要做什么（规划、工具选择、委派）
  • 调用工具——内置工具、社区工具、MCP 工具或技能工具
  • 通过 task 工具将子任务委派给子 Agent
  • 管理产出物（文件、输出、交付物）
  • 在计划模式下更新待办列表
  • 向用户返回最终响应或产出物

Lead Agent 不硬编码特定的工作流。它使用模型的推理能力来适应用户提供的任何任务，由系统提示和当前范围内的技能引导。

运行时基础

Lead Agent 基于 LangGraph 和 LangChain Agent 原语构建：

  • langchain.agents 的 create_agent 将 LLM 封装成工具调用 Agent 循环。
  • LangGraph 管理 ThreadState，提供检查点、流式传输和图执行模型。
  • 中间件链包裹 Agent 循环的每一轮，提供记忆、摘要和澄清等跨领域能力。

执行流程

接收消息

用户消息到达并添加到 ThreadState.messages。ThreadState 保存完整的对话历史、任何活跃的待办列表、累积的产出物和运行时元数据。

中间件前处理

在调用模型之前，每个活跃的中间件都有机会修改状态。例如，MemoryMiddleware 将持久化的记忆事实注入到系统提示中，SummarizationMiddleware 在 token 预算超出时可能压缩旧消息。

LLM 推理

模型接收当前消息（包括带有活跃技能指令的系统提示），并产生直接回复或一个或多个工具调用请求。

工具执行

如果请求了工具调用，它们会被分发到相应的处理器——用于文件和命令操作的沙箱工具、用于网络访问的社区工具，或用于子 Agent 委派的 task 工具。

中间件后处理

工具结果返回后、下一次模型调用之前，中间件再次运行。TitleMiddleware 可能在第一次交互后生成线程标题，TodoMiddleware 可能更新任务列表。

循环或响应

如果模型需要更多信息（例如，工具返回了部分结果），循环继续。当模型决定任务完成时，它产生最终消息，循环结束。

状态更新

ThreadState 更新为新消息、产出物和记忆队列。如果配置了检查点，状态将被持久化。

模型选择

Lead Agent 在运行时使用以下优先级顺序解析要使用的模型：

  1. 每次请求配置中的 model_name（或 model），如果提供且有效。
  2. 活跃自定义 Agent 配置中的 model 字段，如果指定了 Agent。
  3. config.yaml 中 models: 列表的第一个模型（全局默认值）。

如果请求的模型名称在配置中找不到，系统回退到默认模型并记录警告。

models:
  - name: my-primary-model
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true
 
  - name: my-fast-model
    use: langchain_openai:ChatOpenAI
    model: gpt-4o-mini
    api_key: $OPENAI_API_KEY

第一个条目（my-primary-model）成为默认值。任何不指定模型或指定未知模型名称的请求都将使用它。

思考模式

如果模型支持扩展思考（例如 DeepSeek Reasoner、启用思考的 Doubao、Anthropic Claude 思考模式），Lead Agent 可以在思考模式下运行。在此模式下，模型的内部推理步骤在响应流中可见。

思考模式通过每次请求的 thinking_enabled 标志控制。如果启用了思考但配置的模型不支持，系统会优雅地回退并记录警告。

计划模式

当请求配置中将 is_plan_mode 设为 true 时，TodoMiddleware 被激活。Agent 然后维护一个结构化的任务列表，在处理复杂任务时将条目标记为 in_progress、completed 或 pending。这为用户提供了 Agent 进度的可见性。

计划模式适用于显示增量进度有价值的复杂、多步骤任务。对于简单请求，最好禁用它以避免不必要的开销。

自定义 Agent

相同的 Lead Agent 运行时同时为默认 Agent 和你创建的任何自定义 Agent 提供服务。自定义 Agent 的区别仅在于：

  • 其名称（ASCII slug，从 display_name 自动派生）
  • 其系统提示或 Agent 特定指令
  • 它有权访问的技能
  • 它可以使用的工具组
  • 它默认使用的模型

自定义 Agent 通过 DeerFlow 应用界面或 /api/agents 端点创建。其配置存储在后端目录的 agents/{name}/config.yaml 中。

当在线程中选择自定义 Agent 时，Lead Agent 在运行时加载该 Agent 的配置。为特定 Agent 切换模型或技能不需要重启服务器。

中间件工具
为什么选择 WASP