From 5a0a10cb9807321a95195b77869811818b529964 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Thu, 2 Apr 2026 17:04:35 -0700 Subject: [PATCH] Docs: Tweaks for documentation consistency. --- docs/cli/trusted-folders.md | 8 +++ docs/cli/tutorials/automation.md | 4 +- docs/core/a2a-server.md | 93 ++++++++++++++++++++++++++++++++ docs/release-confidence.md | 2 +- docs/sidebar.json | 19 ++++++- docs/tools/file-system.md | 24 +++++++-- 6 files changed, 142 insertions(+), 8 deletions(-) create mode 100644 docs/core/a2a-server.md diff --git a/docs/cli/trusted-folders.md b/docs/cli/trusted-folders.md index c271a0dba2..82c04ff29c 100644 --- a/docs/cli/trusted-folders.md +++ b/docs/cli/trusted-folders.md @@ -38,6 +38,14 @@ folder, a dialog will automatically appear, prompting you to make a choice: Your choice is saved in a central file (`~/.gemini/trustedFolders.json`), so you will only be asked once per folder. +### Headless mode and automation + +When running in headless mode (using the `-p` or `--prompt` flag), the trust +dialog is bypassed automatically to ensure that non-interactive workflows and +automation scripts are not interrupted. In this mode, the CLI operates with +restricted permissions as if the folder were untrusted, unless the folder has +been previously trusted through an interactive session. + ## Understanding folder contents: The discovery phase Before you make a choice, the Gemini CLI performs a **discovery phase** to scan diff --git a/docs/cli/tutorials/automation.md b/docs/cli/tutorials/automation.md index 4285cdcf3b..127692b719 100644 --- a/docs/cli/tutorials/automation.md +++ b/docs/cli/tutorials/automation.md @@ -138,7 +138,7 @@ like `jq`. To get pure JSON data from the model, combine the fi # Extract data - gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json + gemini -p "Return a raw JSON object with keys 'version' and 'deps' from @package.json" --output-format json | jq -r '.response' > data.json ``` **Windows PowerShell (`generate_json.ps1`)** @@ -151,7 +151,7 @@ like `jq`. To get pure JSON data from the model, combine the } # Extract data (requires jq installed, or you can use ConvertFrom-Json) - $output = gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | ConvertFrom-Json + $output = gemini -p "Return a raw JSON object with keys 'version' and 'deps' from @package.json" --output-format json | ConvertFrom-Json $output.response | Out-File -FilePath data.json -Encoding utf8 ``` diff --git a/docs/core/a2a-server.md b/docs/core/a2a-server.md new file mode 100644 index 0000000000..10e23a8783 --- /dev/null +++ b/docs/core/a2a-server.md @@ -0,0 +1,93 @@ +# A2A Server + +The A2A Server is a core component of the Gemini CLI that implements the +Agent-to-Agent (A2A) protocol. It enables external clients, such as IDEs or +other AI agents, to interact with the Gemini CLI agent through a standardized, +streaming interface. + + +> [!NOTE] +> This is an experimental feature currently under active development. + +The A2A Server allows Gemini CLI to function as a backend service, providing +capabilities like code generation, tool execution, and workspace analysis to +client applications like Zed, VS Code, and Gemini Code Assist. + +## Overview + +The A2A Server implements the `development-tool` extension for the A2A protocol. +This extension defines a communication contract for rich, interactive workflows, +including: + +- **Task-based streaming:** Real-time updates on the agent's thoughts and tool + invocations. +- **Permission requests:** Standardized mechanism for the agent to request user + approval before executing potentially sensitive tools. +- **Tool lifecycle management:** A structured state machine for tracking tool + execution from creation to completion. +- **Slash command execution:** Programmatic access to built-in Gemini CLI + commands. + +## Usage + +The A2A Server can be started independently or as part of an integrated +workflow. + +### Starting the server + +In a development environment, you can launch the A2A Server from the project +root using npm: + +```bash +npm run start:a2a-server +``` + +This command builds the necessary dependencies and starts the server on its +default port. The server provides an SSE (Server-Sent Events) stream for +real-time updates to connected A2A clients. + +### Integration with IDEs + +Many IDE integrations use the A2A Server to power their "Agent Mode" features. +For example, the [VS Code companion](../ide-integration/index.md) communicates +with the A2A Server to execute complex coding tasks within your workspace. + +## Key features + +### Development tool extension + +The A2A Server uses a specialized set of schemas to enable rich client +interactions: + +- **Agent thoughts:** Streams the agent's internal reasoning as it works through + a task. +- **Tool calls:** Provides a detailed, stateless representation of tool + execution, including `PENDING`, `EXECUTING`, and `SUCCEEDED` statuses. +- **Confirmation requests:** Requests user permission for shell commands, file + edits, or MCP tool usage via the client UI. + +### Separation of concerns + +The A2A architecture enforces a strict separation of concerns: + +1. **A2A Protocol:** Standardizes the communication and task management between + the client and the Gemini CLI agent. +2. **MCP (Model Context Protocol):** Serves as the authoritative interface for + accessing client-side capabilities, such as reading active buffers or + accessing the local file system. + +## Troubleshooting + +If you encounter issues with the A2A Server: + +- **Check logs:** Review the server output for errors during initialization or + client connection. +- **Verify A2A compliance:** Ensure that the client application is correctly + implementing the A2A protocol and the `development-tool` extension. +- **Network permissions:** Ensure that the server has the necessary permissions + to listen on its configured port and communicate with MCP servers. + +## Next steps + +- Learn about [Remote subagents](./remote-agents.md) and A2A connectivity. +- Explore the [IDE integration guide](../ide-integration/index.md). diff --git a/docs/release-confidence.md b/docs/release-confidence.md index c46a702820..80f900b2f0 100644 --- a/docs/release-confidence.md +++ b/docs/release-confidence.md @@ -89,7 +89,7 @@ manually run through this checklist. - [ ] Vertex AI - **Basic prompting:** - - [ ] Run `gemini "Tell me a joke"` and verify a sensible response. + - [ ] Run `gemini -p "Tell me a joke"` and verify a sensible response. - [ ] Run in interactive mode: `gemini`. Ask a follow-up question to test context. diff --git a/docs/sidebar.json b/docs/sidebar.json index ea82a64481..c3f0616ec9 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -95,6 +95,11 @@ } ] }, + { + "label": "A2A Server", + "badge": "🔬", + "slug": "docs/core/a2a-server" + }, { "label": "Agent Skills", "slug": "docs/cli/skills" }, { "label": "Checkpointing", "slug": "docs/cli/checkpointing" }, { "label": "Headless mode", "slug": "docs/cli/headless" }, @@ -158,8 +163,18 @@ "items": [ { "label": "Custom commands", "slug": "docs/cli/custom-commands" }, { - "label": "Enterprise configuration", - "slug": "docs/cli/enterprise" + "label": "Enterprise administration", + "collapsed": true, + "items": [ + { + "label": "Enterprise configuration", + "slug": "docs/cli/enterprise" + }, + { + "label": "Enterprise Admin Controls", + "slug": "docs/admin/enterprise-controls" + } + ] }, { "label": "Ignore files (.geminiignore)", diff --git a/docs/tools/file-system.md b/docs/tools/file-system.md index a6beb1d76d..cd1bc58bb8 100644 --- a/docs/tools/file-system.md +++ b/docs/tools/file-system.md @@ -15,9 +15,13 @@ Lists the names of files and subdirectories directly within a specified path. - **Tool name:** `list_directory` - **Arguments:** - `dir_path` (string, required): Absolute or relative path to the directory. - - `ignore` (array, optional): Glob patterns to exclude. + - `ignore` (array, optional): Glob patterns to exclude (e.g., + `["*.tmp", "build/"]`). - `file_filtering_options` (object, optional): Configuration for `.gitignore` and `.geminiignore` compliance. + - `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore`. + - `respect_gemini_ignore` (boolean, optional): Whether to respect + `.geminiignore`. ### `read_file` (ReadFile) @@ -27,8 +31,22 @@ and PDF. - **Tool name:** `read_file` - **Arguments:** - `file_path` (string, required): Path to the file. - - `offset` (number, optional): Start line for text files (0-based). - - `limit` (number, optional): Maximum lines to read. + - `start_line` (number, optional): The 1-based line number to start reading + from. + - `end_line` (number, optional): The 1-based line number to end reading at + (inclusive). + +### `read_many_files` (ReadManyFiles) + +Reads and concatenates content from multiple files or entire directories. This +is the tool triggered by the `@` symbol in your prompt. + +- **Tool name:** `read_many_files` +- **Arguments:** + - `paths` (array of strings, required): List of paths to files or directories. + - `ignore` (array of strings, optional): Glob patterns to exclude. + - `file_filtering_options` (object, optional): Configuration for `.gitignore` + and `.geminiignore` compliance. ### `write_file` (WriteFile)