配置运行环境

Environment 是会话沙箱的蓝图，不是一台正在跑的机器。你描述期望的预装包和出网策略，平台负责构建；创建一次即可在多个会话与定时部署里复用。

决定什么：这个会话的沙箱里有哪些软件、能访问哪些外网。
你要做什么：至少创建一份（会话必填 environment_id）。大多数情况用默认即可：cloud + 无限制网络。只有要增装依赖或收紧出网时，才改 packages / networking。
改了谁受影响：创建会话时配置被固化。之后改 Environment 只影响新会话，正在跑的不受影响。

必须引用你自己创建、未归档的 Environment。

创建 Environment

最简单的 Environment 只需要一个名字，配置全部取默认值（cloud 类型、无额外软件包、无限制网络）：

environment=$(curl -sS "$BASE_URL/v1/environments" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "name": "default-env",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"}
    }
  }')

ENVIRONMENT_ID=$(jq -r '.id' <<< "$environment")

响应中的 config 是规范化后的完整配置：packages 六个包管理器的列表都会出现（未声明为空数组），networking 回显生效的网络策略。

在会话中使用 Environment

创建会话时通过 environment_id 引用：

curl -sS "$BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENVIRONMENT_ID\"
  }"

快照语义：创建会话时，Environment 的当前配置会被固化为该会话的环境快照。此后对 Environment 的更新只影响之后创建的会话，不影响正在运行的会话。定时部署只保存引用，每次触发时按环境的当前配置固化进新会话。

配置选项

软件包（packages）

通过六个包管理器声明沙箱中要预装的软件包，服务端排序去重后按 apt → cargo → gem → go → npm → pip 的顺序安装：

curl -sS "$BASE_URL/v1/environments" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "name": "data-analysis-env",
    "config": {
      "type": "cloud",
      "packages": {
        "apt": ["poppler-utils"],
        "pip": ["pandas", "matplotlib", "openpyxl"],
        "npm": ["typescript"]
      },
      "networking": {"type": "unrestricted"}
    }
  }'

约束：每个包管理器最多 200 项；每项最长 256 字符，不含空白或控制字符，不得以 - 开头。自定义 registry / source / index URL 与私有源凭据配置一律拒绝（400 Extra inputs are not permitted）。

网络（networking）

网络策略是二选一的 tagged union：

类型	行为
unrestricted	默认。沙箱可自由出网。
limited	只允许访问 allowed_hosts 列出的主机；包管理器与 MCP 出网需单独放行。

{
  "type": "cloud",
  "packages": { "pip": ["requests"] },
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com", "*.internal.example.com"],
    "allow_package_managers": true,
    "allow_mcp_servers": false
  }
}

limited 模式的字段：

allowed_hosts：最多 256 项；每项是主机名或 *.example.com 通配，不得带协议前缀、端口或路径（写 github.com，不要写 https://github.com）；服务端会小写化并排序去重。
allow_package_managers：默认 false。limited 环境声明了 packages 时必须显式设为 true，否则返回 400。
allow_mcp_servers：默认 false。是否放行 Remote MCP 服务器的出网连接。

unrestricted 模式下不得携带 limited 专属字段，未知字段一律 400。

Environment 生命周期

操作	行为
更新	POST /v1/environments/:id。config 整体替换（非深合并），metadata 键级合并。只影响之后创建的会话。已归档环境返回 400。
归档	POST /v1/environments/:id/archive。阻止新的会话 / 部署绑定；仍引用它的会话在下一次消费环境的交互时被终止（不使用沙箱工具的纯模型会话豁免）。
删除	DELETE /v1/environments/:id。不做引用计数：引用方在下一次使用时得到 not found，定时部署的下一次触发在创建会话阶段失败。删除前请确认没有活跃引用。

管理 Environment

# 列出（分页，默认每页 20）
curl -sS "$BASE_URL/v1/environments" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

# 查看单个
curl -sS "$BASE_URL/v1/environments/$ENVIRONMENT_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

预装运行时

无论是否声明 packages，云沙箱镜像都预装了常用的语言运行时与工具链（Python、Node.js、常见 CLI 工具等），完整清单见预装沙箱环境。packages 声明用于在这个基线之上增装依赖。

下一步

预装沙箱环境

沙箱预装内容与目录结构

创建会话

引用 Environment 启动会话

定时任务

在定时任务中复用 Environment

本页对应 OpenAPI

Environment：创建、更新、归档

开始使用

定义 Agent

运行会话

上下文与记忆

自动化

参考

配置运行环境

创建 Environment

在会话中使用 Environment

配置选项

软件包（packages）

网络（networking）

Environment 生命周期

管理 Environment

预装运行时

下一步

预装沙箱环境

创建会话

定时任务

本页对应 OpenAPI

​创建 Environment

​在会话中使用 Environment

​配置选项

​软件包（packages）

​网络（networking）

​Environment 生命周期

​管理 Environment

​预装运行时

​下一步

预装沙箱环境

创建会话

定时任务

本页对应 OpenAPI

创建 Environment

在会话中使用 Environment

配置选项

软件包（packages）

网络（networking）

Environment 生命周期

管理 Environment

预装运行时

下一步