Dify Agent Server 模块分析 (Commit 55f95dbc)#

注意：自 PR #38841 起，shellctl 已用 Go 重写为 dify-agent-runtime。本文档描述的是 commit 55f95dbc 中的原始 Python 实现。

概述#

Commit 55f95dbc 于 2026-05-14 由 BeautyyuYanli 合并，对应 PR #36087 feat(agent): init agent server。该提交向 Dify monorepo 引入了一个全新的独立子包 dify-agent，总计新增 128 个文件、17,357 行代码（含约 6,000 行以上测试代码），是 Dify 迄今为止规模最大的单次功能提交之一 1。

dify-agent 是一个基于 FastAPI 的生产级 AI Agent 后端服务，为异步 Agent 运行提供完整的生命周期管理能力，包括：

• 异步运行执行：运行在后台 asyncio 任务中，客户端断连不影响 Agent 执行
• Redis 事件流：所有运行记录和事件以 Redis Stream 形式持久化，支持游标分页和 SSE 回放
• Python 客户端库：提供同步 / 异步 HTTP 客户端，含 SSE 重连逻辑
• Agenton 框架：一个可独立使用的无状态 Layer 图组合框架，支持可序列化运行时状态和会话快照

整个包由三大顶层命名空间组成：

该提交以多个子提交递进完成，涵盖项目脚手架（feat(agent): add dify agent project setup）、LLM 适配器（feat(agent): add dify llm adapter）、Agenton 引擎初始化（initialize the agenton engine）及结构调整（move the collections folder structure）等阶段 1。

与 Dify 现有架构的关系#

旧版 Agent 系统#

在 dify-agent 包引入之前，Dify 的 Agent 执行依赖于主应用（api/）中的一套同步 runner 体系：

BaseAgentRunner 2 是所有 Agent runner 的抽象基类，负责工具初始化与转换、Agent 思考链条（AgentThought）的数据库持久化、对话历史组织，以及与 QueueManager 的事件发布集成。

CotAgentRunner 3 继承自 BaseAgentRunner，实现链式思维（Chain-of-Thought）执行模式：通过 thought → action → observation 的迭代循环驱动 Agent，使用 CotAgentOutputParser 解析 ReAct 格式输出，并强制执行最大迭代次数限制。

FunctionCallAgentRunner 4 同样继承自 BaseAgentRunner，利用 LLM 的原生函数调用能力（tool_calls），支持流式和非流式两种工具调用提取路径，每次迭代动态更新工具参数。

此外还有 CotChatAgentRunner 5 和 CotCompletionAgentRunner 6 两个针对不同对话模式的 CoT 变体。

工作流 Agent 节点#

AgentNode 7 是更新的工作流集成点，继承自 graphon Node 基类，可嵌入 Dify 工作流图中。它使用 AgentStrategyResolver 动态加载 Agent 策略实现，通过消息转换适配工作流格式，并管理 Plugin 凭证。

Plugin Agent Strategy 层#

PluginAgentStrategy 8 实现了策略模式，将具体 Agent 执行委托给 PluginAgentClient，支持流式响应。

PluginAgentClient 9 通过 HTTP 与 Plugin Daemon（默认端口 5002）通信，负责：

• 获取 Agent 策略提供者和策略定义
• 使用结构化参数调用 Agent 策略
• 将内部格式与 Plugin Daemon 格式互转

Plugin Daemon 承载着 LLM 提供者插件的完整运行时（如 langgenius/openai），是 Agent 实际发起 LLM 调用的入口。

新模块的定位#

dify-agent 包并不替换上述现有组件，而是在其旁边建立了一个独立的微服务边界：

• 集成方式：PR #36284 将 dify-agent 从开发依赖提升至生产依赖 10，API 端通过 DifyAgentBackendRunClient 实现完整的 Agent 后端集成
• 与 Plugin Daemon 的关系：新模块直接与 Plugin Daemon（端口 5002）通信，复用了同一个 LLM 提供者运行时基础设施
• 与 Redis 的关系：Redis 仅作为持久化存储使用（非作业队列），保存 run 记录和 Redis Stream 事件，两端均可独立扩展

┌─────────────────────────────────────────────────────┐
│ Dify API (api/) │
│ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ 旧版 Runner │ │ dify-agent Client │ │
│ │ (CoT / FC) │ │ (HTTP → Agent Server) │ │
│ └──────┬───────┘ └──────────┬───────────────┘ │
└─────────┼─────────────────────┼─────────────────────┘
          │ │
          ▼ ▼
   ┌─────────────┐ ┌──────────────────┐
   │Plugin Daemon│ │ dify-agent │
   │ :5002 │◄─────│ Server :8000 │
   └─────────────┘ └────────┬─────────┘
                                 │
                            ┌────▼─────┐
                            │ Redis │
                            └──────────┘

这一设计标志着 Dify 从单体同步执行模型向异步微服务化 Agent 执行的架构演进。

graphon 升级与 HITL 逻辑迁移#

PR #38247 将 graphon 依赖从 0.5.3 升级至 0.6.0，并将 Human-in-the-Loop（HITL）表单定义和验证逻辑从 graphon 迁移回 Dify。graphon v0.6.0 保留了最小 HITL 回调契约（HITLContext、HITLDecision、PauseRequested、Completed、Expired），而 Dify 现在拥有工作流专用的表单 schema、字段类型（Paragraph、Select、File、FileList）、超时语义和 DifyHITLCallback 实现。这一重构明确了架构边界：graphon 提供通用暂停 / 恢复基础设施，Dify 管理具体的人工输入表单业务逻辑。

HITL 逻辑迁移详情#

新增模块 api/core/workflow/nodes/human_input/ 包含 Dify 拥有的 HITL 实现：

• entities.py (374 行)：表单 schema 定义，包括 HumanInputNodeData、FormInputConfig 类型（ParagraphInputConfig、SelectInputConfig、FileInputConfig、FileListInputConfig）、UserActionConfig、FormDefinition，以及 validate_human_input_submission 验证函数
• callback.py (329 行)：DifyHITLCallback 类，桥接 Dify 人工输入语义到 graphon HITL 决策。该回调处理表单创建、状态规范化、超时判断、提交数据恢复和占位符渲染
• enums.py：FormInputType、HumanInputFormStatus（WAITING、EXPIRED、SUBMITTED、TIMEOUT）、ButtonStyle、TimeoutUnit、ValueSourceType
• pause_reason.py：Dify 的 HumanInputRequired 暂停原因和 DifyHITLEventType
• boundary.py、session_binding.py、_exc.py：边界协议、会话绑定和异常定义

超时语义变更#

新的超时处理区分节点级超时和全局过期：

• HumanInputFormStatus.TIMEOUT：节点级超时到达，通过 Expired(selected_handle="__timeout__") 返回 graphon 超时分支
• HumanInputFormStatus.EXPIRED：全局过期（由 HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS 控制），视为无效恢复状态，抛出 AssertionError
• HumanInputFormStatus.WAITING 且全局截止时间已过：同样视为无效，抛出 AssertionError
• HumanInputFormStatus.WAITING 且仅节点级截止时间已过：仍返回超时分支

HumanInputFormEntity 新增 created_at 属性，用于计算全局截止时间（created_at + HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS）。

Agent V2 节点集成#

Agent v2 节点现已集成新的 Dify 拥有的 HITL 实体和回调：

• api/core/workflow/nodes/agent_v2/agent_node.py：使用 DifyHITLCallback 构建人工输入暂停，通过 default_session_binding 转换暂停原因为 graphon HitlRequired
• api/core/workflow/nodes/agent_v2/ask_human_hitl.py 和 ask_human_resume.py：与新的 HumanInputRequired 暂停原因和表单实体协作

Repository 和 Service 层变更#

• human_input_repository.py：增强 HumanInputFormEntity 协议（新增 created_at 属性），新增 get_by_form_id() 方法（17 行新增）
• workflow_service.py：重构调试人工输入节点构建逻辑（66 行新增、40 行删除），现使用 _DebugHumanInputNode 数据类和 DifyHITLCallback 的静态渲染方法
• pause_state_persist_layer.py：更新以支持新的暂停状态处理（11 行新增）

Node Factory 和 Runtime 更新#

• node_factory.py：create_node 方法现为 BuiltinNodeTypes.HUMAN_INPUT 实例化 DifyHITLCallback，并传递表单仓库、节点数据、对话 ID、投递方法、显示标志和文件引用工厂（19 行新增）
• node_runtime.py：修改以使用新的暂停 / 恢复语义（15 行新增、17 行删除）

架构意义#

此变更实现了更清晰的架构边界：graphon 保留通用的 HITL 决策协议（PauseRequested、Completed、Expired），而 Dify 拥有工作流特定的表单定义、验证规则、超时语义和兼容性载荷形状。这种分离使 graphon 保持轻量级和通用，同时给予 Dify 对人工输入节点业务逻辑的完全控制。

核心架构设计#

设计原则#

dify-agent 服务器遵循三条核心设计原则，这些原则在 app.py 的模块文档字符串中有明确阐述 11：

1. 进程内执行（In-Process Execution）

所有 Agent 运行作为后台 asyncio.Task 在同一 FastAPI 进程内执行，而非通过 Celery、RQ 等外部任务队列分发。这意味着客户端断开 HTTP 连接不会取消正在执行的 Agent 运行 —— 执行独立于请求处理器生命周期之外。

2. 无作业队列（No Job Queue）

Redis 在此系统中不作为作业队列使用。创建 run 的请求负载（包含 Layer 配置和模型凭证）从不写入 Redis，仅将运行记录和事件流持久化到 Redis 12。执行调度完全由进程本地的 RunScheduler 负责。

3. 请求先验证后持久化（Validate-Before-Persist）

每次创建 run 请求会先进入一次轻量级的 Agenton 运行进行语义验证 —— 检查用户提示、结构化输出契约和退出策略 —— 之后才持久化 run 记录 13。由于 Dify 的默认 Layer 生命周期钩子是无副作用的，这一验证过程不会触发任何外部服务调用。

三大核心组件#

HTTP 进程通过 FastAPI lifespan 管理三个共享资源，确保有序的启动和关闭 14：

1. Redis Run Store（RedisRunStore）#

15

负责所有持久化操作：

• Run 记录：以 JSON 字符串存储在 Redis Key 中，记录 run_id、status、created_at、updated_at、error
• 事件流：每个 run 对应一条 Redis Stream，事件以 xadd 追加写入
• TTL 刷新：每次写入状态或事件时，同步刷新 run 记录和事件流的过期时间（默认保留 3 天）
• 取消观察：wait_for_cancellation(run_id) 方法阻塞等待第一个被接受的取消意图从私有取消意图 Redis Stream 到达。该方法仅监听 run_cancel_intent_key 流（私有取消意图流），一旦可用即返回 RunCancellationIntent
• 事件迭代：iter_events(run_id, after) 先回放已有事件，再以阻塞 XREAD 读取实时事件。迭代在产出第一个终端事件（run_succeeded、run_failed 或 run_cancelled）后立即返回，无论该事件来自回放还是实时推送。方法不再在终端事件后继续阻塞循环

Redis Stream ID 作为公开的事件游标，0-0 表示从头回放，支持断点续传。

2. 共享 Plugin Daemon HTTP 客户端#

16

整个 FastAPI 进程共享一个 httpx.AsyncClient 实例用于与 Plugin Daemon 通信，配置了完整的连接超时、读取超时和连接池限制。该客户端由 lifespan 拥有，Agenton Layer 和 Provider 借用它而不持有所有权，确保资源的确定性释放。

关键配置参数（来自 ServerSettings）：

• read_timeout：默认 600 秒（LLM 推理可能耗时较长）
• max_connections：默认 100
• max_keepalive_connections：默认 20

3. 进程本地 Run Scheduler（RunScheduler）#

17

调度器维护一个进程本地的 active_tasks 字典（run_id → asyncio.Task），通过 asyncio.Lock 保护关键区域，确保以下操作的原子性：

• 检查 stopping 标志
• 执行 run 请求验证
• 持久化 run 记录
• 注册后台任务

调度器现在为每个 run 监督两个任务：本地 runner 任务和取消观察者任务。取消通过 Redis 持久化，而非通过进程本地状态跟踪。

FastAPI Lifespan 生命周期#

@asynccontextmanager
async def lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:
    redis = Redis.from_url(...) # 1. 初始化 Redis 客户端
    plugin_daemon_http_client = ... # 2. 创建共享 HTTP 客户端
    store = RedisRunStore(redis, ...) # 3. 创建 Run 存储
    scheduler = RunScheduler(store, ...) # 4. 创建进程本地调度器
    try:
        yield # 5. 服务运行中
    finally:
        await scheduler.shutdown() # 6. 优雅停机（等待运行中任务）
        await plugin_daemon_http_client.aclose() # 7. 释放 HTTP 连接
        await redis.aclose() # 8. 关闭 Redis 连接

14

这一设计使得所有资源生命周期显式且可预测，便于测试和部署。

Agenton 框架#

Agenton 是随 dify-agent 包一同引入的、可独立使用的状态仅有的（State-Only）Layer 组合框架。其设计理念明确：核心框架管理四件事 —— 无状态 Layer 图组合、可序列化 runtime_state 生命周期、每个活跃调用的资源作用域（per-active-invocation resource scopes）和会话快照（session snapshots）。活跃资源（如 HTTP 客户端、进程句柄）现在通过 Layer.resource_context() 在 Layer 实例上管理，但 Agenton 从不序列化或快照这些非可序列化运行时对象 18。

Layer 抽象#

Layer 是 Agenton 的核心抽象，是一个泛型基类 19：

class Layer(ABC, Generic[DepsT, PromptT, UserPromptT, ToolT, ConfigT, RuntimeStateT]):
    deps: DepsT # 依赖的其他 Layer 实例（当前运行绑定）
    config: ConfigT # 验证过的 Pydantic 配置 DTO
    runtime_state: RuntimeStateT # 唯一由 Agenton 管理、可序列化的可变状态

每个 Layer 实例是调用范围的业务对象，不是跨会话的复用定义。CompositorRun 在每次 enter() 调用时创建全新的 Layer 实例，绑定依赖并水化 runtime_state（如有会话快照）。

Layer 生命周期状态#

NEW ──── on_context_create() ──── ACTIVE
                                     │
                    ┌────────────────┤
                    │ │
         on_context_suspend() on_context_delete()
                    │ │
               SUSPENDED CLOSED
                    │
         on_context_resume()
                    │
                 ACTIVE

20

ExitIntent 决定退出行为：SUSPEND（默认，保存快照以便恢复）或 DELETE（丢弃状态）。

Layer.resource_context () 和失败的进入#

Layer.resource_context() 是一个异步上下文管理器，用于包装活跃调用中的活跃非可序列化资源。Agenton 在 on_context_create() 或 on_context_resume() 之前进入此上下文，并在 on_context_suspend() 或 on_context_delete() 之后退出。用于存储在 Layer 实例上的活跃客户端、进程句柄等资源。

如果 on_context_create() 或 on_context_resume() 抛出异常：

• Layer 永远不会进入 ACTIVE 状态
• 正常的 on_context_suspend()/on_context_delete() 钩子不会为该失败的进入尝试运行
• 进入钩子拥有业务补偿的责任
• resource_context() 清理仍然会发生

LayerDeps 类型化依赖#

Layer 通过 LayerDeps 子类声明依赖形状，注解成员必须是具体的 Layer 子类或可选类型 21：

class MyLayerDeps(LayerDeps):
    plugin: DifyPluginLayer # 必须依赖
    output: OutputLayer | None # 可选依赖

依赖在 Compositor 构建 CompositorRun 时直接解析并绑定为 Layer 实例引用，无需依赖注入容器或查找 API。依赖目标必须指向前置图节点，由 Compositor 验证。

Layer 体系结构#

dify-agent 提供了十个层次的 Layer 实现（包括 PR #38162 新增的两个层）：

1. PlainLayer（agenton_collections）#

22

最简单的 Layer 类型，直接提供纯文本提示和工具：

• PromptLayer（type_id: plain.prompt）：接受 prefix/user/suffix 提示配置
• ToolsLayer：携带 Python callable 工具列表
• ObjectLayer：携带任意类型对象供下游 Layer 访问

2. Pydantic AI Bridge Layer#

将 Agenton Layer 的提示和工具转换为 Pydantic AI Agent 所期望的格式，作为 Agenton 与 Pydantic AI 之间的适配桥梁。

PydanticAIHistoryLayer（type_id: pydantic_ai.history）：状态专用历史层，在 runtime_state.messages 中存储 pydantic-ai 的 ModelMessage 序列，使 Agenton 会话快照可持久化和恢复类型化消息历史。该层不提供任何系统提示、用户提示或工具，仅通过 message_history 属性暴露存储的历史，并提供 replace_messages()、append_messages() 和 clear() 方法用于状态管理。

PR #40872 更新：Dify Agent 现将当前系统提示作为运行级 instructions 参数传递给 Pydantic AI，而非通过临时 message_history 前缀渲染。当配置了有效的 context_window_tokens 时，Pydantic AI Harness 2.31 的分层压缩机制会在超出输入预算时重写历史：首先清理旧的工具结果（保留最近 3 对工具调用 / 结果），若仍超限则使用当前模型增量总结旧消息（保留最近 20 条消息和首个用户消息）。输入预算计算公式：对于正值 max_tokens，取 min(floor(window * 0.8), window - max_tokens)；否则取 floor(window * 0.8)。当未提供上下文窗口元数据时，Dify Agent 保持历史未压缩（回退为先前的无压缩行为）；当预算为非正值时，运行在模型解析或调用前失败。
PR #40972 更新：一旦 Pydantic AI 在运行捕获（run capture）中绑定并构建消息，历史持久化现在覆盖所有终端结果（成功、失败、超时、取消）。历史通过 capture_run_messages() 上下文管理器捕获，捕获的消息在 finally 块中持久化到历史层，确保即使失败或取消的运行也保存历史。如果失败或取消发生在捕获包含任何消息之前，则保留先前恢复的历史。中断的部分消息可以包含 state="interrupted" 标记，Pydantic AI 在恢复时会修复。

3. Dify Plugin Layer（dify_agent）#

23

DifyPluginLayer（type_id: dify.plugin）：共享的 Plugin Daemon 租户 / 用户上下文层，携带 tenant_id 和 user_id，不持有 HTTP 客户端。Plugin Daemon URL 和 API Key 由服务端 Provider 工厂注入，确保这些敏感配置不出现在公开的 HTTP 请求体中。该层作为共享依赖被 LLM 和工具层复用，具体的 plugin_id 由业务层（LLM、工具）各自携带 24。

DifyPluginLLMLayer（type_id: dify.plugin.llm）：依赖 DifyPluginLayer，持有插件包 ID（plugin_id）、模型提供者（model_provider）、模型名称（model）和模型凭证配置。其 get_model() 方法接受共享的 httpx.AsyncClient，返回 Pydantic AI 兼容的模型实例。

PR #40872 更新：DifyPluginLLMLayerConfig 新增可选的 context_window_tokens: int | None 字段（必须大于 0），用于向 Dify Agent 运行时传递当前模型的有效上下文窗口能力。该字段由 Dify API 端请求构建器从租户和凭证绑定的模型插件 schema 解析（通过 resolve_model_context_window() 函数），在提供者身份规范化之前完成。运行时使用此显式能力元数据构建 Pydantic AI Harness 的上下文感知历史压缩功能，无需将其混入用户模型设置或上游 Provider 参数。

DifyPluginToolsLayer（type_id: dify.plugin.tools）：插件工具暴露层，将 API 侧预备的插件工具声明注册为 Pydantic AI 工具。API 侧负责解析 daemon 声明、合并参数和生成模型可见 JSON schema；Agent 侧负责验证隐藏输入、应用默认值、调用 daemon 并转换响应。配置包含工具列表（DifyPluginToolConfig），每个工具携带自己的 plugin_id、提供者名称（provider）、daemon 工具名称（tool_name）、凭证类型（credential_type）、运行时隐藏参数（runtime_parameters）以及 API 预备的参数声明（parameters、parameters_json_schema）。

4. Output Layer#

OutputLayer（type_id: dify.output）：无状态的结构化输出层，基于 JSON Schema 构建动态 Pydantic 类型，该类型同时编码模型侧输出模式和运行时 jsonschema 验证逻辑。结构化输出工具名称固定为 final_output（不可配置），调用者仅可控制 json_schema、description 和 strict 参数。无效的模型输出将触发 Pydantic AI 的内置重试机制。

5. Ask-Human Layer#

DifyAskHumanLayer（type_id: dify.ask_human）：基于 pydantic-ai 外部延迟工具的无状态人工请求层。该层提供一个名为 ask_human 的可选外部工具，在首次运行期间不执行任何 Python 代码，而是通过 run_succeeded 事件的 deferred_tool_call 字段返回延迟工具调用。该层强制执行字段类型、字段数量、动作数量和字符限制的防护栏，并验证组合以确保每次运行最多只能有一个 ask-human 层。返回的延迟工具调用包含人工请求表单定义（字段、动作、紧急程度），客户端提交的人工响应通过 CreateRunRequest.deferred_tool_results 字段恢复运行。延迟工具结果需要包含先前消息历史的 history layer，因此 ask-human 流程必须与 history layer 配合使用。

6. Dify Config Layer#

DifyConfigLayer（type_id: dify.config，PR #38162 新增）：运行时 Dify 配置层，基于 shell 支持的急切拉取机制。该层管理 Agent 配置资产，包括技能（skills）、文件（files）、环境变量（environment variables）和笔记（notes）。通过 shell 层提供 prompt-mentioned 目标的实体化，在层初始化时急切拉取提及的技能和文件到本地工作区。配置包含 config_version（可选，含 writable 标志）、mentioned_skill_names 和 mentioned_file_names 列表。该层生成两部分提示内容：前缀提示（prefix prompts）显示已加载的技能和文件拉取输出，后缀提示（suffix prompts）包含配置上下文 JSON 和 CLI 帮助文档。CLI 命令包括：config manifest、skills pull/push/delete、files pull/push/delete、env pull/push、note pull/push。当 config_version.writable 为 true 时，可变配置修改命令可用。该层依赖 DifyShellLayer（通过 DifyConfigDeps），在层图中位于 shell 层之后，确保急切拉取操作在模型命令使用的相同文件系统中实体化内容。

7. Dify Shell Layer#

DifyShellLayer（type_id: dify.shell）：shell 适配器提供者 / 执行器机制支持的有状态工具层，暴露 shell_run、shell_wait、shell_input 和 shell_interrupt 四个工具。该层仅在 runtime_state 中持久化 JSON 安全的 shell 会话状态，而在 resource_context() 活跃时将活跃 ShellctlHandle 保存在 Layer 实例上。Agenton 在 on_context_create 或 on_context_resume 之前进入该资源作用域，并在 on_context_suspend 或 on_context_delete 之后退出，因此业务钩子和 shell 工具可以依赖活跃资源而无需将其序列化到快照中。该层将工作区生命周期委托给 ShellProvisionProtocol：provision() 分配新工作区，reattach() 从描述符重建句柄，destroy() 拆除工作区。内部工作区分配逻辑（_allocate_workspace、_workspace_mkdir_script、_workspace_cleanup_script）已移除，现由提供者处理。会话 ID 验证已放宽：现在仅拒绝包含 /、.. 或单引号的值（不再要求精确的 5+2 十六进制格式）。该层具有可选依赖 DifyShellLayerDeps（包含 drive: DifyDriveLayer | None、config: DifyConfigLayer | None 和 execution_context: DifyExecutionContextLayer | None），并可通过 build_shell_agent_stub_env 和 ShellAgentStubTokenFactory 向用户可见的 shell.run 作业注入 Agent Stub 环境变量（DIFY_AGENT_STUB_API_BASE_URL、DIFY_AGENT_STUB_AUTH_JWE 和 DIFY_AGENT_STUB_DRIVE_BASE），仅当 shell layer 构建时传入了有效的 agent_stub_api_base_url 和 agent_stub_token_factory 参数。当运行包含 dify.drive 依赖时，注入的 drive base 从 Agent Stub drive 挂载和 drive 引用计算（如 /mnt/drive/agent-123）。没有 drive 依赖时，CLI 保留历史 /mnt/drive 回退值。服务器拥有的脚本（如 run_remote_script）通过 Go 作业执行器（shellctl-runner）运行，取代了之前生成的 bash/python runner 脚本。该层通过 shell_home_root 字段配置 per-agent HOME 目录的根路径：shell 命令以 HOME=<shell_home_root>/<agent_id> 环境变量运行。shell_home_root 默认为 /home（适用于 Linux 和容器部署），通过 from_config_with_settings() 构造器传入，并经 _normalize_shell_home_root() 辅助函数规范化（去除尾部斜杠，验证绝对路径）。_shell_home_dir() 方法现在使用 shell_home_root 构造 HOME 路径，替代硬编码的 /home/<agent_id>。对于本地 macOS 开发，应将 shell_home_root 设置为可写路径（如 /tmp/dify-agent-home）。

Shell Layer 系统提示（PR #40623）：该层通过 _build_prefix_prompt() 方法提供模式感知的前缀提示，而非静态函数 _shell_layer_prefix_prompt()。系统提示描述文件系统空间：

• $HOME 被描述为 "系统空间"（system space）
• 当前工作目录（cwd） 被描述为 "临时工作空间"（temporary working space），相对路径从 cwd 解析
• 临时文件 应存储在 <cwd>/.tmp（通常为 ./.tmp），而非 /tmp

前缀提示的工作位置引导根据模式变化：

• build-draft 模式（当 execution_context.config.agent_config_version_kind == "build_draft"）：使用 _BUILD_DRAFT_WORKING_LOCATION_PROMPT，建议针对系统空间的工作和变更优先使用 $HOME，将 cwd 用于草稿文件、中间结果和其他临时工作
• 默认模式：使用 _DEFAULT_WORKING_LOCATION_PROMPT，建议优先使用 cwd 进行工作，并说明 $HOME 或 cwd 中的更改不更新已保存的 Agent 状态

运行时路径、文件系统生命周期、Shell 工具行为、已保存的 Agent 状态和公共协议契约保持不变 —— 仅系统提示措辞得到澄清。

PR #38162 Shell Layer 更新：

• shell-session-manager 版本更新至 2.3.0（从 2.2.1）
• local-sandbox 镜像新增工具：git、openssh-client、jq、ripgrep、unzip、zip、file、procps、less
• Node.js 22.22.1 和 pnpm 11.9.0 安装，支持 JavaScript/TypeScript 运行时
• dify-agent 作为独立 uv 工具安装，带 grpc extra
• shell layer 的可选依赖现在包含 config: DifyConfigLayer | None，支持配置层集成

Shell Layer 配置模型（dify-agent/src/dify_agent/layers/shell/configs.py）：

• DifyShellEnvVarConfig：Shell 环境变量声明，包含 name（环境变量名）和 value（字符串值）字段
• DifyShellSecretRefConfig：敏感凭证引用，包含 name（环境变量名）字段，值由外部系统注入
• DifyShellCliToolConfig：CLI 工具声明，包含 name、install_commands 列表，以及工具专用的 env: list[DifyShellEnvVarConfig] 和 secret_refs: list[DifyShellSecretRefConfig] 字段
• DifyShellLayerConfig：顶层配置，包含全局 env、secret_refs、cli_tools 列表、sandbox 配置和 redact_patterns 字段（regex 字符串列表，默认为空列表，用于定义 per-agent 的输出脱敏模式）

Shell layer 在工作区初始化时会检查是否有任何 CLI 工具需要安装。引导脚本由 shellctl-runner 在工作区首次创建时执行，环境变量注入是临时的（ephemeral），不持久化到工作区文件。

输出脱敏机制：Shell layer 通过 _redact_output() 方法对 shell 工具返回的输出进行两层脱敏处理：

1. 内置令牌脱敏：总是将 Agent Stub JWE 令牌值（通过环境变量 DIFY_AGENT_STUB_AUTH_JWE 注入的实际令牌字符串）替换为 ***。该脱敏为无条件执行，不可禁用。仅当令牌长度 > 8 字符时应用（避免对短值误报）。每个作业的实际注入令牌值通过 _job_agent_stub_tokens 字典跟踪（job_id → 令牌字符串），在 _tool_run() 启动作业时记录，在作业完成或中断时清理
2. 模式脱敏：依次应用来自服务器级别的 shell_redact_patterns 和 per-agent 配置的 config.redact_patterns 中的正则表达式模式，通过 re.sub(pattern, "***", text) 掩码匹配内容

输出脱敏在 _tool_run()、_tool_wait() 和 _tool_input() 三个工具方法返回观察结果前统一应用，确保模型看到的 shell 输出已移除敏感内容。

Path Isolation (Landlock)#

PR #39000 引入了基于 Landlock 的路径隔离机制，通过新的 Go 作业执行器（shellctl-runner）提供沙箱安全：

架构：shellctl-runner 以两种模式运行：

1. Parent 模式（默认）：由 tmux 调用，等待 start-gate，加载环境，fork 子进程，等待退出，写入退出产物
2. Child 模式（--exec 标志）：应用 Landlock 限制，然后 exec 用户脚本

访问模型（默认）：

执行器自动创建 $CWD/.tmp 并设置 TMPDIR、TMP、TEMP 指向它，使临时文件隔离在每个工作区内。

环境变量：完整的环境变量列表及其默认值，详见源代码 internal/envvar/envvar.go。关键变量包括：

系统要求：Linux ≥ 5.13。不支持的内核会在 stderr 打印警告并继续运行（无文件系统隔离）。

run_remote_script 方法：与模型可见的 shell.run 不同，该服务器拥有的边界不注入 Agent Soul shell 环境。将用户控制的 shell 环境排除在此路径之外，防止沙箱代码在 dify-agent file upload 执行前覆盖受信任的 Agent Stub 环境值。

environment_descriptor() 方法：返回用于 shell 适配器的可序列化工作区种子。桥接层的 runtime_state 到 dify_agent.adapters.shell：返回的描述符标识会话工作区，以便适配器的 ShellProvisionProtocol.reattach 可以重建指向它的活跃句柄而无需重新分配，并且无需重新进入该层。如果会话标识缺失或不一致，则抛出 ValueError。

Shell 适配器协议层#

Shell 适配器架构（dify-agent/src/dify_agent/adapters/shell/）：引入了提供者无关的 shell 层抽象，支持当前的 shellctl 后端和未来的第三方 shell 提供者。

协议层次结构（protocols.py）：

• ShellResourceProtocol：对已配置 shell 环境的活跃引用

  • commands: ShellCommandProtocol：命令执行接口
  • files: ShellFileTransferProtocol：文件传输接口
  • sandbox_id: str | None：沙箱标识符（由提供者返回，用于恢复）
  • suspend() -> None：暂停沙箱，保持存活以便后续重连
  • delete() -> None：销毁沙箱，永久释放资源

• ShellProviderProtocol：创建、重新连接和销毁 shell 环境

  • create() -> ShellResourceProtocol：分配新沙箱并返回活跃资源
  • attach(sandbox_id: str) -> ShellResourceProtocol：重连已有沙箱，不分配新资源

• ShellCommandProtocol：在已配置环境内运行命令

  • run(script, cwd, env, timeout) -> ShellRunResult：执行脚本并等待完成

• ShellFileTransferProtocol：文件传输操作

  • upload(content, remote_path, cwd) -> None：上传字节到工作区
  • download(remote_path, cwd) -> bytes：从工作区下载字节

• SandboxExpiredError：当 attach() 目标沙箱已过期时抛出（继承自 ShellProviderError）

  • sandbox_id: str：失效的沙箱标识符
  • __cause__: ShellProviderError：原始提供者错误

Shellctl 实现（shellctl.py）：

• ShellctlProvider：实现 ShellProviderProtocol，管理 shellctl 连接

  • create()：构建新的 shellctl 客户端并返回 ShellctlResource
  • attach(sandbox_id)：忽略 sandbox_id，构建新客户端（shellctl 服务器无沙箱概念）
  • 使用 client_factory: ShellctlClientFactory 创建客户端（可选）

• ShellctlResource：shellctl 的活跃连接

  • 持有 client: ShellctlClientProtocol
  • commands：ShellctlCommands 实例
  • files：ShellctlFileTransfer 实例
  • sandbox_id：返回 shellctl entrypoint URL 作为稳定标识符
  • suspend() 和 delete()：均调用 _close_client() 关闭 HTTP 客户端（shellctl 服务器和文件系统保持不变）

• ShellctlCommands：在 shellctl 工作区内执行命令

  • 有状态：跟踪每个启动作业的分页偏移量和输出部分
  • run() 启动命令、排空输出窗口直到完成（最多 64 个窗口），然后删除作业
  • 实现可选的 input() 和 interrupt() 功能

• ShellctlFileTransfer：基于 base64 的文件传输

  • upload() 将 base64 编码的内容通过管道传输到 base64 -d
  • download() 在帧标记之间发出文件的 base64 并提取有效负载

工厂模式（factory.py）：

• create_shell_provider(settings)：基于 DIFY_AGENT_SHELL_PROVIDER 选择提供者
  • 支持 "shellctl" 和 "enterprise" 提供者
  • "shellctl" 要求 shellctl_entrypoint 配置
  • "enterprise" 要求 enterprise_sandbox_gateway_endpoint 配置
  • 返回 ShellProviderProtocol 实现

Enterprise 实现（enterprise/enterprise.py，PR #38528 新增）：

• EnterpriseGatewayClient：企业沙箱网关控制平面 HTTP 客户端

  • create_sandbox(tenant_id, template) -> _CreateSandboxReply：分配新沙箱
  • delete_sandbox(sandbox_id) -> None：销毁沙箱
  • 使用 X-Inner-Api-Key 头认证

• EnterpriseShellProvider：实现 ShellProviderProtocol，通过网关分配沙箱

  • create()：调用网关 POST /v1/sandboxes 分配新沙箱，返回 EnterpriseResource
  • attach(sandbox_id)：构建指向网关 /proxy/{sandboxId} 路由的 shellctl 客户端，通过 run("true") 验证沙箱存活，若网关返回 404（sandbox_expired 或 NOT_FOUND）则抛出 SandboxExpiredError
  • 配置参数：gateway_endpoint、auth_token、tenant_id、template、gateway_timeout、proxy_timeout

• EnterpriseResource：企业沙箱的活跃会话

  • 持有 gateway: EnterpriseGatewayClient、shellctl_client: ShellctlClientProtocol、commands、files
  • sandbox_id：返回网关分配的沙箱标识符
  • suspend()：关闭 shellctl 和网关客户端，不删除沙箱（沙箱 pod 保持存活）
  • delete()：关闭客户端并调用网关 DELETE /v1/sandboxes/{sandboxId} 销毁沙箱

配置（config.py）：

• ShellAdapterSettings：shell 适配器环境变量
  • shell_provider: Literal["shellctl", "enterprise"]（默认 "shellctl"）
  • shellctl_entrypoint: str | None
  • shellctl_auth_token: str | None
  • enterprise_sandbox_gateway_endpoint: str | None
  • enterprise_sandbox_gateway_auth_token: str | None
  • enterprise_sandbox_gateway_timeout: float（默认 30.0）
  • enterprise_sandbox_proxy_timeout: float（默认 60.0）
  • 验证规则："shellctl" 要求 shellctl_entrypoint，"enterprise" 要求 enterprise_sandbox_gateway_endpoint，均需有效的 http (s) URL

DifyShellLayer 变更（PR #38528）：

• 沙箱生命周期管理：

  • DifyShellRuntimeState 新增 sandbox_id: str | None 字段
  • resource_context() 在首次运行时（sandbox_id 为 None）调用 shell_provider.create() 分配新沙箱，将返回的 sandbox_id 持久化到 runtime_state
  • 后续运行调用 shell_provider.attach(sandbox_id) 重连已有沙箱
  • 若 attach() 抛出 SandboxExpiredError，错误传播给调用者（用户必须开始新会话）

• 资源清理策略：

  • 新增 _resource_should_delete: bool 标志（默认 False）
  • resource_context() 退出时：若 _resource_should_delete 为 True 调用 resource.delete()，否则调用 resource.suspend()
  • on_context_create() 失败时设置 _resource_should_delete = True
  • on_context_delete() 结尾设置 _resource_should_delete = True

• 工作区生命周期：

  • 初始化：from_config_with_settings 接受 shell_provider: ShellProviderProtocol 和 shell_redact_patterns: list[str] | None 参数（而非 shellctl_entrypoint 和 shellctl_client_factory）
  • 层在 resource_context() 活跃时持有 _shell_resource: ShellResourceProtocol | None
  • 内部工作区分配逻辑已委托给提供者（_allocate_workspace、_workspace_mkdir_script、_workspace_cleanup_script 方法已移除）

• 设计原理：

  • 默认使用 suspend() 保持沙箱存活，支持跨对话轮次复用同一沙箱（企业版沙箱 pod 生命周期管理）
  • delete() 仅在层初始化失败或最终销毁时调用，确保资源可控释放

RemoteCommandResult 变更：从数据类中移除了几个字段，因为它们是调用者不使用的内部 shellctl 分页详细信息：

• 已移除：job_id、done、offset、output_path
• 保留：status、exit_code、output、truncated

8. Dify Drive Layer（已移除）#

PR #40887 更新：Agent Drive 系统（包括 dify.drive 层、数据库表 agent_drive_files、Drive 专用 API 路由、Agent Stub Drive 协议和 dify-agent drive CLI 命令）已从代码库中完全移除。Config-native 的 skill 和 file 路径（通过 Agent Soul 快照和 dify.config）成为管理 Agent 资产的唯一方式。遗留的 Soul files 字段和工作流文件引用中持久化的 drive_key 值在迁移 89919253ca7a 中被移除。历史 Drive 资产不会自动转换为 config 资产。Shell layer 不再引用 Drive mount 路径或注入 Drive 相关环境变量。

9. Dify Core Tools Layer#

DifyCoreToolsLayer（type_id: dify.core_tools，PR #38162 新增）：API 路由的 agent 可访问工具层，用于必须在 Dify API 服务边界内执行的提供者家族。该层将 API 准备的工具声明解析为 Pydantic AI 工具，工具调用委托给 POST /inner/api/agent/tools/invoke 端点，使凭证和提供者本地状态保留在 API 进程中。该层依赖 DifyExecutionContextLayer 获取调用者身份，通过 DifyCoreToolsClient 与内部 API 通信。配置包含工具列表（DifyCoreToolConfig），每个工具携带 name（或 tool_name）、description、parameters_json_schema（API 准备的模型可见 schema）以及 runtime_parameters（隐藏参数）。工具调用策略：配置错误返回 "工具不可用" 观察；可重试失败（超时、连接失败、HTTP 429/502）返回 TEMPORARY_UNAVAILABLE_OBSERVATION；不可重试失败（如 app_not_found、credential_invalid、tool_not_found）返回特定错误文本。该层在层图中位于 plugin tools 层之后，作为工具执行链的一部分。

10. Dify Knowledge Base Layer#

DifyKnowledgeBaseLayer（type_id: dify.knowledge_base）：知识库检索层，为 Agent 提供基于 Dify 数据集的知识检索能力。该层向模型暴露一个固定名称的工具 knowledge_base_search，工具签名仅接受 query 参数，所有其他检索控制（数据集 ID、检索模式、top_k、score_threshold、元数据过滤）均由配置层面控制，对模型不可见。

配置模型（dify-agent/src/dify_agent/layers/knowledge/configs.py）：

• DifyKnowledgeBaseLayerConfig：主配置，包含 dataset_ids（数据集 ID 列表）、retrieval（检索配置）、metadata_filtering（元数据过滤配置）、max_result_content_chars（单条结果内容截断长度，默认 2000）、max_observation_chars（完整观察截断长度，默认 12000）
• DifyKnowledgeRetrievalConfig：检索配置，包含 mode（"multiple" 或 "single"）、top_k（multiple 模式下必需，≥1）、score_threshold（默认 0.0）、reranking_mode（默认 "reranking_model"）、reranking_enable（默认 True）、reranking_model（重排序模型配置，DifyKnowledgeRerankingModelConfig）、weights（多路召回权重，可选）、model（single 模式下的生成模型配置，DifyKnowledgeModelConfig）
• DifyKnowledgeMetadataFilteringConfig：元数据过滤配置，包含 mode（"disabled"、"automatic"、"manual"，默认 "disabled"）、metadata_model_config（automatic 模式下的模型配置）、conditions（manual 模式下的过滤条件，DifyKnowledgeMetadataConditions）
• DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID：常量，值为 "dify.knowledge_base"

后端集成（dify-agent/src/dify_agent/layers/knowledge/client.py 和 layer.py）：

• DifyKnowledgeBaseClient：HTTP 客户端，调用 Dify API 内部端点 /inner-api/knowledge/retrieve，携带执行上下文（tenant_id、user_id、app_id、user_from、invoke_from）和检索参数
• 层依赖 DifyExecutionContextLayer 获取调用者身份，通过 lifespan 共享的 httpx.AsyncClient 发起请求
• 工具执行策略：
  • 空查询返回本地验证观察（BLANK_QUERY_OBSERVATION）
  • 可重试失败（超时、连接失败、HTTP 429/502）返回临时不可用观察（TEMPORARY_UNAVAILABLE_OBSERVATION）
  • 不可重试失败直接抛出异常使运行失败
• 观察格式：编号列表，每条包含标题、数据集 / 文档 / 分数元数据和截断内容，整体观察按 max_observation_chars 截断；空结果返回 NO_RESULTS_OBSERVATION

API 端服务（api/services/knowledge_retrieval_inner_service.py）：

• InnerKnowledgeRetrievalService：内部 API 服务，验证调用者应用和请求数据集的租户所有权，然后委托给工作流检索栈 DatasetRetrieval.knowledge_retrieval()
• 仅执行租户级授权检查，不检查 dataset.enable_api 或用户级数据集权限，保持与工作流检索语义一致
• 返回结构：InnerKnowledgeRetrieveResponse，包含 results 列表和 usage 统计（InnerKnowledgeRetrieveUsage）

REST 端点（api/controllers/inner_api/knowledge/retrieval.py）：

• POST /inner-api/knowledge/retrieve：受信任的内部调用端点，通过 @inner_api_key_required 装饰器认证内部 API 密钥
• 请求体：InnerKnowledgeRetrieveRequest（含调用者上下文、数据集 ID、查询、检索配置、元数据过滤、附件 ID）
• 响应体：InnerKnowledgeRetrieveResponse（含检索结果和 LLM 使用统计）

工作流集成（api/core/workflow/nodes/agent_v2/runtime_request_builder.py）：

• build_knowledge_layer_config()：从 Agent Soul 配置构建知识层配置，仅在配置了有效数据集 ID 时生成层
• 当前实现强制使用 multiple 检索模式，top_k 默认为 4（配置缺失时），score_threshold 仅在 Agent Soul 显式启用时转发（通过 query_config.score_threshold_enabled 和 query_config.score_threshold 字段）
• 层通过 AgentBackendWorkflowNodeRunInput 的 knowledge 字段注入到运行时请求

设计原理：知识层将 Agent 知识检索从 "工具调用声明" 升级为 "运行时基础设施层"，通过固定工具身份（knowledge_base_search）和配置驱动控制，确保 API 端 Agent Soul 映射的稳定性。层依赖执行上下文获取完整调用者身份（tenant_id、user_id、user_from、app_id、invoke_from 五个必需字段），使知识检索能够在工作流和 Agent App 两种调用场景下复用相同的权限和可观察性基础设施。

Compositor 与 CompositorRun#

Compositor 存储不可变的图节点计划，from_config() 通过 type_id 解析 Provider 25。每次调用 enter() 创建独立的 CompositorRun：

async with compositor.enter(configs=layer_configs, session_snapshot=snapshot) as run:
    # run.user_prompts - 聚合的用户提示
    # run.prompts - 聚合的系统提示
    # run.tools - 聚合的工具列表
    # run.get_layer() - 按名称获取 Layer 实例
    # run.session_snapshot - 退出后填充

26

PR #40872/40972 更新：历史层辅助函数已从 build_run_message_history() 和 append_successful_run_history() 重命名为 replace_run_history()（PR #40972 进一步重命名，移除 "successful"）。该函数从运行捕获的历史中移除临时指令（ModelRequest.instructions），然后通过 history_layer.replace_messages() 替换（而非追加到）存储的历史。PR #40972 将此逻辑应用于所有终端结果：通过 capture_run_messages() 捕获的消息在 finally 块中持久化，确保成功、失败、超时和取消运行都保存历史，前提是捕获包含至少一条消息。

会话快照机制#

CompositorSessionSnapshot 按 Compositor 顺序保存每个 Layer 的生命周期状态和 runtime_state。成功运行的终端事件（run_succeeded）包含快照，消费者可将其原样传入下次 CreateRunRequest 的 session_snapshot 字段以恢复运行。

重要：快照不包含 Output Layer 配置，因此恢复使用结构化输出的运行时必须重新提交相同的 output Layer。

HTTP API 接口#

dify-agent 服务器提供四个 HTTP 端点，全部挂载在 /runs 前缀下，由 create_runs_router() 工厂函数生成 27。

端点总览#

POST /runs — 创建运行#

请求体：CreateRunRequest

{
  "composition": {
    "schema_version": 1,
    "layers": [
      { "name": "prompt", "type": "plain.prompt", "config": { "user": "你好！" } },
      { "name": "plugin", "type": "dify.plugin", "config": { "tenant_id": "...", "plugin_id": "langgenius/openai" } },
      { "name": "llm", "type": "dify.plugin.llm", "deps": {"plugin": "plugin"}, "config": { "model_provider": "openai", "model": "gpt-4o-mini", "credentials": {} } }
    ]
  },
  "session_snapshot": null,
  "on_exit": { "default": "suspend", "layers": {} }
}

响应体（202 Accepted）：CreateRunResponse

{ "run_id": "01JVE...", "status": "running" }

错误响应：

• 422 Unprocessable Entity：请求未通过语义验证（如空用户提示、不支持的 output layer 图形状）
• 503 Service Unavailable：调度器正在关闭，不再接受新运行

控制器将已知的 RunRequestValidationError 和 SchedulerStoppingError 映射为对应 HTTP 状态码，其他基础设施异常则交由 FastAPI 默认错误处理以避免将内部问题误报为客户端错误 28。

GET /runs/{run_id} — 查询运行状态#

返回指定运行的当前状态和元数据 29。

响应体：RunStatusResponse

{
  "run_id": "01JVE...",
  "status": "succeeded",
  "created_at": "2026-05-14T06:20:00Z",
  "updated_at": "2026-05-14T06:20:05Z",
  "error": null,
  "error_type": null
}

字段说明：

• status：枚举值 running | succeeded | failed | cancelled
• error：失败运行的错误消息（成功或运行中时为 null）
• error_type：失败运行的机器可读类别（RunFailureType | None），当已识别的失败类别适用时填充（例如 "agent_run_limit_exceeded"）

注：cancelled 状态由显式取消请求（POST /runs/{run_id}/cancel）产生；优雅停机期间被取消的运行记录为 failed（reason: "shutdown"）

GET /runs/{run_id}/events — 轮询事件#

基于 Redis Stream ID 的游标分页事件查询，适用于短轮询或单次历史查询 30。

查询参数：

• after：上次返回的最后一个事件 ID（默认 0-0，表示从头开始）
• limit：单次返回最大事件数（范围 1–500，默认 100）

响应体：RunEventsResponse

{
  "run_id": "01JVE...",
  "events": [ { "id": "1747202401000-0", "run_id": "...", "type": "run_started", "data": {}, "created_at": "..." } ],
  "next_cursor": "1747202401000-0"
}

将 next_cursor 作为下次请求的 after 参数即可实现分页追踪。

GET /runs/{run_id}/events/sse — SSE 事件流#

服务端推送事件（Server-Sent Events）端点，适用于需要实时感知运行进度的客户端 31。

支持的游标传递方式（按优先级）：

1. Query 参数 after
2. HTTP Header Last-Event-ID（SSE 标准重连头）
3. 默认 0-0（从头回放）

响应的 Content-Type 为 text/event-stream，每条 SSE 帧携带一个 JSON 事件。底层通过 store.iter_events() 先回放已有事件，然后以 xread(block=30_000) 阻塞等待新事件 32。

终端事件后的流关闭行为：服务器在交付终端事件（run_succeeded、run_failed 或 run_cancelled）后正常关闭 SSE 响应。客户端必须在消费终端事件后停止重连。after 查询参数和 Last-Event-ID 头均为排他性恢复游标，因此服务器不会重新发送由提供的游标已排除的终端事件。

Python 客户端库（dify_agent.client）对 SSE 端点实现了带重连的完整封装：瞬时流 / 连接 / 读取失败、超时和 HTTP 5xx 响应将携带最后已知事件 ID 重连；HTTP 4xx、DTO 验证失败和格式错误的帧则立即抛出异常。客户端的 stream_events() 和 stream_events_sync() 方法跟踪终端事件，在观察到终端事件后不再重连，即使响应正常结束或引发可重连的传输错误。

POST /runs/{run_id}/cancel — 取消运行#

原子性地取消运行，不依赖进程本地任务所有权 33。

请求体：CancelRunRequest

{
  "reason": "user_requested",
  "message": "User cancelled the run"
}

响应体（200 OK）：CancelRunResponse

{ "run_id": "01JVE...", "status": "cancelled" }

错误响应：

• 404 Not Found：run 记录不存在
• 409 Conflict：终端事件（succeeded/failed）已赢得竞争

幂等性：对已经 cancelled 的 run 重试取消请求返回 200（幂等成功）。

原子性保证：取消端点使用与 runner 成功 / 失败路径相同的 finalize_run 机制，确保仅首次终端转换生效。取消请求尝试原子性地提交 run_cancelled 事件；若成功，拥有该 runner 的进程观察到共享的 run_cancelled 事件，然后取消并清理其本地任务。HTTP 响应确认逻辑取消已持久化；本地 runner 清理可能仍在进行。若其他终端事件已赢得竞争，则返回 409。

运行执行流程#

从 HTTP 请求到终端事件，一次完整的 Agent 运行经历验证、持久化、调度、执行四个阶段，涉及 RunScheduler 和 AgentRunRunner 两个核心类 33 34。

PR #40872/40972 更新：执行流程核心变更包括：(1) 系统提示现作为 Pydantic AI 的运行级 instructions 参数传递，而非渲染到 message_history；(2) 当 LLM 层配置了 context_window_tokens 时，build_compaction_capability() 构建的 Pydantic AI Harness 分层压缩器会在运行时估算并可能重写超限的历史；(3) 运行捕获的消息通过 capture_run_messages() 上下文管理器捕获，在 finally 块中持久化到历史层（PR #40972），覆盖所有终端结果（成功、失败、超时、取消）；(4) replace_run_history() 函数（从 PR #40872 的 replace_successful_run_history() 重命名）会先移除临时指令再替换存储的历史。

阶段一：验证（Validate）#

在任何数据写入 Redis 之前，validate_run_request() 对请求进行完整的语义检查 35：

1. validate_output_layer_composition()
   → 检查 output layer 图形状（至多一个 dify.output layer，且位置合法）

2. validate_history_layer_composition()
   → 检查 history layer 图形状（至多一个 pydantic_ai.history layer，名称必须为保留 ID，不支持依赖）

3. normalize_composition()
   → 将公开 RunComposition DTO 拆分为：
     - CompositorConfig（图节点定义）
     - dict[str, LayerConfigInput]（各节点的 per-run 配置）

4. build_pydantic_ai_compositor()
   → 通过 type_id 解析 Provider，构建 Compositor 实例

5. validate_layer_exit_signals()
   → 验证 on_exit 中引用的所有 layer 名称确实存在于图中

6. compositor.enter(configs, session_snapshot) ← 轻量级 Agenton 进入
   → apply_layer_exit_signals() 检查退出信号
   → has_non_blank_user_prompt() 确保有非空用户提示
   → resolve_run_output_contract() 构建结构化输出契约（如有）

验证过程中会遇到的异常均被规范化为 RunRequestValidationError，对应 HTTP 422 响应。

阶段二：持久化（Persist）#

验证通过后，store.create_run() 生成唯一 run_id（基于时间排序的 ID），创建状态为 running 的 run 记录，并以配置的 TTL 写入 Redis 36。

安全设计：创建 run 的请求体（含 Layer 配置和模型凭证）从不持久化到 Redis，仅作为内存对象传入后台任务，防止凭证泄露到存储层 37。

阶段三：调度（Schedule）#

asyncio.create_task() 将执行逻辑包装为后台任务，注册到 active_tasks 字典 38：

task = asyncio.create_task(
    self._run_record(record, request),
    name=f"dify-agent-run-{record.run_id}"
)
self.active_tasks[record.run_id] = task
task.add_done_callback(lambda _task, run_id=record.run_id: self.active_tasks.pop(run_id, None))

任务完成（无论成功或失败）后自动从 active_tasks 中移除。active_tasks 仅用于本地任务引用、优雅停机和清理，不再用于接受取消请求时的所有权检查。此后，POST /runs 请求立即返回 202 给客户端，执行在后台异步进行。

阶段四：执行（Execute）#

调度器的 _run_record() 方法为每个 run 监督两个任务：

1. 本地 runner 任务：执行 AgentRunRunner.run()，与之前相同
2. 取消观察者任务：通过 store.wait_for_cancellation(run_id) 监视私有取消意图流，等待被接受的取消意图

监督逻辑：

1. 创建 cancel_requested 事件（asyncio.Event）
2. 启动 runner_task 和 observer_task
3. 等待第一个任务完成（FIRST_COMPLETED）
4. 如果 observer_task 完成：
   - observer 返回 RunCancellationIntent
   - 设置 cancel_requested
   - 取消并等待 runner_task（重注入取消信号）
   - 调用 finalize_cancellation() 终结取消
5. 如果 runner_task 完成：
   - 正常结束，取消 observer_task
6. CancelledError 处理（优雅停机）：
   - 设置 cancel_requested
   - 取消并等待两个任务
7. finally 块：
   - 确保 observer_task 被取消
   - 确保 runner_task 被取消（若仍在运行）

AgentRunRunner.run() 执行流程不变 39：

1. emit_run_started → 写入 run_started 事件到 Redis Stream
2. _run_agent() 核心执行
3. 成功路径：finalize_run(SUCCEEDED)
4. 失败路径：finalize_run(FAILED)
5. 取消路径：通过 is_cancelled() 回调检测，调用 finalize_run(CANCELLED)

40

错误分类与失败类型映射#

AgentRunRunner 通过 _run_failed_error_payload() 辅助函数将运行时异常映射为公开错误载荷（error、error_type、reason）：

error_type 和 reason 在终端终结化时以原子方式持久化到 Redis run 记录和 run_failed 事件中。error_type 提供稳定的机器可读分类，reason 提供诊断性上下文，error 提供人类可读的错误文本。

事件模型#

dify-agent 使用追加写入的事件日志作为运行观察的唯一接口。所有事件通过 Redis Streams 持久化，客户端通过轮询或 SSE 消费 42。

事件信封结构#

每个事件共享相同的基础字段 43：

事件类型使用 Pydantic 的 discriminator="type" 机制，客户端可通过 RUN_EVENT_ADAPTER.validate_json() 反序列化为正确的具体类型 44。

四种事件类型#

1. run_started — 运行开始#

{
  "id": "1747202401000-0",
  "run_id": "01JVE...",
  "type": "run_started",
  "data": {},
  "created_at": "2026-05-14T06:20:01Z"
}

在 AgentRunRunner.run() 开始执行时立即发出，data 为空对象，表示 Agent 运行时已就绪 45。

2. pydantic_ai_event — Pydantic AI 流式事件#

{
  "id": "1747202401500-0",
  "run_id": "01JVE...",
  "type": "pydantic_ai_event",
  "data": { "type": "text-delta", "delta": "你好" },
  "created_at": "2026-05-14T06:20:01.5Z"
}

data 字段为 Pydantic AI 原生的 AgentStreamEvent，包含文本增量、工具调用等原始流式事件。每个 Pydantic AI 流式事件触发一条此类记录 46。

3. run_succeeded — 运行成功（终端事件）#

{
  "id": "1747202405000-0",
  "run_id": "01JVE...",
  "type": "run_succeeded",
  "data": {
    "output": "你好！我是 Dify Agent，很高兴为你服务。",
    "session_snapshot": {
      "schema_version": 1,
      "layers": [ { "name": "prompt", "lifecycle_state": "suspended", "runtime_state": {} }, ... ]
    }
  },
  "created_at": "2026-05-14T06:20:05Z"
}

终端成功事件的设计要点（47）：最终输出和可恢复的 Agenton 会话快照一同包含在同一事件中。消费者可将终端事件视为运行的完整摘要，无需关联多个不同的载荷事件。

RunSucceededEventData 现在具有两个互斥的结果字段：

• output: JsonValue | None：最终 JSON-safe 输出（对于非结构化文本为字符串，对于结构化输出为 JSON 对象）
• deferred_tool_call: DeferredToolCallPayload | None：外部工具请求载荷（用于 ask-human 流程）
• session_snapshot: CompositorSessionSnapshot：总是存在

有且仅有 output 或 deferred_tool_call 之一会被设置。当 ask-human 层激活且模型请求人工输入时，事件将包含 deferred_tool_call 而非 output；正常完成时包含 output。

4. run_failed — 运行失败（终端事件）#

{
  "id": "1747202402000-0",
  "run_id": "01JVE...",
  "type": "run_failed",
  "data": {
    "error": "LLM returned invalid structured output after retries",
    "error_type": null,
    "reason": null,
    "usage": {
      "prompt_tokens": 250,
      "completion_tokens": 120,
      "total_tokens": 370
    }
  },
  "created_at": "2026-05-14T06:20:02Z"
}

RunFailedEventData 字段：

• error: str：人类可读的错误消息文本
• error_type: RunFailureType | None：稳定的机器可读失败类别（如 "agent_run_limit_exceeded"），与自由文本 reason 字段不同，提供结构化的失败分类
• reason: str | None：诊断性失败原因（优雅停机取消时为 "shutdown"，其他运行时错误为 null）
• usage: AgentRunUsage | None：运行失败时累积的提供者使用量（可选）

RunFailureType 枚举（StrEnum）：

当前定义的失败类型：

• AGENT_RUN_LIMIT_EXCEEDED = "agent_run_limit_exceeded"：Dify Agent 执行预算违规（由 Pydantic AI 的 UsageLimitExceeded 映射而来），包括 Dify Agent 控制的请求 / 步骤预算耗尽和墙上时钟运行超时。不包括提供者超时或连接超时

更多失败类型可能在未来版本中添加。当失败未被分类到已知类型时，error_type 为 null。

5. run_cancelled — 运行取消（终端事件）#

{
  "id": "1747202403000-0",
  "run_id": "01JVE...",
  "type": "run_cancelled",
  "data": {
    "reason": "user_requested",
    "message": "User cancelled the run",
    "usage": {
      "prompt_tokens": 180,
      "completion_tokens": 0,
      "total_tokens": 180
    }
  },
  "created_at": "2026-05-14T06:20:03Z"
}

RunCancelledEventData 字段：

• reason: str | None：取消原因（如 "user_requested"）
• message: str | None：取消消息
• session_snapshot: CompositorSessionSnapshot | None：会话快照（如有）
• usage: AgentRunUsage | None：运行取消时累积的提供者使用量（可选）

取消事件通过 POST /runs/{run_id}/cancel 端点触发，使用原子性的 finalize_run 机制确保仅首次终端转换成功。

PR #40937 更新：自此 PR 起，usage 字段现在包含在 RunFailedEventData 和 RunCancelledEventData 中。Agent 运行失败或取消时累积的提供者使用量会被保留并传播，确保计费统计不依赖运行成功完成。该使用量通过 Agent backend 协议、Redis 终结、API 事件适配器和 Agent v2 工作流元数据流传播，并直接持久化到 Agent App 的 Message 表，使 Monitor 聚合能够准确反映所有 Agent 执行的成本，无论运行是否成功完成或客户端是否保持连接直至终端事件。

完整事件流示意#

成功运行：

run_started
pydantic_ai_event (text-delta: "你")
pydantic_ai_event (text-delta: "好")
...
pydantic_ai_event (text-delta: "。")
run_succeeded { output: "你好...", session_snapshot: {...}, usage: {...} }

失败运行：

run_started
pydantic_ai_event (text-delta: "...")
...
run_failed { error: "...", reason: null, usage: {...} }

用户取消：

run_started
pydantic_ai_event (text-delta: "...")
...
run_cancelled { reason: "user_requested", message: "...", usage: {...} }

服务关闭取消：

run_started
...
run_failed { error: "run cancelled during server shutdown", reason: "shutdown", usage: {...} }

消费者应将收到 run_succeeded、run_failed 或 run_cancelled 事件作为终止读取事件流的信号。每个运行至多追加一个终端事件。

Docker 镜像与 CI/CD#

官方 dify-agent-local-sandbox 镜像#

PR #38841 更新：Docker 镜像现从 dify-agent-runtime/ 构建。以下描述适用于原始 Python 实现。

仓库现提供官方的 dify-agent-local-sandbox Docker 镜像。原始实现通过 dify-agent/docker/local-sandbox/Dockerfile 构建；PR #38841 后改为从 dify-agent-runtime/docker/Dockerfile 构建。

镜像特征（原始 Python 版本）：

• 安装 [grpc] 完整依赖：此镜像合并了之前仅 shellctl 镜像与沙箱可见的 Agent Stub 客户端 CLI。它默认运行 shellctl，shellctl 管理的作业可以调用 dify-agent ... 而无需在运行时安装额外的包

• shell-session-manager 版本：2.2.1（从 2.2.0 升级）

• Agent Stub CLI 包含：包含带有 gRPC 传输 extra 的 dify-agent Agent Stub 客户端 CLI

• 布局与现有部署一致：virtualenv 位于 /opt/dify-agent/.venv，非 root 用户 uid 1001（dify），与 dify-api 镜像约定保持一致

• 暴露端口 5004：默认监听端口为 5004

• 启动命令：shellctl serve --listen 0.0.0.0:5004

• 平台支持：支持 linux/amd64 和 linux/arm64 双平台

镜像特征（Go 重写版本，PR #38841）：

• 纯 Go 构建：镜像从 Go 源码（dify-agent-runtime/）构建，而非 Python
• 包含二进制：shellctl（主服务器）、shellctl-sanitize-pty、shellctl-runner-exit、shellctl-runner（作业执行器）、dify-agent（CLI）
• 纯 Go SQLite 驱动：使用 modernc.org/sqlite，无需 CGO
• Go 版本要求：Go 1.26
• Drop-in 替换：HTTP API、SQLite schema 和文件系统布局与 Python 版本保持一致
• Dockerfile 路径：dify-agent-runtime/docker/Dockerfile
• 构建上下文：dify-agent-runtime/

镜像地址：langgenius/dify-agent-local-sandbox:<tag>（可通过仓库变量覆盖）

CI/CD 集成#

Docker 镜像集成到现有的 build-push.yml GitHub Actions 工作流中，与 dify-api 和 dify-web 使用相同的触发规则和标签策略。

构建矩阵扩展：

• dify-agent-backend 镜像包含 build-agent-amd64 和 build-agent-arm64 构建任务
• dify-agent-local-sandbox 镜像包含 build-local-sandbox-amd64 和 build-local-sandbox-arm64 构建任务
• Fork 构建验证包含相应的验证任务
• 镜像合并阶段包含聚合双平台 manifest 的合并任务

工作流变更（.github/workflows/build-push.yml）：

• 环境变量 DIFY_AGENT_IMAGE_NAME（默认 langgenius/dify-agent-backend）和 DIFY_AGENT_LOCAL_SANDBOX_IMAGE_NAME（默认 langgenius/dify-agent-local-sandbox）
• 构建上下文为仓库根目录（{{defaultContext}}），Dockerfile 路径分别为 dify-agent/Dockerfile 和 dify-agent/docker/local-sandbox/Dockerfile
• 与 API/Web 镜像共享标签和推送逻辑（主分支、版本标签、PR 构建）

Dockerfile 技术细节#

dify-agent-backend 多阶段构建（dify-agent/Dockerfile）：

FROM python:3.12-slim-bookworm AS base
# 安装 uv 0.8.9

FROM base AS packages
# 复制 dify-agent/pyproject.toml、uv.lock、src/
# uv sync --frozen --no-dev --no-editable --extra server

FROM base AS production
# 复制 virtualenv，设置环境变量，创建非 root 用户
# EXPOSE 5050
# CMD ["uvicorn", "dify_agent.server.app:app", "--host", "0.0.0.0", "--port", "5050"]

dify-agent-local-sandbox 多阶段构建（原始 Python 版本）：

FROM python:3.12-slim-bookworm AS base
# 安装 uv 0.8.9, tmux, curl, ca-certificates

FROM base AS packages
# 复制 dify-agent/pyproject.toml、uv.lock、src/
# uv sync --frozen --no-dev --no-editable --extra grpc
# uv pip install shell-session-manager==2.2.1

FROM base AS production
# 复制 virtualenv，设置环境变量，创建非 root 用户
# EXPOSE 5004
# CMD ["shellctl", "serve", "--listen", "0.0.0.0:5004"]

dify-agent-local-sandbox 多阶段构建（Go 重写版本，PR #38841）：

FROM golang:1.26 AS go-builder
# 构建五个 Go 二进制：shellctl、shellctl-sanitize-pty、
# shellctl-runner-exit、shellctl-runner、dify-agent

FROM python:3.12-slim-bookworm AS production
# 安装运行时工具（Node.js 22.22.1、pnpm 11.9.0、uv）
# 复制 Go 二进制到 /usr/local/bin/
# 创建 dify 用户（uid 1001）
# EXPOSE 5004
# CMD ["shellctl", "serve", "--listen", "0.0.0.0:5004"]

关键设计点：

1. 独立构建：dify-agent 子包有独立的 pyproject.toml 和 uv.lock，无需依赖 api/ 项目文件
2. frozen lock：使用 --frozen 信任签入的 lock 文件，确保构建可重现
3. 非 root 运行：用户 dify (uid 1001)，满足容器安全最佳实践
4. Storage 目录预创建：backend 镜像创建 /app/api/storage，确保运行时可写
5. Go 重写优势（PR #38841）：更快的启动时间、更小的内存占用、零 CGO 依赖

包目录结构#

以下是 dify-agent 包的完整目录树（共约 128 个文件），按功能分组并附注关键文件的职责说明 49：

dify-agent/
│
├── Dockerfile # 官方 dify-agent-backend 镜像定义
├── src/ # 源代码根目录
│ │
│ ├── agenton/ # 核心框架（可独立使用）
│ │ ├── __init__.py
│ │ ├── compositor/ # 图组合引擎
│ │ │ ├── core.py # Compositor & LayerNode — 不可变图计划
│ │ │ ├── providers.py # LayerProvider — 工厂抽象
│ │ │ ├── run.py # CompositorRun — 单次调用上下文
│ │ │ ├── schemas.py # CompositorConfig、SessionSnapshot 模式定义
│ │ │ └── types.py # 泛型类型别名
│ │ └── layers/ # Layer 基础抽象
│ │ ├── base.py # Layer、LayerDeps、LifecycleState、ExitIntent
│ │ └── types.py # PlainLayer 等类型化 Layer 家族
│ │
│ ├── agenton_collections/ # 通用 Layer 实现集合
│ │ ├── layers/
│ │ │ ├── plain/
│ │ │ │ ├── basic.py # PromptLayer、ToolsLayer、ObjectLayer
│ │ │ │ └── dynamic_tools.py # 动态工具 Layer
│ │ │ └── pydantic_ai/
│ │ │ ├── bridge.py # Pydantic AI 桥接 Layer
│ │ │ └── history.py # PydanticAIHistoryLayer（可选历史层）
│ │ └── transformers/
│ │ └── pydantic_ai.py # Pydantic AI 格式转换器
│ │
│ └── dify_agent/ # Dify 专用运行时
│ ├── adapters/
│ │ └── llm/
│ │ ├── model.py # DifyLLMAdapterModel — Pydantic AI 兼容 LLM 模型
│ │ └── provider.py # DifyPluginDaemonProvider — Plugin Daemon 连接
│ ├── client/
│ │ ├── __init__.py # 公开 Client 类
│ │ └── _client.py # 同步/异步 HTTP 客户端，含 SSE 重连逻辑
│ ├── layers/
│ │ ├── ask_human/
│ │ │ ├── __init__.py # 公开 ask-human 客户端安全 DTO
│ │ │ ├── configs.py # DifyAskHumanLayerConfig（字段和动作限制）
│ │ │ ├── layer.py # DifyAskHumanLayer（type_id: dify.ask_human）
│ │ │ └── schema.py # AskHumanToolArgs、AskHumanToolResult schema
│ │ ├── dify_plugin/
│ │ │ ├── configs.py # DifyPluginLayerConfig、DifyPluginLLMLayerConfig
│ │ │ ├── llm_layer.py # DifyPluginLLMLayer（type_id: dify.plugin.llm）
│ │ │ └── plugin_layer.py # DifyPluginLayer（type_id: dify.plugin）
│ │ ├── output/
│ │ │ ├── configs.py # OutputLayerConfig（JSON Schema 定义）
│ │ │ └── output_layer.py # OutputLayer（type_id: dify.output）
│ │ └── shell/
│ │ ├── configs.py # DifyShellLayerConfig
│ │ └── layer.py # DifyShellLayer（type_id: dify.shell）
│ ├── protocol/
│ │ └── schemas.py # 公开 HTTP 线协议 DTO（CreateRunRequest 等）
│ ├── runtime/
│ │ ├── agent_factory.py # create_agent() — Pydantic AI Agent 构建器
│ │ ├── agenton_validation.py # Agenton 进入时验证错误分类
│ │ ├── compositor_factory.py # build_pydantic_ai_compositor()
│ │ ├── event_sink.py # RunEventSink 协议 & emit_* 工具函数
│ │ ├── history.py # History layer 助手（验证、获取、message_history 构建）
│ │ ├── layer_exit_signals.py # on_exit 信号验证与应用
│ │ ├── output_type.py # 结构化输出契约解析
│ │ ├── run_scheduler.py # RunScheduler — 进程本地 asyncio 任务调度
│ │ ├── runner.py # AgentRunRunner — 单次运行执行
│ │ └── user_prompt_validation.py # 用户提示非空检查
│ ├── server/
│ │ ├── app.py # FastAPI 应用工厂（lifespan 管理）
│ │ ├── routes/
│ │ │ └── runs.py # POST/GET /runs 路由
│ │ ├── schemas.py # RunRecord、new_run_id 服务端模式
│ │ ├── settings.py # ServerSettings（DIFY_AGENT_ 环境变量）
│ │ └── sse.py # SSE 事件流生成器
│ └── storage/
│ ├── redis_keys.py # Redis 键名生成函数
│ └── redis_run_store.py # RedisRunStore — 运行记录 & 事件流存储
│
├── tests/ # 测试套件（约 42 个文件，6000+ 行）
│ ├── docs/ # 文档示例测试
│ │ ├── test_examples.py # 可执行文档代码片段测试
│ │ └── test_snippets.py
│ └── local/ # 本地单元测试（镜像 src/ 结构）
│ ├── agenton/ # Compositor & Layer 测试
│ ├── agenton_collections/ # 通用 Layer 实现测试
│ └── dify_agent/ # Dify 运行时、服务器、存储、客户端测试
│
├── docs/ # MkDocs 文档源文件
│ ├── dify-agent/ # Dify Agent 操作指南
│ │ ├── get-started/index.md # 快速入门指南
│ │ └── guide/index.md # 操作手册
│ └── agenton/ # Agenton 框架文档
│ ├── index.md
│ └── guide/index.md
│
├── examples/ # 使用示例
│ ├── agenton/agenton_examples/ # Agenton 基础示例
│ │ ├── basics.py # 基本 Layer 组合
│ │ ├── pydantic_ai_bridge.py # Pydantic AI 桥接示例
│ │ └── session_snapshot.py # 会话快照恢复示例
│ └── dify_agent/dify_agent_examples/ # Dify Agent 服务器客户端示例
│ ├── run_server_consumer.py # 短轮询客户端
│ ├── run_server_sse_consumer.py # SSE 客户端
│ └── run_server_sync_client.py # 同步客户端
│
├── docker/ # Docker 镜像定义
│ └── local-sandbox/ # local-sandbox Docker 镜像
│ └── Dockerfile
│
├── .example.env # 环境变量配置模板
├── AGENTS.md # 开发规范（编码风格、测试、文档）
├── Makefile # 开发命令（serve、dev、test、typecheck）
├── mkdocs.yml # MkDocs 文档构建配置
└── pyproject.toml # Python 包配置（依赖、工具链）

50

配置说明#

所有服务器配置通过以 DIFY_AGENT_ 为前缀的环境变量进行管理，对应 ServerSettings Pydantic 设置类 51。设置文件读取顺序：当前目录的 .env，然后是 dify-agent/.env（从仓库根目录运行时）52。

完整环境变量参考#

配置文件组织（自 PR #41065）：许多 Dify Agent 配置已从 docker/.env.example 迁移至服务专用的环境文件：

• 核心 Agent 配置：docker/envs/core-services/dify-agent.env.example
• API 相关配置：docker/envs/core-services/api.env.example
• 共享配置：docker/envs/core-services/shared.env.example
  Docker Compose 环境块中的重复映射已移除，配置通过服务 env 文件拥有。

Redis 配置#

关闭与数据保留#

Plugin Daemon 连接#

出站 HTTP 客户端配置#

新增（PR #41065）：共享出站 HTTP 客户端超时和连接限制配置。

API 客户端配置#

注：以下 API 客户端设置现位于 docker/envs/core-services/api.env.example（自 PR #41065）。

Shell Layer 配置#

E2B 配置#

注：E2B 相关设置现位于 docker/envs/core-services/dify-agent.env.example（自 PR #41065），支持从根 .env 回退。

Agent Stub 配置#

生成有效的 server secret：

python -c 'import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode())'

Agent Stub 配置验证规则：

• 当 DIFY_AGENT_STUB_API_BASE_URL 已设置时，DIFY_AGENT_SERVER_SECRET_KEY 必须提供
• 当 DIFY_AGENT_STUB_GRPC_BIND_ADDRESS 已设置时，DIFY_AGENT_STUB_API_BASE_URL 必须使用 grpc:// 协议

Dify API 内部调用配置#

ServerSettings 辅助方法：

• create_agent_stub_token_codec() -> AgentStubTokenCodec | None：当 server_secret_key 已配置时返回 Agent Stub token 编解码器
• create_agent_stub_file_request_handler() -> DifyApiAgentStubFileRequestHandler | None：当 inner_api_key 已配置时返回文件请求处理器
• create_outbound_http_timeout() -> httpx.Timeout：从服务器设置构建共享出站 HTTP 超时对象
• get_shell_redact_patterns() -> list[str]：解析 shell_redact_patterns 字段（JSON 数组格式），返回 regex 字符串列表。空 / 空白值返回空列表。若格式非法（非 JSON 数组）抛出 ValueError

最小必要配置#

根据快速入门指南，本地开发需要以下环境变量 53：

DIFY_AGENT_REDIS_URL=redis://localhost:6379/0
DIFY_AGENT_REDIS_PREFIX=dify-agent
DIFY_AGENT_PLUGIN_DAEMON_URL=http://localhost:5002
DIFY_AGENT_PLUGIN_DAEMON_API_KEY=replace-with-plugin-daemon-server-key
DIFY_AGENT_INNER_API_URL=http://localhost:5001
DIFY_AGENT_INNER_API_KEY=replace-with-inner-api-key

如果计划使用 dify.shell 层，还需根据提供者类型配置相应的环境变量。对于 "shellctl" 提供者，需设置 DIFY_AGENT_SHELLCTL_ENTRYPOINT；对于 "enterprise" 提供者，需设置 DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_ENDPOINT 和 DIFY_AGENT_ENTERPRISE_SANDBOX_GATEWAY_AUTH_TOKEN。若 shell 作业需要通过 dify-agent 命令回调 Agent Stub，则需设置 DIFY_AGENT_STUB_API_BASE_URL（如 https://agent.example.com/agent-stub 或 grpc://agent.example.com:50051）和 32 字节 base64url 编码的 DIFY_AGENT_SERVER_SECRET_KEY。

其余参数均有合理默认值，生产环境按需调整。

安全提示：DIFY_AGENT_PLUGIN_DAEMON_API_KEY 应通过 secrets 管理工具（如 Kubernetes Secret、Vault）注入，避免硬编码在配置文件中。

Docker Compose 部署配置（PR #41065 变更）#

Local Sandbox 数据持久化#

自 PR #41065 起，local_sandbox 服务现使用两个 Docker 命名卷持久化沙箱数据：

volumes:
  - dify_agent_local_sandbox_home:/home/dify
  - dify_agent_local_sandbox_workspace:/workspace

这些卷在容器重新创建时保留数据。初次部署时卷为空，Docker Compose 不会从已有容器的可写层迁移旧数据。

移除的环境映射#

以下环境变量已从 docker-compose.yaml 的 environment 块移除（现由服务 env 文件管理）：

API 和 Worker 服务（移至 api.env.example）：

• AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS
• AGENT_BACKEND_STREAM_MAX_RECONNECTS

Agent Backend 服务（移至 dify-agent.env.example 或移除）：

• DIFY_AGENT_REDIS_PREFIX
• DIFY_AGENT_E2B_API_KEY（现在 env 文件中支持回退语法）
• DIFY_AGENT_E2B_TEMPLATE
• DIFY_AGENT_E2B_ACTIVE_TIMEOUT_SECONDS
• DIFY_AGENT_E2B_SHELLCTL_PORT
• DIFY_AGENT_SHUTDOWN_GRACE_SECONDS
• DIFY_AGENT_RUN_RETENTION_SECONDS
• DIFY_AGENT_RUN_TIMEOUT_SECONDS

Compose 环境块现在仅保留：

• 必须从根 .env 派生的共享凭证（REDIS_PASSWORD、PLUGIN_DAEMON_KEY）
• 必须在运行时填充的服务发现端点（DIFY_AGENT_PLUGIN_DAEMON_URL、DIFY_AGENT_INNER_API_URL）
• 无默认值的可选设置（DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN）

可选的 Agent 和 API 配置通过服务 env 文件拥有，显式设置在 docker/.env 中的值仍然可以覆盖服务 env 文件。

Agent Stub 协议#

Agent Stub 是本次 PR 引入的新子系统，允许 shell 作业内的命令通过标准化协议回调 Dify Agent 服务器。该协议位于 dify_agent.agent_stub 模块，支持 HTTP 和 gRPC 两种传输方式。

设计目标#

Agent Stub 解决了 "如何让运行在 shellctl 沙箱内的用户脚本安全地访问 Dify 平台资源" 的问题。Shell layer 在执行用户的 shell.run 命令时，会向作业环境注入两个环境变量：

• DIFY_AGENT_STUB_URL：Agent Stub 端点 URL
• DIFY_AGENT_STUB_AUTH_JWE：JWE（JSON Web Encryption）认证令牌

用户脚本通过 dify-agent CLI 命令使用这些环境变量与服务器通信，无需显式处理认证细节。

协议版本与传输方式#

协议版本：v1（AGENT_STUB_PROTOCOL_VERSION = 1）

传输方式：

HTTP 端点会对路径进行规范化（移除尾部斜杠，保留配置的基础路径）。gRPC 端点必须包含显式端口，且路径部分必须为空或 /。

核心协议实体#

所有 Agent Stub 协议实体定义在 dify_agent.agent_stub.protocol.agent_stub 模块中，使用 Pydantic v2 模型确保类型安全和序列化一致性。

AgentStubConnectRequest#

建立控制平面连接的请求：

{
  "protocol_version": 1,
  "argv": ["my-script.sh", "arg1"],
  "metadata": {} # 可选的自由键值对
}

AgentStubConnectResponse#

连接响应的占位符：

{
  "connection_id": "01JVE...",
  "status": "connected"
}

AgentStubFileUploadRequest#

为文件上传分配签名 URL 的请求：

{
  "filename": "output.csv",
  "mimetype": "text/csv"
}

AgentStubFileUploadResponse#

包含签名数据平面上传 URL 的响应：

{
  "upload_url": "https://s3.example.com/signed-url?..."
}

AgentStubFileMapping#

文件映射，用于下载请求：

{
  "transfer_method": "tool_file", # 或 "local_file", "datasource_file", "remote_url"
  "reference": "dify-file-ref:base64encoded...",
  "url": null # 仅当 transfer_method 为 "remote_url" 时使用
}

reference 必须是规范的 Dify 文件引用格式（dify-file-ref: 前缀 + base64url 编码的 JSON 载荷，包含 record_id 字段）。

AgentStubFileDownloadRequest#

为文件下载分配签名 URL 的请求：

{
  "file": {
    "transfer_method": "tool_file",
    "reference": "dify-file-ref:..."
  }
}

AgentStubFileDownloadResponse#

包含下载元数据和签名 URL 的响应：

{
  "filename": "data.json",
  "mime_type": "application/json",
  "size": 1024,
  "download_url": "https://s3.example.com/signed-url?..."
}

基于 JWE 的令牌认证#

Agent Stub 使用 JWE（RFC 7516）令牌进行认证，令牌由 DIFY_AGENT_SERVER_SECRET_KEY 派生的密钥签发。令牌编解码器位于 dify_agent.agent_stub.server.tokens.agent_stub 模块（服务端专用，不包含在客户端安全包中）。

令牌生命周期和安全约束：

1. Shell layer 在执行用户 shell.run 时调用 ShellAgentStubTokenFactory
2. 工厂函数使用 AgentStubTokenCodec.encode_connection_token() 创建 JWE 令牌，有效期为 5 分钟（AGENT_STUB_TOKEN_TTL_SECONDS = 5 * 60），包含执行上下文（tenant_id、app_id、workflow_run_id 等）和 shell session ID
3. 令牌通过环境变量 DIFY_AGENT_STUB_AUTH_JWE 注入到作业环境
4. 用户脚本调用 dify-agent CLI 时，CLI 从环境变量读取令牌并附加到 HTTP Authorization: Bearer 头或 gRPC metadata
5. 服务器端解码令牌，验证签名和过期时间，恢复执行上下文。解码器拒绝声明生命周期超过最大允许值（5 分钟）的令牌，确保即使外部构造的令牌也无法绕过生命周期限制

令牌过期处理：

• 过期令牌由 AgentStubTokenExpiredError 异常表示（继承自 AgentStubTokenError）
• 对于 expose_expiration=True 的端点（connect、file download、config 操作），服务器返回结构化 401 响应，包含 agent_stub_authorization_expired 错误码和用户可见消息："Agent Stub authorization expired after 5 minutes; start a new shell tool call and retry the command."
• 对于文件上传请求（默认 expose_expiration=False），服务器返回通用认证失败，不暴露过期细节
• CLI 将 Agent Stub 401 错误规范化为用户友好消息，指导用户开始新的 shell 工具调用
• 已运行的进程内的令牌不会自动刷新；过期后用户必须通过新的 shell.run 获取新凭证

令牌包含的执行上下文字段：

• tenant_id、user_id：租户和用户身份
• app_id、workflow_id、workflow_run_id：应用和工作流标识
• node_id、node_execution_id：节点标识
• conversation_id：对话标识
• agent_id、agent_config_version_id：Agent 标识和配置版本
• invoke_from：调用来源（如 workflow_run、agent_app）
• trace_id：分布式追踪 ID
• session_id：Shell 会话 ID（由 shell layer 生成）

dify-agent CLI 工具#

Agent Stub 提供客户端安全的 dify-agent CLI，打包为 dify_agent.agent_stub.cli 模块。CLI 通过 pyproject.toml 的 [project.scripts] 声明为控制台脚本。

命令：

文件上传错误恢复机制：

如果 file upload 完成数据平面上传但公共 URL 创建失败，命令会：

1. 将规范化的 ToolFile 引用（transfer_method、reference）输出到 stdout
2. 退出并返回错误，错误消息包含精确的 dify-agent file public-url '<reference>' 恢复命令

用户可从新的 shell 工具调用运行该命令以创建公共 URL，无需重新上传文件。file public-url 成功时输出完整的 JSON 映射（包含 transfer_method、reference 和 public_download_url）。

未知命令的自动转发：当用户执行 dify-agent unknown-cmd arg1 且 unknown-cmd 不是已知子命令时，CLI 会自动将其视为 connect 请求的 argv，即等价于 dify-agent connect unknown-cmd arg1。此设计简化了自定义命令的调用。

环境变量要求：CLI 依赖 DIFY_AGENT_STUB_URL 和 DIFY_AGENT_STUB_AUTH_JWE。若缺失，CLI 会显示 MissingAgentStubEnvironmentError 并返回退出码 2。

HTTP 路由#

Agent Stub HTTP 端点由 create_agent_stub_router() 工厂函数生成，挂载在 /agent-stub 前缀下：

所有端点要求 Authorization: Bearer <JWE> 头。服务器通过 AgentStubTokenCodec.decode_connection_token() 验证令牌并恢复执行上下文。

gRPC 服务#

当 DIFY_AGENT_STUB_URL 使用 grpc:// 协议时，服务器会启动 gRPC 服务（基于 grpclib）。gRPC 服务定义在 dify-agent/proto/dify/agent/stub/v1/agent_stub.proto，生成的 Python 代码位于 dify_agent.agent_stub.grpc._generated。

gRPC 服务方法：

• Connect(AgentStubConnectRequest) -> AgentStubConnectResponse
• FileUploadRequest(AgentStubFileUploadRequest) -> AgentStubFileUploadResponse
• FileDownloadRequest(AgentStubFileDownloadRequest) -> AgentStubFileDownloadResponse

gRPC 认证令牌通过 metadata authorization: Bearer <JWE> 传递。服务端 AgentStubGrpcService 实现相同的令牌验证和业务逻辑。

gRPC 绑定地址覆盖：默认情况下，gRPC 服务绑定到 DIFY_AGENT_STUB_URL 的 host。若需绑定到不同的本地地址（如绑定到 0.0.0.0 但公开 URL 为特定主机名），可设置 DIFY_AGENT_STUB_GRPC_BIND_ADDRESS（格式：host:port）。

文件请求处理#

Agent Stub 的文件下载请求通过 DifyApiAgentStubFileRequestHandler 桥接到 Dify API 的内部文件服务。该处理器由 ServerSettings.create_agent_stub_file_request_handler() 创建，需要配置：

• DIFY_AGENT_DIFY_API_BASE_URL：Dify API 基础 URL（如 https://api.dify.example.com）
• DIFY_AGENT_DIFY_API_INNER_API_KEY：Dify 内部 API 密钥

处理器将 Agent Stub 的文件映射（AgentStubFileMapping）转换为对 Dify API /inner-api/plugin/files/request-download 端点的调用，并使用执行上下文中的 tenant_id、user_id、invoke_from 字段构建访问作用域。API 返回的签名 URL 直接传递给 CLI 客户端。

对应的 API 端点（本次 PR 新增）：

• POST /inner-api/plugin/files/request-download：接受 FileDownloadRequest，返回签名 URL

API 端通过 FileRequestService 服务类解析文件映射并生成签名 URL，该服务位于 api/services/file_request_service.py。

Shell Layer 集成#

Shell layer 通过以下机制集成 Agent Stub：

1. 可选依赖：DifyShellLayerDeps 包含 execution_context: DifyExecutionContextLayer | None
2. 环境注入工厂：build_shell_agent_stub_env() 使用 agent_stub_url、execution_context、token_factory 和 session_id 构建环境变量字典
3. 令牌工厂：ShellAgentStubTokenFactory 是一个可调用协议，接受 execution_context 和 session_id，返回 JWE 令牌字符串
4. 注入时机：仅在用户可见的 shell.run 工具调用时注入环境变量（通过 shellctl.run() 的 env 参数）。内部生命周期脚本（_run_internal_job_to_completion）明确传递 env=None，不注入 Agent Stub 环境

shellctl 版本更新：本次 PR 将 shellctl 的 Dockerfile 从 shell-session-manager==2.1.1 升级到 2.2.0，以支持 shellctl.run() 的 env 参数。

协议设计要点#

• 客户端安全性：协议模块（dify_agent.agent_stub.protocol）和 CLI（dify_agent.agent_stub.cli）不依赖服务器专用的 JWE 加密库，可单独打包分发
• 令牌作用域隔离：每个 JWE 令牌绑定到特定的执行上下文和 shell session，防止跨会话令牌滥用
• 透明的传输选择：HTTP 和 gRPC 共享相同的协议 DTO，客户端通过 URL scheme 自动选择传输方式
• 规范化文件引用：强制使用 dify-file-ref: 格式，确保文件引用的规范性和可审计性

本地开发#

dify-agent 提供 Makefile 封装所有常用开发操作 54。

前提条件 55：

• Python 3.12 或更高版本
• uv（Python 包管理器）
• Redis 实例（本地 Docker 或远端）
• 可访问的 Dify Plugin Daemon

安装依赖：

cd dify-agent
uv sync --all-extras --all-groups

启动 Redis（如本地未运行）：

docker run -d --name dify-agent-redis -p 6379:6379 redis:7-alpine

启动服务器：

# 生产模式
make serve

# 开发模式（uvicorn 热重载）
make dev

两个命令均将服务监听在 http://127.0.0.1:8000。等效的手动命令为 56：

uv run --extra server uvicorn dify_agent.server.app:app --host 127.0.0.1 --port 8000 --reload

其他开发命令：

水平扩展#

dify-agent 服务器设计支持水平扩展，但需了解其进程本地调度的约束：

可扩展方面：

• 多个服务实例可共享同一 Redis 实例和 Plugin Daemon，每个实例独立管理自己的 active_tasks
• Redis Streams 天然支持多消费者并发读取，事件轮询和 SSE 端点可在任意实例上服务任意 run（只要 run 的 Redis 数据存在）
• 通过负载均衡器分发 POST /runs 请求，各实例均匀承接新运行
• 取消端点可在任意 API 进程上原子性地接受正在运行的 run。拥有 runner 的进程观察到共享的 run_cancelled 事件，然后取消并清理其本地任务。HTTP 响应确认逻辑取消已持久化；本地 runner 清理可能仍在进行

约束方面：

• 每次 POST /runs 将 run 绑定到处理该请求的进程，执行与进程生命周期耦合
• 进程崩溃时，该进程正在执行的所有 run 状态丢失，无法自动迁移到其他实例
• GET /runs/{id} 和事件端点可在任意实例上处理（通过共享 Redis），但 run 的实际执行只在创建它的进程中进行

推荐扩展模式：

• 将读取密集型端点（GET /runs/*）与创建端点（POST /runs）通过负载均衡器统一入口对外暴露
• 使用多个 dify-agent 进程实例，通过 DIFY_AGENT_REDIS_PREFIX 区分不同服务组（如按租户隔离）

部署要求：首先在所有地方部署原子终端终结，然后在依赖路由无关取消之前，确保每个可以拥有 runner 的进程都有取消观察者。

优雅停机#

当 FastAPI 进程接收终止信号时，lifespan 的 finally 块触发有序关闭流程 57：

1. scheduler.shutdown() 被调用
   a. 设置 stopping=True（阻止新 run 创建）
   b. 快照当前 active_tasks 列表
   c. asyncio.wait(tasks, timeout=SHUTDOWN_GRACE_SECONDS)
      → 等待所有活跃任务自然完成

2. 超时后：
   a. 取消未完成的 asyncio.Task
   b. 对每个被取消的 run 写入 run_failed 事件（reason="shutdown"）
   c. 更新 run 状态为 "failed"

3. plugin_daemon_http_client.aclose() → 关闭 HTTP 连接池
4. redis.aclose() → 关闭 Redis 连接

这确保了正在运行的 Agent 有机会完成，同时为被迫中断的运行留下可观察的失败记录。

故障恢复限制#

dify-agent 有意保持简单的故障模型，不实现自动恢复 58：

"If the process crashes, currently active runs are lost until an external operator marks or retries them."

当前限制：

• 进程崩溃：active_tasks 是纯内存结构，进程崩溃后无法恢复正在执行的 run
• 无自动重试：失败的 run 不会自动重新调度到其他进程
• 状态残留：崩溃的进程可能留下状态为 running 的 Redis 记录，这些记录在 TTL 到期前会误导客户端

运维应对策略：

• 通过监控系统检测长时间处于 running 状态的 run（超过预期最大执行时间）
• 使用外部脚本将孤立的 running run 标记为 failed
• 配合 Kubernetes 的 Pod 重启策略保证服务进程的存活性

关键设计决策分析#

以下表格汇总了 dify-agent 中的核心技术选型，并分析每个决策的原因和影响。

FastAPI vs 其他框架#

FastAPI 的 lifespan 机制是选型的关键因素 —— 它提供了精确的资源初始化和清理钩子，使得 Redis 连接、HTTP 客户端和调度器的生命周期管理代码仅需约 25 行即可完整实现 14。

进程本地调度的权衡#

这一选择有意降低了系统复杂度：与 Celery/RQ 等方案相比，省去了 Worker 进程管理、任务序列化和分布式锁等问题。代价是单进程容量有限，且崩溃恢复需要外部运维干预。对于 Dify 的初期微服务化尝试而言，这是合理的渐进式复杂度控制 59。

Redis Streams 的设计价值#

相比简单的 Redis List 或 Pub/Sub，Redis Streams 提供了：

• 持久化重放：客户端可以从任意偏移量重放历史事件（SSE 断线重连）
• 游标分页：Stream ID 天然作为不需要额外状态的游标
• block 读取：xread(block=30000) 实现高效的实时等待，无需轮询 60

Pydantic AI 与结构化输出#

将 Pydantic AI 的重试机制与自定义 jsonschema 验证钩子结合，使得结构化输出验证成为 LLM 推理管道的一部分，无效输出自动触发模型重试，对 AgentRunRunner 透明，降低了业务层错误处理的负担 61。

开发规范#

dify-agent 包通过 AGENTS.md 文件确立了完整的开发规范，要求在修改任何源代码之前必须阅读相关的 docstring 和注释 62。

类型注解规范#

代码应包含完整的类型注解，遵循以下原则 63：

• 使用现代 Python 形式：list[str]、dict[str, int]，避免 List[str]、Dict[str, int]
• 避免 Any：除非有充分理由，否则不使用 Any 类型
• 结构化数据：已知键集合的字典数据用 TypedDict；可选键使用 NotRequired[...]；真正动态键空间才用 dict[...]
• 类成员显式声明：在类体顶部（__init__ 之前）用类型注解声明所有成员变量，使类的形状一目了然

class Example:
    user_id: str
    created_at: datetime

    def __init__(self, user_id: str, created_at: datetime) -> None:
        self.user_id = user_id
        self.created_at = created_at

类型检查使用 basedpyright，须在每次编辑后保持通过：

make typecheck

64

代码风格#

• 格式化工具：Ruff（含格式化和 lint）
• 行宽限制：120 字符（含空格）65
• 命名规范：变量和函数用 snake_case，类用 PascalCase，常量用 UPPER_CASE
• 通用原则：优先使用简单函数而非小型工具类；避免不必要的 dunder 方法；代码应清晰直观，避免巧妙技巧 66

make check # 仅检查
make fix # 格式化 + 自动修复

测试方法#

遵循 TDD（测试驱动开发） 原则 67：

1. 先写失败测试
2. 使实现通过
3. 在测试和类型检查均通过的前提下重构

测试组织规则：

• 本地测试放在 dify-agent/tests/local/ 下
• 目录结构镜像 dify-agent/src/ 结构，确保测试位置可预测

有价值的测试应覆盖 68：

• 调用者和下游代码可以观察到并依赖的行为
• 单元对其依赖在边界上的使用方式（成功、失败、空响应、错误响应）
• 文档化的不变量、错误映射和输入 / 输出形状保证

无价值的测试包括（应避免）69：

• 仅镜像当前实现的测试（内部重构就需要更新）
• 对私有辅助函数、内部状态的测试
• 发明出来仅为使当前实现通过的 mock 行为

文档规范#

模块、类、函数三级 docstring 均为必要项 70：

日志规范#

71

• 禁止使用 print()
• 使用模块级 logger：logger = logging.getLogger(__name__)
• 日志级别：可重试事件用 warning，终端失败用 error
• 日志上下文：相关时附加 tenant_id、app_id、run_id 等标识符

Pydantic 使用规范#

• 使用 Pydantic v2 约定
• 默认设置 extra="forbid" 防止意外字段
• 使用 @field_validator / @model_validator 编写领域规则 72

class TriggerConfig(BaseModel):
    endpoint: HttpUrl
    secret: str

    model_config = ConfigDict(extra="forbid")

    @field_validator("secret")
    def ensure_secret_prefix(cls, value: str) -> str:
        if not value.startswith("dify_"):
            raise ValueError("secret must start with dify_")
        return value

包管理#

使用 uv 管理 Python 包（--project dify-agent 标志）73，确保与仓库其他部分的工具链一致。

总结#

Commit 55f95dbc（PR #36087）是 Dify 平台架构演进史上的一个重要里程碑。它在不破坏现有系统的前提下，以 128 个文件、17,357 行代码从零构建了一个独立、生产级的异步 Agent 执行后端。

关注点分离#

该提交最突出的设计贡献是对关注点的清晰分离，体现在三个层次：

这种分层设计使得 Agenton 框架具备独立演化的能力，dify_agent 层可随 Dify 平台需求变化而调整，互不干扰。

与现有系统的关系#

新模块与旧版 BaseAgentRunner / CotAgentRunner / FunctionCallAgentRunner 体系并存而非替代：

• 旧版 runner 仍承担现有会话式 Agent 的同步执行
• dify-agent 服务器提供了面向微服务架构的新执行路径，PR #36284 通过 DifyAgentBackendRunClient 完成了 API 端的生产集成，工作流节点现已能够创建 run、流式消费事件并管理 Agent 配置
• 两者共用同一个 Plugin Daemon 基础设施（端口 5002），无需重复部署

架构演进的意义#

dify-agent 代表了 Dify 从同步、进程内、与主应用紧耦合的 Agent 执行向异步、可独立部署、事件驱动的微服务化 Agent 执行的演进方向：

1. 执行异步化：Agent 运行不再绑定 HTTP 请求生命周期，长时间运行的任务不再受 HTTP 超时限制
2. 可观察性：Redis Streams 提供完整的事件历史，支持回放、SSE 实时推送和游标分页
3. 状态可恢复：SessionSnapshot 机制使 Agent 运行天然支持中断恢复，为未来的暂停 / 继续功能奠定基础
4. 凭证安全：模型凭证不持久化，降低了分布式部署中的安全攻击面
5. 可测试性：完整的测试套件（42 个测试文件，6,000+ 行）确保了生产部署的可靠性

随着 Dify 平台继续向分布式、多租户、高并发方向演进，dify-agent 所建立的这套架构模式 —— 进程内调度 + Redis 持久化 + Plugin Daemon 委托 + Agenton 组合框架 —— 将成为后续功能迭代的重要基础。

PR #36284 - API 端集成#

PR #36284 feat: add new agent 于 2026-05-19 完成了 Agent 后端在 API 端的全面集成，建立了从工作流节点到 Agent 服务器的完整调用链路。该提交新增约 50 个文件、5,000+ 行代码，涵盖客户端包装、领域模型、REST 控制器和业务服务四大组件。

Agent Backend Client 集成#

api/clients/agent_backend/#

API 端通过薄包装层调用 dify-agent 公开客户端，确保工作流代码依赖本地协议而非跨服务契约：

DifyAgentBackendRunClient（client.py）74：

• 包装 dify_agent.client.Client 的同步方法（create_run_sync、cancel_run_sync、stream_events_sync、wait_run_sync）
• 将 dify-agent 异常规范化为 API 原生错误类型（AgentBackendError 子类）
• 定义 AgentBackendRunClient 协议作为工作流集成的稳定边界

错误映射（errors.py）：将跨服务异常转换为 API 端异常层次结构：

• DifyAgentValidationError → AgentBackendValidationError
• DifyAgentHTTPError → AgentBackendHTTPError（含 HTTP 状态码）
• DifyAgentTimeoutError → AgentBackendTransportError
• DifyAgentStreamError → AgentBackendStreamError

事件适配器（event_adapter.py）：将 dify-agent 的事件流转换为工作流节点可消费的格式

请求构建器（request_builder.py）：封装 CreateRunRequest 构造逻辑，处理 Layer 配置、执行上下文和退出策略

Domain Models（领域模型）#

api/models/agent.py#

引入四个核心数据库模型，建立 Agent 的完整生命周期管理：

Agent：工作区范围内的 Agent 身份标识

• scope: AgentScope：roster（团队共享）或 workflow_only（工作流专用）
• source: AgentSource：agent_app、workflow、imported、system
• active_config_version_id：指向当前生效的配置版本
• roster_unique_name：计算列，确保 roster 中 active 状态的 Agent 名称唯一
• 索引：tenant_id + status + updated_at、tenant_id + scope + status、tenant_id + workflow_id

AgentConfigVersion：不可变的 Agent Soul 快照版本

• config_snapshot: LongText：存储 JSON 字符串，不含明文凭证
• version: int：每个 Agent 内单调递增的语义版本号
• version_note：版本说明（可选）
• 唯一约束：(agent_id, version)
• @property config_snapshot_dict：按需解析 JSON

AgentConfigVersionRevision：配置版本的审计快照

• 记录每次保存操作（含对现有版本的覆盖写）
• operation: AgentConfigVersionOperation：CREATE_VERSION、SAVE_CURRENT_VERSION、SAVE_NEW_VERSION、SAVE_NEW_AGENT、SAVE_TO_ROSTER
• previous_config_snapshot：用于 diff 对比（仅在覆盖现有版本时非空）
• revision: int：每个 ConfigVersion 内单调递增
• 唯一约束：(agent_config_version_id, revision)

WorkflowAgentNodeBinding：工作流节点与 Agent 配置版本的绑定关系

• binding_type: WorkflowAgentBindingType：roster_agent（引用 Roster Agent）或 inline_agent（内联专用 Agent）
• node_job_config: LongText：存储工作流节点作业配置的 JSON，不含 Agent Soul
• workflow_version: str：关联工作流版本（如 draft）
• 唯一约束：(tenant_id, workflow_id, workflow_version, node_id)

设计要点：

• Agent Soul（配置快照）与 Node Job（节点作业配置）严格分离，避免数据冗余
• Roster Agent 可被多个工作流节点引用，配置版本在所有绑定间共享
• 配置快照明确禁止存储明文凭证，仅保存凭证引用
• Revision 表实现完整的变更审计链

Controllers（REST 端点）#

api/controllers/console/agent/#

两个控制器模块提供 Agent Composer 和 Roster 的 HTTP 访问接口：

composer.py：Agent Composer 端点（工作流节点和 Agent App 两种变体）

• GET /apps/{app_id}/workflows/draft/nodes/{node_id}/agent-composer：加载工作流节点的 Composer 状态
• PUT /apps/{app_id}/workflows/draft/nodes/{node_id}/agent-composer：保存工作流节点的 Composer 配置
• POST /apps/{app_id}/workflows/draft/nodes/{node_id}/agent-composer/validate：验证保存载荷合法性
• GET /apps/{app_id}/workflows/draft/nodes/{node_id}/agent-composer/candidates：查询可用的候选资源
• POST /apps/{app_id}/workflows/draft/nodes/{node_id}/agent-composer/impact：计算配置版本影响范围
• POST /apps/{app_id}/workflows/draft/nodes/{node_id}/agent-composer/save-to-roster：将工作流 Agent 保存到 Roster
• GET /apps/{app_id}/agent-composer：加载 Agent App 的 Composer 状态
• PUT /apps/{app_id}/agent-composer：保存 Agent App 的 Composer 配置
• POST /apps/{app_id}/agent-composer/validate：验证 Agent App 保存载荷
• GET /apps/{app_id}/agent-composer/candidates：查询 Agent App 可用候选

roster.py：Agent Roster 管理端点

• GET /agents：列出租户内所有 roster Agent（分页、搜索、排序）
• POST /agents：创建新 roster Agent
• GET /agents/{agent_id}：查询单个 Agent 详情
• PUT /agents/{agent_id}：更新 Agent 元数据（名称、描述、图标）
• DELETE /agents/{agent_id}：归档 Agent
• GET /agents/{agent_id}/config-versions：列出 Agent 的所有配置版本
• POST /agents/{agent_id}/config-versions：创建新配置版本
• GET /agents/{agent_id}/config-versions/{version_id}：查询单个配置版本详情
• PUT /agents/{agent_id}/config-versions/{version_id}：更新现有配置版本（覆盖）
• POST /agents/{agent_id}/config-versions/{version_id}/activate：激活指定配置版本

设计特点：

• 所有端点均需 setup_required、login_required、account_initialization_required 认证
• 编辑操作额外要求 edit_permission_required
• 使用 flask_restx 自动生成 OpenAPI 文档（console_ns.expect 注册 Pydantic 模型）
• 返回体为 JSON 字典（由 Service 层序列化）

Services（业务逻辑）#

api/services/agent/#

三个服务模块封装 Agent 的业务逻辑和数据库操作：

AgentComposerService（composer_service.py）：Agent Composer 业务逻辑中心

• load_workflow_composer()：加载工作流节点的 Composer 状态，返回 agent、version、binding、soul_lock、node_job、save_options
• save_workflow_composer()：根据 save_strategy 执行不同保存路径：
  • NODE_JOB_ONLY：仅保存节点作业配置
  • SAVE_TO_CURRENT_VERSION：覆盖当前配置版本（创建新 Revision）
  • SAVE_AS_NEW_VERSION：创建新配置版本（递增版本号）
  • SAVE_AS_NEW_AGENT：创建新 roster Agent 并绑定
  • SAVE_TO_ROSTER：将 workflow-only Agent 提升为 roster Agent
• load_agent_app_composer()：加载 Agent App 的 Composer 状态
• save_agent_app_composer()：保存 Agent App 配置（支持 SAVE_TO_CURRENT_VERSION 和 SAVE_AS_NEW_VERSION）
• calculate_impact()：统计指定配置版本被引用的工作流节点数量

RosterService（roster_service.py）：Roster Agent CRUD 和版本管理

• list_agents()：分页查询、全文搜索、多字段排序
• create_agent()：创建新 Agent 并初始化首个配置版本
• get_agent()：查询 Agent 详情（含活跃配置版本）
• update_agent()：更新 Agent 元数据（名称、描述、图标）
• archive_agent()：软删除（状态置为 archived，记录 archived_by 和 archived_at）
• list_config_versions()：列出 Agent 的所有配置版本（逆序分页）
• create_config_version()：创建新配置版本（自动递增版本号）
• get_config_version()：查询单个配置版本详情
• update_config_version()：覆盖现有配置版本（创建新 Revision）
• activate_config_version()：激活指定配置版本（更新 Agent.active_config_version_id）
• list_config_version_revisions()：查询配置版本的所有审计 Revision
• duplicate_agent()：复制 Agent 及其活跃配置版本

ComposerConfigValidator（composer_validator.py）：Composer 保存载荷验证

• validate_save_payload()：检查 ComposerSavePayload 的语义一致性（如 SAVE_AS_NEW_AGENT 必须提供 new_agent_name）

设计模式：

• Service 层直接操作 SQLAlchemy ORM 模型，返回序列化后的 JSON 字典
• 使用 IntegrityError 捕获唯一约束冲突（如 Agent 名称重复）
• 配置快照存储为 JSON 字符串（_json_dump 确保一致的格式）
• 所有写操作通过 db.session.commit() 统一提交

Entities（数据传输对象）#

api/models/agent_config_entities.py#

定义 Agent 域的 Pydantic DTO，服务于 HTTP 请求 / 响应和业务逻辑：

AgentEnvVariableConfig：环境变量配置，包含 name、key、env_name、variable、type、value、default、required 字段

AgentSecretRefConfig：敏感凭证引用，包含 name、key、env_name、variable、type、id、ref、credential_id、provider_credential_id、provider、permission、permission_status 字段

AgentCliToolEnvConfig：CLI 工具环境配置容器，包含 variables: list[AgentEnvVariableConfig] 和 secret_refs: list[AgentSecretRefConfig] 字段

AgentCliToolConfig：CLI 工具配置，包含 enabled、name、id、label、icon、description、category、install、setup_command、invoke_metadata、新增的 env: AgentCliToolEnvConfig 字段、pre_authorized、authorization_status、permission、permission_status

注：PR #37324 调整了文件中类的定义顺序 ——AgentEnvVariableConfig、AgentSecretRefConfig 和 AgentCliToolEnvConfig 现在定义在 AgentCliToolConfig 之前（原先位于文件后部），以满足 Python 前向引用要求。

AgentSoulConfig：Agent Soul 配置（对应 dify-agent 的 RunComposition）

• instruction: str：Agent 指令（系统提示）
• app_features: dict：应用特性配置
• app_variables: list：应用变量列表

注：PR #37651 从 AgentSoulConfig 移除了 skills_files 字段。Drive 支持的配置现在从提及和 agent drive 服务动态构建。

WorkflowNodeJobConfig：工作流节点作业配置

• declare_output_type: str | None：声明的输出类型
• previous_node_outputs: list：前置节点输出映射

ComposerSavePayload：Composer 保存请求体

• variant: ComposerVariant：workflow 或 agent_app
• save_strategy: ComposerSaveStrategy：保存策略枚举
• agent_soul: AgentSoulConfig | None：Agent Soul 配置（按策略可选）
• node_job: WorkflowNodeJobConfig | None：节点作业配置（仅工作流变体）
• new_agent_name: str | None：新 Agent 名称（SAVE_AS_NEW_AGENT 时必需）
• version_note: str | None：版本说明
• binding: dict | None：现有绑定上下文

ComposerCandidatesResponse：Composer 候选资源响应

• allowed_node_job_candidates: dict：节点作业候选（前置节点输出、输出类型等）
• allowed_soul_candidates: dict：Soul 候选（技能文件、工具、数据集、人工联系人）

协议扩展（dify-agent 包）#

PR #36284 对 dify-agent 协议进行了扩展，新增取消运行和执行上下文字段：

ExecutionContext（dify_agent/protocol/schemas.py）：Dify 执行上下文

• tenant_id、app_id、workflow_id、workflow_run_id、node_id、node_execution_id
• conversation_id、agent_id、agent_config_version_id
• invoke_from: InvokeFrom：调用来源（workflow_run、single_step、agent_app、babysit、fasten）
• trace_id：分布式追踪 ID

CreateRunRequest 扩展字段：

• execution_context: ExecutionContext | None：执行上下文（用于可观察性和产品关联）
• purpose: RunPurpose：运行目的（workflow_node、single_step、agent_app、babysit、fasten_preview）
• idempotency_key: str | None：幂等键
• metadata: dict[str, JsonValue]：自由键值元数据

CancelRunRequest / CancelRunResponse：新增取消运行协议

• reason: str | None：取消原因
• message: str | None：取消消息
• 响应体包含 run_id 和 status: "cancelled"

新增事件类型：

• run_paused：可恢复暂停事件（含 reason、message、session_snapshot）
• run_cancelled：终端取消事件（由显式取消请求触发）

RunStatus 扩展：新增 paused 和 cancelled 状态（原有 running、succeeded、failed）

dify-agent 客户端扩展（dify_agent/client/_client.py）：

• cancel_run_sync()、cancel_run()：同步和异步取消运行方法
• wait_run_sync()、wait_run()：轮询等待运行终止方法

依赖变更#

api/pyproject.toml：将 dify-agent 从 dev 依赖组移至生产依赖，标志 API 端集成正式启用

架构意义#

PR #36284 实现了从 dify-agent 服务器（Commit 55f95dbc） 到 API 生产集成 的完整闭环：

现在，工作流节点可通过以下路径调用 Agent 后端：

Workflow Node
    → AgentComposerService.load_workflow_composer()
        → WorkflowAgentNodeBinding (DB)
            → Agent.active_config_version_id
                → AgentConfigVersion.config_snapshot
                    → DifyAgentBackendRunClient.create_run(CreateRunRequest)
                        → dify_agent.client.Client.create_run_sync()
                            → POST http://agent-backend:8000/runs
                                → RunScheduler.schedule_run()
                                    → AgentRunRunner.run()

这一集成建立了数据库持久化的 Agent 身份系统（Agent Roster）和工作流可引用的配置版本机制，使 Agent 配置从 "一次性请求负载" 演进为 "版本化、可审计、可复用的领域资产"。