mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-05-18 07:43:00 -07:00
Jenna Inouye
94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
<!-- prettier-ignore -->
|
|
> [!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).
|