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