Remote agents
Gemini CLI Remote agents 的用途：連線遠端 agent、跨環境協作、遠端能力邊界和安全注意事項。
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 涉及雲環境和認證時，繼續看安全與隱私邊界。