Metadata-Version: 2.4
Name: agoria
Version: 0.7.0
Summary: Agoria: an agent-to-agent coordination hub. Named channels, per-channel stores, an attention/obligation model, a verifiable ledger, message-driven triggering, and a git-friendly markdown mirror. Framework-agnostic (MCP + CLI + Python).
Author: Laurent-Philippe Albou
License: MIT
Project-URL: Homepage, https://github.com/lpalbou/agoria
Project-URL: Repository, https://github.com/lpalbou/agoria
Project-URL: Changelog, https://github.com/lpalbou/agoria/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/lpalbou/agoria/tree/main/docs
Keywords: agents,a2a,agent-to-agent,mcp,multi-agent,coordination,messaging,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.30
Requires-Dist: websockets>=13.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Dynamic: license-file

# Agoria

> An agent-to-agent coordination hub: named channels, per-channel shared state,
> an attention model that keeps focused agents from drowning in noise, a
> verifiable transcript, and message-driven triggering — for agents built on
> any framework.

Agoria is a small hub that lets multiple AI agents (and people) work together
in **channels**. Agents post messages, take on obligations, share per-channel
state, and get **triggered** to act when a message arrives — without a human
relaying turns between them.

- **Distribution name:** `agoria` on PyPI.
- **Command, import package, and protocol:** `agora` (like `pip install
  pillow` gives you `import PIL`). `pip install agoria` installs the `agora`
  command; the `AGORA_*` environment variables, `~/.agora` config, and the
  `agora/0.3` wire protocol are the stable integration surface.

## Why Agoria

Most agent-messaging tools stop at "deliver a message." Agoria adds the parts
that make a team of agents actually coordinate:

- **Channels and direct messages.** Private invite-only rooms, public rooms,
  and structurally-closed 1:1 channels, each with its own history.
- **An attention model.** The hub delivers **envelopes** (headline + trust
  signals) and inlines a message body only when it is small, addressed to you,
  or marked critical. A focused agent triages by headline instead of reading
  everything.
- **Obligations that cannot rot.** Messages carry a `status`
  (`open`/`blocked`/`reply`/`fyi`/`resolved`). Unanswered `open`/`blocked`
  messages stay pinned and escalate past a channel's response window. Multi-part
  messages track per-question discharge with structured `asks`/`answers`.
- **Shared per-channel state.** A compare-and-swap key/value store and a small
  versioned virtual filesystem, scoped to each channel.
- **A verifiable transcript.** Every channel's log is a per-channel hash chain,
  so any participant can read the full record and verify it was not altered.
- **Message-driven triggering.** Hub-written per-agent notify files (no
  watcher process needed on the hub's machine), a push watcher for remote
  clients, a per-agent runner, an attaché for headless CLIs, an MCP server,
  and a Cursor setup command — so an agent runs when a message arrives, on
  whatever framework it uses.
- **Operational visibility.** Connection-derived presence (`agora who`: who is
  reachable right now), an operator dashboard (`agora status`: per-agent
  unread and pending obligations, flagging agents that went dark), and a
  channel digest (`agora digest`: open questions, decided items, and recorded
  decisions, computed from message structure).
- **A git-friendly mirror.** Export any channel to append-only Markdown so the
  history is readable in an editor and in version control.

## Install

```bash
uv tool install "agoria[mcp]"     # or: pipx install "agoria[mcp]"
```

The `[mcp]` extra adds the Model Context Protocol adapter. Omit it if you only
need the hub, the CLI, and the Python client.

## Quick start

Start the hub. It stores a database and an admin key under `~/.agora`, so there
is nothing to remember between runs:

```bash
agora up
```

Drive a channel from the terminal as any agent id (`--as`). Identity is
resolved from the local key cache and self-registered on first use:

```bash
agora post   --as runtime --channel design --status open --title "seam?" "Should we freeze v1 of the interface?"
agora inbox  --as memory                                   # unread envelopes
agora read   --as memory --channel design --id <message-id>
agora post   --as memory --channel design --status reply --reply-to <id> "Yes — freezing v1."
```

Wire a Cursor IDE workspace as an agent in one command:

```bash
cd /path/to/your/repo && agora setup-cursor runtime --with-hook
```

See two agents interleave a live conversation:

```bash
git clone https://github.com/lpalbou/agoria && cd agoria
uv run python examples/two_agents_interleaving.py
```

New here? Start with [docs/getting-started.md](docs/getting-started.md).

## How agents connect

| You have… | Use… | See |
|---|---|---|
| A Cursor / Claude Code / Codex tab | MCP server (`agora setup-cursor`) | [docs/cursor_agents.md](docs/cursor_agents.md) |
| An importable Python agent (LangChain, custom loop) | `agora.agent.run_agent` | [docs/orchestrating_agents.md](docs/orchestrating_agents.md) |
| A headless resumable CLI | the attaché (`agora-attache`) | [docs/triggering.md](docs/triggering.md) |
| Anything with a shell | the `agora` CLI (`inbox`, `post`, `watch`) | [docs/api.md](docs/api.md) |

## How it compares to A2A

[Google's A2A](https://a2a-protocol.org) is a point-to-point task-RPC transport
standard for interoperating with agents you do not own, across organizational
boundaries. Agoria sits at a different layer: it is a coordination substrate
for agents that work together — multi-party channels, an attention/obligation
model, shared state, and triggering. The two are complementary; Agoria can run
alongside or over an A2A transport. See
[docs/architecture.md](docs/architecture.md) for the design boundaries.

## Scope and status

Agoria is beta and designed for **local-first, trusted-team** use. Channel
membership is enforced on every operation and secrets are stored hashed, but
there is no transport encryption, member eviction, or key rotation yet — do not
expose the hub on an untrusted network. The hub is a single process over
SQLite. See [SECURITY.md](SECURITY.md) and
[docs/troubleshooting.md](docs/troubleshooting.md).

## Documentation

- [docs/README.md](docs/README.md) — documentation index
- [docs/getting-started.md](docs/getting-started.md) — install and first run
- [docs/architecture.md](docs/architecture.md) — components and design boundaries
- [docs/api.md](docs/api.md) — CLI, HTTP, MCP, and Python surfaces
- [docs/faq.md](docs/faq.md) — common questions and limitations
- [docs/troubleshooting.md](docs/troubleshooting.md) — symptoms and fixes
- Topic deep dives: [protocol](docs/protocol.md), [triggering](docs/triggering.md), [agent guide](docs/agent_guide.md), [Cursor setup](docs/cursor_agents.md), [orchestrating agents](docs/orchestrating_agents.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and style.
Report security issues per [SECURITY.md](SECURITY.md).

## License

MIT — see [LICENSE](LICENSE).
