Execution Environment

有些能力不是一个纯函数。MCP server 要连接，浏览器要启动，SQLite 要打开连接，Python 或 shell 执行环境要受 policy 控制。把这些生命周期藏进 action 函数里，会让资源复用、审批、健康检查和释放都变得不可见。

Execution Environment 负责在 Action 或 TriggerFlow step 执行前准备、复用和释放这些托管资源。

什么时候需要读这页

多数应用开发者可以先用更高层入口：

• agent.enable_python(...)
• agent.enable_shell(...)
• agent.enable_nodejs(...)
• agent.enable_sqlite(...)
• agent.use_mcp(...)
• agent.use_actions(Browse(...))

只有下面几种情况需要深入 Execution Environment：

• 你在写依赖 live resource 的自定义 ActionExecutor。
• 你在写 ExecutionEnvironmentProvider 插件。
• 你要让 TriggerFlow execution 拿到托管 resource。
• 你在设计需要 sandbox、process、MCP、browser、credential 或 cleanup 生命周期的新 built-in capability。

它在栈里的位置

Agent helper / built-in action / custom action / TriggerFlow
  ↓ declares requirement
ExecutionEnvironmentManager
  ↓ ensure / health check / approval / release
ExecutionEnvironmentProvider
  ↓
managed handle / live resource

全局 manager 暴露为：

from agently import Agently

Agently.execution_environment

业务代码通常不直接调用 manager。Action dispatcher 会在执行器调用前根据 requirement 自动 ensure。

内置 provider

Kind	常见使用方	托管资源
mcp	agent.use_mcp(...) / MCP actions	MCP transport resource
python	agent.enable_python(...)	Python sandbox
bash	agent.enable_shell(...)	受控命令 runner
node	agent.enable_nodejs(...)	Node.js runner
sqlite	agent.enable_sqlite(...)	SQLite connection
browser	需要托管 browser 的 Browse actions	browser/page/session wrapper
docker	Docker executor actions	Docker CLI runner

Search 不放在这里。Search 是无状态 Action-native package，timeout、backend、region、proxy 属于 Search package / executor 配置。

它和 Skills、Actions、沙箱的关系

Execution Environment 不是第四种任务规划方式。它只负责“执行某个能力前，需要什么受管环境”。几个边界要分清：

场景	Owner
模型应该调用哪个能力	Actions / Action Runtime / planner
这次任务应该使用哪份行为指导	Skills Executor
脚本、shell、Python、Node、浏览器、MCP server 怎么启动和释放	Execution Environment
高风险动作能不能发生	PolicyApproval / host policy
分支、等待、恢复和过程流怎么推进	TriggerFlow

Skill 可以描述“这个任务需要运行脚本或调用工具”，但不能自己授予 shell、文件、MCP 或浏览器权限。真正的 capability loading 和审批仍由 host、Action Runtime 和 Execution Environment 管住。

Action 执行流

ActionCall
  → resolve ActionSpec
  → ensure ActionSpec.execution_environments
  → 注入 execution_environment_handles / resources
  → ActionExecutor.execute(...)
  → 释放 action-call scope handles

自定义 ActionExecutor.execute(...) 签名不需要变。托管 handle 会通过 action_call["execution_environment_handles"] 传入，live resource 通过 action_call["execution_environment_resources"] 传入。

TriggerFlow 里使用

TriggerFlow 仍然使用 runtime_resources 作为 execution-local live resource 入口。Execution Environment 不替代这个 API，但可以把托管 resource 注入到 execution-local resources。

execution = flow.create_execution(
    execution_environments=[
        {
            "kind": "python",
            "scope": "execution",
            "resource_key": "sandbox",
        }
    ],
)

manager 会 ensure 资源，并在 execution close 时释放。手动传入的 runtime_resources={...} 是 unmanaged，不参与 manager health check 或自动释放。

Manager API

这组 API 面向框架、action 和插件开发者：

Agently.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")

声明是 lazy 的：只校验和记录 requirement，不启动资源。ensure(...) 在 policy 和 approval 允许时启动或复用 handle。

复用 ready handle 前，manager 会调用 provider.async_health_check(handle)。健康则增加 ref count；不健康则发出 execution_environment.unhealthy，释放旧 handle，再 ensure 新 handle。

Approval 和 observation

需要人工或服务端审批时，接入 policy approval：

Agently.policy_approval.register_handler("my_handler", handler)
Agently.configure_policy_approval(handler="my_handler")

默认 input_timeout_fail 只适合交互式 CLI。非交互服务环境应注册自己的 handler，例如写入 pending approval 后用 continue_with(...) 恢复。

manager 会发出 execution_environment.* observation 事件，例如 declared、approval_required、ensuring、ready、unhealthy、releasing、released、failed。payload 只应包含稳定 id 和状态元信息，不应包含原始凭证、环境变量、secret 或 live resource 对象。

示例

可运行示例见 Agently examples/execution_environment/：

• 本地 Python environment。
• Agent + Ollama / DeepSeek 驱动的环境决策。
• TriggerFlow execution-local resource。
• Node.js、SQLite、browser environment。
• health check 和复用。

常见误用

• 应用开发从 Agently.execution_environment 起步，而不是从 enable_* helper 起步。
• 把外部进程生命周期藏进 ActionExecutor。
• 把 Search 当 Execution Environment。
• 把 Skill 选中当成执行环境授权。
• 让脚本在主进程裸跑，而不是走受控 Python/shell/Node provider。
• 把 TriggerFlow runtime_resources 当可序列化 state。
• 在服务环境使用默认 CLI approval handler。

下一步

• Action Runtime：Action Runtime
• MCP：MCP
• TriggerFlow resources：State 与 Resources
• 扩展边界：扩展边界