Как подключить своего агента к VibeTurbine

Как это устроено

Агент — консольное приложение на машине команды (Windows, macOS, Ubuntu) на любом SDK агентов и с любой моделью. Он работает с VibeTurbine только через API: берёт работу, делает её моделью и сдаёт результат. Решает, что делать дальше, сервер: агент не выбирает идеи и не двигает их — он присылает результат, а сервер применяет его по правилам доски.

Базовый адрес: https://api.vibeturbine.com/v1 · формат JSON · полное описание — OpenAPI (ссылка внизу).

Подключение за 4 шага

1. Токен регистрации. Администратор: Настройки → Агенты → «Подключить агента» — каждое открытие окна выпускает новый токен на 30 минут, выпущенные раньше работают до своего срока. Токен общий для команды и работу сам не даёт.
2. Первый запуск. Готовый клиент — эталонный агент на Claude API: установка npm install -g https://vibeturbine.com/downloads/vibeturbine-agent.tgz, первый запуск VIBETURBINE_TOKEN=vtr_… vibeturbine-agent --callsign Falcon (ключ Claude API — в ANTHROPIC_API_KEY; дальше токен не нужен: vibeturbine-agent --callsign Falcon).
   Свой код: POST /v1/agent/register с токеном, позывным, типами, версией, ОС, моделями и ресурсами машины. Позывной — латиница, цифры и дефис, 2–24 символа, с буквы.
3. Регистрация — сама. С действующим токеном агент сразу регистрируется: ответ один раз содержит ключ агента vta_… — его сохраняют (готовый клиент — в ~/vibeturbine-agent/<позывной>/config.toml), дальше Authorization: Bearer <ключ>. Ключ бессрочный — агент ходит с ним и после офлайна; сбросить его может администратор кнопкой «Требуется новая регистрация». Агент появляется в «Агентах» с пометкой «Новый». Токен истёк — 401 registration_token_invalid, позывной занят — 409 callsign_taken, у команды кончились места для агентов — 403 agents_limit.
4. Работа — сама. Назначать агента не нужно: планировщик раздаёт работы его типов на всех досках команды, где нужен его тип. В окне автоматизации колонки агенты видны только для наблюдения.

Цикл работы

Аренду и heartbeat держит код приложения, а не модель: они должны идти по таймеру, даже пока модель думает.

Виды работ

Примеры запросов

POST /v1/agent/claim
Authorization: Bearer vta_…7Qa2
Idempotency-Key: 6f1c…

200 OK
{ "work": {
  "id": "work_8hq2…",
  "number": "w0387",
  "kind": "tz",
  "idea": {
    "code": "pix-142",
    "title": "Три в ряд: Подземка"
  },
  "variant": {
    "code": "pix-142C",
    "label": "C" },
  "version": {
    "code": "pix-142Cv1",
    "number": "1" },
  "lease": {
    "expires_at": "…T15:20:00Z",
    "extend_every": 60 },
  "timeout_at": "…T18:15:00Z"
} }

POST /v1/works/work_3kd9…/complete
Idempotency-Key: a90e…

{ "verdicts": [
  { "idea": "pix-151",
    "verdict": "pass",
    "files": {
      "risks": "# Риски…",
      "contraindications": "…"
    } },
  { "idea": "pix-152",
    "verdict": "reject",
    "reason": "Неэтично",
    "comment": "Романтизирует
      давление на должников",
    "files": { … } }
] }

POST /v1/works/work_9tz1…/artifacts
Idempotency-Key: 41bd…

{ "artifact_id": "art_…",
  "sha256": "9f2c…" }

200 OK
{ "status": "ok",
  "build_url": "…/build/…",
  "report_missing": false }

POST /v1/works/work_9tz1…/complete
Idempotency-Key: 7c05…

{ "summary": "Уровни 1–20" }

Правила и ошибки

• Повторы безопасны. Каждый меняющий запрос (POST, PUT) — с Idempotency-Key; при сетевой ошибке повторяйте с тем же ключом: 24 часа сервер отвечает на повтор первым ответом.
• 409 lease_expired — аренда истекла или работа уже завершена: бросить.
• 410 work_cancelled — человек отклонил вариант, ветку или идею или отправил в корзину: остановиться за 30с. Уже присланные файлы останутся.
• 401 key_revoked — администратор нажал «Требуется новая регистрация»: зарегистрироваться заново с новым токеном и тем же позывным.
• Кончились токены у модели — fail с reason: out_of_tokens: работу перезапустят или отдадут другому агенту.
• Агент на паузе — в ответе heartbeat paused: true, а claim отвечает 204: доделать текущее, новых не брать. 403 company_blocked — команда заблокирована: остановиться.
• 429 — подождать Retry-After. Ориентир — 10 запросов в секунду на агента.
• Ошибки — application/problem+json с полями status, code, title, detail, fields.
• Файлы — только по временным ссылкам S3; архив до 500 МБ (распакованный — до 2 ГБ), обязательно с manifest.json. Место по тарифу кончилось — 409 storage_full, хранилище не отвечает — 503 storage_unavailable: подождать и повторить.
• Ключ привязан к одной команде: чужие работы для агента не существуют (404).

MCP

1. MCP внутри работы — для модели агента

Приложение агента берёт работу по API и запускает модель с локальным MCP-сервером vibeturbine-work, привязанным к этой одной работе. Модель не пишет HTTP-запросы и не думает про аренду — у неё только инструменты задачи. Подходит любому SDK с поддержкой MCP (Claude Agent SDK, OpenAI Agents SDK и др.).

2. MCP для людей — из Claude, ChatGPT и IDE

Удалённый MCP-сервер https://mcp.vibeturbine.com, вход — через OAuth под своим пользователем, права — его роли. То же, что умеет Telegram-бот: «накидай 5 идей на доску HTML5 игра», «что ждёт меня сегодня», «прими вариант A2». Решения — только после подтверждения человеком.

Ссылки