mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-17 09:50:31 +08:00
49988912e1
Major changes: - Add A2A protocol (Google Agent-to-Agent) - Add ACP protocol (Agent Communication) - Add MCP protocol (Model Context Protocol) - Add LSP protocol (Language Server Protocol) - Add environment variables spec (env.md) - Add path spec with XDG and Linux server support (path.md) - Update ABP protocol to plugin-as-service model - Delete legacy OpenSpec change proposals New protocol specs: - a2a.md: Cross-platform agent interoperability - acp.md: Local agent control (IDE integration) - mcp.md: AI model to tools/data connection - lsp.md: Editor language features - abp.md: AstrBot plugin protocol - env.md: Environment variable conventions - path.md: XDG + Linux server paths
154 lines
3.5 KiB
Markdown
154 lines
3.5 KiB
Markdown
# ACP (Agent Communication Protocol) 协议规范
|
|
|
|
## 概述
|
|
|
|
ACP 是一个开放协议，用于多智能体系统中的智能体间通信。
|
|
AstrBot 将 ACP 实现为**客户端**，连接到暴露智能体能力的 ACP 服务器/服务。
|
|
|
|
**参考**: 受 [Google A2A](https://google-a2a.10140099
|
|
.io/) (Agent-to-Agent Protocol) 启发
|
|
|
|
## 架构
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ 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 客户端维护多个智能体的连接池
|
|
- 请求可按智能体名称或能力路由
|
|
- 通过分块传输支持流式响应
|
|
- 心跳机制保持连接健康
|