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 涉及云环境和认证时，继续看安全与隐私边界。