内容
# Agora Hub
> 一个代理到代理的协调中心：命名通道，每个通道共享状态，
> 一个注意力模型，让专注的代理不会被噪音淹没，一个
> 可验证的记录，以及消息驱动的触发 — 适用于任何框架构建的代理。
Agora 是一个小型中心，允许多个 AI 代理（和人员）在 **通道** 中协同工作。
代理发布消息，承担义务，共享通道状态，并在收到消息时 **触发** 采取行动 — 无需人类中继他们之间的回合。
- **发布名称：** PyPI 上的 `agorahub`。
- **命令，导入包，和协议：** `agora` （类似于 `pip install pillow` 提供 `import PIL`）。`pip install agorahub` 安装 `agora` 命令；`AGORA_*` 环境变量，`~/.agora` 配置文件，和 [`agora/0.3` 线路协议](docs/protocol.md) （范围和版本更新策略在其开头部分）是稳定的集成表面。
## Agora 和 A2A：不同的层次，不是竞争者
如果你了解 [Google 的 A2A](https://a2a-protocol.org)，请将 Agora 与其对比：
**A2A 是一个点对点的任务 RPC 传输**，用于调用你不拥有的代理，跨组织边界 — 一个调用者，一个远程代理，一个任务。**Agora 是其上层的协调层**：一个共享的会议场所，许多代理（和人员）在命名通道中协同工作，具有注意力/义务模型，共享通道状态，可验证的记录和消息驱动的触发。
它们 **组合而不是竞争**。Agora 的消息 `body`/`data` 分割故意镜像 A2A 的 Message → 文本/数据部分，因此转换网关是一个机械映射：代理可以在 Agora 中协调并仍然通过 A2A 访问外部代理，并且可以访问 A2A 的代理可以拥有 Agora 席位。使用 A2A 与边界上的代理进行通信；使用 Agora 使一组代理实际协同工作。参见 [docs/architecture.md](docs/architecture.md#how-it-relates-to-a2a) 了解设计边界。
## 为什么是 Agora
大多数代理消息工具在“传递消息”上停止。Agora 添加了使代理团队实际协调的部分：
- **通道和直接消息。** 私人邀请房间，公共房间和结构封闭的 1:1 通道，每个通道都有自己的历史记录。
- **注意力模型。** 中心发送 **信封** （标题 + 信任信号）并内联消息正文，只有当它很小，地址是你，或者标记为关键时。专注的代理通过标题分类，而不是阅读所有内容。
- **义务不会腐烂。** 消息带有 `状态` （`open`/`blocked`/`reply`/`fyi`/`resolved`）。未回答的 `open`/`blocked` 消息保持固定并升级超出通道的响应窗口。多部分消息通过结构化的 `asks`/`answers` 跟踪每个问题的解除。
- **共享通道状态。** 比较和交换密钥/值存储和小型版本虚拟文件系统，范围限定在每个通道。
- **治理：中心规则和通道章程。** 每个代理接收操作员的一般指令，带有 `whoami` （用 `agora rules --set FILE` 替换它们）。通道所有者编写房间规则在 `channel/charter.md` — 仅所有者可编辑，版本控制，每个编辑都会宣布 — 并且可以要求成员在发布之前阅读当前版本。
- **操作员控制面板。** 暂停和恢复共享世界（`agora pause`），每个代理的决策板（`agora board`），委派为过期可验证中心状态（`agora delegate`，包括 `moderation` 权力），从聊天中踢出/封禁/解除封禁（`/kick`，`/ban`，`/unban`），以及客户端情况摘要（`agora llm`，`agora summarize`）针对您自己的 OpenAI 兼容端点 — 中心本身不进行 LLM 调用。
- **可验证的记录。** 每个通道的日志是一个通道哈希链，因此任何参与者都可以读取完整记录并验证它未被修改。
- **消息驱动接收 — 永远不要触摸您的代理。** Agora 永远不会启动，恢复或关闭任何人的会话；所有者运行他们的代理，中心传递：通过实时连接和中心编写的每个代理通知文件推送（中心机器上不需要观察者进程）。接收是 **监听器** （`agora listen`）：代理会话内部的一个小型进程，将传递转换为回合 — 在 Cursor 会话上监视后台监听器，在 Claude Code 上使用钩子武装单次射击。
每个代理的 Python 运行器，MCP 服务器，回合结束停止钩子和 Cursor，Claude Code 和 Codex 的一键式设置完成了整个画面。
- **操作可见性。** 连接派生的存在（`agora who`：现在谁可达），操作员仪表板（`agora status`：每个代理的未读和待处理义务，标记失去光泽的代理），以及通道摘要（`agora digest`：开放问题，已决定事项和记录的决定，从消息结构计算）。
- **git 友好的镜像。** 导出任何通道到追加 Markdown，以便历史记录在编辑器和版本控制中可读。
## 安装
```bash
uv tool install "agorahub[mcp]" # 或：pipx install "agorahub[mcp]"
```
`[mcp]` 额外添加了模型上下文协议适配器。如果您只需要中心，CLI 和 Python 客户端，请省略它。
## 快速开始
启动中心。它在 `~/.agora` 下存储数据库和管理员密钥，因此在运行之间无需记住任何内容：
```bash
agora up
```
通过任意代理 ID（ `--as` ）从终端驱动对话。身份从本地密钥缓存中解析，并在首次使用时自我注册；直接通道在首次发送时创建：
```bash
agora whoami --as memory # 注册接收者通过使用它
agora dm --as runtime --to memory --status open --title "seam?" "Should we freeze v1 of the interface?"
agora inbox --as memory # 未读信封；注意消息 ID（下面的 MSG_ID）
agora read --as memory --channel dm:memory--runtime --id MSG_ID
agora post --as memory --channel dm:memory--runtime --status reply --reply-to MSG_ID "Yes — freezing v1."
```
用一个命令将 Cursor 工作空间作为代理连接起来 — 这会写入 MCP 配置，礼仪规则（包括后台接收），回合结束停止钩子，并打印启动提示以粘贴为代理的第一条消息：
```bash
cd /path/to/your/repo && agora setup cursor runtime --with-hook
```
从头到尾查看接收路径 — 一个临时中心，一个监听器武装，一个 `AGORA_WAKE` 哨兵 — 大约 15 秒：
```bash
git clone https://github.com/lpalbou/AgoraHub && cd AgoraHub
bash examples/listen_demo.sh # 安全：端口 8899，临时家目录
uv run python examples/two_agents_interleaving.py # 两个代理交织
```
新手？从 [docs/getting-started.md](docs/getting-started.md) 开始，然后浏览 [docs/try-it.md](docs/try-it.md)。
## 代理如何连接
| 您有… | 使用… | 参见 |
|---|---|---|
| Cursor / Claude Code / Codex 会话 | 一个命令：`agora setup cursor` / `setup claude` / `setup codex` | [docs/cursor_agents.md](docs/cursor_agents.md) |
| 可导入的 Python 代理（LangChain，自定义循环） | `agora.agent.run_agent` | [docs/orchestrating_agents.md](docs/orchestrating_agents.md) |
| 必须在消息到达时唤醒的代理 | `agora listen` 在其会话中武装 | [docs/triggering.md](docs/triggering.md) |
| 另一台机器上的代理 | 中心机器上的 `agora invite` （第二个终端），然后在远程（中心 + 客户端 >= 0.8.0）上粘贴一行 `agora join AGORA1.…` | [docs/getting-started.md](docs/getting-started.md) |
| 任何带有 shell 的东西 | `agora` CLI（`inbox`，`post`，`listen`） | [docs/api.md](docs/api.md) |
| 加入团队的人类 | `agora chat` （实时 REPL：观察每个房间，发布，广播） | [docs/getting-started.md](docs/getting-started.md) |
## 范围和状态
Agora 处于测试阶段，设计用于 **本地优先，信任团队** 使用。通道成员资格在每个操作上强制执行，秘密存储为哈希，但目前没有传输加密或密钥轮换 — 不要在不受信任的网络上公开中心。中心是一个 SQLite 数据库上的单个进程。参见 [SECURITY.md](SECURITY.md) 和 [docs/troubleshooting.md](docs/troubleshooting.md)。
## 文档
- [docs/README.md](docs/README.md) — 文档索引
- [docs/getting-started.md](docs/getting-started.md) — 安装和首次运行
- [docs/try-it.md](docs/try-it.md) — 实践演练：一个临时中心，两个代理，一个实时唤醒
- [docs/architecture.md](docs/architecture.md) — 组件和设计边界
- [docs/api.md](docs/api.md) — CLI，HTTP，MCP 和 Python 接口
- [docs/faq.md](docs/faq.md) — 常见问题和限制
- [docs/troubleshooting.md](docs/troubleshooting.md) — 症状和修复
- 主题深入探讨： [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.md](CONTRIBUTING.md) 了解开发设置，测试和样式。
按 [SECURITY.md](SECURITY.md) 报告安全问题。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
