第2章 Agently框架执行环境：受管资源生命周期管理
执行环境（Execution Environment）是框架层面的一层，负责在 Action 或工作流步骤运行前，准备并释放受管执行依赖。
它拥有并管理 MCP 传输、命令执行器、沙箱、浏览器、SQLite 连接、外部进程运行器等资源的生命周期与策略。Action 和 TriggerFlow 可以请求使用这些环境，但不拥有环境的生命周期。
面向读者
大多数应用开发者不需要从这里入手。建议优先使用内置 Action 和 Agent Component 辅助方法来声明意图，比如启用 Python、shell、工作区、MCP、SQLite、向量存储或 coding-workspace 能力。
在以下情况下才需要阅读本页：
- 编写依赖受管活跃资源的自定义 ActionExecutor
- 编写 ExecutionEnvironmentProvider 插件
- 了解 Action 或 TriggerFlow 如何接收受管资源
- 设计需要沙箱、进程、MCP、客户端、凭证或清理生命周期的新内置能力
不要把 Agently.execution_environment 当作应用开发的默认心智模型，它是高级能力背后的核心生命周期层。
位置
textAgent Component / built-in Action / custom Action / TriggerFlow / Skills plan | v ActionSpec.execution_environments or TriggerFlow execution requirements | v ExecutionEnvironmentManager | v ExecutionEnvironmentProvider | v managed handle / live resource
V1 以如下方式暴露全局管理器：
pythonfrom agently import Agently
Agently.execution_environment
大多数应用代码不需要直接调用管理器。内置的 MCP、Bash、Python、Node.js、Docker、Browser 和 SQLite Action 可以声明自身需求，Action 调度器会在执行器调用前确保这些需求得到满足。
更完整的归属模型请参考 Architecture / Extension Boundaries。
内置行为
内置 provider 包括：
KindUsed byManaged resourcemcpagent.use_mcp(...) / MCP actionsMCP transport resourcebashagent.enable_shell(...) / Bash sandbox actionsconfigured command runnerpythonagent.enable_python(...) / Python sandbox actionsconfigured Python sandboxnodeagent.enable_nodejs(...) / Node.js executor actionsconfigured Node.js runnerdockerDocker executor actionsDocker CLI runnerbrowserBrowse actions that opt into managed browser resourcesmanaged browser/page/session wrappersqliteagent.enable_sqlite(...) / SQLite executor actionsSQLite connection
Search 特意未列在其中。它是一个无状态的 Action 原生能力包；代理、超时、后端和区域配置属于 Search 包/执行器的配置，而不属于 Execution Environment。
这些 provider 是底层环境实现。面向用户的能力通常应以 Action 形式暴露，场景化快捷方式则应通过 Agent Component 或未来的 agent.enable_* 辅助方法提供。
Action 执行流程：
textActionCall -> resolve ActionSpec -> ensure ActionSpec.execution_environments -> inject execution_environment_resources into action_call -> ActionExecutor.execute(...) -> release action_call-scoped handles
自定义 ActionExecutor.execute(...) 的签名不变。受管句柄通过 action_call["execution_environment_handles"] 传递，活跃资源通过 action_call["execution_environment_resources"] 传递。
TriggerFlow
TriggerFlow 仍使用 runtime_resources 作为执行本地活跃资源的兼容接口，Execution Environment 不会重命名或替换该 API。
你可以在创建或启动执行时传入受管需求：
pythonexecution = flow.create_execution( execution_environments=[ { "kind": "python", "scope": "execution", "resource_key": "sandbox", } ], )
管理器会确保资源就绪，注入到执行本地资源中，并在执行关闭时释放。手动传入的 runtime_resources={...} 仍是非受管的，不会由管理器做健康检查或自动释放。
直接使用管理器 API
该 API 面向框架、Action 和插件开发者。
管理器支持：
pythonAgently.execution_environment.declare(requirement) Agently.execution_environment.ensure(requirement_or_id) await Agently.execution_environment.async_ensure(requirement_or_id) Agently.execution_environment.release(handle_or_id) Agently.execution_environment.release_scope("session", owner_id) Agently.execution_environment.inspect(id) Agently.execution_environment.list(scope="execution") Agently.policy_approval.register_handler("my_handler", handler) Agently.configure_policy_approval(handler="my_handler")
declare 是惰性的：它只校验并记录需求，不会启动任何东西。ensure(...) 会在策略和审批许可下启动或复用句柄。审批通过框架级的 Agently.policy_approval handler 处理。默认的 input_timeout_fail handler 只在交互式 CLI 中弹出提示，超时后拒绝，在非交互式服务中则立即拒绝。围绕 TriggerFlow 执行的服务封装应注册自己的 handler，例如先记录待审批状态，之后用 continue_with(...) 恢复执行。复用就绪句柄前，管理器会调用 provider.async_health_check(handle)。健康的句柄复用并 ref_count + 1；不健康的句柄会发出 execution_environment.unhealthy 事件、被释放，然后重新确保一个新句柄。V2 刻意不引入后台调度器、租约 TTL 或自动重连循环。
如果你在开发应用，请先确认内置 Action 或 Agent Component 是否已提供所需能力。
观测
管理器会发出 execution_environment.* 系列框架事件：
- execution_environment.declared
- execution_environment.approval_required
- execution_environment.ensuring
- execution_environment.ready
- execution_environment.unhealthy
- execution_environment.releasing
- execution_environment.released
- execution_environment.failed
事件负载只包含稳定的 id 和状态元数据，不得包含原始凭证、环境变量、命令密钥或活跃资源对象。
示例
可运行的示例位于 examples/execution_environment。建议从本地的 agent.enable_python(...) 快速上手示例开始，再看 Ollama 和 DeepSeek 模型驱动的示例。TriggerFlow 示例面向需要受管执行本地资源的工作流或框架开发者。
另见
Action Runtime MCP TriggerFlow State and Resources
