DEV Community

Cover image for BeeAI Framework A2A Service Implementation Guide
cz
cz

Posted on

BeeAI Framework A2A Service Implementation Guide

#beeai #a2a #agents

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 

sequenceDiagram
    participant User as User
    participant Client as BeeAI Chat Client
    participant Server as BeeAI Chat Agent
    participant LLM as Ollama (granite3.3:8b)
    participant Tools as Tool Collection

    User->>Client: Input chat message
    Client->>Server: HTTP request (A2A Protocol)
    Server->>LLM: Process user request
    LLM->>Tools: Call tools (search/weather etc.)
    Tools-->>LLM: Return tool results
    LLM-->>Server: Generate response
    Server-->>Client: Return A2A response
    Client-->>User: Display chat results
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Environment Setup

System Requirements

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

Install uv 

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

# Or use pip
pip install uv
Enter fullscreen mode Exit fullscreen mode

Install Ollama and Model 

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

# Pull required model
ollama pull granite3.3:8b
Enter fullscreen mode Exit fullscreen mode

A2A Server Implementation (Agent)

Core Implementation Analysis

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

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()
Enter fullscreen mode Exit fullscreen mode

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 

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
Enter fullscreen mode Exit fullscreen mode

Environment Variable Configuration 

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
Enter fullscreen mode Exit fullscreen mode

A2A Client Implementation (Host)

Core Implementation Analysis

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

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)
Enter fullscreen mode Exit fullscreen mode

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 

# 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
Enter fullscreen mode Exit fullscreen mode

Environment Variable Configuration 

export BEEAI_AGENT_URL="http://127.0.0.1:9999"  # Server address
Enter fullscreen mode Exit fullscreen mode

Complete Execution Flow

1. Start Server 

# 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)
Enter fullscreen mode Exit fullscreen mode

2. Start Client 

# 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 👤 :
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Technical Points

Dependency Management

Both projects use pyproject.toml to manage dependencies:

Server Dependencies:

dependencies = [
    "beeai-framework[a2a,search] (>=0.1.36,<0.2.0)"
]
Enter fullscreen mode Exit fullscreen mode

Client Dependencies:

dependencies = [
    "beeai-framework[a2a] (>=0.1.36,<0.2.0)",
    "pydantic (>=2.10,<3.0.0)",
]
Enter fullscreen mode Exit fullscreen mode

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 

from beeai_framework.tools.custom import CustomTool

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

Custom Client Interface

You can replace ConsoleReader to implement GUI or Web interface:

class WebInterface:
    async def get_user_input(self):
        # Implement web interface input
        pass

    async def display_response(self, response):
        # Implement web interface output
        pass
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)