Remote agents
Gemini CLI Remote agents 的用途：連線遠端 agent、跨環境協作、遠端能力邊界和安全注意事項。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Remote agents | 遠端代理 | 在遠端環境跑的 Agent。 |
| 網路暴露 | exposure | 遠端連線的對外訪問面。 |
| 認證 | auth | 遠端訪問的身份校驗。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你判斷要不要用 Remote agents、怎麼安全連線。
你是 Gemini CLI 遠端代理顧問。
【角色】
Gemini CLI 遠端代理顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 為什麼想用遠端（算力 / 環境 / 資料在遠端）：___
- 遠端環境型別：___
- 現有認證方式：___
- 最擔心的安全點：___
- 經驗水平：___
【工作流程】
1. 判斷是否真需要遠端
2. 給連線和認證設定
3. 收緊網路暴露面
4. 說明常見故障
5. 給驗證和排障
【輸出規範】
▌一、是否需要遠端
▌二、連線 + 認證
▌三、網路暴露收緊
▌四、故障排查
【硬約束】
- 能用本地就不開遠端
- 遠端必須認證，不裸暴露埠
- 生產環境遠端預設人工確認
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述Remote agents 讓 Gemini CLI 可以連線和使用遠端 agent。它適合把某些專門能力放到遠端環境，但安全邊界要比本地 subagent 更謹慎。
Remote agent 會引入網路、遠端記錄、認證和資料跨邊界問題。第一次呼叫只給低敏、只讀任務。
官方實現基於 Agent-to-Agent（A2A）協議。Gemini CLI 可以連線符合 A2A 的遠端 subagent，把任務委託給遠端服務後接收結果。
適合場景
- 遠端有專門執行環境。
- 團隊共享某個專門能力。
- 本機不適合安裝重依賴。
- 任務需要訪問遠端資源。
定義方式
Remote agent 用 Markdown 檔案加 YAML frontmatter 定義，放在：
- 專案級：
.gemini/agents/*.md - 使用者級：
~/.gemini/agents/*.md
最小示例：
---
kind: remote
name: my-remote-agent
agent_card_url: https://example.com/agent-card
---kind 必須是 remote，name 必須是合法 slug。遠端能力來源可以是 agent_card_url，也可以是內聯 agent_card_json。一個 Markdown 檔案可以定義多個 remote agent，但目前只支援 remote list，不支援把 local 和 remote 混在同一個檔案裡。
網路和認證
如果設定了代理，Gemini CLI 會使用 settings.json 的 general.proxy 或標準環境變數 HTTP_PROXY、HTTPS_PROXY。
官方支援的認證方式包括：
apiKey：把靜態 key 放進 HTTP header。http：Bearer、Basic 或其他 HTTP auth scheme。google-credentials：Google ADC，適合 Google Cloud / Cloud Run。oauth：OAuth 2.0 Authorization Code + PKCE。
專案級 agent 檔案不要直接寫明文金鑰。apiKey 和 http 的 secret 支援 $ENV_VAR 或 !command 動態讀取；優先用環境變數或命令獲取短期 token。
風險
- 遠端 agent 能看到什麼資料。
- 遠端記錄如何儲存。
- 憑據是否會跨邊界。
- 網路失敗如何恢復。
- 任務結果如何驗證。
- 遠端 agent card 是否可信。
- 認證 token 是否會發到非預期 host。
| 風險點 | 檢查 |
|---|---|
| 資料外發 | 遠端能看到哪些 prompt、檔案和結果 |
| 遠端記錄 | 服務端是否儲存請求和響應 |
| 認證 | token 是否只發給預期 host |
| 網路失敗 | 超時、重試、降級策略是否明確 |
| 結果驗證 | 本地如何複核遠端輸出 |
建議
先用只讀任務驗證 remote agent，再逐步開放寫操作。不要把遠端 agent 當成“更強的本地 agent”，它多了網路、許可權和資料邊界。
對 Google Cloud 場景，google-credentials 只會把 token 發給已知 Google-owned hosts，例如 *.googleapis.com 和 *.run.app。其他域名應改用 apiKey、http 或 oauth，不要繞過 host 限制。
管理和關閉
會話內用 /agents list 檢視 local 和 remote agents，用 /agents reload 過載定義，用 /agents enable <name> 和 /agents disable <name> 控制單個 agent。要整體關閉 agents，可在 settings.json 裡設定：
{
"experimental": {
"enableAgents": false
}
}驗收方式
先驗證 agent card 能讀取，再驗證認證方式不會把金鑰寫入專案檔案。第一次呼叫只給遠端只讀、低敏任務；拿到結果後，用本地命令或人工檢查複核。遠端 agent 的結果不能直接等同於本地已驗證產物。
接下來去哪
模型與執行時
Agents & Skills 結束後，繼續看模型選擇、路由、token caching 和執行時模式。
Subagents
回看本地 subagent 和 remote agent 的邊界差異。
Cloud security
遠端 agent 涉及雲環境和認證時，繼續看安全與隱私邊界。