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:

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

1. Perplexity Search Agent - AI-powered web search and research
2. 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]"

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

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

Option B: Build Your Own Agents

1. Create uAgents using the uAgents framework
2. Register on Agentverse and get them running
3. Copy the agent addresses from your agent profiles
4. 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:

1. View agent manifests at:

   • http://localhost:9002/.well-known/agent.json
   • http://localhost:9003/.well-known/agent.json

2. Use A2A clients to discover and interact with your agents

3. 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

1. Port conflicts: Ensure ports 9002, 9003, 8002, and 8003 are available
2. Agent not responding: Verify the Agentverse agent is active and responding
3. Bridge seed issues: Use consistent seeds across restarts
4. 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:

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

Resources

• A2A Protocol Documentation
• uAgents Framework
• Agentverse Platform
• A2A SDK Documentation

Happy building! 🚀