npm package: @ouvinte/a2a-bridge
Description: A2A Bridge - Connect OpenClaw to the Agent2Agent protocol with CLI tools
Author: BeardKoda
Latest version: 1.0.15

# 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)

```bash
npm install -g @ouvinte/a2a-bridge
```

### Via Git Clone

```bash
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)

```bash
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

```bash
# 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 admin@example.com \
  --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

```bash
# 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

```bash
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:

```bash
--agent-id <agentId>
```

## Configuration

### View Config

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

### Set Values

```bash
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

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

## Logging

### View Logs

```bash
# 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

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

### Remote Test

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

### Manual Test with curl

```bash
# 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:

```bash
# 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

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

### Edit Skills

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

## Architecture

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

## Uninstallation

```bash
# 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