193 lines
7.1 KiB
Markdown
193 lines
7.1 KiB
Markdown
# Интеграция агентов — ресёрч
|
||
|
||
## Аналогия с GitLab Runners
|
||
|
||
| GitLab | Team Board |
|
||
|--------|------------|
|
||
| Runner | Agent Instance |
|
||
| Runner Token | Agent Token |
|
||
| `.gitlab-ci.yml` | Контракт (contract.json) |
|
||
| Job | Task |
|
||
| Executor (docker/shell) | Adapter (OpenClaw/Anthropic/CLI) |
|
||
| Runner registration | `POST /api/v1/agents/register` |
|
||
| Runner tags | Agent capabilities |
|
||
|
||
## Архитектура подключения
|
||
|
||
```
|
||
1. Админ создаёт Agent в UI → получает registration token
|
||
2. На сервере запускается Agent Instance с этим токеном
|
||
3. Agent Instance регистрируется: POST /ws?token=<reg_token>
|
||
4. Tracker подтверждает → выдаёт session token
|
||
5. Agent слушает задачи через WebSocket
|
||
6. При получении задачи → выполняет через адаптер
|
||
```
|
||
|
||
## Контракт агента (contract)
|
||
|
||
Файл, описывающий что агент умеет и как с ним взаимодействовать.
|
||
Хранится в трекере, привязан к конкретному агенту.
|
||
|
||
```json
|
||
{
|
||
"version": "1",
|
||
"capabilities": ["coding", "review", "docs"],
|
||
"max_concurrent_tasks": 2,
|
||
"timeout_seconds": 600,
|
||
"accept_task_types": ["coding", "review"],
|
||
"tools": {
|
||
"file_read": true,
|
||
"file_write": true,
|
||
"git_commit": true,
|
||
"git_pr": true,
|
||
"web_search": false,
|
||
"shell_exec": false
|
||
},
|
||
"limits": {
|
||
"max_file_size_mb": 10,
|
||
"max_files_per_task": 20,
|
||
"max_comment_length": 5000
|
||
}
|
||
}
|
||
```
|
||
|
||
## Операции агента (через WebSocket)
|
||
|
||
Агент должен уметь:
|
||
|
||
### Задачи
|
||
| Операция | WS Event | Описание |
|
||
|----------|----------|----------|
|
||
| Получить задачу | `task.assigned` (входящее) | Трекер назначает задачу агенту |
|
||
| Взять задачу | `task.take` | Агент сам берёт задачу из TODO |
|
||
| Обновить статус | `task.status` | draft→ready→in_progress→review→completed |
|
||
| Обновить описание | `task.update` | Изменить title, description |
|
||
| Создать задачу | `task.create` | Агент создаёт подзадачу |
|
||
| Создать подзадачу | `task.create` (с parent_id) | Декомпозиция |
|
||
| Добавить зависимость | `task.dependency.add` | TEA-3 depends on TEA-1 |
|
||
|
||
### Комментарии
|
||
| Операция | WS Event | Описание |
|
||
|----------|----------|----------|
|
||
| Добавить комментарий | `task.comment` | Текст, code snippets |
|
||
| Читать комментарии | `task.comments.list` | История обсуждения |
|
||
|
||
### Файлы
|
||
| Операция | WS Event / HTTP | Описание |
|
||
|----------|-----------------|----------|
|
||
| Загрузить файл | `POST /api/v1/tasks/{id}/files` | Результат работы |
|
||
| Скачать файл | `GET /api/v1/tasks/{id}/files/{fid}` | Входные данные |
|
||
| Список файлов | `task.files.list` | Что есть в задаче |
|
||
|
||
### Чат
|
||
| Операция | WS Event | Описание |
|
||
|----------|----------|----------|
|
||
| Сообщение в чат | `chat.send` | Обсуждение |
|
||
| Читать чат | `chat.history` | Контекст |
|
||
|
||
## Страница настройки в UI
|
||
|
||
### /settings/agents
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ Агенты [+ Создать] │
|
||
├─────────────────────────────────────────────┤
|
||
│ ● Кодер online 2 tasks │
|
||
│ claude-opus coding, review │
|
||
│ Подключён: 2 часа назад │
|
||
│ │
|
||
│ ● Аналитик offline │
|
||
│ gpt-4 analytics, docs │
|
||
│ Последний раз: вчера │
|
||
│ │
|
||
│ ○ Тестировщик не зарегистрирован │
|
||
│ Токен: tb-agent-abc123... [Копировать] │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Создание агента
|
||
1. Имя + slug
|
||
2. Системный промпт (роль)
|
||
3. Контракт (capabilities, tools, limits)
|
||
4. Генерация registration token
|
||
5. Инструкция по запуску:
|
||
```bash
|
||
team-board-agent register \
|
||
--tracker wss://team.uix.su/ws \
|
||
--token tb-agent-abc123... \
|
||
--adapter anthropic \
|
||
--api-key sk-ant-...
|
||
```
|
||
|
||
## Регистрация и аутентификация
|
||
|
||
### Шаг 1: Создание (UI)
|
||
- Админ создаёт агента в UI
|
||
- Генерируется одноразовый registration token
|
||
- Токен показывается один раз
|
||
|
||
### Шаг 2: Регистрация (Agent Instance)
|
||
```
|
||
Agent → Tracker: ws connect + registration token
|
||
Tracker: validates token, marks agent as registered
|
||
Tracker → Agent: session token (долгоживущий)
|
||
Agent: сохраняет session token локально
|
||
```
|
||
|
||
### Шаг 3: Работа
|
||
```
|
||
Agent → Tracker: ws connect + session token
|
||
Tracker: validates, marks online
|
||
Agent ←→ Tracker: events (tasks, chat, files)
|
||
```
|
||
|
||
### Отзыв токена
|
||
- Админ в UI нажимает "Отозвать"
|
||
- Tracker закрывает WebSocket
|
||
- Agent не может переподключиться
|
||
- Нужна новая регистрация
|
||
|
||
## SDK (Python)
|
||
|
||
```python
|
||
from team_board import Agent, AnthropicAdapter
|
||
|
||
agent = Agent(
|
||
tracker_url="wss://team.uix.su/ws",
|
||
token="tb-session-xyz...",
|
||
)
|
||
|
||
@agent.on_task
|
||
async def handle_task(task):
|
||
# Читаем описание и файлы
|
||
files = await task.list_files()
|
||
|
||
# Работаем через адаптер
|
||
result = await agent.adapter.complete(
|
||
system=agent.system_prompt,
|
||
messages=[{"role": "user", "content": task.description}],
|
||
)
|
||
|
||
# Добавляем комментарий
|
||
await task.comment(result.text)
|
||
|
||
# Загружаем файл
|
||
await task.upload_file("result.py", result.code)
|
||
|
||
# Меняем статус
|
||
await task.set_status("review")
|
||
|
||
agent.run()
|
||
```
|
||
|
||
## Приоритеты реализации
|
||
|
||
1. [ ] Tracker: token generation + WS auth
|
||
2. [ ] Tracker: agent events (task.take, task.status, task.comment, task.create)
|
||
3. [ ] Tracker: file upload/download API
|
||
4. [ ] UI: /settings/agents page
|
||
5. [ ] SDK: Python package (team-board-agent)
|
||
6. [ ] SDK: AnthropicAdapter + OpenClawAdapter
|
||
7. [ ] Первый агент: тестовый (echo/summarize)
|
||
8. [ ] Первый реальный агент: Кодер (через OpenClaw/Claude)
|