Dify Agent 执行上下文层Execution Context Layer为插件守护进程调用传递租户与执行身份【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/difyDify Agent 采用分层Layer架构组织一次 Agent 运行的全部资源其中「执行上下文层」execution-context layer承担着共享 Dify 运行标识与租户/用户身份的职责是插件 LLM 层、插件工具层等所有需要访问插件守护进程plugin daemon的业务层的共同底座。读完本文你将理解该层在 Dify Agent 分层组合中的定位、全部配置字段的取值规则与服务端凭证的注入机制并能结合源码与测试用例掌握其“无状态、不持有 HTTP 客户端”的设计约束从而正确编写包含执行上下文层的运行组合RunComposition。一、执行上下文层在分层架构中的定位执行上下文层携带三类信息共享的 Dify 运行标识如app_id、workflow_run_id、node_id等调用插件守护进程所需的租户 ID 与可选的终端用户 ID用于可观测性与链路关联的调用来源分类invoke_from等身份信息。根据官方文档 execution-context-layer 的说明该层需要与 plugin LLM layer 配合使用当调用方希望把 Dify 工具暴露给模型时还需叠加 plugin tool layer。这两个业务层都依赖执行上下文层来触达插件守护进程——例如插件 LLM 层通过deps{execution_context: execution_context}显式声明这种绑定关系因为 API 网关在解析模型凭证时需要调用方身份。该层的类型 ID 为dify.execution_context对应源码常量DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID定义在 configs.pyDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID: Final[str] dify.execution_context二、配置字段全解官方文档给出的字段表如下原文档骨架字段类型含义tenant_idstr调用插件守护进程时使用的 Dify 租户/工作区 ID。user_idstr \| None可选的终端用户 ID透传给插件守护进程。invoke_fromLiteral[...]记录用于可观测性与关联的 Dify 调用方类别。app_id/workflow_id/workflow_run_id/node_id/node_execution_id/conversation_id/agent_id/agent_config_version_id/trace_idstr \| None随运行转发、由 Dify 管理的可选执行标识。对照当前仓库的实现 DifyExecutionContextLayerConfig该配置类在上述字段之外还包含几组必填或可选的身份字段编写组合时必须注意字段类型含义agent_modeLiteral[workflow_run, single_step, agent_app, babysit, fasten]必填Agent 后端运行模式标识本次运行属于哪类 Dify 产品场景。invoke_fromLiteral[service-api, openapi, web-app, trigger, explore, debugger, published, validation]必填Dify 调用方类别用于可观测性与关联。user_fromLiteral[account, end-user] \| None可选调用者身份模型。知识库层knowledge layer会读取该字段让 Dify 内部 API 区分「平台用户」与「终端用户」的检索且该身份判定不受模型控制。agent_config_version_kindLiteral[snapshot, draft, build_draft] \| None可选Agent 配置版本类别。此外配置类声明了ConfigDict(extraforbid, ...)即拒绝任何未知字段。测试 test_configs.py 明确验证了两点传入daemon_url这类运行时设置会触发ValidationError——守护进程传输配置不属于客户端提交的层配置传入任意未知字段如unknown同样被拒绝。另一个容易踩坑的点测试 test_execution_context_rejects_legacy_agent_mode_in_invoke_from 表明把旧的agent_mode取值如workflow_run塞进invoke_from会被视为非法值。invoke_from只接受上文列出的 8 个调用方类别运行模式必须写入独立的agent_mode字段。三、基本用法官方文档给出的最小示例如下原文档骨架注意当前版本还需补充必填的agent_mode字段from dify_agent.layers.execution_context import ( DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig, ) from dify_agent.protocol import RunLayerSpec execution_context_layer RunLayerSpec( nameexecution_context, typeDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, configDifyExecutionContextLayerConfig( tenant_idreplace-with-tenant-id, user_idreplace-with-user-id, invoke_fromworkflow_run, ), )如果不需要终端用户 ID省略user_id或传None即可其余大部分可选执行标识app_id、workflow_run_id、node_id等在不可获得时同样可以省略——只有tenant_id、agent_mode、invoke_from是必填项。结合仓库内 plugin-llm-layer 文档 展示的完整最小模型组合一份与当前源码取值严格对齐的执行上下文层写法是from dify_agent.layers.execution_context import ( DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig, ) from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, RunComposition, RunLayerSpec composition RunComposition( layers[ RunLayerSpec( nameexecution_context, typeDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, configDifyExecutionContextLayerConfig( tenant_idreplace-with-tenant-id, user_idreplace-with-user-id, user_fromaccount, app_idreplace-with-app-id, agent_modesingle_step, invoke_fromdebugger, ), ), # ……以及依赖它的 llm 层deps{execution_context: execution_context} ] )四、服务端配置守护进程凭证不进层配置官方文档强调执行上下文层的配置不包含守护进程传输设置这些凭证配置在 Dify Agent 服务端DIFY_AGENT_PLUGIN_DAEMON_URLhttp://localhost:5002 DIFY_AGENT_PLUGIN_DAEMON_API_KEYreplace-with-plugin-daemon-server-key这样做的目的是让服务端凭证既不进入客户端提交的层配置也不进入会话快照session snapshot避免敏感信息随快照流转。服务端对应的读取位置在 server/settings.py两个设置项均有默认值plugin_daemon_url: str http://localhost:5002 plugin_daemon_api_key: str 即守护进程 URL 默认为本地http://localhost:5002API Key 默认为空生产环境必须显式设置。这些设置的用途说明可参考 get-started 文档DIFY_AGENT_PLUGIN_DAEMON_API_KEY是服务端发给插件守护进程的 API Key。五、源码级实现凭证如何注入、客户端如何创建5.1 层实例只能由 Provider 工厂创建从源码结构看DifyExecutionContextLayer 是一个刻意保持“纯配置/纯设置”的PlainLayer直接调用from_config(config)会抛出TypeError强制要求经由 Provider 工厂构造服务端专用的构造入口是from_config_with_settings(config, *, daemon_url, daemon_api_key)把服务端注入的daemon_url与daemon_api_key作为实例字段保存。而工厂注入发生在运行时的 compositor_factory.pylayer_typeDifyExecutionContextLayer, createlambda config: DifyExecutionContextLayer.from_config_with_settings( DifyExecutionContextLayerConfig.model_validate(config), daemon_urlplugin_daemon_url, ... )也就是说客户端提交的只是DifyExecutionContextLayerConfig守护进程 URL 与 API Key 由服务端在组装 Compositor 时补齐——这正是第四节环境变量设计的底层依据。5.2 create_tool_client业务层共用同一个共享 HTTP 客户端执行上下文层为下游业务层提供的核心能力是 create_tool_clientdef create_tool_client(self, *, plugin_id: str, http_client: httpx.AsyncClient) - DifyPluginDaemonToolClient: if http_client.is_closed: raise RuntimeError(DifyExecutionContextLayer.create_tool_client() requires an open shared HTTP client.) return DifyPluginDaemonToolClient( tenant_idself.config.tenant_id, plugin_idplugin_id, plugin_daemon_urlself.daemon_url, plugin_daemon_api_keyself.daemon_api_key, user_idself.config.user_id, http_clienthttp_client, )要点有三层本身不创建、不缓存、不关闭 HTTP 客户端。运行时把由 FastAPI lifespan 持有的共享httpx.AsyncClient在每次工具调用时传入层只是把它装配进DifyPluginDaemonToolClientplugin_id由调用方业务层传入——具体是哪个插件包属于业务调用细节执行上下文层只负责身份与传输上下文传入的共享客户端若已关闭会抛出RuntimeError快速失败。5.3 测试用例验证的三条约束unit 测试 用三个用例钉死了上述行为test_execution_context_layer_creates_tool_client_from_shared_http_client用httpx.MockTransport构造共享客户端验证生成的工具客户端逐字段继承tenant_id、user_id、plugin_id、守护进程 URL 与 API Key且客户端不会被层关闭test_execution_context_layer_rejects_closed_shared_http_client已关闭的共享客户端会触发RuntimeErrortest_execution_context_layer_lifecycle_does_not_manage_http_client进入完整 Compositor 生命周期含session_snapshot与suspend_layer_on_exit后共享客户端依然保持打开——证明该层不参与资源生命周期管理。六、注意事项汇总结合官方文档 Notes 小节与源码实现使用时需注意不管理 HTTP 客户端生命周期执行上下文层不会打开、缓存、关闭或快照 HTTP 客户端其生命周期钩子保持继承的空实现资源管理交给运行时plugin_id归属业务层模型调用属于插件 LLM 层的plugin_id工具调用属于每个插件工具配置的plugin_id执行上下文层只携带共享的 Dify 调用上下文约定层名为execution_context如果使用别的名字必须同步把 LLM 层与工具层deps中的依赖指向改为该名字extraforbid严格校验不要在层配置里塞daemon_url等传输字段也不要把运行模式误填进invoke_from二者都会导致ValidationError。至此执行上下文层的完整链路是客户端在RunLayerSpec中提交租户/用户/执行标识 → 服务端 Provider 工厂注入守护进程 URL 与 API Key → 业务层通过create_tool_client复用共享 HTTP 客户端访问插件守护进程。这一设计把敏感凭证与无状态身份配置彻底分离使会话快照与客户端请求都不携带服务端密钥。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dify Agent 执行上下文层（Execution Context Layer）：为插件守护进程调用传递租户与执行身份
Dify Agent 执行上下文层Execution Context Layer为插件守护进程调用传递租户与执行身份【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/difyDify Agent 采用分层Layer架构组织一次 Agent 运行的全部资源其中「执行上下文层」execution-context layer承担着共享 Dify 运行标识与租户/用户身份的职责是插件 LLM 层、插件工具层等所有需要访问插件守护进程plugin daemon的业务层的共同底座。读完本文你将理解该层在 Dify Agent 分层组合中的定位、全部配置字段的取值规则与服务端凭证的注入机制并能结合源码与测试用例掌握其“无状态、不持有 HTTP 客户端”的设计约束从而正确编写包含执行上下文层的运行组合RunComposition。一、执行上下文层在分层架构中的定位执行上下文层携带三类信息共享的 Dify 运行标识如app_id、workflow_run_id、node_id等调用插件守护进程所需的租户 ID 与可选的终端用户 ID用于可观测性与链路关联的调用来源分类invoke_from等身份信息。根据官方文档 execution-context-layer 的说明该层需要与 plugin LLM layer 配合使用当调用方希望把 Dify 工具暴露给模型时还需叠加 plugin tool layer。这两个业务层都依赖执行上下文层来触达插件守护进程——例如插件 LLM 层通过deps{execution_context: execution_context}显式声明这种绑定关系因为 API 网关在解析模型凭证时需要调用方身份。该层的类型 ID 为dify.execution_context对应源码常量DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID定义在 configs.pyDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID: Final[str] dify.execution_context二、配置字段全解官方文档给出的字段表如下原文档骨架字段类型含义tenant_idstr调用插件守护进程时使用的 Dify 租户/工作区 ID。user_idstr \| None可选的终端用户 ID透传给插件守护进程。invoke_fromLiteral[...]记录用于可观测性与关联的 Dify 调用方类别。app_id/workflow_id/workflow_run_id/node_id/node_execution_id/conversation_id/agent_id/agent_config_version_id/trace_idstr \| None随运行转发、由 Dify 管理的可选执行标识。对照当前仓库的实现 DifyExecutionContextLayerConfig该配置类在上述字段之外还包含几组必填或可选的身份字段编写组合时必须注意字段类型含义agent_modeLiteral[workflow_run, single_step, agent_app, babysit, fasten]必填Agent 后端运行模式标识本次运行属于哪类 Dify 产品场景。invoke_fromLiteral[service-api, openapi, web-app, trigger, explore, debugger, published, validation]必填Dify 调用方类别用于可观测性与关联。user_fromLiteral[account, end-user] \| None可选调用者身份模型。知识库层knowledge layer会读取该字段让 Dify 内部 API 区分「平台用户」与「终端用户」的检索且该身份判定不受模型控制。agent_config_version_kindLiteral[snapshot, draft, build_draft] \| None可选Agent 配置版本类别。此外配置类声明了ConfigDict(extraforbid, ...)即拒绝任何未知字段。测试 test_configs.py 明确验证了两点传入daemon_url这类运行时设置会触发ValidationError——守护进程传输配置不属于客户端提交的层配置传入任意未知字段如unknown同样被拒绝。另一个容易踩坑的点测试 test_execution_context_rejects_legacy_agent_mode_in_invoke_from 表明把旧的agent_mode取值如workflow_run塞进invoke_from会被视为非法值。invoke_from只接受上文列出的 8 个调用方类别运行模式必须写入独立的agent_mode字段。三、基本用法官方文档给出的最小示例如下原文档骨架注意当前版本还需补充必填的agent_mode字段from dify_agent.layers.execution_context import ( DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig, ) from dify_agent.protocol import RunLayerSpec execution_context_layer RunLayerSpec( nameexecution_context, typeDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, configDifyExecutionContextLayerConfig( tenant_idreplace-with-tenant-id, user_idreplace-with-user-id, invoke_fromworkflow_run, ), )如果不需要终端用户 ID省略user_id或传None即可其余大部分可选执行标识app_id、workflow_run_id、node_id等在不可获得时同样可以省略——只有tenant_id、agent_mode、invoke_from是必填项。结合仓库内 plugin-llm-layer 文档 展示的完整最小模型组合一份与当前源码取值严格对齐的执行上下文层写法是from dify_agent.layers.execution_context import ( DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig, ) from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, RunComposition, RunLayerSpec composition RunComposition( layers[ RunLayerSpec( nameexecution_context, typeDIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, configDifyExecutionContextLayerConfig( tenant_idreplace-with-tenant-id, user_idreplace-with-user-id, user_fromaccount, app_idreplace-with-app-id, agent_modesingle_step, invoke_fromdebugger, ), ), # ……以及依赖它的 llm 层deps{execution_context: execution_context} ] )四、服务端配置守护进程凭证不进层配置官方文档强调执行上下文层的配置不包含守护进程传输设置这些凭证配置在 Dify Agent 服务端DIFY_AGENT_PLUGIN_DAEMON_URLhttp://localhost:5002 DIFY_AGENT_PLUGIN_DAEMON_API_KEYreplace-with-plugin-daemon-server-key这样做的目的是让服务端凭证既不进入客户端提交的层配置也不进入会话快照session snapshot避免敏感信息随快照流转。服务端对应的读取位置在 server/settings.py两个设置项均有默认值plugin_daemon_url: str http://localhost:5002 plugin_daemon_api_key: str 即守护进程 URL 默认为本地http://localhost:5002API Key 默认为空生产环境必须显式设置。这些设置的用途说明可参考 get-started 文档DIFY_AGENT_PLUGIN_DAEMON_API_KEY是服务端发给插件守护进程的 API Key。五、源码级实现凭证如何注入、客户端如何创建5.1 层实例只能由 Provider 工厂创建从源码结构看DifyExecutionContextLayer 是一个刻意保持“纯配置/纯设置”的PlainLayer直接调用from_config(config)会抛出TypeError强制要求经由 Provider 工厂构造服务端专用的构造入口是from_config_with_settings(config, *, daemon_url, daemon_api_key)把服务端注入的daemon_url与daemon_api_key作为实例字段保存。而工厂注入发生在运行时的 compositor_factory.pylayer_typeDifyExecutionContextLayer, createlambda config: DifyExecutionContextLayer.from_config_with_settings( DifyExecutionContextLayerConfig.model_validate(config), daemon_urlplugin_daemon_url, ... )也就是说客户端提交的只是DifyExecutionContextLayerConfig守护进程 URL 与 API Key 由服务端在组装 Compositor 时补齐——这正是第四节环境变量设计的底层依据。5.2 create_tool_client业务层共用同一个共享 HTTP 客户端执行上下文层为下游业务层提供的核心能力是 create_tool_clientdef create_tool_client(self, *, plugin_id: str, http_client: httpx.AsyncClient) - DifyPluginDaemonToolClient: if http_client.is_closed: raise RuntimeError(DifyExecutionContextLayer.create_tool_client() requires an open shared HTTP client.) return DifyPluginDaemonToolClient( tenant_idself.config.tenant_id, plugin_idplugin_id, plugin_daemon_urlself.daemon_url, plugin_daemon_api_keyself.daemon_api_key, user_idself.config.user_id, http_clienthttp_client, )要点有三层本身不创建、不缓存、不关闭 HTTP 客户端。运行时把由 FastAPI lifespan 持有的共享httpx.AsyncClient在每次工具调用时传入层只是把它装配进DifyPluginDaemonToolClientplugin_id由调用方业务层传入——具体是哪个插件包属于业务调用细节执行上下文层只负责身份与传输上下文传入的共享客户端若已关闭会抛出RuntimeError快速失败。5.3 测试用例验证的三条约束unit 测试 用三个用例钉死了上述行为test_execution_context_layer_creates_tool_client_from_shared_http_client用httpx.MockTransport构造共享客户端验证生成的工具客户端逐字段继承tenant_id、user_id、plugin_id、守护进程 URL 与 API Key且客户端不会被层关闭test_execution_context_layer_rejects_closed_shared_http_client已关闭的共享客户端会触发RuntimeErrortest_execution_context_layer_lifecycle_does_not_manage_http_client进入完整 Compositor 生命周期含session_snapshot与suspend_layer_on_exit后共享客户端依然保持打开——证明该层不参与资源生命周期管理。六、注意事项汇总结合官方文档 Notes 小节与源码实现使用时需注意不管理 HTTP 客户端生命周期执行上下文层不会打开、缓存、关闭或快照 HTTP 客户端其生命周期钩子保持继承的空实现资源管理交给运行时plugin_id归属业务层模型调用属于插件 LLM 层的plugin_id工具调用属于每个插件工具配置的plugin_id执行上下文层只携带共享的 Dify 调用上下文约定层名为execution_context如果使用别的名字必须同步把 LLM 层与工具层deps中的依赖指向改为该名字extraforbid严格校验不要在层配置里塞daemon_url等传输字段也不要把运行模式误填进invoke_from二者都会导致ValidationError。至此执行上下文层的完整链路是客户端在RunLayerSpec中提交租户/用户/执行标识 → 服务端 Provider 工厂注入守护进程 URL 与 API Key → 业务层通过create_tool_client复用共享 HTTP 客户端访问插件守护进程。这一设计把敏感凭证与无状态身份配置彻底分离使会话快照与客户端请求都不携带服务端密钥。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考