Version: 1.0.5

Building Multi-Agent Systems with A2A Inbound Adapter

What We're Building

In this hands-on guide, we'll build a multi-agent system that exposes specialized Agentverse uAgents through the A2A protocol. By the end, you'll have:

Note: Use a unique agent name and description when starting your adapters/bridges. Uniqueness helps derive a unique agent address and avoids collisions with other agents.

Multiple A2A endpoints running on different ports
Specialized agents accessible to A2A clients
Real-world examples of agent coordination and discovery
Production-ready configuration for deployment

We'll create two specialized agents:

Perplexity Search Agent - AI-powered web search and research
Finance Q&A Agent - Financial analysis and planning assistance

Architecture

Each agent will run as a separate A2A server, allowing A2A clients to discover and use them independently or in coordination.

🛠️ Step 1: Installation

Install the A2A Inbound adapter package:

pip install "uagents-adapter[a2a-inbound]==0.6.2"

This installs all required dependencies including:

a2a-sdk[all,sqlite]>=0.2.11 - A2A SDK with all features + SQLite support
uvicorn>=0.27.0 - ASGI server for running the A2A bridge server
httpx>=0.25.0 - Async HTTP client
click>=8.0.0 - CLI framework for command-line interface
python-dotenv>=1.0.0 - Environment variable management

Step 2: Choose Your Agents

You have two options for agents:

Option A: Use Existing Agents from Agentverse Marketplace

Visit Agentverse.ai
Browse the marketplace for agents that match your needs
Copy the agent address from the agent's profile page
Ensure the agent is active and responding to messages

Option B: Build Your Own Agents

Create uAgents using the uAgents framework
Register on Agentverse and get them running
Copy the agent addresses from your agent profiles
Test that they respond to chat messages

For this tutorial, we'll use pre-configured agents from the marketplace:

Perplexity Search Agent: agent1qgzd0c60d4c5n37m4pzuclv5p9vwsftmfkznksec3drux8qnhmvuymsmshp
Finance Q&A Agent: agent1qdv2qgxucvqatam6nv28qp202f3pw8xqpfm8man6zyegztuzd2t6yem9evl

Step 3: Build the Multi-Agent System

Agent 1: Perplexity Search Agent

Create a file called perplexity_adapter.py:

import os
import sys
import time
from uagents_adapter.a2a_inbound.adapter import A2ARegisterTool

def main():
    """Start A2A bridge for Perplexity Search Agent."""
    
    # Set bridge seed for consistent agent identity (required in production)
    os.environ["UAGENTS_BRIDGE_SEED"] = "perplexity_bridge_seed_2024"
    
    # Configure the bridge
    config = {
        "agent_address": "agent1qgzd0c60d4c5n37m4pzuclv5p9vwsftmfkznksec3drux8qnhmvuymsmshp",
        "name": "Perplexity Search Agent",
        "description": "AI-powered web search and research assistant with real-time information access",
        "skill_tags": ["search", "research", "web", "ai", "information", "news"],
        "skill_examples": ["Search for latest AI news", "Research quantum computing trends", "Find information about climate change"],
        "port": 9002,
        "bridge_port": 8002,
        "host": "localhost"
    }
    
    # Start the A2A bridge
    adapter = A2ARegisterTool()
    
    try:
        result = adapter.invoke(config)
        
        if result.get("success"):
            # Keep the server running
            while True:
                time.sleep(1)
        else:
            print(f"❌ Failed to start bridge: {result}")
            return 1
            
    except KeyboardInterrupt:
        print("\n👋 Shutting down Perplexity bridge...")
        return 0
    except Exception as e:
        print(f"❌ Error: {e}")
        return 1

if __name__ == "__main__":
    sys.exit(main())

Agent 2: Finance Q&A Agent

Create a file called finance_adapter.py:

import os
import sys
import time
from uagents_adapter.a2a_inbound.adapter import A2ARegisterTool

def main():
    """Start A2A bridge for Finance Q&A Agent."""
    
    # Set bridge seed for consistent agent identity (required in production)
    os.environ["UAGENTS_BRIDGE_SEED"] = "finance_bridge_seed_2024"
    
    # Configure the bridge
    config = {
        "agent_address": "agent1qdv2qgxucvqatam6nv28qp202f3pw8xqpfm8man6zyegztuzd2t6yem9evl",
        "name": "Finance Q&A Agent",
        "description": "AI-powered financial advisor and Q&A assistant for investment, budgeting, and financial planning guidance",
        "skill_tags": ["finance", "investment", "budgeting", "financial_planning", "assistance"],
        "skill_examples": ["Analyze AAPL stock performance", "Compare crypto portfolios", "Budget planning advice"],
        "port": 9003,
        "bridge_port": 8003,
        "host": "localhost"
    }
    
    # Start the A2A bridge
    adapter = A2ARegisterTool()
    
    try:
        result = adapter.invoke(config)
        
        if result.get("success"):
            # Keep the server running
            while True:
                time.sleep(1)
        else:
            print(f"❌ Failed to start bridge: {result}")
            return 1
            
    except KeyboardInterrupt:
        print("\n👋 Shutting down Finance bridge...")
        return 0
    except Exception as e:
        print(f"❌ Error: {e}")
        return 1

if __name__ == "__main__":
    sys.exit(main())

Step 4: Run Your Multi-Agent System

Terminal 1: Start Perplexity Agent

python perplexity_adapter.py

Expected output:

INFO:root:🔗 Using provided bridge port: 8002
INFO:uagents_adapter.a2a_inbound.agentverse_executor:🔐 Using user-provided bridge seed from environment
INFO:     [a2a_agentverse_bridge]: Starting agent with address: agent1qvdrt7kqg2k67czm8wzs724jv63fsq5cr2lq4mymtptj576sdpu9yngzden
INFO:uagents_adapter.a2a_inbound.agentverse_executor:A2A Bridge agent started with address: agent1qvdrt7kqg2k67czm8wzs724jv63fsq5cr2lq4mymtptj576sdpu9yngzden
INFO:uagents_adapter.a2a_inbound.agentverse_executor:Target Agentverse agent: agent1qgzd0c60d4c5n37m4pzuclv5p9vwsftmfkznksec3drux8qnhmvuymsmshp
INFO:     [a2a_agentverse_bridge]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8002&address=agent1qvdrt7kqg2k67czm8wzs724jv63fsq5cr2lq4mymtptj576sdpu9yngzden
INFO:     [a2a_agentverse_bridge]: Starting server on http://0.0.0.0:8002 (Press CTRL+C to quit)
INFO:     [a2a_agentverse_bridge]: Starting mailbox client for https://agentverse.ai
INFO:     [a2a_agentverse_bridge]: Mailbox access token acquired
INFO:     [uagents.registration]: Registration on Almanac API successful
INFO:uagents_adapter.a2a_inbound.agentverse_executor:✅ A2A Bridge to Agentverse started successfully
INFO:root:🚀 A2A server starting on localhost:9002
INFO:root:🔗 Bridging to Agentverse agent: agent1qgzd0c60d4c5n37m4pzuclv5p9vwsftmfkznksec3drux8qnhmvuymsmshp
INFO:root:📋 Agent name: Perplexity Search Agent
INFO:root:🏷️  Tags: search, research, web, ai, information, news
INFO:     Started server process [14746]

Terminal 2: Start Finance Agent

python finance_adapter.py

Expected output:

INFO:root:🔗 Using provided bridge port: 8003
INFO:uagents_adapter.a2a_inbound.agentverse_executor:🔐 Using user-provided bridge seed from environment
INFO:     [a2a_agentverse_bridge]: Starting agent with address: agent1qvdrt7kqg2k67czm8wzs724jv63fsq5cr2lq4mymtptj576sdpu9yngzden
INFO:uagents_adapter.a2a_inbound.agentverse_executor:A2A Bridge agent started with address: agent1qvdrt7kqg2k67czm8wzs724jv63fsq5cr2lq4mymtptj576sdpu9yngzden
INFO:uagents_adapter.a2a_inbound.agentverse_executor:Target Agentverse agent: agent1qdv2qgxucvqatam6nv28qp202f3pw8xqpfm8man6zyegztuzd2t6yem9evl
INFO:     [a2a_agentverse_bridge]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8003&address=agent1qvdrt7kqg2k67czm8wzs724jv63fsq5cr2lq4mymtptj576sdpu9yngzden
INFO:     [a2a_agentverse_bridge]: Starting server on http://0.0.0.0:8003 (Press CTRL+C to quit)
INFO:     [a2a_agentverse_bridge]: Starting mailbox client for https://agentverse.ai
INFO:     [a2a_agentverse_bridge]: Mailbox access token acquired
INFO:     [uagents.registration]: Registration on Almanac API successful
INFO:uagents_adapter.a2a_inbound.agentverse_executor:✅ A2A Bridge to Agentverse started successfully
INFO:root:🚀 A2A server starting on localhost:9003
INFO:root:🔗 Bridging to Agentverse agent: agent1qdv2qgxucvqatam6nv28qp202f3pw8xqpfm8man6zyegztuzd2t6yem9evl
INFO:root:📋 Agent name: Finance Q&A Agent
INFO:root:🏷️  Tags: finance, investment, budgeting, financial_planning, assistance
INFO:     Started server process [14747]

Step 5: Test Your Multi-Agent System

Test Perplexity Search Agent

curl -X POST http://localhost:9002/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the latest developments in quantum computing?",
    "session_id": "test_session_1"
  }'

Test Finance Q&A Agent

curl -X POST http://localhost:9003/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What should I consider when investing in tech stocks?",
    "session_id": "test_session_2"
  }'

Step 6: Discover Agents via A2A Protocol

Your agents are now discoverable via the A2A protocol. You can:

View agent manifests at:
- http://localhost:9002/.well-known/agent.json
- http://localhost:9003/.well-known/agent.json
Use A2A clients to discover and interact with your agents
Integrate with other A2A-compatible systems

Production Considerations

Environment Variables

For production deployment, set these environment variables:

export UAGENTS_BRIDGE_SEED="your_secure_seed_here"
export AGENTVERSE_API_KEY="your_agentverse_api_key"
export UAGENTS_MAILBOX_KEY="your_mailbox_key"

Security

Use strong, unique seeds for each bridge agent
Secure your API keys and never commit them to version control
Implement proper authentication for production deployments
Monitor agent health and implement logging

Scaling

Load balancing: Use a reverse proxy to distribute traffic
Health checks: Implement monitoring for agent availability
Auto-scaling: Use container orchestration for dynamic scaling
Caching: Implement response caching for frequently asked questions

Troubleshooting

Common Issues

Port conflicts: Ensure ports 9002, 9003, 8002, and 8003 are available
Agent not responding: Verify the Agentverse agent is active and responding
Bridge seed issues: Use consistent seeds across restarts
Network connectivity: Ensure firewall allows connections to required ports

Debug Mode

Enable debug logging by setting the log level:

import logging
logging.basicConfig(level=logging.DEBUG)

Next Steps

Now that you have a working multi-agent system, you can:

Add more agents by creating additional adapter scripts
Implement custom routing logic for intelligent agent selection
Build A2A clients to interact with your agents
Deploy to production with proper monitoring and scaling
Integrate with other A2A-compatible platforms

Resources

Happy building! 🚀

What We're Building​

Architecture​

🛠️ Step 1: Installation​

Step 2: Choose Your Agents​

Option A: Use Existing Agents from Agentverse Marketplace​

Option B: Build Your Own Agents​

Step 3: Build the Multi-Agent System​

Agent 1: Perplexity Search Agent​

Agent 2: Finance Q&A Agent​

Step 4: Run Your Multi-Agent System​

Terminal 1: Start Perplexity Agent​

Terminal 2: Start Finance Agent​

Step 5: Test Your Multi-Agent System​

Test Perplexity Search Agent​

Test Finance Q&A Agent​

Step 6: Discover Agents via A2A Protocol​

Production Considerations​

Environment Variables​

Security​

Scaling​

Troubleshooting​

Common Issues​

Debug Mode​

Next Steps​

Resources​