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 端點時，才會傳輸 Model Context Protocol (MCP) 伺服器的標頭設定，其中包含後端驗證權杖。

執行與生命週期管理

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

  • 沙箱環境：代理程式會在全代管沙箱環境中執行，並使用 Antigravity 測試架構進行自動化調度。

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

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

  • 代理程式協作：提供相同的 env_id 進行互動時，多個代理程式會共用相同的環境。

預先安裝軟體

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

類別 套件/工具
UNIX 工具
  • bc
  • curl
  • fd-find
  • gawk
  • gcloud CLI
  • git
  • htop
  • iproute2
  • jq
  • lsof
  • procps
  • ripgrep
  • rsync
  • tree
  • unzip
  • wget
  • which
Python 3.11 套件
  • ast-grep-cli
  • beautifulsoup4
  • google-genai
  • numpy
  • pandas
  • pyyaml
  • requests
Node.js 20 全域套件
  • create-next-app
  • create-vite
  • typescript

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

技能掛接架構

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

來源設定範例

以下範例會附加技能登錄檔中的三項技能：

"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/

沙箱內建工具

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

工具名稱 說明
bash 在沙箱終端機中執行殼層指令，並傳回輸出內容。
file_system 讀取、寫入及刪除檔案內容，並列出目錄內容。

後續步驟

總覽

瞭解 Agent Platform 的 Managed Agents API，這是以設定為導向的 REST 優先環境，可建構自主代理程式。

指南

瞭解如何使用 REST API 建立、更新、列出、取得及刪除代理程式。

指南

瞭解如何在執行階段與代理程式互動、管理工作階段狀態，以及動態覆寫設定。