---
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="/docs/gemini-cli/official/05-models-runtime" />
  <Card title="Subagents" description="回看本地 subagent 和 remote agent 的边界差异。" href="/docs/gemini-cli/official/04-agents-skills/44-subagents" />
  <Card title="Cloud security" description="远端 agent 涉及云环境和认证时，继续看安全与隐私边界。" href="/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)
