docs: add RESEARCH.md - agent integration analysis
- OpenClaw multi-agent capabilities - ACP protocol for external agents - CLI bridge options - Web terminal architecture - Comparison and recommendations
This commit is contained in:
parent
b84b9f91f6
commit
35907c0e0f
357
RESEARCH.md
Normal file
357
RESEARCH.md
Normal file
@ -0,0 +1,357 @@
|
|||||||
|
# Team Board — Research: Agent Integration
|
||||||
|
|
||||||
|
Исследование возможностей подключения AI-агентов к Team Board.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Текущие возможности OpenClaw
|
||||||
|
|
||||||
|
### 1. sessions_spawn — спавн изолированных субагентов
|
||||||
|
|
||||||
|
```
|
||||||
|
Task → Spawn → Isolated Session → Result → Announce back
|
||||||
|
```
|
||||||
|
|
||||||
|
**Параметры:**
|
||||||
|
- `task` (required) — задача для агента
|
||||||
|
- `label` — метка для логов
|
||||||
|
- `agentId` — ID агента (если разрешён в allowlist)
|
||||||
|
- `model` — переопределение модели
|
||||||
|
- `runTimeoutSeconds` — таймаут
|
||||||
|
- `cleanup` — `delete|keep`
|
||||||
|
|
||||||
|
**Поведение:**
|
||||||
|
- Создаёт новую сессию `agent:<agentId>:subagent:<uuid>`
|
||||||
|
- Субагенты имеют полный набор инструментов минус session tools
|
||||||
|
- Не блокирует: возвращает `{ status: "accepted", runId, childSessionKey }`
|
||||||
|
- После завершения — announce в исходный чат
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. sessions_send — отправка между сессиями
|
||||||
|
|
||||||
|
```
|
||||||
|
Agent A → sessions_send → Agent B → Response
|
||||||
|
```
|
||||||
|
|
||||||
|
**Параметры:**
|
||||||
|
- `sessionKey` (required)
|
||||||
|
- `message` (required)
|
||||||
|
- `timeoutSeconds` — 0 = fire-and-forget
|
||||||
|
|
||||||
|
**Поведение:**
|
||||||
|
- Поддерживает ping-pong между агентами (до 5 итераций)
|
||||||
|
- Контекст сохраняется
|
||||||
|
- Провenance маркируется как `inter_session`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. sessions_list / sessions_history
|
||||||
|
|
||||||
|
- Список активных сессий
|
||||||
|
- История сообщений сессии
|
||||||
|
- Фильтры по типу, времени, каналу
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Multi-Agent Routing
|
||||||
|
|
||||||
|
Несколько агентов в одном gateway:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
agents:
|
||||||
|
list:
|
||||||
|
- id: main
|
||||||
|
workspace: ~/.openclaw/workspace
|
||||||
|
- id: coder
|
||||||
|
workspace: ~/projects/coder-workspace
|
||||||
|
- id: reviewer
|
||||||
|
workspace: ~/projects/reviewer-workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
**Каждый агент имеет:**
|
||||||
|
- Свой workspace (файлы, AGENTS.md, SOUL.md)
|
||||||
|
- Свой state directory
|
||||||
|
- Своё хранилище сессий
|
||||||
|
- Свои auth profiles
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. ACP (Agent Client Protocol)
|
||||||
|
|
||||||
|
Стандартный протокол для подключения внешних агентов.
|
||||||
|
|
||||||
|
```
|
||||||
|
External Agent ↔ ACP ↔ OpenClaw Gateway
|
||||||
|
```
|
||||||
|
|
||||||
|
**Реализация в OpenClaw:**
|
||||||
|
- `src/acp/server.ts` — ACP сервер
|
||||||
|
- `src/acp/client.ts` — ACP клиент
|
||||||
|
- Использует `@agentclientprotocol/sdk`
|
||||||
|
|
||||||
|
**Dangerous tools требуют approval:**
|
||||||
|
- exec, spawn, shell
|
||||||
|
- sessions_spawn, sessions_send
|
||||||
|
- gateway
|
||||||
|
- fs_write, fs_delete, fs_move
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Варианты интеграции для Team Board
|
||||||
|
|
||||||
|
### Вариант 1: OpenClaw Multi-Agent (рекомендуется)
|
||||||
|
|
||||||
|
```
|
||||||
|
Team Board API
|
||||||
|
↓
|
||||||
|
OpenClaw Gateway
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ Agent: main (Lead) │
|
||||||
|
│ Agent: coder (Developer) │
|
||||||
|
│ Agent: reviewer (QA) │
|
||||||
|
│ Agent: analyst (Research) │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Плюсы:**
|
||||||
|
- Готовая инфраструктура
|
||||||
|
- Сохранение контекста через сессии
|
||||||
|
- Единый API
|
||||||
|
- Безопасность (sandbox, permissions)
|
||||||
|
- Инструменты (exec, browser, files)
|
||||||
|
|
||||||
|
**Реализация:**
|
||||||
|
1. Добавить агентов в `openclaw.json`
|
||||||
|
2. Team Board вызывает `sessions_spawn` / `sessions_send` через Gateway API
|
||||||
|
3. Результаты через webhook или polling
|
||||||
|
|
||||||
|
**Конфиг:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"list": [
|
||||||
|
{
|
||||||
|
"id": "main",
|
||||||
|
"workspace": "~/.openclaw/workspace"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "coder",
|
||||||
|
"workspace": "~/workspaces/coder",
|
||||||
|
"model": "anthropic/claude-sonnet-4-20250514"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"defaults": {
|
||||||
|
"subagents": {
|
||||||
|
"allowAgents": ["main", "coder", "reviewer"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Вариант 2: ACP Bridge для CLI агентов
|
||||||
|
|
||||||
|
Для подключения Claude Code CLI без траты API токенов.
|
||||||
|
|
||||||
|
```
|
||||||
|
Claude Code CLI (Max subscription)
|
||||||
|
↓
|
||||||
|
ACP Client Wrapper
|
||||||
|
↓
|
||||||
|
OpenClaw Gateway
|
||||||
|
↓
|
||||||
|
Team Board
|
||||||
|
```
|
||||||
|
|
||||||
|
**Компоненты:**
|
||||||
|
|
||||||
|
1. **PTY Session Manager**
|
||||||
|
```python
|
||||||
|
import pexpect
|
||||||
|
|
||||||
|
class CliSession:
|
||||||
|
def __init__(self, command="claude"):
|
||||||
|
self.child = pexpect.spawn(command)
|
||||||
|
|
||||||
|
def send(self, message: str) -> str:
|
||||||
|
self.child.sendline(message)
|
||||||
|
self.child.expect(r'\n>') # wait for prompt
|
||||||
|
return self.child.before.decode()
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **ACP Translator**
|
||||||
|
```python
|
||||||
|
class AcpCliBridge:
|
||||||
|
def handle_request(self, request):
|
||||||
|
response = self.cli_session.send(request.message)
|
||||||
|
return AcpResponse(content=response)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Сложности:**
|
||||||
|
- CLI интерактивный, не headless
|
||||||
|
- Нужно парсить вывод
|
||||||
|
- Контекст внутри CLI сессии
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Вариант 3: Direct API + Context Store
|
||||||
|
|
||||||
|
Прямые вызовы API с хранением контекста в БД.
|
||||||
|
|
||||||
|
```
|
||||||
|
Team Board
|
||||||
|
↓
|
||||||
|
Agent Service
|
||||||
|
↓
|
||||||
|
┌──────────────────────────────────┐
|
||||||
|
│ Claude API │ Codex │ Gemini │
|
||||||
|
└──────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
Context Store (PostgreSQL)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Схема контекста:**
|
||||||
|
```sql
|
||||||
|
CREATE TABLE agent_contexts (
|
||||||
|
id UUID PRIMARY KEY,
|
||||||
|
agent_id UUID REFERENCES agents(id),
|
||||||
|
session_id UUID REFERENCES sessions(id),
|
||||||
|
messages JSONB, -- история сообщений
|
||||||
|
metadata JSONB, -- system prompt, tools, etc.
|
||||||
|
created_at TIMESTAMPTZ,
|
||||||
|
updated_at TIMESTAMPTZ
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**При каждом запросе:**
|
||||||
|
1. Загрузить контекст из БД
|
||||||
|
2. Добавить новое сообщение
|
||||||
|
3. Вызвать API с полным контекстом
|
||||||
|
4. Сохранить ответ в БД
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Web Terminal Interface
|
||||||
|
|
||||||
|
### Архитектура
|
||||||
|
|
||||||
|
```
|
||||||
|
Browser (xterm.js)
|
||||||
|
↓ WebSocket
|
||||||
|
Team Board Frontend
|
||||||
|
↓ WebSocket
|
||||||
|
Team Board Backend (Session Manager)
|
||||||
|
↓ PTY / API
|
||||||
|
Agent (OpenClaw / CLI / API)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Компоненты
|
||||||
|
|
||||||
|
**Frontend:**
|
||||||
|
- xterm.js — терминальный эмулятор
|
||||||
|
- WebSocket клиент
|
||||||
|
- Session selector UI
|
||||||
|
|
||||||
|
**Backend:**
|
||||||
|
- WebSocket сервер
|
||||||
|
- Session Manager
|
||||||
|
- PTY spawner (для CLI агентов)
|
||||||
|
- OpenClaw Gateway client (для OpenClaw агентов)
|
||||||
|
|
||||||
|
### Пример кода (Backend)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from fastapi import WebSocket
|
||||||
|
import asyncio
|
||||||
|
|
||||||
|
class AgentSessionManager:
|
||||||
|
def __init__(self):
|
||||||
|
self.sessions = {}
|
||||||
|
|
||||||
|
async def create_session(self, agent_type: str, config: dict):
|
||||||
|
if agent_type == "openclaw":
|
||||||
|
return OpenClawSession(config)
|
||||||
|
elif agent_type == "cli":
|
||||||
|
return CliSession(config)
|
||||||
|
elif agent_type == "api":
|
||||||
|
return ApiSession(config)
|
||||||
|
|
||||||
|
async def handle_websocket(self, ws: WebSocket, session_id: str):
|
||||||
|
session = self.sessions[session_id]
|
||||||
|
|
||||||
|
async for message in ws.iter_text():
|
||||||
|
response = await session.send(message)
|
||||||
|
await ws.send_text(response)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Сравнение вариантов
|
||||||
|
|
||||||
|
| Критерий | OpenClaw Multi-Agent | ACP CLI Bridge | Direct API |
|
||||||
|
|----------|---------------------|----------------|------------|
|
||||||
|
| Сложность | Низкая | Высокая | Средняя |
|
||||||
|
| Контекст | ✓ Автоматический | ✓ В CLI | Ручной |
|
||||||
|
| Инструменты | ✓ Полный набор | ✓ CLI tools | ✗ Нет |
|
||||||
|
| API токены | Нужны | Не нужны (Max) | Нужны |
|
||||||
|
| Готовность | Сейчас | Требует разработки | Требует разработки |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Рекомендуемый план
|
||||||
|
|
||||||
|
### Фаза 1: OpenClaw Multi-Agent (быстрый старт)
|
||||||
|
|
||||||
|
1. Добавить агентов в конфиг OpenClaw
|
||||||
|
2. Team Board API вызывает Gateway
|
||||||
|
3. Использовать `sessions_spawn` для задач
|
||||||
|
4. Использовать `sessions_send` для коммуникации
|
||||||
|
|
||||||
|
**Результат:** Рабочая система с несколькими агентами
|
||||||
|
|
||||||
|
### Фаза 2: Web Terminal UI
|
||||||
|
|
||||||
|
1. xterm.js на фронте
|
||||||
|
2. WebSocket сервер
|
||||||
|
3. Прямое взаимодействие с агентами
|
||||||
|
|
||||||
|
**Результат:** Terminal-like опыт в браузере
|
||||||
|
|
||||||
|
### Фаза 3: ACP CLI Bridge (опционально)
|
||||||
|
|
||||||
|
1. PTY wrapper для Claude Code CLI
|
||||||
|
2. ACP транслятор
|
||||||
|
3. Интеграция с Gateway
|
||||||
|
|
||||||
|
**Результат:** CLI агенты без API токенов
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Открытые вопросы
|
||||||
|
|
||||||
|
1. **Headless mode в Claude Code CLI?**
|
||||||
|
- Нужно проверить `claude --help`
|
||||||
|
- Возможно есть `--message` или `--non-interactive`
|
||||||
|
|
||||||
|
2. **Как шарить файлы между агентами?**
|
||||||
|
- Общий workspace?
|
||||||
|
- Git как source of truth?
|
||||||
|
- Копирование через API?
|
||||||
|
|
||||||
|
3. **Rate limiting для API агентов?**
|
||||||
|
- Очередь задач
|
||||||
|
- Приоритеты
|
||||||
|
- Backoff при ошибках
|
||||||
|
|
||||||
|
4. **Мониторинг агентов?**
|
||||||
|
- Статус (idle/working/error)
|
||||||
|
- Использование токенов
|
||||||
|
- Время выполнения
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Документ обновляется по мере исследования.*
|
||||||
Loading…
Reference in New Issue
Block a user