Google A2A Agent Example

This repository implements a simple Agent-to-Agent (A2A) communication example based on Google's A2A protocol. A2A is Google's proposed standard for enabling AI agents to communicate with each other through a standardized API.

Overview

The implementation consists of two main components:

1. Server (server.py): A Flask-based server acting as an AI agent. It implements the core A2A protocol endpoints:

   • /.well-known/agent.json: Provides the agent's metadata (Agent Card), describing its capabilities and URL.
   • /tasks/send: Accepts tasks from other agents (or clients like client.py), processes them using an AI model (OpenAI's GPT-4o-mini) and external tools (Brave Search via MCP), and returns the result.

2. Client (client.py): A simple Python script demonstrating how to interact with the A2A server:

   • Discovers the agent by fetching its Agent Card.
   • Sends a task (a user query) to the agent's /tasks/send endpoint.
   • Receives and prints the agent's response.

Architecture

The interaction flow can be visualized as follows:

sequenceDiagram
    participant C as Client (client.py)
    participant S as A2A Server (server.py)
    participant MCP as Brave MCP Server
    participant OAI as OpenAI API

    C->>S: GET /.well-known/agent.json (Discover Agent)
    S-->>C: Agent Card JSON
    C->>S: POST /tasks/send (Task Request with User Query)
    S->>OAI: Process Query (Initial processing)
    Note right of S: Agent decides to use Brave Search
    S->>MCP: Search Request
    MCP-->>S: Search Results
    S->>OAI: Process Query + Search Results
    OAI-->>S: Final Response Text
    S-->>C: Task Response (with Agent's Final Message)

• The Client initiates communication by discovering the A2A Server.
• The Client sends a task (e.g., "What is Google A2A?") to the Server.
• The Server uses the pydantic-ai library, which coordinates with:
  • The OpenAI API to understand the request and generate responses.
  • A Brave Search MCP Server (managed via MCPServerStdio) when web search is needed. MCP (Model Context Protocol) standardizes how AI models interact with external tools/data sources.
• The Server sends the final response back to the Client.

Setup

1. Clone the repository:

   git clone <repository_url>
   cd <repository_directory>
   

2. Create and activate a virtual environment:

   • Windows:

     python -m venv venv
     .\venv\Scripts\activate
     

   • macOS/Linux:

     python3 -m venv venv
     source venv/bin/activate
     

3. Create a .env file: Create a file named .env in the root directory and add your API keys:

   OPENAI_API_KEY=your_openai_api_key
   BRAVE_API_KEY=your_brave_api_key
   

   (Replace your_openai_api_key and your_brave_api_key with your actual keys)

4. Install dependencies:

   pip install -r requirements.txt
   

5. Run the server: Open a terminal, activate the virtual environment, and run:

   python server.py
   

   The server will start, typically on http://localhost:5000.

6. Run the client: Open a separate terminal, activate the virtual environment, and run:

   python client.py
   

   The client will discover the server, send a predefined question, and print the agent's response.

A2A Protocol Details

Google's A2A protocol defines a standard way for agents to communicate via HTTP. Key concepts include:

• Agent Card (/.well-known/agent.json): A standard JSON document describing an agent's identity, capabilities (e.g., streaming support), and API endpoints.
• Task API (/tasks/send, /tasks/receive, etc.): Endpoints for exchanging tasks and messages. This example only implements the essential /tasks/send.
• Standardized Message Format: A consistent JSON structure for messages exchanged between agents, typically including roles (user, agent) and content parts.

For more in-depth information, refer to the official Google A2A protocol documentation (link if available).