cwc-workshops Environments API指南：创建与配置Agent隔离沙箱环境

cwc-workshops Environments API指南：创建与配置Agent隔离沙箱环境

【免费下载链接】cwc-workshops项目地址: https://gitcode.com/GitHub_Trending/cw/cwc-workshops

在 cwc-workshops 这套 Agent 工作坊示例中，Environments API 是搭建 Claude Managed Agent 的核心环节之一：一个Environment（环境）就是"容器的配置模板"，它定义了你 Agent 运行沙箱的云类型、网络策略和预装依赖。掌握environments.create之后，你只需几行代码就能为 Agent 创建完全隔离的云端执行环境，实现安全的一键部署。

为什么 Agent 需要隔离沙箱环境 🛡️

Managed Agents 的运行链路是固定的四步：Agent → Environment → Session → Events。其中：

资源	角色	一句话理解
Agent	大脑	定义模型、提示词和工具
Environment	躯壳	定义容器和网络配置
Session	一次任务	把大脑放进躯壳开始干活
Events	神经系统	双向流式事件通道

沙箱按会话创建、用完即销毁（ephemeral），你无需自己运维任何容器。仓库中agents-that-remember工作坊的开场白把这件事总结得很精辟："agents are templates that define model and prompt configuration, and environments are templates that define container configuration"。

三步创建第一个环境：从零到隔离沙箱

以ship-your-first-managed-agent（Incident-2277 故障排查工作坊）为例，创建环境只是 7 个函数里的第 2 步。参考实现见 agent_complete.py：

env = client.beta.environments.create( name=f"sre-agent-{uuid.uuid4().hex[:6]}", config={"type": "cloud", "networking": {"type": "unrestricted"}}, )

三步走：

1. 命名：带上随机后缀，避免多人共用同一 API Key 时重名冲突
2. 选类型："type": "cloud"表示使用托管云沙箱，容器在首次会话时才会真正分配（约需 15~20 秒）
3. 定网络策略：unrestricted（放开）或limited（白名单），这是最关键的安全开关

拿到env.id后，把它传给sessions.create(environment_id=env_id)，沙箱即告就绪。完整链路可对照 agent.py 中的提示注释练习。

最小配置 vs 精细化配置：networking 与 packages

最简环境只需一个{"type": "cloud"}，仓库里 bootstrap.sh 就通过 CLI 一行搞定：

ant beta:environments create --name "$ENV_NAME" --config '{"type":"cloud"}'

生产级配置则要精细得多。看 Deal Desk 工作坊的投资研究沙箱 research.yaml：

name: deal-research config: type: cloud networking: type: limited allow_package_managers: true allow_mcp_servers: true allowed_hosts: - sec.gov - "*.edgar-online.com" - "*.googleapis.com" - finance.yahoo.com packages: type: packages pip: - pandas - numpy - yfinance

这份配置体现了三个最佳实践：

• 🔒网络白名单（allowed_hosts）：只放行 SEC、EDGAR 等必要域名，其余出站全部拦截，防止提示注入后的数据外泄
• 📦预装依赖（packages.pip）：把 pandas、numpy 等常用库写进环境模板，Agent 开箱即用
• 🔌按需开关 MCP：allow_mcp_servers控制沙箱能否连接外部工具服务器

环境 ID 的正确管理：幂等与复用

环境是账号级资源，创建后 ID 应持久化，切勿每次运行都新建。仓库里的几个工作坊给出了三种典型做法：

方式一：YAML 文件 + 幂等脚本。Deal Desk 的 setup.sh 直接用ant beta:environments create < seed/environments/research.yaml读取配置文件创建环境，并把返回的 ID 写回.env；重跑时检测到已有ENVIRONMENT_ID就直接复用，脚本完全幂等。

方式二：本地 JSON 缓存。StockPilot 工作坊在 cma.py 的ensure_env()中实现"查缓存 → 查远端 → 才创建"的逻辑，ID 缓存在.stockpilot_ids.json里，部署可重复执行。

方式三：先 list 后 create。bootstrap.sh 先按名字environments list查一次，查不到才创建——适合交互式工作坊场景。

在 Session 中绑定环境并挂载资源

环境创建完毕后，绑定动作发生在创建 Session 时。以 SRE 工作坊为例（见 agent_complete.py）：

session = client.beta.sessions.create( agent=agent_id, environment_id=env_id, resources=[{"type": "file", "file_id": log_file_id, "mount_path": "app.log"}], )

注意resources参数：它把之前上传的文件（如 7 万行日志）挂载进沙箱文件系统，Agent 就能在隔离环境里直接 grep、写脚本分析。多 Agent 场景下同样适用——StockPilot 的每个子 Agent 会话都复用同一个environment_id，见 cma.py。

💡经验提示：环境不区分版本，一个环境可被所有会话共享；但 Agent 有版本管理，会话永远使用最新 Agent 版本 + 指定环境，两者职责清晰分离。

常见配置速查表 🧭

配置项	取值	适用场景
config.type	cloud	所有托管沙箱（当前唯一类型）
networking.type	unrestricted	开发调试、需随意装包
networking.type	limited	生产环境、金融/合规场景
allowed_hosts	域名列表（支持*.x.com通配符）	限定出站白名单
allow_package_managers	true/false	是否允许 pip/npm 等在线装包
allow_mcp_servers	true/false	沙箱能否连 MCP 外部工具
packages.pip	包名列表	预装 Python 依赖

选型口诀：练习用unrestricted图快；一旦 Agent 要处理真实业务数据（如 research.yaml 中的尽调场景），立即切到limited+ 最小白名单。

总结：Environments API 一页纸清单

1. 定位：Environment = 容器配置模板，与 Agent（大脑模板）配对使用
2. 创建：Python SDK 用client.beta.environments.create()，CLI 用ant beta:environments create < 配置.yaml
3. 安全：生产环境务必用limited网络 +allowed_hosts白名单
4. 复用：环境 ID 要持久化（.env或 JSON 缓存），创建逻辑保持幂等
5. 绑定：在sessions.create时通过environment_id挂载，配合resources注入文件

想动手实践，可克隆本仓库并进入任一工作坊目录（如 ship-your-first-managed-agent 或 production-ready-agent），每个工作坊都自带完整的环境配置示例和分步练习：

git clone https://gitcode.com/GitHub_Trending/cw/cwc-workshops

从 4 行代码的unrestricted环境起步，再进阶到 18 行的白名单 + 依赖预装配置——这就是 Environments API 从入门到生产的全部路径 🚀

【免费下载链接】cwc-workshops项目地址: https://gitcode.com/GitHub_Trending/cw/cwc-workshops