# Список 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 — личный ключ

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

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

```bash
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`](/docs/openlines/config). Поле `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 — [Ошибки](/docs/errors).

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

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

- [AI-агенты](/docs/agents)
- [Конфигурации Открытых линий](/docs/openlines/config)
- [Ошибки API](/docs/errors)