agentic_huge_data_base / wiki
页面 Dify · 9.6 高级聊天与智能体 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 9.6

9.6 · 高级聊天与智能体 API（Advanced Chat and Agent APIs）

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

项目Dify 章节9.6 状态全文译文 模块工作流与编排、文档对象与元数据、智能体运行时、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Advanced Chat and Agent APIs 上一章9.5 下一章9.7
源码线索
  • 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/advanced_chat/app_generator.py
  • api/core/app/apps/advanced_chat/app_runner.py
  • api/core/app/apps/advanced_chat/generate_task_pipeline.py
模块标签
  • 工作流与编排
  • 文档对象与元数据
  • 智能体运行时
  • 测试、发布与运维
  • 记忆与上下文

章节正文

高级聊天与智能体 API

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/9.6-advanced-chat-and-agent-apis

高级聊天与智能体 API

相关源文件

本章引用的主要源码文件：

  • 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/advanced_chat/app_generator.py
  • api/core/app/apps/advanced_chat/app_runner.py
  • api/core/app/apps/advanced_chat/generate_task_pipeline.py
  • api/core/app/apps/agent_chat/app_generator.py
  • api/core/app/apps/agent_chat/app_runner.py
  • api/core/app/apps/base_app_runner.py
  • api/core/app/apps/chat/app_generator.py
  • api/core/app/apps/chat/app_runner.py
  • api/core/app/apps/completion/app_generator.py
  • api/core/app/apps/completion/app_runner.py
  • api/core/app/apps/message_based_app_generator.py
  • api/core/app/apps/pipeline/pipeline_runner.py
  • api/core/app/apps/workflow/app_generator.py
  • api/core/app/apps/workflow/app_runner.py
  • api/core/app/apps/workflow/generate_task_pipeline.py
  • api/core/app/apps/workflow_app_runner.py
  • api/core/app/entities/queue_entities.py
  • api/core/app/entities/task_entities.py
  • api/core/app/task_pipeline/easy_ui_based_generate_task_pipeline.py
  • api/core/app/task_pipeline/message_cycle_manager.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/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/chat/test_base_app_runner_multimodal.py
  • api/tests/unit_tests/core/app/apps/test_advanced_chat_app_generator.py
  • api/tests/unit_tests/core/app/task_pipeline/test_easy_ui_based_generate_task_pipeline.py
  • api/tests/unit_tests/core/app/task_pipeline/test_message_cycle_manager_optimization.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 的高级功能，特别是智能体模式（提供工具执行可见性）和基于工作流的聊天应用（提供详细的节点执行事件）。这些高级功能在基础聊天 API 之上增加了对 AI 推理过程和工作流执行状态的细粒度可观测性。

关于基础聊天功能（包括消息发送、会话管理和文件处理），请参见聊天与补全 API。关于不依赖聊天会话的独立工作流执行，请参见工作流执行 API。

目的与范围

高级聊天 API 在基础聊天之上提供了两大增强功能：

  1. 智能体模式：通过 agent_thought 事件暴露智能体的推理过程，包括工具选择、工具输入和工具观察结果。该功能由专门的运行器处理，例如 CotAgentRunner api/core/agent/cot_agent_runner.py:38-38 和 FunctionCallAgentRunner api/core/agent/fc_agent_runner.py:34-34。
  2. 基于工作流的聊天：通过 AdvancedChatAppGenerateTaskPipeline api/core/app/apps/advanced_chat/generate_task_pipeline.py:141-141，为基于工作流构建的聊天应用流式传输详细的工作流执行事件（workflow_started、node_started、node_finished、workflow_finished）。

两种模式均使用服务器推送事件（SSE）流式传输来提供执行的实时可见性，从而实现丰富的用户界面体验，让用户了解 AI 的思考和行为过程。

来源：api/core/app/apps/advanced_chat/generate_task_pipeline.py:24-54、api/core/agent/cot_agent_runner.py:38-46、api/core/app/entities/queue_entities.py:15-54

智能体模式架构

智能体思考事件
Dify · 智能体思考事件 · 图 1
Dify · 智能体思考事件 · 图 1

图：智能体模式执行流程

在智能体模式下，聊天应用使用工具来完成任务。智能体每次推理迭代都会以 agent_thought 事件的形式暴露出来。CotAgentRunner 负责管理思考、行动和观察的循环 api/core/agent/cot_agent_runner.py:103-133。

  1. 推理：智能体的思考过程被捕获在 AgentScratchpadUnit 的 thought 字段中 api/core/agent/cot_agent_runner.py:162-163。
  2. 工具选择：智能体决定使用哪些工具的信息存储在 action 字段中 api/core/agent/cot_agent_runner.py:152-158。
  3. 观察结果：工具执行后的响应通过 ToolEngine 被捕获为观察结果 api/core/agent/cot_agent_runner.py:137-142。

来源：api/core/agent/cot_agent_runner.py:103-173、api/core/app/entities/queue_entities.py:19-19、api/core/agent/fc_agent_runner.py:85-87

智能体消息与常规消息事件

在智能体模式下，文本输出使用 agent_message 事件，而不是 message 事件：

事件类型代码实体描述
messageQueueTextChunkEvent在非智能体应用中直接流式传输的大语言模型文本片段 api/core/app/entities/queue_entities.py:47-47。
agent_messageQueueAgentMessageEvent工具执行周期结束后的最终响应 api/core/app/entities/queue_entities.py:18-18。
agent_thoughtQueueAgentThoughtEvent工具执行详情，由 BaseAgentRunner 管理 api/core/app/entities/queue_entities.py:19-19。

来源：api/core/app/entities/queue_entities.py:18-47、api/core/app/task_pipeline/easy_ui_based_generate_task_pipeline.py:31-32

基于工作流的聊天应用

工作流事件流
Dify · 工作流事件流 · 图 2
Dify · 工作流事件流 · 图 2

图：基于工作流的聊天事件流

当聊天应用使用工作流构建时，AdvancedChatAppGenerateTaskPipeline 会处理来自 AppQueueManager 的事件 api/core/app/apps/advanced_chat/generate_task_pipeline.py:141-158。这提供了每个节点执行的可见性。

  • workflow_started：当图开始执行时触发 api/core/app/entities/queue_entities.py:51-51。
  • node_started：当特定节点开始执行时发出 api/core/app/entities/queue_entities.py:42-42。
  • node_succeeded：包含输出和执行元数据（如 Token 使用量）api/core/app/entities/queue_entities.py:43-43。

来源：api/core/app/apps/advanced_chat/generate_task_pipeline.py:24-54、api/core/app/entities/queue_entities.py:39-52

指定工作流版本

AdvancedChatAppGenerator 允许通过参数指定特定的工作流版本 api/core/app/apps/advanced_chat/app_generator.py:108-118。

  • 工作流模型：生成器直接接受一个 Workflow 模型实例 api/core/app/apps/advanced_chat/app_generator.py:111-111。
  • 草稿支持：Dify 通过 WorkflowDraftVariableService 和 DraftVarLoader 区分已发布的工作流和草稿 api/core/app/apps/advanced_chat/app_generator.py:58-61。

来源：api/core/app/apps/advanced_chat/app_generator.py:108-118、api/core/app/apps/advanced_chat/generate_task_pipeline.py:95-106

事件流序列

完整事件序列示例

序列由任务管线管理，该管线将执行包装在生成器中 api/core/app/apps/workflow/generate_task_pipeline.py:124-133。

  1. 工作流事件：QueueWorkflowStartedEvent 首先到达 api/core/app/entities/queue_entities.py:51-51。
  2. 节点事件：节点发出 QueueNodeStartedEvent 和 QueueNodeSucceededEvent api/core/app/entities/queue_entities.py:42-43。
  3. 智能体事件：如果使用了智能体运行器，则会穿插 QueueAgentThoughtEvent api/core/agent/cot_agent_runner.py:118-120。
  4. 高级聊天结束：QueueAdvancedChatMessageEndEvent 表示高级聊天的完成 api/core/app/entities/queue_entities.py:26-26。

来源：api/core/app/apps/workflow/generate_task_pipeline.py:124-133、api/core/app/entities/queue_entities.py:15-54、api/core/agent/cot_agent_runner.py:113-120

性能与成本追踪

细粒度指标

指标通过 LLMUsage 实体收集 api/core/agent/cot_agent_runner.py:18-18。

  • 节点级别：节点在执行期间追踪使用量，并在 node_succeeded 事件中返回 api/core/app/entities/queue_entities.py:43-43。
  • 工作流级别：WorkflowAppBlockingResponse 从执行中汇总 total_tokens 和 total_steps api/core/app/apps/workflow/generate_task_pipeline.py:163-165。
  • 智能体级别：CotAgentRunner 通过 increase_usage 辅助函数累积多次迭代的使用量 api/core/agent/cot_agent_runner.py:89-99。

来源：api/core/app/apps/workflow/generate_task_pipeline.py:153-170、api/core/agent/cot_agent_runner.py:89-99、api/core/app/entities/task_entities.py:239-240