docs: Add Experimental Remote Agent Docs (#17697)

docs/core/remote-agents.md

@@ -0,0 +1,84 @@
+# Remote Subagents (experimental)
+
+Gemini CLI supports connecting to remote subagents using the Agent-to-Agent
+(A2A) protocol. This allows Gemini CLI to interact with other agents, expanding
+its capabilities by delegating tasks to remote services.
+
+Gemini CLI can connect to any compliant A2A agent. You can find samples of A2A
+agents in the following repositories:
+
+- [ADK Samples (Python)](https://github.com/google/adk-samples/tree/main/python)
+- [ADK Python Contributing Samples](https://github.com/google/adk-python/tree/main/contributing/samples)
+
+> **Note: Remote subagents are currently an experimental feature.**
+
+## Configuration
+
+To use remote subagents, you must explicitly enable them in your
+`settings.json`:
+
+```json
+{
+  "experimental": {
+    "enableAgents": true
+  }
+}
+```
+
+## Defining remote subagents
+
+Remote subagents are defined as Markdown files (`.md`) with YAML frontmatter.
+You can place them in:
+
+1.  **Project-level:** `.gemini/agents/*.md` (Shared with your team)
+2.  **User-level:** `~/.gemini/agents/*.md` (Personal agents)
+
+### Configuration schema
+
+| Field            | Type   | Required | Description                                                                                                    |
+| :--------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------- |
+| `kind`           | string | Yes      | Must be `remote`.                                                                                              |
+| `name`           | string | Yes      | A unique name for the agent. Must be a valid slug (lowercase letters, numbers, hyphens, and underscores only). |
+| `agent_card_url` | string | Yes      | The URL to the agent's A2A card endpoint.                                                                      |
+
+### Single-subagent example
+
+```markdown
+---
+kind: remote
+name: my-remote-agent
+agent_card_url: https://example.com/agent-card
+---
+```
+
+### Multi-subagent example
+
+The loader explicitly supports multiple remote subagents defined in a single
+Markdown file.
+
+```markdown
+---
+- kind: remote
+  name: remote-1
+  agent_card_url: https://example.com/1
+- kind: remote
+  name: remote-2
+  agent_card_url: https://example.com/2
+---
+```
+
+> **Note:** Mixed local and remote agents, or multiple local agents, are not
+> supported in a single file; the list format is currently remote-only.
+
+## Managing Subagents
+
+Users can manage subagents using the following commands within the Gemini CLI:
+
+- `/agents list`: Displays all available local and remote subagents.
+- `/agents refresh`: Reloads the agent registry. Use this after adding or
+  modifying agent definition files.
+- `/agents enable <agent_name>`: Enables a specific subagent.
+- `/agents disable <agent_name>`: Disables a specific subagent.
+
+> **Tip:** You can use the `@cli_help` agent within Gemini CLI for assistance
+> with configuring subagents.

docs/core/subagents.md

@@ -171,21 +171,13 @@ If you need to further tune your sub-agent, you can do so by selecting the model
 to optimize for with `/model` and then asking the model why it does not think
 that your sub-agent was called with a specific prompt and the given description.
 
-## Remote agents (Agent2Agent)
+## Remote subagents (Agent2Agent)
 
-Gemini CLI can also delegate tasks to remote agents using the Model Context
+Gemini CLI can also delegate tasks to remote subagents using the Agent-to-Agent
-Protocol (MCP) or compatible Agent2Agent interfaces.
+(A2A) protocol.
 
-To define a remote agent, use `kind: remote` and provide the `agent_card_url`.
+See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed
-
+configuration and usage instructions.
-```markdown
----
-name: bigquery-analyst
-description: Can query BigQuery datasets and visualize results.
-kind: remote
-agent_card_url: https://agent.example.com/cards/bigquery-analyst
----
-```
 
 ## Extension sub-agents
 

docs/sidebar.json

@@ -82,6 +82,10 @@
         "label": "Sub-agents (experimental)",
         "slug": "docs/core/subagents"
       },
+      {
+        "label": "Remote subagents (experimental)",
+        "slug": "docs/core/remote-agents"
+      },
       { "label": "Hooks (experimental)", "slug": "docs/hooks" },
       { "label": "IDE integration", "slug": "docs/ide-integration" },
       { "label": "MCP servers", "slug": "docs/tools/mcp-server" }

packages/core/src/agents/cli-help-agent.test.ts

@@ -55,22 +55,6 @@ describe('CliHelpAgent', () => {
     expect(query).toContain('${question}');
   });
 
-  it('should include sub-agent information when agents are enabled', () => {
-    const enabledConfig = {
-      getMessageBus: () => ({}),
-      isAgentsEnabled: () => true,
-      getAgentRegistry: () => ({
-        getDirectoryContext: () => 'Mock Agent Directory',
-      }),
-    } as unknown as Config;
-    const agent = CliHelpAgent(enabledConfig) as LocalAgentDefinition;
-    const systemPrompt = agent.promptConfig.systemPrompt || '';
-
-    expect(systemPrompt).toContain('### Sub-Agents (Local & Remote)');
-    expect(systemPrompt).toContain('Remote Agent (A2A)');
-    expect(systemPrompt).toContain('Agent2Agent functionality');
-  });
-
   it('should process output to a formatted JSON string', () => {
     const mockOutput = {
       answer: 'This is the answer.',

packages/core/src/agents/cli-help-agent.ts

@@ -84,14 +84,6 @@ export const CliHelpAgent = (
       '- **CLI Version:** ${cliVersion}\n' +
       '- **Active Model:** ${activeModel}\n' +
       "- **Today's Date:** ${today}\n\n" +
-      (config.isAgentsEnabled()
-        ? '### Sub-Agents (Local & Remote)\n' +
-          "User defined sub-agents are defined in `.gemini/agents/` or `~/.gemini/agents/` as .md files. **CRITICAL:** These files **MUST** start with YAML frontmatter enclosed in triple-dashes `---`, for example:\n\n```yaml\n---\nname: my-agent\n---\n```\n\nWithout this mandatory frontmatter, the agent will not be discovered or loaded by Gemini CLI. The Markdown body following the frontmatter becomes the agent's system prompt (`system_prompt`). Always reference the types and properties outlined here directly when answering questions about sub-agents.\n" +
-          '- **Local Agent:** `kind = "local"`, `name`, `description`, `system_prompt`, and optional `tools`, `model`, `temperate`, `max_turns`, `timeout_mins`.\n' +
-          '- **Remote Agent (A2A):** `kind = "remote"`, `name`, `agent_card_url`. Remote Agents do not use `system_prompt`. Multiple remote agents can be defined by using a YAML array at the top level of the frontmatter. **Note:** When users ask about "remote agents", they are referring to this Agent2Agent functionality, which is completely distinct from MCP servers.\n' +
-          '- **Agent Names:** Must be valid slugs (lowercase letters, numbers, hyphens, and underscores only).\n' +
-          '- **User Commands:** The user can manage agents using `/agents list` to see all available agents and `/agents refresh` to reload the registry after modifying definition files. You (the agent) cannot run these commands.\n\n'
-        : '') +
       '### Instructions\n' +
       "1. **Explore Documentation**: Use the `get_internal_docs` tool to find answers. If you don't know where to start, call `get_internal_docs()` without arguments to see the full list of available documentation files.\n" +
       '2. **Be Precise**: Use the provided runtime context and documentation to give exact answers.\n' +