Content
# Babel
Multi-protocol communication server that routes and translates messages between AI agents using different communication protocols: ACP, MCP, A2A, and Coral.
## What It Does
The Protocol Bridge is a **router and translator**, not an agent. It:
- Routes messages between agents using different protocols
- Translates protocol-specific formats to a common internal format
- Manages agent discovery and capability matching
- Handles authentication and trust management across protocols
The bridge **does not**:
- Create or simulate agents
- Generate responses on behalf of agents
## Quick Start
### Installation
**Prerequisites:**
- Python 3.11 or higher
- pip package manager
**1. Install dependencies:**
```bash
pip install fastapi uvicorn pydantic pyjwt jsonschema httpx aiohttp sse-starlette websockets redis pytest pytest-asyncio python-multipart requests
```
Or use the requirements file:
```bash
pip install -r requirements-list.txt
```
**2. Configure environment (optional):**
```bash
cp .env.example .env
```
Edit `.env` to add your secrets if using authentication.
**3. Run the server:**
```bash
python main.py
```
Server starts on `http://0.0.0.0:5000`
### Verify It's Running
```bash
curl http://localhost:5000/health
```
Expected response:
```json
{"status":"healthy","service":"Babel"}
```
## Registering Agents
The bridge starts with **zero agents**. You must register agents before they can communicate.
### Option 1: Web UI (Recommended)
<img width="603" height="351" alt="image" src="https://github.com/user-attachments/assets/cf39fe71-c6e0-448a-84bc-962b11c87534" />
1. Open your browser to `http://localhost:5000/ui/`
2. Fill out the registration form:
- **Agent ID**: Format `protocol://name@domain` (e.g., `acp://myagent@localhost`)
- **Protocol**: Select ACP, MCP, A2A, or Coral
- **Endpoint URL**: Where your agent service is running (e.g., `http://localhost:8001/acp`)
- **API Key**: Optional authentication key for your agent
- **Capabilities**: One per line, format `name:Description`
3. Click "Register Agent"
The agent will appear in the list below the form.
### Option 2: API Endpoint
```bash
curl -X POST http://localhost:5000/agents/register \
-H "Content-Type: application/json" \
-d '{
"agent_id": "acp://myagent@localhost",
"protocol": "ACP",
"endpoint": "http://localhost:8001/acp",
"api_key": "optional-key",
"capabilities": [
{"name": "chat", "description": "Chat capability"},
{"name": "search", "description": "Search capability"}
]
}'
```
### View Registered Agents
**Web UI:** Go to `http://localhost:5000/ui/`
**API:**
```bash
curl http://localhost:5000/agents
```
### Remove an Agent
**Web UI:** Click the "Remove" button next to the agent
**API:**
```bash
curl -X DELETE http://localhost:5000/agents/acp://myagent@localhost
```
## API Endpoints
### Core Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Redirects to web UI |
| GET | `/health` | Health check |
| GET | `/agents` | List all registered agents |
| GET | `/agents/{agent_name}` | Get specific agent details |
| POST | `/agents/register` | Register a new agent |
| DELETE | `/agents/{agent_id}` | Unregister an agent |
| GET | `/metrics` | System metrics and statistics |
| GET | `/registry/agents` | Alternative agent listing endpoint |
### ACP (Agent Communication Protocol)
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/runs` | Create a new ACP run |
| GET | `/runs/{run_id}` | Get run status |
| GET | `/runs/{run_id}/await` | Await run completion (suspend/resume) |
| DELETE | `/runs/{run_id}` | Cancel a run (DELETE method) |
| POST | `/runs/{run_id}/cancel` | Cancel a run (POST method) |
| GET | `/sessions` | List ACP sessions |
| POST | `/sessions` | Create ACP session |
| GET | `/sessions/{session_id}` | Get session details |
| DELETE | `/sessions/{session_id}` | Delete session |
**Example - Create Run:**
```bash
curl -X POST http://localhost:5000/runs \
-H "Content-Type: application/json" \
-d '{
"agent_name": "acp://myagent@localhost",
"message": {
"role": "user",
"parts": [{"type": "text", "text": "Hello"}]
}
}'
```
**Example - Get Run Status:**
```bash
curl http://localhost:5000/runs/{run_id}
```
### MCP (Model Context Protocol)
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/mcp/jsonrpc` | JSON-RPC 2.0 endpoint |
| POST | `/mcp/jsonrpc-direct` | Direct JSON-RPC endpoint |
**Supported JSON-RPC methods:**
- `ping` - Health check
- `tools/list` - List available tools
- `tools/call` - Execute a tool
- `resources/list` - List available resources
**Example:**
```bash
curl -X POST http://localhost:5000/mcp/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "ping",
"id": 1
}'
```
### A2A (Agent-to-Agent)
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/.well-known/agent.json` | Agent card discovery (standard) |
| GET | `/.well-known/agent-card.json` | Agent card discovery (alternative) |
| POST | `/a2a/jsonrpc` | JSON-RPC 2.0 endpoint |
| POST | `/a2a` | JSON-RPC endpoint alias |
**Supported JSON-RPC methods:**
- `agent/info` - Get agent information
- `tasks/send` - Send a task
- `message/send` - Send a message
**Example - Agent Discovery:**
```bash
curl http://localhost:5000/.well-known/agent.json
```
**Example - Send Message:**
```bash
curl -X POST http://localhost:5000/a2a/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "agent/info",
"params": {"agent_id": "a2a://assistant@localhost"},
"id": 1
}'
```
### Coral (Mesh Protocol)
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/coral/info` | Coral protocol information |
| GET | `/coral/agents` | List Coral agents |
| POST | `/coral/agents` | Register Coral agent |
| GET | `/coral/threads` | List threads |
| POST | `/coral/threads` | Create a thread |
| GET | `/coral/threads/{thread_id}` | Get thread details |
| GET | `/coral/threads/{thread_id}/messages` | Get thread messages |
| POST | `/coral/threads/{thread_id}/messages` | Send message to thread |
| GET | `/coral/notifications` | Get notifications |
**Example - Create Thread:**
```bash
curl -X POST http://localhost:5000/coral/threads \
-H "Content-Type: application/json" \
-d '{
"agent_id": "coral://mesh@localhost",
"metadata": {"topic": "discussion"}
}'
```
**Example - Send Message:**
```bash
curl -X POST http://localhost:5000/coral/threads/{thread_id}/messages \
-H "Content-Type: application/json" \
-d '{
"content": "Hello from Coral",
"sender": "coral://mesh@localhost"
}'
```
### Streaming Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/stream/events` | Server-Sent Events (SSE) for all events |
| GET | `/stream/tasks/{task_id}/events` | SSE for specific task events |
| WebSocket | `/ws` | WebSocket connection for bidirectional streaming |
**SSE Example:**
```bash
curl http://localhost:5000/stream/events
```
**WebSocket Example:**
```javascript
const ws = new WebSocket('ws://localhost:5000/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received:', data);
};
```
### Routing & Simulation
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/route/simulate` | Simulate routing between agents |
| POST | `/api/route/simulate` | API version of route simulation |
## Cross-Protocol Communication
The bridge automatically translates between protocols. To route a message from one protocol to another, specify the target agent ID:
```bash
# Send ACP message to MCP agent
curl -X POST http://localhost:5000/runs \
-H "Content-Type: application/json" \
-d '{
"agent_name": "mcp://tools@localhost",
"message": {
"role": "user",
"parts": [{"type": "text", "text": "Execute tool"}]
}
}'
```
The bridge will:
1. Receive the ACP-formatted message
2. Translate it to the internal format
3. Convert it to MCP format
4. Forward it to the MCP agent
## Authentication
Authentication is optional but recommended for production.
### Supported Methods
**1. API Key (X-API-Key header):**
```bash
curl -H "X-API-Key: your-api-key" http://localhost:5000/agents
```
**2. Bearer Token (treated as API key):**
```bash
curl -H "Authorization: Bearer your-api-key" http://localhost:5000/agents
```
**3. JWT Token:**
```bash
curl -H "Authorization: JWT your-jwt-token" http://localhost:5000/agents
```
**4. ANS Domain (Agent Name System):**
```bash
curl -H "X-Agent-Domain: your-agent-domain" http://localhost:5000/agents
```
### Configuration
Edit `.env` file:
```bash
JWT_SECRET=your-secret-key-minimum-32-characters
ADMIN_TOKEN=your-admin-token
API_KEY_SECRET=your-api-key-secret
```
### Notes
- Bearer tokens are treated as API keys, not JWTs
- For true JWT authentication, use the `Authorization: JWT` prefix
- API keys can be passed via X-API-Key header or Bearer token
- ANS domain authentication is available for agent-based identity
## Architecture
```
ai_bridge/
├── core/
│ ├── app_factory.py # Application initialization
│ ├── broker.py # Message routing with circuit breaker
│ ├── registry.py # Agent discovery and management
│ ├── router.py # Capability-based routing
│ └── routes.py # HTTP endpoints
├── protocols/
│ ├── acp_adapter.py # ACP protocol handler
│ ├── mcp_adapter.py # MCP protocol handler
│ ├── a2a_adapter.py # A2A protocol handler
│ └── coral_adapter.py # Coral protocol handler
├── auth/
│ └── trust_manager.py # Authentication and authorization
├── schema/
│ ├── internal_schema.py # Common message format
│ └── schema_registry.py # Protocol schema management
├── infrastructure/
│ ├── persistence.py # Redis-based state management
│ └── streaming.py # SSE and WebSocket handlers
└── utils/
└── error_translation.py # Error mapping across protocols
```
## Production Deployment
### Environment Variables
Create a `.env` file:
```bash
JWT_SECRET=your-production-secret-key
ADMIN_TOKEN=your-production-admin-token
API_KEY_SECRET=your-production-api-key-secret
REDIS_URL=redis://your-redis-host:6379
```
### Running in Production
**Option 1: Direct Python**
```bash
python main.py
```
**Option 2: Docker**
Create `Dockerfile`:
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements-list.txt .
RUN pip install --no-cache-dir -r requirements-list.txt
COPY . .
EXPOSE 5000
CMD ["python", "main.py"]
```
Build and run:
```bash
docker build -t babel .
docker run -p 5000:5000 --env-file .env babel
```
**Option 3: Production ASGI Server**
```bash
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:5000
```
### Production Checklist
- [ ] Set strong values for `JWT_SECRET`, `ADMIN_TOKEN`, `API_KEY_SECRET`
- [ ] Configure Redis for persistent state management
- [ ] Enable HTTPS/TLS at load balancer or reverse proxy
- [ ] Set up monitoring and alerting
- [ ] Configure rate limiting
- [ ] Review and restrict CORS settings
- [ ] Set up log aggregation
- [ ] Configure health check endpoints in orchestration platform
## Error Handling
### HTTP Status Codes
| Code | Meaning |
|------|---------|
| 200 | Success |
| 400 | Bad request - invalid parameters |
| 401 | Unauthorized - authentication required |
| 404 | Not found - agent or resource doesn't exist |
| 500 | Internal server error |
| 503 | Service unavailable - adapter not available |
### JSON-RPC Error Codes
| Code | Meaning |
|------|---------|
| -32700 | Parse error |
| -32600 | Invalid request |
| -32601 | Method not found |
| -32602 | Invalid params |
| -32603 | Internal error |
### Circuit Breaker
The broker includes circuit breaker protection:
- Opens after 5 consecutive failures
- Stays open for 60 seconds
- Automatically recovers when agent becomes healthy
## Monitoring
### System Metrics
```bash
curl http://localhost:5000/metrics
```
Returns:
```json
{
"metrics": {
"total_messages": 1234,
"active_agents": 5,
"protocols": {
"acp": {"count": 2},
"mcp": {"count": 1},
"a2a": {"count": 1},
"coral": {"count": 1}
}
}
}
```
### Event Streaming
Monitor all system events in real-time:
```bash
curl http://localhost:5000/stream/events
```
## Troubleshooting
**Problem: Agent not found**
```bash
curl http://localhost:5000/agents
```
Verify the agent is registered and the agent_id format is correct (e.g., `acp://name@domain`).
**Problem: Connection refused**
Check that the agent's endpoint URL is reachable and the agent service is running.
**Problem: Authentication failed**
Ensure the API key or token is correctly configured in both the bridge and agent.
**Problem: Messages not routing**
Check the broker logs for circuit breaker status. The agent may be marked as unhealthy after repeated failures.
**Problem: 503 Service Unavailable**
The protocol adapter is not available. Verify the adapter is initialized in the application.
**Debug Mode:**
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## Project Files
```
.
├── main.py # Application entry point
├── requirements-list.txt # Python dependencies
├── README.md # This file
├── replit.md # Technical documentation
├── HOW_TO_REGISTER_AGENTS.md # Agent registration guide
├── .env.example # Environment template
├── .gitignore # Git ignore rules
├── .replit # Replit configuration
├── ai_bridge/ # Main source code
└── static/
└── index.html # Web UI for agent management
```
## Support
For issues or questions:
1. Check the troubleshooting section above
2. Review `HOW_TO_REGISTER_AGENTS.md` for agent setup
3. Check system metrics at `/metrics`
4. Enable debug logging for detailed diagnostics
