agents-cli 代码执行安全完全指南：沙箱 per-user 环境隔离如何守护 AI Agent

agents-cli 代码执行安全完全指南：沙箱 per-user 环境隔离如何守护 AI Agent

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

agents-cli 是一套面向 Google Cloud 的 AI Agent 开发 CLI 与技能集，把任何编码助手变成创建、评估和部署 AI Agent 的专家。其中代码执行安全是生产落地的核心议题：当 Agent 需要替你运行 Shell 命令或 Python 代码时，如何通过沙箱隔离与per-user 环境隔离设计，确保每个用户的代码互不干扰、凭证绝不泄露？本文带你完整看懂这套设计。

为什么 AI Agent 必须做好代码执行安全？

让 LLM 直接执行代码，听起来很爽，但风险同样明显：

• 🔓权限放大：代码一旦运行，就可能以进程的完整权限读写文件、调用 API；
• 🔁多用户串扰：多人共用一个 Agent 时，A 用户的会话绝不能碰到 B 用户的数据和密钥；
• 📤数据外泄：恶意指令可能诱导 Agent 把敏感凭证"顺路"发到外部网络。

agents-cli 的解法不是"禁止 Agent 跑代码"，而是分层设防：不同信任级别、不同场景的代码，被放进不同强度的执行环境。

三层防线：从本地进程到 per-user 沙箱

1️⃣ 本地进程内执行：最快，但要求"只跑可信代码"

在评估阶段，自定义代码指标（Code Execution Metric）默认在CLI 进程内执行，无需 GCP 项目即可开跑。官方文档明确提醒：该函数以 CLI 的权限运行，只能用于你信任的代码。

📖 字段与取舍的完整说明见 metrics-guide.md 与 evaluation.md。

2️⃣ 远程沙箱：Vertex AI CodeExecutionMetric

在指标配置里加一行execution: remote，代码就会被上传到 Vertex AI 的沙箱中服务端执行，与你的本机进程完全隔离。两个要点：

• 需要已配置的 GCP 项目 + 区域；
• 沙箱内没有网络——依赖外部 LLM 调用的判分逻辑要保留在本地模式运行，这正是"最小权限"思想的体现。

同样，ADK 侧也提供两种代码执行器：BuiltInCodeExecutor（模型内置）与VertexAiCodeExecutor（托管沙箱、可跨会话保持状态），详见 adk-python.md。

3️⃣ per-user 长时沙箱：多用户生产环境的终极答案

当 Agent 要"替用户执行 Shell 命令或 Python"，且需要隔离的、按用户划分的环境时，agents-cli 工作流会指向官方参考配方long-horizon-harness——一个完整的 Agent 执行框架（harness）：

• 🧱per-user sandbox：每个用户独享一个可跨天存活的沙箱工作区，代码、文件、状态彼此隔离；
• 🔐per-user secrets：每个用户的凭证单独存放，模型永远看不到，只在工具调用时由代码侧注入；
• 🛡️分层工具护栏 + 外泄检测：对出网流量做 egress/exfil 检查，高风险操作前触发审批门（human-in-the-loop）；
• 🤝子代理委派：带隔离上下文窗口的子代理，进一步缩小单点故障面。

能力与配方的完整映射表（"你需要什么 → 学哪个配方"）维护在 samples.md，这是官方技能包里"安全能力目录"的入口。

如何快速上手：找到并学习 per-user 沙箱配方

agents-cli 的理念是"研究并改造，而非从零手写"——手写 Docker/E2B 沙箱包装层，恰恰说明你停在了名字层面。标准动作只有三步：

1. 在 samples.md 的主题索引中确认能力对应的配方（沙箱、per-user 环境、密钥、审批门 →long-horizon-harness）；
2. 克隆该配方，先读它的AGENTS.md——意图、文件阅读顺序、"可直接复制 vs 需改造"的边界都写清楚了；
3. 只摘取你需要的模式，不必整体引入 harness。

这套"先查目录再动手"的约束被直接写进了工作流技能 workflow/SKILL.md：只要需求涉及"替用户跑代码、隔离的 per-user 环境"，就必须先查配方，再承诺实现方案。

安全行为可观测：隔离之外还要"看得见"

隔离是底线，可观测是保障。部署后的 Agent 会接入 Cloud Trace / Logging 与 Agent Analytics，工具调用、护栏拦截、审批事件全链路留痕，出了问题能精确回溯到某次工具调用。

更多实践参考 bigquery-agent-analytics.md。

小结：让 Agent 跑代码，安全不打折

agents-cli 的代码执行安全设计可以概括为一句话：按信任级别分层设防，用官方配方而非手写轮子实现 per-user 隔离。把 skills/ 目录下的技能交给你的编码助手，它会在正确阶段自动带你走到正确的配方上——这也是"把助手变成专家"的精髓所在。

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli