---
title: "Remote agents"
description: "Gemini CLI Remote agents 的用途：連線遠端 agent、跨環境協作、遠端能力邊界和安全注意事項。"
verifiedAt: "2026-05-09"
---

Remote agents 讓 Gemini CLI 可以連線和使用遠端 agent。它適合把某些專門能力放到遠端環境，但安全邊界要比本地 subagent 更謹慎。

> [!WARNING]
> Remote agent 會引入網路、遠端日誌、認證和資料跨邊界問題。第一次呼叫只給低敏、只讀任務。

官方實現基於 Agent-to-Agent（A2A）協議。Gemini CLI 可以連線符合 A2A 的遠端 subagent，把任務委託給遠端服務後接收結果。

## 適合場景

- 遠端有專門執行環境。
- 團隊共享某個專門能力。
- 本機不適合安裝重依賴。
- 任務需要訪問遠端資源。

## 定義方式

Remote agent 用 Markdown 檔案加 YAML frontmatter 定義，放在：

- 專案級：`.gemini/agents/*.md`
- 使用者級：`~/.gemini/agents/*.md`

最小示例：

```markdown
---
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` 裡設定：

```json
{
  "experimental": {
    "enableAgents": false
  }
}
```

## 驗收方式

先驗證 agent card 能讀取，再驗證認證方式不會把金鑰寫入專案檔案。第一次呼叫只給遠端只讀、低敏任務；拿到結果後，用本地命令或人工檢查複核。遠端 agent 的結果不能直接等同於本地已驗證產物。

## 接下來去哪

<Cards>
  <Card title="模型與執行時" description="Agents & Skills 結束後，繼續看模型選擇、路由、token caching 和執行時模式。" href="/zh-Hant/docs/gemini-cli/official/05-models-runtime" />
  <Card title="Subagents" description="回看本地 subagent 和 remote agent 的邊界差異。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/44-subagents" />
  <Card title="Cloud security" description="遠端 agent 涉及雲環境和認證時，繼續看安全與隱私邊界。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/66-cloud-security-privacy" />
</Cards>

## 官方來源

- [Gemini CLI remote agents](https://github.com/google-gemini/gemini-cli/blob/main/docs/core/remote-agents.md)
