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