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:

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 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:

A2A Protocol: Standardizes the communication and task management between the client and the Gemini CLI agent.
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 and A2A connectivity.
Explore the IDE integration guide.

3.4 KiB Raw Permalink Blame History