From 3103697ea73ea17c115ed408f4ec92b86d62b7c3 Mon Sep 17 00:00:00 2001 From: Adam Weidman <65992621+adamfweidman@users.noreply.github.com> Date: Tue, 27 Jan 2026 17:15:28 -0500 Subject: [PATCH] docs: Add Experimental Remote Agent Docs (#17697) --- docs/core/remote-agents.md | 84 +++++++++++++++++++ docs/core/subagents.md | 18 ++-- docs/sidebar.json | 4 + .../core/src/agents/cli-help-agent.test.ts | 16 ---- packages/core/src/agents/cli-help-agent.ts | 8 -- 5 files changed, 93 insertions(+), 37 deletions(-) create mode 100644 docs/core/remote-agents.md diff --git a/docs/core/remote-agents.md b/docs/core/remote-agents.md new file mode 100644 index 0000000000..3e5b8b06d1 --- /dev/null +++ b/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 `: Enables a specific subagent. +- `/agents disable `: Disables a specific subagent. + +> **Tip:** You can use the `@cli_help` agent within Gemini CLI for assistance +> with configuring subagents. diff --git a/docs/core/subagents.md b/docs/core/subagents.md index 8a0937eb31..4c68711d6c 100644 --- a/docs/core/subagents.md +++ b/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 -Protocol (MCP) or compatible Agent2Agent interfaces. +Gemini CLI can also delegate tasks to remote subagents using the Agent-to-Agent +(A2A) protocol. -To define a remote agent, use `kind: remote` and provide the `agent_card_url`. - -```markdown ---- -name: bigquery-analyst -description: Can query BigQuery datasets and visualize results. -kind: remote -agent_card_url: https://agent.example.com/cards/bigquery-analyst ---- -``` +See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed +configuration and usage instructions. ## Extension sub-agents diff --git a/docs/sidebar.json b/docs/sidebar.json index 588bc9ce5f..204c719f33 100644 --- a/docs/sidebar.json +++ b/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" } diff --git a/packages/core/src/agents/cli-help-agent.test.ts b/packages/core/src/agents/cli-help-agent.test.ts index e330aa769b..ec1659024e 100644 --- a/packages/core/src/agents/cli-help-agent.test.ts +++ b/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.', diff --git a/packages/core/src/agents/cli-help-agent.ts b/packages/core/src/agents/cli-help-agent.ts index dee10f0ab6..5a564924c6 100644 --- a/packages/core/src/agents/cli-help-agent.ts +++ b/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' +