Agent Platform 沙箱環境中的 Managed Agents API

Agent Platform 的 Managed Agents API 會在標準、隔離的 Linux 沙箱中運作。在這個安全無虞的全代管執行容器中，自訂代理程式可直接進行推理、規劃工作流程、執行 Bash 指令，以及讀取或寫入檔案。

每個沙箱環境都提供下列核心系統和控制選項：

• 永久檔案系統：在多輪互動中，安全地保留檔案、代理邏輯和執行狀態。

• Bash 終端機：提供安全環境，可執行終端機指令、執行自訂指令碼，以及處理本機檔案。

• 網路隔離：預設為停用。您可以明確宣告網路 allowlist，讓代理程式存取公開網際網路資源或下載外部程式庫。

• 可擴充的整合：支援動態匯入自訂功能，包括標準 Web API、Model Context Protocol (MCP) 伺服器，或 Skill Registry 中的技能。

沙箱權限和安全性

為維持標準企業安全界限，遠端沙箱會依據下列權限模型運作：

• 網路隔離：根據預設，沙箱運作時不會存取外部網路。在環境設定中設定網域許可清單，明確啟用連線功能。如需許可清單範例，請參閱「設定網路存取權」。

• 以最小權限執行：啟用網路存取權後，容器會缺少特殊管理憑證或權限。根據預設，只能查詢公開網際網路位置。

• Cloud Storage 和 Skill Registry 掛接的資料範圍：從 Google Cloud Storage 或 Skill Registry 附加外部資料來源時，環境會提供範圍縮減的授權權杖，僅存取代理程式設定中指定的特定目錄或技能。沙箱不含環境憑證，也無法存取專案中的其他存放區或檔案。

• MCP 憑證範圍：只有在存取設定中定義的特定 MCP 端點時，才會傳輸模型內容通訊協定 (MCP) 伺服器的標頭設定，其中包含後端驗證權杖。

執行作業和生命週期管理

這些標準參數會控管沙箱執行作業和生命週期：

• 沙箱環境：代理會在全代管沙箱環境中執行，並使用 Antigravity 控管機制進行自動化調度管理。

• 沙箱存留時間 (TTL)：沙箱環境的標準存留時間 (TTL) 為 7 天。每次新互動都會自動重設這個計時器，確保有效代理人保持可用狀態。

• 代理設定持續性：後端會持續儲存代理設定，直到您將明確的 DELETE 要求傳送至 Agents API 為止。

• 代理協作：在互動期間提供相同的 env_id，多個代理就會共用相同環境。

預先安裝軟體

沙箱包含標準 Linux 公用程式集：

啟用網路存取權後，代理程式可在執行階段使用 pip install 或 npm install 安裝其他套件。這些套件會保留在環境快照中，並在重複使用相同 env_id 時，繼續提供互動功能。

技能掛接架構

從代理 base_environment.sources 內的技能登錄檔等來源設定外部技能時，這些資源會直接附加至沙箱檔案系統。系統會將每個技能放在指定的目標目錄中，並保留原始技能套件目錄結構。這個機構可確保代理程式仍能探索個別技能檔案。

來源設定範例

以下範例會附加 Skill Registry 中的三項技能：

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/pdf-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/finance-skill",
    "target": "/.agent/skills/"
  },
  {
    "type": "skill_registry",
    "source": "projects/{projectID}/locations/{location}/skills/git-skill",
    "target": "/.agent/other-skills/"
  }
]

掛接後的沙箱檔案系統結構

沙箱環境佈建完成後，檔案會掛接在容器中，並依下列方式建構：

/ (root)
└── .agent/
    ├── skills/                    <-- Mount Target for pdf-skill & finance-skill
    │   ├── pdf-skill/             <-- Preserved skill directory
    │   │   ├── SKILL.md
    │   │   └── scripts/
    │   └── finance-skill/         <-- Preserved skill directory
    │       ├── SKILL.md
    │       └── scripts/
    └── other-skills/              <-- Mount Target for git-skill
        └── git-skill/             <-- Preserved skill directory
            ├── SKILL.md
            └── scripts/

沙箱內建工具

在受管理環境中執行時，代理程式可存取多種預設工具：

後續步驟