Для AI-агентов: markdown этой страницы — /docs-content/agents/list.md индекс документации — /llms.txt

Список AI-агентов

GET /v1/agents

Возвращает неудалённых AI-агентов владельца API-ключа на текущем портале. Метод читает локальные данные Вайбкод, поэтому отдельный скоуп Битрикс24 не нужен.

Владелец списка определяется по Vibe-пользователю, которому принадлежит ключ. Для OAuth-приложения X-Api-Key задаёт этого владельца; пользовательская сессия vibe_session_* в Authorization не меняет фильтр. Поэтому ключ OAuth-приложения без Bearer-сессии тоже возвращает агентов Vibe-владельца ключа, а не пустой список.

bitrixBotId — числовой ID пользователя-бота в Битрикс24. Это значение передаётся в welcomeBotId конфигурации Открытой линии. Пока создание бота не завершилось, поле равно null.

Параметры запроса

Параметр Тип Обяз. По умолчанию Описание
limit integer нет 50 Размер страницы, от 1 до 200
offset integer нет 0 Смещение от начала списка

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/agents?limit=50&offset=0" \
  -H "X-Api-Key: $VIBE_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/agents?limit=50&offset=0" \
  -H "X-Api-Key: $VIBE_APP_KEY" \
  -H "Authorization: Bearer $VIBE_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/agents?limit=50&offset=0', {
  headers: { 'X-Api-Key': process.env.VIBE_API_KEY },
})
const { success, data } = await response.json()

JavaScript — OAuth-приложение

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/agents?limit=50&offset=0', {
  headers: {
    'X-Api-Key': process.env.VIBE_APP_KEY,
    Authorization: `Bearer ${process.env.VIBE_SESSION_TOKEN}`,
  },
})
const { success, data } = await response.json()

Поля ответа

Поле Тип Описание
success boolean true, если запрос выполнен успешно
data object Конверт результата
data.agents array Агенты текущей страницы
data.agents[].id string ID агента на платформе Вайбкод
data.agents[].name string Название агента
data.agents[].status string CREATING, RUNNING, STOPPED, ERROR или DELETED
data.agents[].kind string Тип рантайма: HERMES или OPENCLAW
data.agents[].bitrixBotId integer | null ID пользователя-бота в Битрикс24; значение для welcomeBotId
data.hasNextPage boolean true, если после текущей страницы есть записи

Следующую страницу запросите с offset + limit. Удалённые агенты и агенты другого пользователя или портала не возвращаются.

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "cmf123example",
        "name": "Поддержка клиентов",
        "status": "RUNNING",
        "kind": "HERMES",
        "bitrixBotId": 417
      }
    ],
    "hasNextPage": false
  }
}

Привязка к Открытой линии

Скопируйте bitrixBotId выбранного агента в welcomeBotId при создании или обновлении openline-configs. Поле agentId для этого не используется. queue содержит ID сотрудников-операторов и не идентифицирует Hermes-агента.

Пример ответа при ошибке

401 — передан неизвестный API-ключ:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Ошибки

HTTP Код Когда возникает
401 MISSING_API_KEY Заголовок X-Api-Key отсутствует
401 INVALID_API_KEY Ключ не опознан: такой строки на платформе нет
401 KEY_INACTIVE Ключ неактивен или отозван
401 KEY_EXPIRED Срок действия ключа истёк
401 WRONG_AUTH_SCHEME Ключ OAuth-приложения ошибочно передан как Bearer-токен
401 INVALID_SESSION Bearer-сессия OAuth-приложения неизвестна или истекла
401 TOKEN_EXPIRED Истёкший пользовательский OAuth-токен не удалось обновить
401 NO_PORTAL Ключ не привязан к порталу
403 SESSION_APP_MISMATCH Bearer-сессия принадлежит другому приложению или порталу
403 MANAGEMENT_KEY_NO_ENTITY_ACCESS Передан management-ключ вместо ключа приложения

Полный список общих ошибок API — Ошибки.

Создание, изменение и удаление агентов доступны только в кабинете агентов. DELETE /v1/bots/:id удаляет самостоятельного чат-бота, а не AI-агента.

Смотрите также