agentic_huge_data_base / wiki
页面 Dify · 14.2 Dify 智能体服务端与运行时 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 14.2

14.2 · Dify 智能体服务端与运行时 API（Dify Agent Server and Runtime API）

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

项目Dify 章节14.2 状态全文译文 模块智能体运行时、工作流与编排、记忆与上下文、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Dify Agent Server and Runtime API 上一章14.1 下一章13
源码线索
  • 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_config_manager.py
  • api/core/app/apps/agent_chat/app_runner.py
  • api/core/app/apps/base_app_runner.py
模块标签
  • 智能体运行时
  • 工作流与编排
  • 记忆与上下文
  • 接口与服务契约
  • 界面与交互

章节正文

Dify 智能体服务端与运行时 API

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/14.2-dify-agent-server-and-runtime-api

Dify 智能体服务器与运行时 API

相关源文件

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

  • 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_config_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/app/features/rate_limiting/rate_limit.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/enums/quota_type.py
  • api/factories/file_factory/message_files.py
  • api/factories/file_factory/validation.py
  • api/models/oauth.py
  • api/models/trigger.py
  • api/providers/trace/trace-langsmith/src/dify_trace_langsmith/entities/langsmith_trace_entity.py
  • api/services/app_generate_service.py
  • api/services/async_workflow_service.py
  • api/services/errors/app.py
  • api/services/quota_service.py
  • api/tasks/trigger_processing_tasks.py
  • api/tasks/workflow_schedule_tasks.py
  • api/tests/unit_tests/core/app/features/rate_limiting/conftest.py
  • api/tests/unit_tests/core/app/features/rate_limiting/test_rate_limit.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/factories/test_file_validation.py
  • api/tests/unit_tests/services/test_app_generate_service.py
  • api/tests/unit_tests/services/test_async_workflow_service.py

本文档描述了源代码中实现的 Dify Agent 服务器与运行时 API 的实现和功能。内容涵盖 FastAPI 服务器入口点、用于运行 AI Agent 工作负载的 API 请求/事件模式、将内部 Agenton 框架连接到 Dify 后端平台的适配器层，以及本地开发环境的配置。本页面是一个技术叶子节点，专注于 Agent 服务器的详细集成和运行时方面。

概述

Dify Agent 服务器与运行时 API 提供了一个 RESTful 接口，用于在 Dify 平台内运行 AI 请求并管理基于 Agent 的工作负载。它作为 Agent 执行请求的入口点，将这些请求转换为 Agenton Agent 组合框架内的操作流程，并支持流式和事件驱动的交互模式。

该运行时 API 将 Dify 的后端组件（如应用程序、模型、用户上下文、记忆和工具）连接到基于 Agenton 的 Agent 运行器，这些运行器负责编排 AI 模型调用、工具调用和多轮推理。

关键组件包括：

  • FastAPI 服务器作为 AI 执行的 HTTP 入口点。
  • 运行 API 请求和事件模式定义了 Agent 操作的输入和输出数据格式。
  • 适配器层将 Dify 后端应用程序和用户数据转换为 Agenton 运行时实体。
  • 本地开发便利功能，用于独立运行 Agent 服务器。

组件与数据流

智能体运行时入口点
  • Agent 运行时实现为一个 FastAPI 服务器，它公开了用于 AI 模型调用和事件流的 RESTful 端点。
  • 它接受传入的 API 请求，这些请求描述了任务参数、用户上下文和配置。
  • 这些请求被转换为 Agenton 组合计划，其中包含管理不同 Agent 任务的分层节点。
  • 服务器实时流式返回包含部分大语言模型（LLM）输出、工具使用信号（Agent 思考）和完成通知的事件。
API 请求和事件模式
  • 服务器为 运行 API 请求和响应定义了精确的 Pydantic 模式。
  • 输入模式表示：
    • 任务参数和 AI 模型配置。
    • 用户输入、记忆状态和上下文变量。
    • 工具配置和数据集。
  • 输出模式表示：
    • 流式增量大语言模型（LLM）结果（LLMResultChunk）。
    • 结构化的 Agent 思考和工具调用事件。
    • 完成和错误事件。

这些模式确保了可靠、强类型的通信和可扩展性。

适配器层：Agenton 到 Dify 后端
  • 适配器层在 Agenton 框架和 Dify 后端之间进行中介。
  • Dify 后端提供数据模型，如 App、Conversation、Message、ModelInstance 等，表示应用程序和用户上下文。
  • 适配器将这些后端实体转换为 Agenton 兼容的实体，如 AgentChatAppGenerateEntity 和 AgentEntity。
  • 它初始化适当的 Agent 运行器（例如 CotAgentRunner、FunctionCallAgentRunner），并配置记忆、工具、模型实例和回调处理器。
  • 在运行时，适配器：
    • 管理向 Dify 后端队列管理器发布事件。
    • 聚合流式大语言模型（LLM）输出。
    • 传播 Agent 思考和工具调用事件。
    • 管理提示消息组织和记忆检索。
    • 处理工具调用及其输入/输出。

该层在前端 API、Agent 执行逻辑和后端数据集成之间强制实现了关注点分离。

本地开发设置
  • Agent 服务器设计为便于 本地开发，支持启动独立的 FastAPI 服务器实例。
  • 开发者可以独立于完整的 Dify 后端平台运行和测试 Agent 运行时。
  • 这有助于调试、集成测试以及 Agent 技能和 API 交互的增量开发。

关键类及其角色

类名描述文件位置（行号）
BaseAgentRunner所有 Agent 运行器的抽象基类；管理共享的 Agent 状态、记忆、工具、队列、回调等。core/agent/base_agent_runner.py:53-180
CotAgentRunner思维链 Agent 运行器，实现带有工具集成和输出解析的迭代推理。core/agent/cot_agent_runner.py:38-203
FunctionCallAgentRunner用于函数调用模型的 Agent 运行器，管理工具调用检测和输出流。core/agent/fc_agent_runner.py:34-173
AppGenerateService服务类，根据应用模式（聊天、Agent 聊天等）分发应用生成请求。services/app_generate_service.py:39-148
TokenBufferMemory记忆管理类，用于检索和组织对话历史记录和文件作为提示消息。core/memory/token_buffer_memory.py:30-180
SimplePromptTransform负责将输入提示模板转换为基本聊天和补全模型的运行时提示消息。core/prompt/simple_prompt_transform.py:43-230
AdvancedPromptTransform处理工作流大语言模型（LLM）节点的高级提示转换，支持复杂模板和记忆集成。core/prompt/advanced_prompt_transform.py:24-216

FastAPI 服务器工作流（简化版）

Dify · FastAPI 服务器工作流（简化版） · 图 1
Dify · FastAPI 服务器工作流（简化版） · 图 1

图表说明：

  • 客户端向 FastAPI 服务器提交运行 API 请求。
  • 服务器校验请求并通过适配器构建 Agent 运行时实体。
  • Agent 运行器与 TokenBufferMemory 交互以检索消息历史，通过 ToolManager 初始化工具，并调用大语言模型（LLM）模型实例。
  • 当模型生成流式片段时，Agent 运行器将思考和工具调用事件发布到后端队列管理器进行处理/记录。
  • 流式片段和事件通过适配器反馈给服务器，并流式返回给客户端。

来源： api/core/agent/base_agent_runner.py:53-180 api/core/agent/cot_agent_runner.py:38-203 api/core/agent/fc_agent_runner.py:34-173 api/services/app_generate_service.py:39-148

智能体运行器与执行模型

BaseAgentRunner
  • 所有 Agent 运行器的核心抽象超类。
  • 持有以下引用：
    • 后端上下文：tenant_id、conversation、message、user_id。
    • 模型配置和模型实例。
    • 已加载的工具和数据集检索器工具。
    • 回调处理器和队列管理器。
    • 记忆（TokenBufferMemory）和提示消息。
  • 负责：
    • 为 Agent 组织提示消息。
    • 管理 Agent 的迭代思考和工具调用周期。
    • 通过 AppQueueManager 发布思考事件。
    • 检查模型功能，如流式工具调用支持。
CotAgentRunner
  • 实现带有迭代推理的思维链（CoT）。
  • 运行一个以最大迭代次数为上限的循环，重复调用模型。
  • 检测 Agent 输出中的工具调用动作。
  • 处理观察结果和工具调用输出，并将其作为提示上下文反馈。
  • 发出包含思考内容和动作标注的流式片段。
  • 维护一个草稿板以累积 Agent 推理状态。
FunctionCallAgentRunner
  • 专注于"函数调用"风格的 Agent 交互。
  • 流式输出部分结果，同时识别嵌入的工具调用。
  • 提前发布思考事件以指示 Agent 处理状态。
  • 处理流式和阻塞式大语言模型（LLM）输出格式。
  • 管理迭代周期，类似于 CoT，但专注于函数调用的结构化输出。

提示消息构建与记忆集成

系统使用 提示转换器 将输入模板、用户查询、文件和记忆历史转换为模型运行时消费的 PromptMessage 对象列表。

  • SimplePromptTransform 使用简单的提示模板为基本的聊天和补全模式构建提示消息。
  • AdvancedPromptTransform 支持复杂的提示模板，具有变量模板、记忆窗口和上下文处理功能。
  • 两个转换类都支持将图像和文件作为提示消息内容对象嵌入。

TokenBufferMemory 组件从数据库中获取对话历史消息和相关文件。它将它们转换为具有丰富内容（包括图像）的 UserPromptMessage 和 AssistantPromptMessage 对象。

然后，Agent 运行器在组装用于大语言模型（LLM）调用的提示消息时会包含此记忆，从而支持上下文连续性。

来源： api/core/app/apps/base_app_runner.py:52-186 api/core/memory/token_buffer_memory.py:30-180 api/core/prompt/simple_prompt_transform.py:43-230 api/core/prompt/advanced_prompt_transform.py:24-216

适配器层：从 Dify 后端到 Agenton 运行时实体

Agent 服务器接收请求中序列化的后端实体，并且必须将它们转换为 Agenton 使用的内部 API 实体。此适配器：

  • 将 App 模型和用户凭证解析为 AgentChatAppGenerateEntity。
  • 为 Agent 运行器构建 AgentEntity 配置。
  • 根据 Agent 类型管理特定运行器类（CotAgentRunner、FunctionCallAgentRunner）的实例化。
  • 注入记忆、模型实例和工具。
  • 通过 ToolManager 解析工具运行时配置。
  • 管理 Agent 运行器与后端队列事件发布者（AppQueueManager）之间的交互。

该层将后端数据模型与 Agent 运行时执行细节抽象开来，促进了灵活性和模块化。

本地开发与可测试性

  • 模块化的 FastAPI 服务器设计让开发者可以隔离运行 Agent 运行时。
  • 这允许使用 HTTP 客户端进行轻量级调试和交互式测试。
  • 流式输出事件支持实时可视化和工作流实验。
  • 系统日志和详细的运行时追踪有助于故障排除。

图表：连接自然语言空间与代码实体空间

此图表将高级概念（"自然语言空间"）映射到特定的代码实体（"代码实体空间"），揭示了概念性的 Dify Agent 服务器与运行时 API 如何转化为已实现的类和模块。

Dify · 图表：连接自然语言空间与代码实体空间 · 图 2
Dify · 图表：连接自然语言空间与代码实体空间 · 图 2

图表使用的来源： api/services/app_generate_service.py:39-148 api/core/agent/base_agent_runner.py:53-180 api/core/agent/cot_agent_runner.py:38-203 api/core/agent/fc_agent_runner.py:34-173 api/core/memory/token_buffer_memory.py:30-180 api/core/app/apps/base_app_queue_manager.py（未显示但被引用） api/core/tools/tool_manager.py（未显示但被引用）

图表：代码实体中智能体运行请求的运行时流程

Dify · 图表：代码实体中智能体运行请求的运行时流程 · 图 3
Dify · 图表：代码实体中智能体运行请求的运行时流程 · 图 3

此流程说明了代码内部的运行时调用链：

  • API 请求触发 AppGenerateService。
  • 服务选择一个 Agent 运行器类型。
  • Agent 运行器检索记忆历史和工具配置。
  • 运行器调用大语言模型（LLM）模型实例，流式返回响应片段。
  • 思考和工具调用事件被发布到队列管理器。
  • 流式事件被发送回客户端。

来源： api/services/app_generate_service.py:39-148 api/core/agent/base_agent_runner.py:53-180 api/core/agent/cot_agent_runner.py:38-203 api/core/agent/fc_agent_runner.py:34-173 api/core/memory/token_buffer_memory.py:30-180

角色职责总结

组件职责
FastAPI 服务器API 端点暴露、输入校验、请求-响应生命周期管理
AppGenerateService分发生成请求的入口点，带有速率限制和配额执行
AgentRunner 类实际的执行逻辑，实现 Agent 推理、模型交互、工具调用编排
TokenBufferMemory获取和组织对话历史及相关文件作为提示消息对象
ToolManager运行时工具创建和管理，用于可调用的 Agent 工具
AppQueueManager思考和工具调用生命周期通知的事件发布
ModelInstance抽象的大语言模型（LLM）提供商实例，用于模型调用和流式输出

结论

Dify Agent 服务器与运行时 API 是一个不可或缺的组件，它将 Dify 的后端系统与基于 Agenton 框架的 AI Agent 执行运行时连接起来。FastAPI 服务器公开了一个健壮、类型化的 API 接口，而适配器层则将 Dify 后端实体映射到 Agent 运行时对象。Agent 运行器处理核心模型调用、工具调用、状态持久化和事件流机制。

理解 BaseAgentRunner 及其特化类（CotAgentRunner、FunctionCallAgentRunner）、通过 TokenBufferMemory 进行的记忆集成以及分发服务 AppGenerateService 等关键类，对于扩展或调试 Dify Agent 运行时的开发者至关重要。这种架构支持丰富、可组合的 AI Agent，支持多种应用程序类型、流式范式和复杂的 Agent 行为。

来源：

  • api/core/agent/base_agent_runner.py:53-180
  • api/core/agent/cot_agent_runner.py:38-203
  • api/core/agent/fc_agent_runner.py:34-173
  • api/services/app_generate_service.py:39-148
  • api/core/memory/token_buffer_memory.py:30-180
  • api/core/prompt/simple_prompt_transform.py:43-230
  • api/core/prompt/advanced_prompt_transform.py:24-216