mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-16 01:40:15 +08:00
165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
# ACP (Agent Communication Protocol) 协议规范
|
||
|
||
## 概述
|
||
|
||
ACP 是一个开放协议，用于多智能体系统中的智能体间通信。
|
||
AstrBot 将 ACP 实现为**客户端**，连接到暴露智能体能力的 ACP 服务器/服务。
|
||
|
||
**参考**: 受 [Google A2A](https://google-a2a.10140099
|
||
.io/) (Agent-to-Agent Protocol) 启发
|
||
|
||
## 实现状态
|
||
|
||
| 组件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| ACP 客户端 | ⚠️ 待实现 | 尚未在 Rust 核心中实现，Python 层无 ACP 客户端 |
|
||
| JSON-RPC 2.0 编解码 | ⚠️ 待实现 | - |
|
||
| 连接池管理 | ⚠️ 待实现 | - |
|
||
| 流式响应 | ⚠️ 待实现 | - |
|
||
|
||
> 相关协议: [A2A](a2a.md)（Google 发起，定位互补）, [agent-message](agent-message.md)（消息处理框架）
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ AstrBot (ACP 客户端) │
|
||
└─────────────────────────────────────┘
|
||
│ JSON-RPC 2.0
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ ACP 服务器/服务 │
|
||
│ - 智能体注册表 │
|
||
│ - 任务委托 │
|
||
│ - 状态同步 │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
## 传输层
|
||
|
||
### TCP 传输
|
||
|
||
- **适用场景**: 本地或云端智能体服务
|
||
- **协议**: 基于 TCP 的 JSON-RPC 2.0
|
||
- **头部**: `Content-Length` 前缀（与 LSP 相同）
|
||
|
||
### Unix Socket 传输
|
||
|
||
- **适用场景**: 高性能本地进程间通信
|
||
- **协议**: 通过 Unix 域套接字的 JSON-RPC 2.0
|
||
|
||
## 消息格式
|
||
|
||
所有消息均为 JSON-RPC 2.0，带 Content-Length 头：
|
||
|
||
```
|
||
Content-Length: <字节数>\r\n
|
||
\r\n
|
||
<json_body>
|
||
```
|
||
|
||
### 请求
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": "唯一标识",
|
||
"method": "agent/call",
|
||
"params": {
|
||
"agent": "智能体名称",
|
||
"action": "动作名称",
|
||
"args": { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": "唯一标识",
|
||
"result": {
|
||
"status": "success",
|
||
"data": { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": "唯一标识",
|
||
"error": {
|
||
"code": -32600,
|
||
"message": "无效请求",
|
||
"data": { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
## 核心方法
|
||
|
||
### 智能体管理
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `agent/list` | 列出可用智能体 |
|
||
| `agent/info` | 获取智能体能力和状态 |
|
||
| `agent/call` | 调用智能体的动作 |
|
||
| `agent/subscribe` | 订阅智能体事件 |
|
||
|
||
### 任务操作
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `task/create` | 创建新任务 |
|
||
| `task/status` | 获取任务状态 |
|
||
| `task/result` | 获取任务结果 |
|
||
| `task/cancel` | 取消运行中的任务 |
|
||
|
||
### 通信
|
||
|
||
| 方法 | 描述 |
|
||
|------|------|
|
||
| `message/send` | 向智能体发送消息 |
|
||
| `message/broadcast` | 向所有智能体广播 |
|
||
|
||
## 错误码
|
||
|
||
| 码值 | 名称 | 描述 |
|
||
|------|------|------|
|
||
| -32700 | Parse Error | 无效的 JSON |
|
||
| -32600 | Invalid Request | 格式错误的请求 |
|
||
| -32601 | Method Not Found | 未知方法 |
|
||
| -32602 | Invalid Params | 无效参数 |
|
||
| -32603 | Internal Error | 服务器错误 |
|
||
| -32000 | Agent Not Found | 未找到智能体 |
|
||
| -32001 | Agent Busy | 智能体正在处理另一请求 |
|
||
| -32002 | Task Not Found | 未找到任务 |
|
||
|
||
## 智能体发现
|
||
|
||
智能体公布其能力：
|
||
|
||
```json
|
||
{
|
||
"agent": "code-reviewer",
|
||
"version": "1.0.0",
|
||
"capabilities": ["review", "lint", "suggest"],
|
||
"endpoints": {
|
||
"tcp": "127.0.0.1:9001",
|
||
"unix": "/var/run/acp/code-reviewer.sock"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实现注意事项
|
||
|
||
- ACP 客户端维护多个智能体的连接池
|
||
- 请求可按智能体名称或能力路由
|
||
- 通过分块传输支持流式响应
|
||
- 心跳机制保持连接健康
|