Skip to content
BranchesTags

Repository files navigation

🚀 Agent Communication Platform (ACP)

一个轻量级、高性能的智能体通信中间件，专为多智能体协作场景设计。提供 Agent 生命周期管理、消息可靠投递、长轮询消费、管理面板等核心能力。

Python FastAPI License

✨ 核心特性

  • Agent 层级管理 – 支持 CEO（管理者）与 Worker（执行者）角色，清晰的权限隔离。
  • 可靠消息投递 – 消息持久化、自动重试、死信队列，保证至少一次投递。
  • 长轮询消费 – 基于 Redis Pub/Sub 实现低延迟消息推送，客户端可挂起等待。
  • 管理控制台 – 内置可视化面板，实时监控 Agent 状态、收件箱积压、审计日志。
  • 并发安全保障 – 针对 SQLite 并发写进行了串行化优化，杜绝死锁与锁库错误。
  • 开箱即用 – 支持 Docker Compose 一键部署，零配置启动。

📖 目录

🏁 快速开始

前置条件

  • Python 3.11+
  • Redis（可选，推荐使用）
  • Docker（可选，用于容器化部署）

1. 克隆仓库

git clone https://github.com/your-org/acp.git
cd acp

2. 安装依赖

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. 配置环境变量

复制 .env.example 为 .env，并按需修改：

cp .env.example .env

必须修改的项：

  • APP_SECRET_KEY – 用于 JWT 签名，请使用随机字符串（openssl rand -hex 32）。
  • ADMIN_TOKEN – 管理员访问令牌，用于登录管理面板。

4. 启动 Redis（可选但推荐）

docker run -d --name acp-redis -p 6379:6379 redis:7-alpine

5. 启动服务

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

6. 访问管理面板

浏览器打开 http://localhost:8000/dashboard，使用 .env 中设置的 ADMIN_TOKEN 登录。

🧩 架构概览

┌─────────────┐     HTTP/REST      ┌──────────────────────────────┐
│   Agent     │ ◄─────────────────► │   FastAPI Application        │
│  (Client)   │                     │  - Agent Management          │
└─────────────┘                     │  - Message Sending           │
                                    │  - Inbox Polling & ACK       │
                                    └──────────┬───────────────────┘
                                               │
                                    ┌──────────▼───────────────────┐
                                    │      Background Queue         │
                                    │   (Serialized DB Writes)      │
                                    └──────────┬───────────────────┘
                                               │
                          ┌────────────────────┼────────────────────┐
                          │                    │                    │
                   ┌──────▼──────┐    ┌───────▼───────┐    ┌───────▼───────┐
                   │   SQLite     │    │    Redis      │    │   Dashboard   │
                   │  (WAL mode)  │    │  (Pub/Sub)    │    │   (Static)    │
                   └──────────────┘    └───────────────┘    └───────────────┘
  • 写操作串行化 – 所有数据库写请求进入内存队列，由单个后台 Worker 串行执行，避免 SQLite 锁冲突。
  • WAL 模式 – 启用 Write‑Ahead Logging，提升并发读性能。
  • Redis 通知 – 新消息到达时通过 Pub/Sub 唤醒长轮询，实现低延迟推送。

📡 API 参考

🔐 认证

所有 API 需在请求头携带：

Authorization: Bearer <token>

Token 类型：

  • 管理员 Token – 通过 .env 配置，可访问所有 /v1/admin/* 接口。
  • Agent Token – 创建 CEO/Worker 时返回，用于业务操作。

🤖 Agent 管理

方法 路径 调用方 说明
POST /v1/agents/ceo 管理员 创建 CEO（每个项目仅允许一个）
POST /v1/agents/workers CEO 创建 Worker
DELETE /v1/agents/workers/{worker_id} CEO 逻辑销毁 Worker
GET /v1/agents?project_id=xxx CEO 查询项目下所有 Agent

📨 消息发送

方法 路径 调用方 说明
POST /v1/messages CEO / Worker 向指定 Agent 发送消息
POST /v1/messages/broadcast CEO 向项目内所有 Worker 广播

📥 消息消费

方法 路径 说明
GET /v1/inbox/poll?timeout=30 长轮询拉取消息
POST /v1/inbox/ack 确认消息，防止重投
GET /v1/inbox/messages 分页查询历史消息
GET /v1/inbox/messages/{message_id} 查询单条消息详情

🛠️ 管理面板 API（管理员专用）

方法 路径 说明
GET /v1/admin/dashboard 监控大盘数据
GET /v1/admin/agents Agent 列表（分页）
POST /v1/admin/freeze/{agent_id} 冻结 Agent
POST /v1/admin/unfreeze/{agent_id} 解冻 Agent
POST /v1/admin/agents/{agent_id}/reset-token 重置 Token
DELETE /v1/admin/agents/{agent_id} 物理删除 Agent
GET /v1/admin/logs 审计日志

完整 API 文档可在服务启动后访问 /docs 或 /redoc 查看。

⚙️ 配置说明

所有配置项通过环境变量设置（支持 .env 文件）。

变量名 默认值 描述
APP_SECRET_KEY dev-secret-key JWT 签名密钥，生产必须修改
ADMIN_TOKEN admin-token 管理员静态令牌，生产必须修改
DATABASE_URL sqlite+aiosqlite:///./agent_platform.db 数据库连接串
REDIS_URL redis://localhost:6379/0 Redis 连接地址
MAX_INBOX_SIZE 1000 单个 Agent 最大积压消息数
MAX_PAYLOAD_SIZE_BYTES 1048576 消息体最大字节数（1MB）
MAX_REDELIVERY_ATTEMPTS 3 最大重试次数
REDELIVERY_TIMEOUT_SECONDS 300 投递超时时间（秒）
MAX_POLL_TIMEOUT 60 长轮询最大挂起秒数

📊 管理面板

内置管理控制台，提供以下视图：

  • 监控大盘 – 在线/离线统计、死信数量、Agent 快览
  • Agent 管理 – 增删改查、冻结/解冻、重置 Token
  • 收件箱总览 – 每个 Agent 的消息积压、未读数、最新消息
  • 统计分析 – 角色分布、状态分布、消息投递率
  • 审计日志 – 所有操作记录，支持过滤
  • 平台日志 – 实时运行日志（内存缓冲 + 文件）

访问地址：http://localhost:8000/dashboard

🐳 部署指南

使用 Docker Compose（推荐）

  1. 构建镜像（或使用已构建的 acp:latest）

    docker build -t acp:latest .

  2. 准备 docker-compose.yml（已包含在项目中）

  3. 修改环境变量 编辑 docker-compose.yml 中的 APP_SECRET_KEY 和 ADMIN_TOKEN。

  4. 启动服务

    docker compose up -d

  5. 查看日志

    docker compose logs -f app

数据卷：

  • app_data – 持久化 SQLite 数据库文件
  • ./logs – 挂载本地日志目录

🧪 开发与测试

运行测试脚本

项目中提供了完整的测试脚本 test.py，覆盖所有 API 场景。

python test.py

持续通信仿真

simulation.py 模拟一个 CEO + 5 个 Worker 的持续通信流程，适合压力观察。

python simulation.py

代码结构

app/
├── api/               # 路由层
├── core/              # 认证、异常
├── models/            # SQLAlchemy 模型
├── schemas/           # Pydantic 模型
├── services/          # 业务逻辑（含写队列）
├── utils/             # 工具（时区处理等）
├── database.py        # 数据库连接与初始化
└── main.py            # 应用入口

dashboard/             # 管理面板静态文件

❓ 常见问题

Q: 为什么 Agent 始终显示离线？

A: Agent 必须在 /v1/inbox/poll 接口被调用后，last_poll_at 字段才会更新，从而被判定为在线。测试时请确保客户端调用了该接口。

Q: 消息未读数不减少？

A: 确认是否调用了 /v1/inbox/ack 接口。只有 ACK 后消息状态才变为 delivered，未读数才会归零。

Q: 出现 database is locked 错误？

A: 项目已针对 SQLite 做了串行化写优化，正常情况下不会出现。若仍发生，请检查是否有多实例同时运行，或考虑切换到 PostgreSQL。

Q: 如何迁移到 PostgreSQL？

A: 只需修改 DATABASE_URL 为 PostgreSQL 连接串，并安装 asyncpg 驱动。应用会自动适配。

Q: 忘记管理员 Token 怎么办？

A: 管理员 Token 写在 .env 文件中，可直接查看。若丢失，修改 .env 后重启服务即可。

📄 许可证

本项目采用 MIT License。

⭐ 如果这个项目对你有帮助，欢迎 Star！
🐛 问题反馈请提交 Issue。

About

AgentsCommunicationPlatform

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages