A2A Protocol Documentation

Appearance

BeeAI Framework A2A Service Implementation Guide ​

Overview ​

This document demonstrates how to implement Agent2Agent (A2A) communication using the BeeAI framework, including complete implementations of both server-side (Agent) and client-side (Host). This example showcases an intelligent chat agent with web search and weather query capabilities.

Architecture Overview ​

Project Structure ​

samples/python/
├── agents/beeai-chat/          # A2A Server (Agent)
│   ├── __main__.py            # Server main program
│   ├── pyproject.toml         # Dependency configuration
│   ├── Dockerfile             # Containerization config
│   └── README.md              # Server documentation
└── hosts/beeai-chat/           # A2A Client (Host)
    ├── __main__.py            # Client main program
    ├── console_reader.py      # Console interaction interface
    ├── pyproject.toml         # Dependency configuration
    ├── Dockerfile             # Containerization config
    └── README.md              # Client documentation

Environment Setup ​

System Requirements ​

  • Python 3.11 or higher
  • uv package manager
  • Ollama local LLM service

Install uv ​

bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or use pip
pip install uv

Install Ollama and Model ​

bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull required model
ollama pull granite3.3:8b

A2A Server Implementation (Agent) ​

Core Implementation Analysis ​

The server uses BeeAI framework's RequirementAgent and A2AServer to provide intelligent agent services:

python
def main() -> None:
    # Configure LLM model
    llm = ChatModel.from_name(os.environ.get("BEEAI_MODEL", "ollama:granite3.3:8b"))
    
    # Create agent with tool configuration
    agent = RequirementAgent(
        llm=llm,
        tools=[ThinkTool(), DuckDuckGoSearchTool(), OpenMeteoTool(), WikipediaTool()],
        memory=UnconstrainedMemory(),
    )

    # Start A2A server
    A2AServer(
        config=A2AServerConfig(port=int(os.environ.get("A2A_PORT", 9999))), 
        memory_manager=LRUMemoryManager(maxsize=100)
    ).register(agent).serve()

Key Features ​

  • Tool Integration: Supports thinking, web search, weather queries, Wikipedia queries
  • Memory Management: Uses LRU cache to manage session state
  • Environment Configuration: Supports model and port configuration via environment variables

Running Server with uv ​

bash
git clone https://github.com/a2aproject/a2a-samples.git
# Enter server directory
cd samples/python/agents/beeai-chat

# Create virtual environment and install dependencies with uv
uv venv
source .venv/bin/activate  # Linux/macOS
uv pip install -e .

# Important note
uv add "a2a-sdk[http-server]"

# Start server
uv run python __main__.py

Environment Variable Configuration ​

bash
export BEEAI_MODEL="ollama:granite3.3:8b"  # LLM model
export A2A_PORT="9999"                     # Server port
export OLLAMA_API_BASE="http://localhost:11434"  # Ollama API address

A2A Client Implementation (Host) ​

Core Implementation Analysis ​

The client uses A2AAgent to communicate with the server, providing an interactive console interface:

python
async def main() -> None:
    reader = ConsoleReader()
    
    # Create A2A client
    agent = A2AAgent(
        url=os.environ.get("BEEAI_AGENT_URL", "http://127.0.0.1:9999"), 
        memory=UnconstrainedMemory()
    )
    
    # User input processing loop
    for prompt in reader:
        response = await agent.run(prompt).on(
            "update",
            lambda data, _: (reader.write("Agent 🤖 (debug) : ", data)),
        )
        reader.write("Agent 🤖 : ", response.result.text)

Interactive Interface Features ​

  • Real-time Debugging: Shows debug information during agent processing
  • Graceful Exit: Input 'q' to exit program
  • Error Handling: Handles empty input and network exceptions

Running Client with uv ​

bash
# Enter client directory
cd samples/python/hosts/beeai-chat

# Create virtual environment and install dependencies with uv
uv venv
source .venv/bin/activate  # Linux/macOS
uv pip install -e .

# Start client
uv run python __main__.py

Environment Variable Configuration ​

bash
export BEEAI_AGENT_URL="http://127.0.0.1:9999"  # Server address

Complete Execution Flow ​

1. Start Server ​

bash
# Terminal 1: Start A2A server
cd samples/python/agents/beeai-chat
uv venv && source .venv/bin/activate
uv pip install -e .
uv add "a2a-sdk[http-server]"
uv run python __main__.py
# Output
INFO:     Started server process [73108]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:9999 (Press CTRL+C to quit)

2. Start Client ​

bash
# Terminal 2: Start A2A client
cd samples/python/hosts/beeai-chat
uv venv && source .venv/bin/activate
uv pip install -e .
uv run python __main__.py
# Output
Interactive session has started. To escape, input 'q' and submit.
User 👤 : what is the weather of new york today
Agent 🤖 (debug) :  value={'id': 'cb4059ebd3a44a2f8b428d83bbff8cac', 'jsonrpc': '2.0', 'result': {'contextId': 'b8a8d863-4c7d-48b7-9bdd-2848abccaae3', 'final': False, 'kind': 'status-update', 'status': {'state': 'submitted', 'timestamp': '2025-09-02T07:52:09.588387+00:00'}, 'taskId': '6e0fce64-51f0-4ad3-b0d5-c503b41bf63a'}}
Agent 🤖 (debug) :  value={'id': 'cb4059ebd3a44a2f8b428d83bbff8cac', 'jsonrpc': '2.0', 'result': {'contextId': 'b8a8d863-4c7d-48b7-9bdd-2848abccaae3', 'final': False, 'kind': 'status-update', 'status': {'state': 'working', 'timestamp': '2025-09-02T07:52:09.588564+00:00'}, 'taskId': '6e0fce64-51f0-4ad3-b0d5-c503b41bf63a'}}
Agent 🤖 (debug) :  value={'id': 'cb4059ebd3a44a2f8b428d83bbff8cac', 'jsonrpc': '2.0', 'result': {'contextId': 'b8a8d863-4c7d-48b7-9bdd-2848abccaae3', 'final': True, 'kind': 'status-update', 'status': {'message': {'contextId': 'b8a8d863-4c7d-48b7-9bdd-2848abccaae3', 'kind': 'message', 'messageId': '8dca470e-1665-41af-b0cf-6b47a1488f89', 'parts': [{'kind': 'text', 'text': 'The current weather in New York today is partly cloudy with a temperature of 16.2°C, 82% humidity, and a wind speed of 7 km/h.'}], 'role': 'agent', 'taskId': '6e0fce64-51f0-4ad3-b0d5-c503b41bf63a'}, 'state': 'completed', 'timestamp': '2025-09-02T07:52:39.928963+00:00'}, 'taskId': '6e0fce64-51f0-4ad3-b0d5-c503b41bf63a'}}
Agent 🤖 :  The current weather in New York today is partly cloudy with a temperature of 16.2°C, 82% humidity, and a wind speed of 7 km/h.
User 👤 :

3. Interaction Example ​

Interactive session has started. To escape, input 'q' and submit.
User 👤 : What's the weather like in Beijing today?
Agent 🤖 (debug) : Querying Beijing weather information...
Agent 🤖 : According to the latest weather data, Beijing is cloudy today with temperatures of 15-22°C, 65% humidity, and wind speed of 3m/s.

User 👤 : Search for the latest developments in artificial intelligence
Agent 🤖 (debug) : Searching for AI-related information...
Agent 🤖 : Based on search results, recent major developments in AI include...

User 👤 : q

Technical Points ​

Dependency Management ​

Both projects use pyproject.toml to manage dependencies:

Server Dependencies:

toml
dependencies = [
    "beeai-framework[a2a,search] (>=0.1.36,<0.2.0)"
]

Client Dependencies:

toml
dependencies = [
    "beeai-framework[a2a] (>=0.1.36,<0.2.0)",
    "pydantic (>=2.10,<3.0.0)",
]

Memory Management ​

  • Server uses LRUMemoryManager to limit session count
  • Both client and server use UnconstrainedMemory to maintain conversation history

Tool Integration ​

The server integrates multiple tools:

  • ThinkTool: Internal thinking and reasoning
  • DuckDuckGoSearchTool: Web search
  • OpenMeteoTool: Weather queries
  • WikipediaTool: Wikipedia queries

Extension and Customization ​

Adding New Tools ​

python
from beeai_framework.tools.custom import CustomTool

agent = RequirementAgent(
    llm=llm,
    tools=[
        ThinkTool(), 
        DuckDuckGoSearchTool(), 
        OpenMeteoTool(), 
        WikipediaTool(),
        CustomTool()  # Add custom tool
    ],
    memory=UnconstrainedMemory(),
)

Custom Client Interface ​

You can replace ConsoleReader to implement GUI or Web interface:

python
class WebInterface:
    async def get_user_input(self):
        # Implement web interface input
        pass
    
    async def display_response(self, response):
        # Implement web interface output
        pass

Summary ​

This implementation guide demonstrates how to build a complete A2A communication system using the BeeAI framework and uv package manager. Through the server's intelligent agent and client's interactive interface, we've implemented a feature-rich chatbot system. This architecture has good scalability and can easily add new tools and features.

More A2A Protocol Examples ​

A2A Protocol Documentation

Copyright © 2025 a2aprotocol.ai