docs/archive/AGENTS-INTEGRATION.md

Интеграция агентов — ресёрч

Аналогия с 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)

Файл, описывающий что агент умеет и как с ним взаимодействовать. Хранится в трекере, привязан к конкретному агенту.

{
  "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. Инструкция по запуску:

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)

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)