Gemini CLI 可以通过 A2A 协议连接运行在远程服务器上的子代理，将特定任务委托给外部 AI 代理处理。配置方法是在 .gemini/agents/ 或 ~/.gemini/agents/ 目录下写一个 .md 文件，声明远程代理的 URL 和认证方式即可。适合将公司内部专业代理（如代码审查、数据分析）接入 Gemini CLI。

远程子代理（Remote Subagents）

Gemini CLI 支持通过 A2A（Agent-to-Agent）协议连接远程子代理，让 CLI 可以把任务委托给任意符合 A2A 规范的远程 AI 代理服务。

这一能力使你可以：

• 将企业内部的专业代理（代码审查、合规检查、数据分析等）接入日常工作流
• 复用已部署在 Cloud Run 或其他平台的 AI 服务
• 构建 AI 代理组成的协作网络

---

配置文件位置

远程代理通过 Markdown 文件（.md）配置：

位置	作用范围
.gemini/agents/*.md	项目级（与团队共享）
~/.gemini/agents/*.md	用户级（个人专用）

---

配置格式

基本字段

---
kind: remote
name: my-remote-agent
agent_card_url: https://example.com/.well-known/agent.json
---

字段	类型	必填	说明
kind	string	是	必须为 remote
name	string	是	代理唯一标识符（小写字母、数字、连字符、下划线）
agent_card_url	string	二选一	A2A card 端点的 URL
agent_card_json	string	二选一	内联 JSON 字符串（无法提供端点时使用）
auth	object	否	认证配置，见下文

多代理配置

一个文件可定义多个远程代理（仅限远程代理，不支持混合本地和远程）：

---
- kind: remote
  name: code-reviewer
  agent_card_url: https://agents.example.com/code-reviewer
- kind: remote
  name: data-analyst
  agent_card_url: https://agents.example.com/data-analyst
---

内联 Agent Card JSON

如果没有提供 Agent Card 端点，可以直接内联 JSON：

---
kind: remote
name: inline-agent
agent_card_json: |
  {
    "protocolVersion": "0.3.0",
    "name": "My Inline Agent",
    "description": "A description of what this agent does.",
    "version": "1.0.0",
    "url": "https://example.com/agent",
    "preferredTransport": "HTTP+JSON",
    "capabilities": {
      "streaming": true
    },
    "skills": [
      {
        "id": "MySkill",
        "name": "My Skill",
        "description": "Describe what this skill does.",
        "tags": ["example"]
      }
    ]
  }
---

推荐使用 |（字面量块标量）格式内联 JSON，避免引号转义问题。

---

认证配置

在 auth 字段中指定认证方式。支持四种类型。

动态值解析

apiKey 和 http 类型的 secret 字段支持动态解析：

格式	说明	示例
$ENV_VAR	从环境变量读取	$MY_API_KEY
!command	执行 Shell 命令，使用输出	!gcloud auth print-token
字面量	直接使用字符串	sk-abc123
$$ / !!	转义前缀	$$NOT_AN_ENV_VAR

安全提示：项目级代理文件会提交到版本控制，优先使用 $ENV_VAR 或 !command 而不是直接写 secret。

API Key 认证

将 API Key 作为 HTTP 请求头发送：

---
kind: remote
name: my-agent
agent_card_url: https://example.com/agent-card
auth:
  type: apiKey
  key: $MY_API_KEY
  name: X-API-Key    # 可选，默认为 X-API-Key
---

HTTP Bearer / Basic 认证

Bearer token：

auth:
  type: http
  scheme: Bearer
  token: $MY_BEARER_TOKEN

Basic auth：

auth:
  type: http
  scheme: Basic
  username: $MY_USERNAME
  password: $MY_PASSWORD

其他 IANA 注册方案（如 Digest）：

auth:
  type: http
  scheme: Digest
  value: $MY_DIGEST_VALUE

Google Application Default Credentials

推荐用于部署在 Google Cloud 的代理：

---
kind: remote
name: cloud-run-agent
agent_card_url: https://my-agent.run.app/.well-known/agent.json
auth:
  type: google-credentials
---

Token 类型自动选择：

目标主机模式	Token 类型	适用场景
*.googleapis.com	Access Token	Google API（Vertex AI 等）
*.run.app	Identity Token	Cloud Run 服务

注意：google-credentials 仅适用于 *.googleapis.com 和 *.run.app，其他域名必须使用其他认证方式。

本地开发：先运行 gcloud auth application-default login

CI/Cloud 环境：使用服务账号，设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量

自定义 OAuth 作用域示例：

auth:
  type: google-credentials
  scopes:
    - https://www.googleapis.com/auth/cloud-platform
    - https://www.googleapis.com/auth/compute

OAuth 2.0（交互式）

首次使用时打开浏览器授权，后续自动刷新 token：

---
kind: remote
name: oauth-agent
agent_card_url: https://example.com/.well-known/agent.json
auth:
  type: oauth
  client_id: my-client-id.apps.example.com
  # client_secret: $MY_CLIENT_SECRET  # 机密客户端时必填
---

如果 Agent Card 已声明 oauth2 安全方案，authorization_url、token_url 和 scopes 可自动从 Card 读取。

认证重试

所有认证方式在收到 401 或 403 响应时，自动重新获取凭据后重试（最多 2 次）。apiKey 的 !command 格式在重试时会重新执行命令获取最新 key。

---

代理管理命令

在 CLI 会话内：

/agents list              # 列出所有本地和远程子代理
/agents reload            # 重新加载代理注册表（修改配置文件后使用）
/agents enable <name>     # 启用指定代理
/agents disable <name>    # 禁用指定代理

---

代理管理代理

在 Gemini CLI 内，可以使用内置的 @cli_help 代理获取配置子代理的帮助：

@cli_help 如何配置一个 Cloud Run 上的远程代理？

---

通过代理连接

如果你的网络需要通过代理访问远程代理，在 settings.json 中配置：

{
  "general": {
    "proxy": "http://my-proxy:8080"
  }
}

也支持标准环境变量 HTTP_PROXY 和 HTTPS_PROXY。

---

禁用远程代理

远程代理默认启用，如需完全禁用：

{
  "experimental": {
    "enableAgents": false
  }
}

---

A2A 兼容代理资源

• ADK Python 样例 — 可部署的 A2A 代理示例
• ADK Python Contributing 样例 — 更多参考实现
• A2A 协议规范 — 完整协议文档

---

常见问题

Q: 远程代理和 MCP 服务器有什么区别？

A: MCP 服务器提供工具（Tool），模型主动调用工具获取数据；远程代理是完整的 AI 代理，可以接受任务并自主完成多步推理。选择标准：需要调用外部 API 数据 → MCP；需要委托复杂任务给专业 AI → 远程代理。

Q: 本地文件修改后代理没有生效，怎么处理？

A: 在 CLI 内运行 /agents reload 重新加载代理注册表，无需重启 CLI。

Q: google-credentials 提示"no credentials found"怎么解决？

A: 本地开发需要先运行 gcloud auth application-default login；CI 环境需要设置 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号 JSON 文件，或在 GKE/Cloud Run 上使用 Workload Identity 绑定服务账号。