系列导航

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

摘要

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

---

一、什么是 Agent

1.1 从 LLM 到 Agent 的本质跃迁

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

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

1. 主动决定调用工具（搜索网页、执行代码、读写文件等）
2. 接收工具执行结果，将其作为新的输入反馈给 LLM
3. 持续迭代上述"思考→行动→观察"的循环，直到任务完成

用一个公式概括：

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 采用三层工具来源架构：

层级	来源	加载时机	典型工具
Built-in	代码内置	编译时确定	present_file、ask_clarification、view_image、task
Configured	config.yaml 配置	启动时加载	web_search、bash、read_file、write_file、str_replace
MCP	外部 MCP 服务器	运行时动态发现	GitHub、Postgres、Puppeteer 等

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 核心逻辑：

中间件	关注点
SandboxMiddleware	代码执行环境的隔离分配与回收
SummarizationMiddleware	上下文窗口溢出时的自动摘要压缩
LoopDetectionMiddleware	检测并打断重复工具调用的死循环
MemoryMiddleware	跨对话的长期记忆提取与注入
SafetyFinishReasonMiddleware	处理提供商安全过滤导致的截断响应
ClarificationMiddleware	拦截澄清请求并中断执行等待用户回复

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

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 在生产环境中可靠运行。

组件	职责
Gateway API (FastAPI)	HTTP 接口、LangGraph 兼容路由、SSE 流式响应
StreamBridge	实时事件推送与重放
Checkpointer	图状态持久化（支持中断恢复）
Sandbox Provider	代码执行隔离（Local / Docker / K8s）
CircuitBreaker	LLM 调用故障熔断
RunJournal	运行时审计日志

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 平台的几条核心设计原则：

1. 关注点分离：模型、工具、提示词、状态各自独立，通过配置组合。不同关注点的变更不互相影响。

2. 可扩展性优先：MCP 协议使工具集无限扩展，Skills 系统使能力可复用，中间件模式使功能可插拔。

3. 生产级韧性：熔断器、循环检测、超时控制、安全防护不是可选项，而是生产环境的必要条件。

4. 配置驱动：一份 config.yaml 控制系统全部行为，无需修改代码即可调整模型、工具、策略。

5. 中间件模式：横切关注点（安全、摘要、记忆、审计）通过中间件实现，不侵入 Agent 核心推理逻辑。

---

下一篇预告

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