# Agora — NATS + MCP

A shared communication bus so that **multiple agents can access and talk to each other**.

NATS is the message bus; MCP is the entry point that lets an MCP client (Claude Code,
Codex, or any other) reach into the Agora. There is no fixed roster — any number of
agents can join by subscribing to the bus, and any MCP client can list, message, and
query them. Agents come and go freely; the control plane just tracks who is currently online.

## Architecture

```
MCP clients (Claude Code / Codex / any MCP client)
      │
  MCP Server (FastMCP, stdio)
      │
  Control Plane (FastAPI :8100)
      │
     NATS (:4222)
   ┌──┬──┬──┬── … ──┐        ← any number of agents can join/leave
 agent  agent  agent  …       (echo, researcher, writer, your own…)
      │
  Webhooks → n8n → your stack
```

## Quick Start

```bash
# 1. Start NATS (native binary — no Docker needed)
nats-server -js -m 8222 --name swarm-nats
# (Alternative, if you prefer Docker:)
#   docker run -d --name nats -p 4222:4222 -p 8222:8222 nats:latest -js -m 8222

# 2. Create the Python env (system Python 3.9 is too old for `mcp`; use 3.11+)
#    This repo ships a ready-to-use venv at .venv313 (Python 3.13).
#    To recreate it:  uv venv --python 3.13 .venv313 && .venv313/bin/pip install -r requirements.txt

# 3. Start the control plane (FastAPI on :8100)
export PYTHONPATH=.
.venv313/bin/python -m core.control_plane

# 4. Start agents (each in its own terminal or as a background process)
.venv313/bin/python -m agents.echo_agent
#    Team example (two cooperating agents):
#      .venv313/bin/python -m agents.team_example researcher
#      .venv313/bin/python -m agents.team_example writer

# 5. Use the MCP server from Claude Code (see mcp-config.snippet.json)
#    Add it to your Claude Code / claude_desktop_config.json mcpServers block.
```

There is also a `run.sh` helper and a `Makefile` for the common commands:

```bash
./run.sh nats        # start NATS
./run.sh control     # start the control plane
./run.sh echo        # start the echo agent
./run.sh bridge <id> # join a turn-based AI (Claude Code/GPT) — see JOINING-AI-AGENT.md
./run.sh test        # run the unit tests
make nats / make control / make echo / make test
```

**Joining:** long-running agent → [JOINING.md](JOINING.md) · turn-based AI →
[JOINING-AI-AGENT.md](JOINING-AI-AGENT.md) · call over HTTP without NATS →
[A2A.md](A2A.md).

## MCP Tools

Once the MCP server is wired in, an MCP client gets these tools (all take flat arguments):

| Tool | Purpose |
|---|---|
| `agora_list_agents` | List agents currently on the bus (optional status filter) |
| `agora_get_agent` | Details for one agent |
| `agora_send_message` | Fire-and-forget direct message to an agent |
| `agora_request_reply` | Send a request and wait for the agent's reply |
| `agora_broadcast` | Message all agents (or a topic) |
| `agora_publish` | Publish to any raw NATS subject |

There's also a **remote MCP server** (Streamable HTTP) so you can add the Agora
as a connector in **Claude web / ChatGPT web** (`search` + `fetch` included) —
see **[MCP-CONNECT.md](MCP-CONNECT.md)**.

## A2A — external access (other devices / other GPTs)

The Agora also speaks the **[A2A protocol](https://a2a-protocol.org)** as its
public contract, so outside agents (another machine, a custom GPT, any A2A SDK
client) can discover and call Agora agents over HTTP — no NATS, no bus
membership. The control plane serves Agent Cards and bridges A2A Tasks to NATS.

| Method | Path | Purpose |
|---|---|---|
| GET | `/.well-known/agent-card.json` | Card for the Agora |
| GET | `/a2a/agents` | Live catalog of agent cards |
| GET | `/a2a/{id}/.well-known/agent-card.json` | One agent's card |
| POST | `/a2a/{id}` | JSON-RPC `message/send` · `message/stream` · `tasks/get` · `tasks/cancel` |

Set `A2A_TOKEN` to require a bearer token, and `A2A_BASE_URL` (+ a tunnel) to
expose it publicly. **See [A2A.md](A2A.md)** for the full guide: client example,
the worker reply contract, auth, and exposing to remote/cloud clients.

## NATS Subject Conventions

| Pattern | Purpose |
|---|---|
| `agent.{id}.inbox` | Direct message to a specific agent |
| `agent.{id}.status` | Agent status updates |
| `agora.broadcast` | Message all agents |
| `agora.topic.{topic}` | Topic-based pub/sub |
| `agora.request.{id}` | Request/reply pattern |
| `control.register` | Agent registration |
| `control.deregister` | Agent deregistration |
| `control.heartbeat` | Agent heartbeats (carry full info, so a restarted control plane re-registers agents) |

## Creating a New Agent

Any agent can join the bus by subclassing `BaseAgent` — that's how "multiple agents can
access" the Agora:

```python
from core.base_agent import BaseAgent
from core.models import SwarmMessage

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(agent_id="my-agent", agent_type="worker", capabilities=["analyze"])

    async def handle_message(self, subject: str, message: SwarmMessage) -> None:
        if message.payload.get("action") == "analyze":
            result = {"ok": True}
            # For a request, reply on the one-shot reply subject:
            await self.reply_to_request(message, result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(MyAgent().start())
```

## NATS Monitoring

NATS exposes a monitoring endpoint at `http://localhost:8222` when started with `-m 8222`.