环境

环境（Environment）以统一方式提供文件、命令、进程、保留输出和端口访问。可以直接用于自动化，也可以把新适配器交给 Harness，让 agent 在所选工作目录、沙箱、容器、虚拟机或远程执行目标中工作。它不要求 agent、模型凭据或托管服务。

环境 provider 内置于 a13n-harness；只有厂商 SDK 通过 extras 按需安装。只调用普通应用工具或远程 API 的 agent 无需环境。

从这里开始

任务	指南
无需网络依赖读写文件	快速入门
选择本地、沙箱、容器或远程执行	选择后端
理解关闭、状态、重新进入和销毁	生命周期与状态
配置内置 provider、凭据和运行时协作对象	Provider 配置
比较六个云 provider	云 provider
实现 provider 或提供 Host 运行时	Provider 与运行时
运行命令、检查进程和读取保留输出	命令与进程
理解路径、搜索模式和输出限制	操作
运行完整的内置生命周期	可运行示例
连接 HTTP 或反向 WebSocket Envd	Remote Envd
向 agent 提供环境工具	Harness 集成

三个概念

Provider 定义： 验证账号输入、凭据和目标配置，再构建适配器，不进行目标 I/O。
Environment： 一次性使用的适配器，负责准备目标、提供操作和关闭本地资源。
EnvironmentState： 由 provider 管理的可移植目标证据，可交给后续新适配器。

close() 不销毁目标；显式 destroy() 是 Host 的独立决策。Direct Local 等 provider 没有可移植目标状态，也不负责销毁目标。根目录、目标 ID 或连接成功都不能证明存在隔离。

选择后端

agent 只需要普通工具或远程 API 时，不使用环境。否则选择 Native 或 Envd 路线：

路线	Provider	适用场景	操作与归属边界
Native	`direct_local`	可信本地自动化	宿主 OS 操作；已有目录，不承诺沙箱隔离
Native	`e2b`	原生托管云沙箱	E2B SDK；创建、暂停、恢复、续期和销毁沙箱
Native	`daytona`	云沙箱	原生停止/启动并保留文件
Native	`modal`	云沙箱	基于快照停止/恢复；固定运行寿命
Native	`vercel`	云沙箱	具有原生会话的命名持久沙箱
Native	`sprites`	云沙箱	持久磁盘与自动休眠/唤醒
Native	`runloop`	云沙箱	Devbox 挂起/恢复和空闲保活
Envd	`local_envd`	CLI 和本地 agent	私有 stdio 守护进程；关闭后保留文件
Native	`docker`	单机服务	Docker Engine 生命周期和 exec；关闭后保留容器
Envd	`http_envd`	网络可达的外部守护进程	HTTP(S) EIP；仅连接
Envd	`websocket_envd`	主动连接 Host 的守护进程	反向 WebSocket EIP；与 Host 集成的 SDK，仅连接

在本地试用远程示例，无需模型、Docker 或云账号。

各层如何配合

Host 选择可信 provider、期望的目标配置、账号配置、当前状态、运行时协作对象、保留策略和授权。
环境 provider 定义 验证账号输入、凭据和目标配置，构建新的单次使用适配器；只在运行时工厂中获取活跃协作对象。
Environment 准备一个精确目标（连接、恢复或创建该目标），提供结构化操作，缓存最新状态，关闭进程内资源，并支持 Host 显式销毁。
Harness 负责执行内挂载名称、访问上限、路由、状态聚合和非破坏性清理。
EIP（环境交互协议，Environment Interaction Protocol）是 a13n-envd 和远程后端使用的结构化操作协议。

EnvironmentState 和 HarnessState 是不同记录。前者是 provider 管理的目标软引用；后者是 agent 续接状态。两者都不恢复当前凭据或授权。

构建能使用环境的 agent

绑定环境提供运行时权限，但不会自动向模型开放操作。添加动态环境 Capability，它会根据每个挂载的有效访问范围和 provider 能力生成模型可见工具：

Python

from a13n_harness import AgentSpec, HarnessBuilder
from a13n_harness.environment import (
    DynamicEnvironmentCapability,
    DynamicEnvironmentConfiguration,
)

executable = HarnessBuilder().build(
    AgentSpec(model="openai-responses:gpt-5"),
    output_type=str,
    capabilities=(
        DynamicEnvironmentCapability(DynamicEnvironmentConfiguration()),
    ),
)

运行示例前配置所选模型 provider，或在测试中将模型替换为确定性的 FunctionModel。

从 Direct Local 开始

Direct Local 开放 Host 选择的已有目录：

Python

from pathlib import Path

from a13n_harness.providers.environment.builtins import select_builtin_environment_providers

(direct_local,) = select_builtin_environment_providers(("direct_local",))
environment = await direct_local.create(
    {"root": {"path": str(Path("./workspace").resolve())}},
    environment_id="workspace",
)

result = await executable.run(
    "Inspect the workspace",
    environment=environment,
)

provider 在准备阶段检查目录，不在进入范围时检查。Harness 在执行后关闭适配器，绝不销毁目标。Direct Local 在关闭时保留目录；其 destroy() 是已声明的空操作，绝不删除该目录。

Direct Local 限制通过当前环境挂载生效。它们不会把获准运行的子进程与 Host 用户账号隔离。

使用 Local Envd

Host 管理共享 Local Envd 运行时；该运行时延迟启动守护进程，并持有其设备连接。每个新适配器都会打开独立会话，使用固定的设备工作目录：

Python

from a13n_harness.providers.environment.builtins import select_builtin_environment_providers
from a13n_harness.providers.environment.local_envd.runtime import (
    LocalEnvdProviderRuntime,
    TemporaryLocalEnvdRuntimeAllocator,
    resolve_a13n_envd_executable,
)

(local_envd,) = select_builtin_environment_providers(("local_envd",))
async with LocalEnvdProviderRuntime(
    executable=resolve_a13n_envd_executable(),
    allocate_private_runtime=TemporaryLocalEnvdRuntimeAllocator(),
) as runtime:
    environment = await local_envd.create(
        {"working_directory": "/absolute/path/to/workspace"},
        environment_id="workspace",
        runtime=runtime,
    )
    result = await executable.run(
        "Inspect the working directory",
        environment=environment,
    )
    # Harness closes this adapter's Session. The Host can use another adapter
    # on the same runtime; leaving this context closes the shared Device.

可执行文件解析依次检查显式参数、A13N_ENVD_EXECUTABLE，再检查 PATH 上的 a13n-envd。客户端和 provider 包不会安装或下载原生二进制文件。

Local Envd 验证守护进程与客户端的精确兼容性，绝不会回退到 Direct Local。Envd 路径指向设备文件系统；固定 cwd 不提供访问隔离。Host 在启动时选择守护进程的 Sandbox 和出站网络模式，Envd 对每个会话实施这些设置；Host 的账号、容器或虚拟机仍决定外层隔离边界。设置和安全边界见 a13n-envd 指南。

重新进入并保留目标

Docker 等有状态 provider 返回 EnvironmentState。Host 持久保存最新状态，并在构建下一新适配器时提供：

Python

current_state = await state_store.load(environment_key)
environment = await docker.create(
    recipe,
    configuration={"docker_host": "unix:///var/run/docker.sock"},
    environment_id="workspace",
    state=current_state,
)

try:
    result = await executable.run(
        "Continue the task",
        environment=environment,
        previous_state=previous_harness_state,
    )
finally:
    await state_store.publish(environment_key, environment.dump_state())

dump_state() 同步读取适配器最新已验证缓存，返回独立副本。进入失败、取消、执行失败或关闭失败后，Host 仍可调用，不会产生额外 provider I/O。

关闭和销毁是两个明确独立的操作：

操作	负责方	效果
进入和执行内使用	Harness	进入新适配器并挂载其操作
`close()`	Harness	释放进程内资源，不移除目标
状态持久化	Host	选择并保存最新权威 `EnvironmentState`
新适配器的 `destroy()`	Host	保留策略决定删除时，移除 provider 管理的精确目标和启动材料

执行暂停或失败后仍会非破坏性关闭适配器。Harness 绝不推断临时所有权，也绝不调用 destroy()。

使用多个环境

传入多个新适配器，并显式提供执行内策略：

Python

from a13n_harness import EnvironmentMount
from a13n_harness.environment import FILE_READ_ACTIONS, EnvironmentPermissionSet

result = await executable.run(
    "Read the source data and write the build output",
    environments={
        "build": build_environment,
        "data": EnvironmentMount(
            data_environment,
            permission_ceiling=EnvironmentPermissionSet(operations=FILE_READ_ACTIONS),
        ),
    },
    default_environment="build",
)

除非挂载设置了 mount_path，默认挂载可通过 /workspace 访问，每个命名挂载可通过 /environment/{name} 访问；设置了 mount_path 的挂载只能通过该根路径访问。存在多个条目时，显式选择 default_environment，或让 /workspace 保持未绑定。映射顺序绝不授予权限。

Harness 在进入前验证完整挂载集合。一个适配器失败时，Harness 会关闭所有可能持有进程内资源的已提供适配器，且不会发布部分挂载集合。回退清理中绝不销毁目标。

环境

从这里开始

三个概念

选择后端

各层如何配合

构建能使用环境的 agent

从 Direct Local 开始

使用 Local Envd

重新进入并保留目标

使用多个环境

仅选择必需操作

下一步

Service 中的环境

本页目录

从这里开始复制章节链接

三个概念复制章节链接

选择后端复制章节链接

各层如何配合复制章节链接

构建能使用环境的 agent复制章节链接

从 Direct Local 开始复制章节链接

使用 Local Envd复制章节链接

重新进入并保留目标复制章节链接

使用多个环境复制章节链接

仅选择必需操作复制章节链接

下一步复制章节链接

Service 中的环境复制章节链接

本页目录

从这里开始

三个概念

选择后端

各层如何配合

构建能使用环境的 agent

从 Direct Local 开始

使用 Local Envd

重新进入并保留目标

使用多个环境

仅选择必需操作

下一步

Service 中的环境