Agently 文档

中文

English

中文

English

Appearance

Execution Environment ​

语言：English · 中文

Execution Environment 是框架级执行环境层，用来在 action 或 workflow step 真正执行前准备、复用和释放托管执行依赖。

它负责 MCP transport、命令 runner、sandbox、browser、SQLite connection 和外部进程 runner 等资源的生命周期和 policy。Action 与 TriggerFlow 可以声明需要这些环境，但不拥有环境生命周期。

面向对象 ​

多数应用开发者不应该从这里开始。优先使用描述意图的 built-in actions 和 Agent Component helpers，例如启用 Python、shell、workspace、MCP、SQLite、 vector store 或 coding workspace 能力。

在这些情况下阅读本页：

  • 你在写依赖托管 live resource 的自定义 ActionExecutor
  • 你在写 ExecutionEnvironmentProvider 插件
  • 你在 review Action 或 TriggerFlow 如何接收托管资源
  • 你在设计需要 sandbox、process、MCP、client、credential 或 cleanup 生命周期的新 built-in capability

不要把 Agently.execution_environment 暴露成默认应用开发心智。它是更高层能力背后的 core lifecycle 层。

所在位置 ​

text
Agent 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 全局 manager 暴露为：

python
from agently import Agently

Agently.execution_environment

多数业务代码不需要直接调用 manager。内置 MCP、Bash、Python、Node.js、Docker、 Browser、SQLite action 可以声明自己的 requirement，Action dispatcher 在 executor 调用前自动 ensure。

更完整的 ownership 模型见 Architecture / 扩展边界。

内置行为 ​

内置 provider：

Kind使用方托管资源
mcpagent.use_mcp(...) / MCP actionsMCP transport resource
bashagent.enable_shell(...) / Bash sandbox actions配置后的命令 runner
pythonagent.enable_python(...) / Python sandbox actions配置后的 Python sandbox
nodeagent.enable_nodejs(...) / Node.js executor actions配置后的 Node.js runner
dockerDocker executor actionsDocker CLI runner
browser选择托管 browser resource 的 Browse actions托管 browser/page/session wrapper
sqliteagent.enable_sqlite(...) / SQLite executor actionsSQLite connection

Search 故意不放在这里。它是无状态的 Action-native capability package；proxy、timeout、 backend、region 属于 Search package/executor 配置，不属于 Execution Environment。

这些 provider 是低层环境实现。面向用户的能力通常应该暴露为 Action，场景快捷入口应该通过 Agent Component 或未来的 agent.enable_* helpers 暴露。

Action 执行流：

text
ActionCall
  -> resolve ActionSpec
  -> ensure ActionSpec.execution_environments
  -> 把 execution_environment_resources 注入 action_call
  -> 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。

可以在创建或启动 execution 时传入托管 requirement：

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

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

直接 Manager API ​

这组 API 面向框架、action 和 plugin 开发者。

manager 支持：

python
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")
Agently.policy_approval.register_handler("my_handler", handler)
Agently.configure_policy_approval(handler="my_handler")

声明是 lazy 的：只校验和记录 requirement，不启动任何东西。ensure(...) 会在 policy 与 approval 允许的情况下启动或复用 handle。approval 由框架全局 Agently.policy_approval handler 决定。默认 input_timeout_fail 只会在交互式 CLI 中提示输入，并在超时后失败；非交互服务环境会立即失败。包裹 TriggerFlow execution 的服务应注册自己的 handler，例如写入 pending approval 后用 continue_with(...) 恢复。 复用 ready handle 前，manager 会调用 provider.async_health_check(handle)。健康则 ref_count + 1 后复用；不健康则发出 execution_environment.unhealthy，释放旧 handle，再 ensure 一个新 handle。V2 不加入后台 health scheduler、lease TTL 或自动 reconnect loop。

如果你在开发应用，应该先检查是否已有 built-in action 或 Agent Component 暴露了你需要的能力。

Observation ​

manager 发出 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

payload 只包含稳定 id 与状态元信息，不能包含原始凭证、环境变量、命令 secret 或 live resource 对象。

Examples ​

可运行示例见 examples/execution_environment。 建议先看本地 agent.enable_python(...) quickstart，再看 Ollama 和 DeepSeek 驱动的模型决策示例。TriggerFlow 示例面向需要托管 execution-local resource 的 workflow 或框架开发者。

另见 ​