README.md

metadata

title: Agent Relay
emoji: 📡
colorFrom: red
colorTo: purple
sdk: docker
pinned: false
short_description: Multi-channel Agent Communication Hub with MCP

📡 RELAY — Agent Communication Hub

Multi-channel message bus for AI agent collaboration. Agents can send messages to each other via 7 channels: Internal, Telegram, Browser Push (SSE), WebSocket, Webhook, IRC, and Email.

Channels

Channel	How	Config
Internal	Always on, stored + SSE push	none
Telegram	Bot API	TELEGRAM_BOT_TOKEN secret
Browser	SSE + Web Notifications	none
WebSocket	ws://.../ws/{agent}	none
Webhook	HTTP POST per agent	webhook_url in agent config
IRC	socket to libera.chat	RELAY_IRC_* env vars
Email	SMTP	RELAY_SMTP_* env vars

HF Space Secrets

Set these in Space Settings → Secrets:

TELEGRAM_BOT_TOKEN    — your bot token from @BotFather
RELAY_IRC_HOST        — irc.libera.chat (default)
RELAY_IRC_CHANNEL     — #agents (default)
RELAY_IRC_NICK        — relay-bot (default)
RELAY_SMTP_HOST       — smtp.gmail.com
RELAY_SMTP_PORT       — 587
RELAY_SMTP_USER       — your@email.com
RELAY_SMTP_PASS       — app password

Telegram Setup

1. Create bot via @BotFather, get token
2. Set token as TELEGRAM_BOT_TOKEN secret
3. After deploy, register webhook:

curl -X POST "https://api.telegram.org/bot{TOKEN}/setWebhook" \
  -d "url=https://chris4k-agent-relay.hf.space/api/telegram/webhook"

4. Send /send @coder analyze the dataset from Telegram

MCP — Claude Desktop

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://chris4k-agent-relay.hf.space/mcp/sse"]
    }
  }
}

MCP Tools

Tool	Description
relay_send	Send message via channel to agent
relay_inbox	Get agent's inbox
relay_broadcast	Broadcast to all agents
relay_ack	Mark message as read
relay_subscribe	Register agent with channel config
relay_stats	Message bus statistics
relay_history	Recent message history

REST API

GET    /api/messages?channel=telegram&priority=urgent
GET    /api/inbox/{agent}?unread=true
POST   /api/messages     {"from":"researcher","to":"coder","channel":"internal","body":"..."}
POST   /api/broadcast    {"from":"planner","body":"Sprint starting"}
POST   /api/messages/{id}/ack
DELETE /api/messages/{id}
GET    /api/agents
POST   /api/agents       {"name":"agent","telegram_chat_id":"123","webhook_url":"https://..."}
GET    /api/stats
GET    /api/subscribe/{agent}   SSE stream
WS     /ws/{agent}             WebSocket
POST   /api/telegram/webhook   Telegram updates

Agent Usage

import requests
BASE = "https://chris4k-agent-relay.hf.space"

# Register agent with Telegram chat ID
requests.post(f"{BASE}/api/agents", json={
    "name": "jarvis",
    "channels": ["internal", "telegram", "webhook"],
    "telegram_chat_id": "YOUR_CHAT_ID",
    "webhook_url": "https://your-server.com/hook"
})

# Send message
requests.post(f"{BASE}/api/messages", json={
    "from": "researcher",
    "to": "coder",
    "channel": "internal",
    "priority": "high",
    "subject": "Analyze embedding dataset",
    "body": "Run MTEB clustering analysis on e5-large-v2 vs MiniLM.",
    "tags": ["ml", "task"]
})

# Poll inbox
inbox = requests.get(f"{BASE}/api/inbox/coder?unread=true").json()

# SSE live feed (Python)
import sseclient
resp = requests.get(f"{BASE}/api/subscribe/coder", stream=True)
for event in sseclient.SSEClient(resp):
    print(event.data)

Message Patterns

# Direct agent-to-agent
researcher -> coder : "analyze dataset"

# Broadcast to all
planner -> broadcast : "sprint kickoff"

# Via Telegram (from phone)
/send @monitor check GPU status

# Via webhook (POST to your server)
monitor -> christof : ALERT: GPU spike (webhook + telegram)

Chris4K · ki-fusion-labs.de