agentic_huge_data_base / wiki
页面 Dify · 14.1 Agenton 框架与分层架构·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 14.1

14.1 · Agenton 框架与分层架构（Agenton Framework and Layer Architecture）

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目Dify 章节14.1 状态全文译文 模块智能体运行时、记忆与上下文、模型调用与提供方适配、配置治理
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Agenton Framework and Layer Architecture 上一章14 下一章14.2
源码线索
  • api/core/agent/base_agent_runner.py
  • api/core/agent/cot_agent_runner.py
  • api/core/agent/cot_chat_agent_runner.py
  • api/core/agent/cot_completion_agent_runner.py
  • api/core/agent/entities.py
  • api/core/agent/fc_agent_runner.py
  • api/core/app/app_config/easy_ui_based_app/agent/manager.py
  • api/core/app/apps/agent_chat/app_runner.py
  • api/core/app/apps/base_app_runner.py
  • api/core/app/apps/chat/app_runner.py
模块标签
  • 智能体运行时
  • 记忆与上下文
  • 模型调用与提供方适配
  • 配置治理
  • 图谱与关系

章节正文

Agenton 框架与分层架构

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/14.1-agenton-framework-and-layer-architecture

Agenton 框架与分层架构

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • api/core/agent/base_agent_runner.py
  • api/core/agent/cot_agent_runner.py
  • api/core/agent/cot_chat_agent_runner.py
  • api/core/agent/cot_completion_agent_runner.py
  • api/core/agent/entities.py
  • api/core/agent/fc_agent_runner.py
  • api/core/app/app_config/easy_ui_based_app/agent/manager.py
  • api/core/app/apps/agent_chat/app_runner.py
  • api/core/app/apps/base_app_runner.py
  • api/core/app/apps/chat/app_runner.py
  • api/core/app/apps/completion/app_runner.py
  • api/core/memory/token_buffer_memory.py
  • api/core/prompt/advanced_prompt_transform.py
  • api/core/prompt/agent_history_prompt_transform.py
  • api/core/prompt/entities/advanced_prompt_entities.py
  • api/core/prompt/prompt_transform.py
  • api/core/prompt/simple_prompt_transform.py
  • api/core/workflow/workflow_entry.py
  • api/factories/file_factory/message_files.py
  • api/factories/file_factory/validation.py
  • api/providers/trace/trace-langsmith/src/dify_trace_langsmith/entities/langsmith_trace_entity.py
  • api/tests/unit_tests/core/app/apps/test_workflow_app_runner_core.py
  • api/tests/unit_tests/core/app/apps/test_workflow_app_runner_single_node.py
  • api/tests/unit_tests/core/memory/test_token_buffer_memory.py
  • api/tests/unit_tests/core/prompt/test_advanced_prompt_transform.py
  • api/tests/unit_tests/core/prompt/test_agent_history_prompt_transform.py
  • api/tests/unit_tests/core/prompt/test_simple_prompt_transform.py
  • api/tests/unit_tests/core/workflow/nodes/llm/test_node.py
  • api/tests/unit_tests/core/workflow/nodes/webhook/test_webhook_file_conversion.py
  • api/tests/unit_tests/core/workflow/nodes/webhook/test_webhook_node.py
  • api/tests/unit_tests/core/workflow/test_workflow_entry.py
  • api/tests/unit_tests/factories/test_file_validation.py

Dify 中的 Agenton 框架为构建和执行 AI 代理与工作流提供了健壮且可扩展的架构。该框架旨在弥合自然语言指令与代码执行之间的鸿沟，支持构建复杂的多步骤 AI 应用。本文档详细介绍了 Agenton 框架的核心组件，包括其编排器（compositor）、LayerNode/LayerProvider 抽象、基于图的计划组合（graph-based plan composition）、会话快照（session snapshots）以及每次运行的配置管理。

目的与范围

Agenton 框架是 Dify 代理能力的基础组件，尤其适用于 AGENT_CHAT 和 WORKFLOW 类型的应用。它支持动态构建和执行 AI 驱动的流程，从而实现复杂的交互和问题求解。该框架的设计强调模块化、可扩展性和可观测性，有助于创建能够适应各种场景并与多种工具和模型集成的复杂 AI 应用。

核心组件

Agenton 框架围绕几个关键的抽象构建，这些抽象实现了其灵活且强大的执行模型。

Agenton 编排器

Agenton 编排器负责编排代理逻辑的执行。它利用分层架构在代理运行期间应用各种功能和关注点。这实现了关注点的清晰分离，并便于扩展代理行为。

LayerNode 和 LayerProvider 抽象

LayerNode 和 LayerProvider 是 Agenton 框架中的基本抽象。它们代表了可组合以构建复杂代理行为的模块化功能单元。

  • LayerNode：LayerNode 封装了代理执行中的特定逻辑片段或步骤。这可以包括与大语言模型（LLM）交互、调用工具或处理数据等任何操作。
  • LayerProvider：LayerProvider 负责提供和管理 LayerNode 实例。它充当工厂角色，用于创建和配置节点，确保节点拥有必要的依赖项和上下文。

在 Dify 的工作流引擎上下文中，GraphEngine api/core/workflow/workflow_entry.py:34-34 是一个核心组件，它采用了分层方法。它允许注入各种层来修改或增强执行流程。例如，LLMQuotaLayer api/core/workflow/workflow_entry.py:11-11 用于管理大语言模型（LLM）的使用量，ObservabilityLayer api/core/workflow/workflow_entry.py:12-12 用于追踪和监控。

图示：Agenton 分层架构

Dify · LayerNode 和 LayerProvider 抽象 · 图 1
Dify · LayerNode 和 LayerProvider 抽象 · 图 1

来源： api/core/workflow/workflow_entry.py:11-12 api/core/agent/cot_agent_runner.py api/core/agent/fc_agent_runner.py

基于图的计划组合

Agenton 框架，特别是通过与 Graphon 库的集成，支持基于图的计划组合。这意味着代理行为可以定义为节点的有向无环图（DAG），其中每个节点代表一个 LayerNode 或一个特定的操作。

Graph 类 api/core/workflow/workflow_entry.py:99-103 用于从配置初始化工作流图。然后，GraphEngine api/core/workflow/workflow_entry.py:34-34 执行该图，管理节点之间的数据流和控制流。这种方法允许以高度灵活和可视化的方式构建复杂的代理工作流。

例如，在 Dify 的工作流引擎中，DifyNodeFactory api/core/workflow/workflow_entry.py:16-18 负责根据工作流配置创建节点实例。该工厂解析适当的节点类并注入必要的依赖项。

图示：基于图的代理计划组合

Dify · 基于图的计划组合 · 图 2
Dify · 基于图的计划组合 · 图 2

来源： api/core/workflow/workflow_entry.py:16-18 api/core/workflow/workflow_entry.py:34-34 api/core/workflow/workflow_entry.py:99-103 graphon/graph_engine.py graphon/graph.py graphon/runtime.py api/core/agent/cot_agent_runner.py api/core/agent/fc_agent_runner.py

会话快照

Agenton 框架支持会话快照，这对于在多次交互之间维护状态或恢复中断的工作流至关重要。这对于长时间运行的代理对话或可能需要人工干预的复杂工作流尤其重要。

GraphRuntimeState api/core/workflow/workflow_entry.py:84-88 对象保存了图执行的当前状态，包括 VariablePool 和执行上下文。该状态可以序列化和反序列化，从而支持代理会话的持久化和恢复。

每次运行的配置管理

每次代理运行都可以拥有自己特定的配置，允许在不修改底层代理定义的情况下动态调整行为。这是通过 GraphInitParams graphon/entities.py:29-29 和 ModelConfigWithCredentialsEntity [api/core/app/entities/app_invoke_entities.py:15-15()] 对象来管理的。

WorkflowEntry 类 api/core/workflow/workflow_entry.py:139-154 接收 graph_config 和 graph_init_params 作为参数，这些参数定义了特定工作流执行的具体设置。这包括 tenant_id、app_id、user_id 和 invoke_from 等详细信息，确保每次运行都在其指定的上下文和权限内操作。

BaseAgentRunner api/core/agent/base_agent_runner.py:53-69 也会为每次运行接收 application_generate_entity、app_config 和 model_config，使其能够根据特定的应用和模型设置来调整其行为。

代理实现

Dify 基于 Agenton 框架实现了不同的代理类型，主要是 CotAgentRunner 和 FunctionCallAgentRunner。两者都继承自 BaseAgentRunner api/core/agent/base_agent_runner.py:53-69，并利用了框架的能力。

BaseAgentRunner

BaseAgentRunner api/core/agent/base_agent_runner.py:53-69 为所有代理类型提供了通用功能，包括：

  • 初始化：设置 tenant_id、application_generate_entity、conversation、app_config、model_config、message、user_id、model_instance 和 memory。
  • 提示词组织：使用 organize_prompt_messages api/core/app/apps/base_app_runner.py:88-99 管理提示消息的构建，包括系统提示词、用户查询和历史消息。
  • 工具管理：初始化并管理代理可用的工具，将其转换为 PromptMessageTool 格式 api/core/agent/base_agent_runner.py:138-158。
  • 大语言模型（LLM）交互：处理与大语言模型（LLM）的交互，包括 Token 计算和调用。
  • 代理思考过程创建：创建 MessageAgentThought 记录以追踪代理的推理过程 api/core/agent/base_agent_runner.py:106-115。

来源： api/core/agent/base_agent_runner.py:53-69 api/core/agent/base_agent_runner.py:106-115 api/core/agent/base_agent_runner.py:138-158 api/core/app/apps/base_app_runner.py:88-99

CotAgentRunner（思维链）

CotAgentRunner api/core/agent/cot_agent_runner.py:38-45 实现了思维链（Chain-of-Thought，CoT）推理策略。它迭代地生成思考、行动和观察结果来解决问题。

  • run 方法：主执行循环 api/core/agent/cot_agent_runner.py:47-175 迭代地调用大语言模型（LLM），解析其输出以获取思考和行动，执行工具，并将观察结果合并回提示词中。
  • _agent_scratchpad：存储 AgentScratchpadUnit api/core/agent/cot_agent_runner.py:42-42 对象的序列，这些对象代表了代理的推理步骤（思考、行动、观察）。
  • CotAgentOutputParser：将大语言模型（LLM）的原始输出解析为结构化的 AgentScratchpadUnit api/core/agent/cot_agent_runner.py:136-136 组件。

CotChatAgentRunner api/core/agent/cot_chat_agent_runner.py:16-33 和 CotCompletionAgentRunner api/core/agent/cot_completion_agent_runner.py:1-1 扩展了 CotAgentRunner，以处理聊天和补全类型的特定提示词格式化。

来源： api/core/agent/cot_agent_runner.py:38-45 api/core/agent/cot_agent_runner.py:42-42 api/core/agent/cot_agent_runner.py:47-175 api/core/agent/cot_agent_runner.py:136-136 api/core/agent/cot_chat_agent_runner.py:16-33 api/core/agent/cot_completion_agent_runner.py:1-1

FunctionCallAgentRunner

FunctionCallAgentRunner api/core/agent/fc_agent_runner.py:34-35 利用支持原生函数调用能力的大语言模型（LLM）。它无需解析文本以获取行动，而是直接从大语言模型（LLM）接收结构化的工具调用。

  • run 方法：执行循环 api/core/agent/fc_agent_runner.py:34-35 使用可用工具调用大语言模型（LLM）。如果大语言模型（LLM）返回工具调用，则执行这些调用，并将其结果反馈给大语言模型（LLM）。
  • check_tool_calls 和 extract_tool_calls：用于从大语言模型（LLM）响应中识别和提取结构化工具调用的方法 api/core/agent/fc_agent_runner.py:122-124。
  • ToolEngine：执行识别出的工具调用 api/core/agent/fc_agent_runner.py:200-200。

来源： api/core/agent/fc_agent_runner.py:34-35 api/core/agent/fc_agent_runner.py:122-124 api/core/agent/fc_agent_runner.py:200-200

数据流与关键函数

代理运行时涉及组件之间复杂的交互，以处理用户查询、生成响应并与外部工具交互。

图示：Agenton 数据流

Dify · 数据流与关键函数 · 图 3
Dify · 数据流与关键函数 · 图 3

来源： api/core/app/apps/base_app_runner.py api/core/app/apps/agent_chat/app_runner.py api/core/prompt/prompt_transform.py api/core/memory/token_buffer_memory.py models/model.py api/core/agent/base_agent_runner.py api/core/agent/cot_agent_runner.py api/core/agent/fc_agent_runner.py core/agent/entities.py core/tools/tool_engine.py core/app/apps/base_app_queue_manager.py core/app/entities/queue_entities.py core/app/entities/app_invoke_entities.py core/app/apps/agent_chat/app_config_manager.py

关键函数与类
  • AppRunner [api/core/app/apps/base_app_runner.py:52-52()]：所有应用运行器的基类，提供通用工具方法，如 recalc_llm_max_tokens api/core/app/apps/base_app_runner.py:54-86 和 organize_prompt_messages api/core/app/apps/base_app_runner.py:88-99。
  • AgentChatAppRunner [api/core/app/apps/agent_chat/app_runner.py:27-30()]：代理聊天应用专用的运行器，负责编排代理的执行流程，包括内容审核、外部数据工具集成和代理类型选择。
  • BaseAgentRunner [api/core/agent/base_agent_runner.py:53-69()]：代理实现的抽象基类，定义了代理的通用接口和共享逻辑。
  • CotAgentRunner [api/core/agent/cot_agent_runner.py:38-45()]：实现思维链推理模式，管理代理的草稿板（scratchpad）和迭代的大语言模型（LLM）调用。
  • FunctionCallAgentRunner [api/core/agent/fc_agent_runner.py:34-35()]：利用大语言模型（LLM）函数调用能力实现代理逻辑。
  • TokenBufferMemory [api/core/memory/token_buffer_memory.py:30-32()]：管理对话历史，将 Message 对象转换为适合大语言模型（LLM）输入的 PromptMessage，并考虑 Token 限制。
  • PromptTransform [api/core/prompt/prompt_transform.py:12-12()]：提示词转换的基类，其中 SimplePromptTransform api/core/prompt/simple_prompt_transform.py:44-47 和 AdvancedPromptTransform api/core/prompt/advanced_prompt_transform.py:24-27 处理不同类型的提示词模板。
  • ToolEngine：负责执行代理调用的工具。
  • AppQueueManager [core/app/apps/base_app_queue_manager.py:10-10()]：处理向客户端发布事件（例如，代理思考、大语言模型（LLM）分块、消息结束）。

来源：

  • api/core/app/apps/base_app_runner.py:52-52
  • api/core/app/apps/base_app_runner.py:54-86
  • api/core/app/apps/base_app_runner.py:88-99
  • api/core/app/apps/agent_chat/app_runner.py:27-30
  • api/core/agent/base_agent_runner.py:53-69
  • api/core/agent/cot_agent_runner.py:38-45
  • api/core/agent/fc_agent_runner.py:34-35
  • api/core/memory/token_buffer_memory.py:30-32
  • api/core/prompt/prompt_transform.py:12-12
  • api/core/prompt/simple_prompt_transform.py:44-47
  • api/core/prompt/advanced_prompt_transform.py:24-27
  • core/app/apps/base_app_queue_manager.py:10-10