A2A Bridge

Connect OpenClaw to the Agent2Agent (A2A) protocol with per-agent bridge management

A2A Bridge is a Linux-first CLI package that runs one or more A2A bridge agents on a single server, each with its own config, server file, PM2 process, and port.

Installation

Via npm (global)

npm install -g @ouvinte/a2a-bridge

Via Git Clone

git clone https://github.com/OuvinteInc/a2a-bridge-setup.git
cd a2a-bridge-setup
npm install
npm link  # Creates global 'a2a-bridge' command

Debian/Ubuntu Package (Coming Soon)

wget https://github.com/OuvinteInc/a2a-bridge-setup/releases/latest/download/a2a-bridge.deb
dpkg -i a2a-bridge.deb

Quick Start

1. Setup an Agent Bridge

# Interactive setup wizard
sudo a2a-bridge setup \
  --agent-id agent-1 \
  --agent-name "Agent One"

# Or with flags
sudo a2a-bridge setup \
  --agent-id agent-1 \
  --agent-name "Agent One" \
  --server-path ~/.a2a-bridges/agent-1/server.js \
  --domain agent.example.com \
  --email [email protected] \
  --port 4120

Notes:

• If --server-path is missing and ~/.a2a-bridges/<agentId>/server.js does not exist, setup seeds a bootstrap server file.
• install still works as a deprecated alias of setup.

2. Start the Server

# Start agent bridge with PM2
a2a-bridge start --agent-id agent-1

# Or run in foreground for debugging
a2a-bridge start --agent-id agent-1 --foreground

3. Check Status

a2a-bridge status --agent-id agent-1

CLI Commands

| Command | Description | |---------|-------------| | setup | Run setup wizard for an agent | | install | Deprecated alias for setup | | start | Start an agent bridge | | stop | Stop an agent bridge | | restart | Restart an agent bridge | | status | Check an agent bridge status | | logs | View agent bridge logs | | config | Manage per-agent configuration | | agent-card | View/edit agent card | | test | Test connectivity | | service | Manage PM2 persistence/reload | | uninstall | Remove from system |

Most commands support:

--agent-id <agentId>

Configuration

View Config

a2a-bridge config --agent-id agent-1 --list

Set Values

a2a-bridge config --agent-id agent-1 --set domain=agent.example.com
a2a-bridge config --agent-id agent-1 --set port=8080
# Optional: phone for notifications
a2a-bridge config --agent-id agent-1 --set userPhone=+1234567890

Config File Location

~/.a2a-bridges/<agentId>/config.json

Logging

View Logs

# Last 50 lines
a2a-bridge logs --agent-id agent-1

# Follow real-time
a2a-bridge logs --agent-id agent-1 --follow

# Last 100 lines
a2a-bridge logs --agent-id agent-1 -n 100

Log Location

/var/log/a2a-bridge/<agentId>/a2a-bridge-<agentId>.log

Testing

Local Test

a2a-bridge test --agent-id agent-1 --local

Remote Test

a2a-bridge test --agent-id agent-1 --remote

Manual Test with curl

# Check agent card
curl https://agent.example.com/.well-known/agent.json

# Health check
curl https://agent.example.com/health

PM2 Integration

The setup automatically manages each agent with PM2:

# Persist PM2 process list for auto-start
a2a-bridge service --agent-id agent-1 enable

# Remove process from PM2 startup list
a2a-bridge service --agent-id agent-1 disable

# Restart process after config changes
a2a-bridge service --agent-id agent-1 reload

# Inspect PM2 processes directly
pm2 ls

Agent Card

Your agent's capabilities are advertised at:

https://yourdomain.com/.well-known/agent.json

View Current Card

a2a-bridge agent-card --agent-id agent-1 --show

Edit Skills

a2a-bridge agent-card --agent-id agent-1 --edit

Architecture

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Other Agent   │──────▶│  Nginx (443)    │──────▶│  A2A Bridge     │
│                 │◀──────│  SSL/Reverse    │◀──────│  (Port 4120)    │
└─────────────────┘      │  Proxy          │      └─────────────────┘
                         └─────────────────┘              │
                                                          ▼
                                                   ┌──────────────┐
                                                   │ OpenClaw     │
                                                   └──────────────┘

Uninstallation

# Keep config and logs
a2a-bridge uninstall --agent-id agent-1

# Remove everything
a2a-bridge uninstall --agent-id agent-1 --purge

Environment Variables

| Variable | Description | |----------|-------------| | A2A_BRIDGE_AGENT_ID | Agent identifier override | | A2A_BRIDGE_CONFIG | Config directory override | | CONFIG_PATH | Config file path override | | PORT | Port override for runtime | | NODE_ENV | Environment (production/development) | | DEBUG | Enable debug logging |

Requirements

• Node.js 18+
• Linux
• pm2, sqlite3, nginx (installed by setup when possible)
• Domain name pointed to server

License

MIT © Ouvinte Inc