从字节跳动 DeerFlow 源码看 Agent 平台设计（一）：什么是 Agent？一个成熟 Agent 平台的 8 个核心组件

系列导航

• 本篇：什么是 Agent？一个成熟 Agent 平台的 8 个核心组件
• 第二篇：工具系统设计 — 从全量绑定到按需加载
• 第三篇：五个核心中间件深度解析
• 第四篇：Agent 生命周期与状态管理

摘要

本文基于字节跳动开源项目 DeerFlow 的源码，从较高维度阐述 Agent 的本质定义，并系统性地拆解一个成熟 Agent 平台所应包含的 8 个核心组件层。通过对生产级代码的分析，为读者建立对 Agent 架构的全局认知。

一、什么是 Agent

1.1 从 LLM 到 Agent 的本质跃迁

传统的大语言模型（LLM）对话是一种"一问一答"的交互模式——用户提出问题，模型返回文本回复。这种模式下，模型的能力边界被限制在文本生成范围内，无法与外部世界产生实质性的交互。

Agent（智能体）的核心突破在于引入了自主决策循环。Agent 不仅能生成文字回答，还能：

用一个公式概括：

Agent = LLM（推理引擎） + Tools（外部能力） + 自主决策循环（ReAct Loop）

1.2 DeerFlow 中的最小 Agent 表达

在 DeerFlow 的源码中，创建一个 Agent 的最小表达如下：

from langchain.agents import create_agent

agent = create_agent(
model=chat_model, # 大脑 — 负责理解、推理、决策
tools=tools_list, # 双手 — 可调用的外部工具集合
system_prompt=prompt, # 人格 — 定义身份、行为规范、约束条件
state_schema=ThreadState # 记忆 — 对话状态的结构定义
)

这四个要素构成了 Agent 的最小可用单元。然而，从一个"能跑起来"的 Agent 到一个"可以上生产"的 Agent 平台，中间还有大量的工程化设计需要完成。

二、成熟 Agent 平台的 8 个核心组件

通过对 DeerFlow 的架构分析，可以将一个成熟的 Agent 平台拆解为以下 8 个核心组件层。

2.1 模型层（Model Layer）

职责：提供推理能力，是 Agent 的"大脑"。

DeerFlow 的模型层设计遵循配置驱动、可插拔的原则。所有模型通过 config.yaml 声明，运行时通过反射机制动态加载：

models:
– name: gpt–4
display_name: GPT–4
use: langchain_openai:ChatOpenAI # 反射路径：包名:类名
model: gpt–4
api_key: $OPENAI_API_KEY # 环境变量解析
supports_thinking: false
supports_vision: true

models/factory.py 中的 create_chat_model() 函数通过 resolve_class() 反射机制将字符串路径解析为实际的 Python 类，实现了 Agent 逻辑与具体模型实现的完全解耦。

设计要点：

• 支持多提供商（OpenAI、Anthropic、DeepSeek、Ollama 等）
• 能力标记（supports_thinking、supports_vision）用于运行时条件分支
• 环境变量解析避免密钥硬编码

2.2 工具层（Tool Layer）

职责：让 Agent 能够操作外部世界，是 Agent 的"双手"。

DeerFlow 采用三层工具来源架构：

get_available_tools() 函数负责合并三层工具来源、去重（同名工具 config 优先）、并应用技能策略过滤。

此外，DeerFlow 还设计了一套延迟加载机制（tool_search），将大量 MCP 工具的完整 schema 隐藏，仅在 Agent 需要时按需暴露。该机制将在本系列第二篇中详细分析。

2.3 提示词层（Prompt Layer）

职责：定义 Agent 的"人格"、工作方式和约束条件。

DeerFlow 的系统提示词是一个精心设计的大型模板（SYSTEM_PROMPT_TEMPLATE），涵盖以下结构化章节：

• 角色定义：Agent 的身份和能力边界
• 思考风格：何时深度推理、何时快速执行
• 澄清机制：在信息不足时主动向用户提问的规则
• 技能系统：动态注入可用技能的描述
• 子 Agent 编排：任务分解和委派的规则
• 响应风格：输出格式、引用规范

关键设计决策：系统提示词保持静态（有利于 LLM 的 KV Cache 前缀缓存），动态信息（日期、记忆上下文等）通过 DynamicContextMiddleware 注入到用户消息中，而非修改系统提示词。

2.4 中间件层（Middleware Layer）

职责：在 Agent 核心推理循环外围注入横切关注点。

这是 DeerFlow 架构中设计最精密的部分。14+ 个中间件按严格顺序组成处理链：

ThreadData → Uploads → Sandbox → DanglingToolCall → Guardrail
→ ToolErrorHandling → Summarization → Todo → TokenUsage
→ Title → Memory → ViewImage → DeferredFilter → SubagentLimit
→ LoopDetection → SafetyFinishReason → Clarification

每个中间件解决一个独立的关注点，不侵入 Agent 核心逻辑：

中间件层的详细设计将在本系列第三篇中展开分析。

2.5 多 Agent 协作层（Multi-Agent Coordination）

职责：将复杂任务分解为多个专业子 Agent 并行处理。

DeerFlow 采用主 Agent + 子 Agent的分层架构：

• Lead Agent（主 Agent）：任务分解、结果整合、全局决策
• Subagent（子 Agent）：具体任务执行，通过 task() 工具接收委派

子 Agent 的执行由 SubagentExecutor 管理，运行在独立的事件循环中，支持：

• 并发控制（max_concurrent_subagents，默认 3）
• 超时机制（timeout_seconds，默认 900 秒）
• 协作取消（通过 cancel_event 信号）

子 Agent 的类型通过注册表管理，包括内置类型（general-purpose、bash）和用户自定义类型（通过 config.yaml 的 custom_agents 配置）。

2.6 状态与记忆层（State & Memory）

职责：管理对话上下文、跨会话记忆和持久化。

DeerFlow 的 ThreadState 扩展了 LangGraph 的 AgentState，包含以下字段：

class ThreadState(AgentState):
messages: list[BaseMessage] # 对话历史（核心）
sandbox: SandboxState # 沙箱环境标识
thread_data: ThreadDataState # 工作空间路径映射
title: str | None # 自动生成的对话标题
artifacts: Annotated[list[str], merge_artifacts] # 生成的文件列表
todos: Annotated[list | None, merge_todos] # 任务追踪
viewed_images: Annotated[dict, merge_viewed_images] # 视觉数据
promoted: Annotated[PromotedTools | None, merge_promoted] # 延迟工具提升记录

记忆系统分为两个层次：

• 短期记忆：当前对话的 messages 列表，通过 Summarization 做上下文窗口管理
• 长期记忆：MemoryMiddleware 异步提取对话中的关键信息，跨对话持久化存储

2.7 运行时与基础设施层（Runtime & Infrastructure）

职责：保障 Agent 在生产环境中可靠运行。

DeerFlow 的部署架构通过 Nginx 统一入口：

• /api/langgraph/* → Gateway（8001 端口）
• /* → Frontend（3000 端口）

2.8 技能层（Skills System）

职责：将专业能力打包为可复用的"技能包"。

技能以 Markdown 文件（SKILL.md）形式存在，包含 frontmatter 元数据和指令内容：

—
name: PDF Processing
description: Handle PDF documents efficiently
allowed-tools:
– read_file
– write_file
– bash
—

# 技能指令内容
（Agent 在需要时通过 read_file 主动加载）

技能系统的设计亮点：

• 渐进式加载：系统提示词中只列出技能名称和摘要，Agent 在判断需要时才读取完整内容
• 工具策略：allowed-tools 约束特定技能场景下可用的工具集
• 分类管理：public/（内置，只读）与 custom/（用户自定义，可编辑）
• 技能进化：skill_evolution 配置允许 Agent 在完成任务后自主创建或修补技能

三、架构全景图

┌─────────────────────────────────────────────────────────┐
│ 用户输入 │
└───────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 中间件链（前处理） │
│ 上下文注入 → 文件处理 → 沙箱准备 → 摘要检查 │
└───────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Agent 核心循环 │
│ │
│ ┌──────┐ ┌────────┐ ┌──────────┐ │
│ │ LLM │───→│ 决策 │───→│ 工具调用 │ │
│ │(大脑)│←───│ (思考) │←───│ (行动) │ │
│ └──────┘ └────────┘ └──────────┘ │
│ ↑ │ │
│ └────── 观察结果 ─────────┘ │
│ │
│ 终止条件：任务完成 / 需要澄清 / 达到限制 │
└───────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 中间件链（后处理） │
│ 标题生成 → 记忆保存 → 循环检测 → 安全检查 │
└───────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 流式输出给用户 │
└─────────────────────────────────────────────────────────┘

四、设计原则总结

通过对 DeerFlow 架构的分析，可以提炼出成熟 Agent 平台的几条核心设计原则：

下一篇预告

第二篇将深入分析 DeerFlow 的工具系统设计，重点讲解当 MCP 工具数量庞大时，如何通过 tool_search 延迟加载机制实现"仅暴露名称、按需加载 schema"的按需发现策略，以及这一设计在业界的独特性。