# AI-агенты — полный текст документации

> Полный текст раздела «AI-агенты» документации Timeweb Cloud в markdown. Каждая статья начинается с заголовка первого уровня и ссылки на свою каноническую страницу.

Индекс: https://timeweb.cloud/docs/ai-agents/llms.txt
Статей: 43
Последнее обновление: 2026-08-18

# AI-агенты

Source: https://timeweb.cloud/docs/ai-agents?utm_source=llms_txt&utm_medium=ai

Платформа AI-агентов позволяет создавать виртуальных помощников на базе [генеративных моделей](https://timeweb.cloud/docs/ai-agents/pricing/models) искусственного интеллекта. 

Агентов можно использовать для различных задач, связанных с генерацией текстовых данных, например:

-   консультации и ответы на вопросы пользователей в формате чата;
-   анализ предоставленных данных и формирование отчетов;
-   ведение программ обучения для погружения новых сотрудников.

Платформа дает возможность добавлять собственные источники данных (базы знаний), чтобы агенты генерировали релевантные тексты по вашей тематике.

Перед внедрением агента в проект вы сможете протестировать его работу и детально настроить его под ваши требования с помощью плейграунда (песочницы) в панели управления.

Работать с AI-агентами можно:

-   **Через эндпоинты**

Каждый агент получает свой API-эндпоинт, который вы можете [интегрировать](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key) в свое приложение и настроить необходимые параметры. 

-   **Через чат-бот**

Любой из агентов может быть встроен на веб-страницу или в приложение [в качестве чат-бота](https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots).

-   **Через бот в мессенджере**

Агент может быть интегрирован в ваш бот [Telegram](https://timeweb.cloud/docs/ai-agents/manage-agents/telegram-bots) или [Макс](https://timeweb.cloud/docs/ai-agents/manage-agents/max-bots), чтобы клиенты могли взаимодействовать с ним через привычный мессенджер.

-   **Через внешний чат**

Можно вести диалог с агентами вне панели управления Timeweb Cloud [в отдельном интерфейсе чата](https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat). В нем доступны все агенты, созданные на аккаунте.

# Управление агентами

Source: https://timeweb.cloud/docs/ai-agents/manage-agents?utm_source=llms_txt&utm_medium=ai

-   [Создание агента](https://timeweb.cloud/docs/ai-agents/manage-agents/create)
-   [Промпты для агентов](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions)
-   [Смена или подключение базы знаний](https://timeweb.cloud/docs/ai-agents/manage-agents/change-knowledge-base)
-   [Настройка и тестирование агента](https://timeweb.cloud/docs/ai-agents/manage-agents/playground)
-   [Ключи доступа](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key)
-   [Встраивание чат-ботов](https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots)
-   [Вложения в чатах](https://timeweb.cloud/docs/ai-agents/manage-agents/attachments-in-chats)
-   [Внешний чат](https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat)
-   [Подключение Telegram-ботов](https://timeweb.cloud/docs/ai-agents/manage-agents/telegram-bots)
-   [Подключение Макс-ботов](https://timeweb.cloud/docs/ai-agents/manage-agents/max-bots)
-   [История чатов](https://timeweb.cloud/docs/ai-agents/manage-agents/chat-history)
-   [Включение веб-поиска](https://timeweb.cloud/docs/ai-agents/manage-agents/web-search)
-   [Приостановка и удаление агента](https://timeweb.cloud/docs/ai-agents/manage-agents/pause-remove)

# Создание агента

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/create?utm_source=llms_txt&utm_medium=ai

Чтобы создать нового AI-агента:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и нажмите «Создать» или «Добавить».
2.  Выберите ИИ-модель для агента. Ее можно будет изменить в дальнейшем.
3.  Настройте тариф агента. 
    

Стоимость агента составляет 1 рубль в месяц, а токены оплачиваются по [поресурсной модели](https://timeweb.cloud/docs/ai-agents/pricing/billing-models) pay-as-you-go. Входящие и исходящие токены тарифицируются отдельно. Списания за сервис выполняются с баланса каждый час.

**Лимит токенов.** Вы можете настроить [лимит потребления токенов](https://timeweb.cloud/docs/ai-agents/pricing/token-limit) в день, чтобы контролировать их расход. Лимит можно изменить в любой момент в дальнейшем.

**Веб-поиск.** Позволяет агенту [искать информацию в интернете](https://timeweb.cloud/docs/ai-agents/manage-agents/web-search). Эту настройку можно изменить в дальнейшем. Опция платная.

**Генерация изображений.** Позволяет [создавать изображения](https://timeweb.cloud/docs/ai-agents/manage-agents/image-generation) в чате с агентом. Эту настройку можно изменить в дальнейшем. Стоимость рассчитывается по токенам.

4.  Задайте промпт — [инструкцию для агента](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions).
    

Инструкция объясняет агенту, что он должен делать. 

В панели доступно несколько примеров инструкций — вы можете изучить их, чтобы ознакомиться с рекомендуемым форматом, или использовать для своего агента, скорректировав под ваши условия.

Вы также можете [написать свою инструкцию](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions#rekomendacii-dlya-sostavleniya-instrukcij) полностью с нуля. В ней нужно максимально четко указать, что должен представлять из себя агент, что ему необходимо делать, какие источники данных использовать.

5.  Подключите существующую [базу знаний](https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases) или создайте новую. Вы также можете создать базу позднее и подключить ее [в настройках агентах](https://timeweb.cloud/docs/ai-agents/manage-agents/change-knowledge-base). 
    

Базы знаний позволяют агентам формировать более полные и точные ответы, опираясь на предоставленные вами источники данных. Примеры баз знаний — документация по продукту, информация о ценах, каталоги товаров.

6.  Подключите существующий [MCP-сервер](https://timeweb.cloud/docs/ai-agents/mcp-server) или создайте новый. Вы также можете подключить MCP-сервер позднее и добавить его [в настройках агентах](https://timeweb.cloud/docs/ai-agents/manage-agents/change-knowledge-base). 
7.  Заполните информацию об агенте: удобное имя, комментарий, проект, в который его нужно добавить.
    
8.  Проверьте все выбранные параметры и нажмите «Заказать».
    

Запуск займет несколько минут, после чего вы сможете начать работу с агентом.

# Системные промпты для агентов

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/instructions?utm_source=llms_txt&utm_medium=ai

Промпт — это текстовый запрос, который определяет как модель должна формировать ответ. Существует два типа промптов:

-   **Промпт пользователя** — текст запроса от конечного пользователя.
-   **Системный промпт** — текстовая инструкция, определяющая поведение агента: его цель, роль, стиль общения и ограничения.

Системный промпт (также инструкция) — влияет на контекст, в котором агент интерпретирует запросы. Он передается с каждым запросом к модели при использовании как встроенного виджета, так и API. Правильно сформулированный промпт повышает точность и релевантность ответов.

Системные промпты позволяют адаптировать агента под конкретные сценарии. Например:

-   эксперт в конкретной области;
-   помощник с узкой специализацией;
-   персонаж с заданным стилем речи.

Перед запуском агента в проекте вы сможете протестировать его работу в плейграунде и дополнительно уточнить инструкцию.

## Как добавить инструкцию

Способ добавления инструкции зависит от выбранного способа использования агента:

### OpenAI-совместимый API

При использовании OpenAI-совместимого API системный промпт указывается при каждой отправке запроса — как сообщение [с ролью system](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#system).

### Виджет и нативный API

Для виджета и нативного API настройка системного промпта выполняется в панели управления. Указать инструкцию можно:

-   При [создании агента](https://timeweb.cloud/docs/ai-agents/manage-agents/create). Вы можете выбрать один из готовых примеров или ввести собственную инструкцию.
    

![4846b8dd Ba05 4961 8fec 82503fd96120 20251031163819993](https://content.timeweb.com/assets/53e996fa-c975-493d-9e9f-3a4a05581e95.png?width=996&height=584)

-   Позже — в разделе «Плейграунд», в настройках существующего агента.
    

![Image 20251101121333931](https://content.timeweb.com/assets/32995fbd-516b-4008-b1b9-cf95cca4a211.png?width=2008&height=1362)

## Рекомендации для составления инструкций

Чтобы создать максимально эффективную инструкцию, отразите в ней следующие ключевые моменты:

-   кем является агент (например, турагентом, сотрудником поддержки и т.д.), 
-   каковы его цели (давать ответы на вопросы, проверять корректность присланных данных, рекомендовать услуги);
-   на какие данные нужно ориентироваться (использовать те или иные ресурсы);
-   какие ограничения у него есть (какие темы можно обсуждать, на каких языках общаться).

#### 1\. Личность агента

Определите личность агента, указав его имя, задачи, область экспертизы. 

**Хороший пример:**

Тебя зовут Webby, ты — виртуальный помощник, который помогает пользователям находить ответы в документации Timeweb Cloud и предоставляет экспертные рекомендации на ее основе.

**Плохой пример:**

Ты — виртуальный помощник на сайте Timeweb Cloud.

#### 2\. Цель агента

Сформулируйте цели следующим образом:

-   Укажите основную цель агента.
-   Перечислите его ключевые обязанности и сферу действия.
-   Опишите его приоритеты, тип помощи и ограничения.

**Хороший пример:**

Твоя главная задача — помогать пользователям разобраться в сервисах Timeweb Cloud и использовать их. Ты должен предоставлять точные, понятные и полные ответы на основе документации Timeweb Cloud.

**Плохой пример:**

Отвечай на вопросы о сервисах Timeweb Cloud.

#### 3\. Экспертиза агента

Экспертиза агента — это области и темы, по которым агент может предоставить точные и релевантные ответы.

-   Используйте четкие формулировки.
-   Укажите конкретные функции агента.
-   Укажите, на какие данные и базы знаний он должен опираться.
-   Научите агента приводить примеры для объяснения сложных вопросов, брать их из проверенных источников и избегать вымышленных примеров.
-   Научите агента использовать пошаговые инструкции, форматируйте их с помощью таблиц или блоков кода.

**Хороший пример:**

Ты — специалист по сервисам Timeweb Cloud и устранению неполадок в них. Твой основной фокус — облачные базы данных, облачные серверы и Kubernetes.

В качестве главного источника истинной информации используй документацию Timeweb Cloud, в качестве дополнительного — инструкции Timeweb Cloud. Твои знания в первую очередь основаны на документации, во вторую — на данных из инструкций.

Никогда не придумывай информацию сам.

При ответе на технические вопросы составляй пошаговые инструкции и используй примеры из документации или инструкций Timeweb Cloud. Для наглядного представления информации используй таблицы. 

**Плохой пример:**

Ты знаешь всё о платформе Timeweb Cloud на базе ее документации. Не выдумывай ответы. Добавляй примеры, когда это полезно.

#### 4\. Темы и стиль общения

Сформулируйте рамки работы агента по тематикам и стилю общения:

-   Укажите, о чем агент может говорить, а какие темы ему запрещены.
-   Уточните основной язык общения и поддерживаемые языки.
-   Укажите необходимый стиль, тон общения.

**Хороший пример:**

Давай ответы только на основе документации и инструкций Timeweb Cloud. Не обсуждай с пользователями юридические вопросы или жалобы — в таких случаях отправляй клиента в поддержку.  

Ты понимаешь и используешь в общении только русский и английский языки. Если пользователь обращается на другом языке, вежливо попроси его сформулировать запрос на русском или английском.

Общайся с пользователями вежливо и доброжелательно, обращайся на «вы» с маленькой буквы.

**Плохой пример:**

Не отвечай на юридические вопросы или жалобы. Общайся только на русском и английском. Будь вежлив. 

#### 5\. Ограничения компетенций агента

-   Явно пропишите, что агент должен признать, если не знает ответа.
-   Научите агента задавать уточняющие вопросы при неясных или неполных запросах.
-   Научите агента отправлять пользователя в документацию или поддержку, если сам он помочь не может.

**Хороший пример:**

Если ты не знаешь ответа, скажи: У меня недостаточно информации, чтобы ответить на этот вопрос. Я с радостью помогу с чем-то еще.

Если запрос неполный, уточни детали: Пожалуйста, опишите подробнее, что вы хотите сделать.

Если чего-то не знаешь, явно сообщи об этом и рекомендуй обратиться в документацию Timeweb Cloud или в поддержку.

**Плохой пример:**

Если не можешь ответить, сообщи пользователю и дай ссылку на документацию.

# Подключение базы знаний

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/change-knowledge-base?utm_source=llms_txt&utm_medium=ai

[База знаний](https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases) — это материалы, из которых агент извлекает релевантную информацию при формировании ответов. Это могут быть, например, документация по вашему продукту или каталоги товаров.

Если вы не подключили базу знаний при создании агента или вам нужно изменить ее на другую, это можно сделать в панели управления.

1.  [Создайте базу знаний](https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases/create), если это еще не сделано.
    
2.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
    
3.  На вкладке «Управление» нажмите «Изменить» у базы знаний.
    

![503dd303 Cd0e 4263 9fd2 7c0a0b26e609](https://content.timeweb.com/assets/43a02a00-b8f3-41a0-abab-99bc50f8dc97.png?width=1520&height=818)

4.  Выберите нужную базу знаний и сохраните изменения.
    

![Без Названия](https://content.timeweb.com/assets/b32707e4-818b-4230-99d4-da8808caf85c.png?width=579&height=359)

# Тестирование и настройка агента (Плейграунд)

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/playground?utm_source=llms_txt&utm_medium=ai

Плейграунд («песочница») — это тестовая площадка, где вы можете проверить работу AI-агента и донастроить его под ваши требования.

![Scr 20250827 Mgvg](https://content.timeweb.com/assets/5eccae11-cd6c-4d58-a6df-a1755b64c425.png?width=2002&height=1372)

Чтобы протестировать агента:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
2.  Перейдите на вкладку «Плейграунд». Вы увидите промпт, заданный на этапе создания агента, настройки агента, а ниже — интерфейс чат-бота для взаимодействия с ним.
3.  Начните общение с агентом, чтобы оценить корректность и скорость ответа, а также степень детализации и стиль общения.
4.  Если нужно скорректировать работу агента, попробуйте изменить его параметры.

### Промпт

Уточните формулировки в инструкции для агента, допишите недостающие требования. Здесь вам помогут наши [рекомендации для инструкций](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions#rekomendacii-dlya-sostavleniya-instrukcij).

Нажмите «Сохранить изменения», чтобы применить новый промпт и снова протестируйте агента.

### Настройки агента

В блоке справа вы можете настроить параметры агента:

-   **Максимальное количество токенов** — задает максимальное количество токенов, которое модель может использовать для ответа. Чем выше значение, тем больше текста выдает модель в ответ.
-   **Температура** — задает степень креативности модели. Чем выше значение, тем более креативные, непредсказуемые (и не всегда корректные) ответы будет выдавать агент.
-   **Top P** — задает порог вероятности выбора слов. Чем выше значение, тем более разнообразны будут ответы. Более низкие значения обеспечат связность и сфокусированность ответов.
-   **Улучшать запрос для поиска** — если включено, агент переформулирует ваш запрос для более точного поиска в базе знаний. Выключите, чтобы искать строго по введенным словам и фразам.
-   **Штраф за присутствие** — снижает количество повторов, накладывая ограничение на токены, которые уже встречались в тексте. Чем больше значение, тем меньше повторений.
-   **Штраф за частоту** — снижает количество повторов на основе частоты появления токенов. Чем больше значение, тем меньше повторений.

Нажмите «Сохранить изменения», чтобы применить выбранные параметры к агенту, и протестируйте его работу.

# Ключи доступа

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key?utm_source=llms_txt&utm_medium=ai

Ключи доступа, или токены, необходимы для выполнения API-запросов к агенту.

Чтобы добавить ключ доступа:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
    
2.  На вкладке «Управление» нажмите «Изменить» в блоке «Доступ по API».
    

![Witty Cygnus 04 16 2026 10 36 Am](https://content.timeweb.com/assets/b3239833-aae1-40b9-80e7-c6de91f7a2ee.png?width=1586&height=869)

3.  Нажмите «Добавить новый ключ».
    
4.  Задайте удобное имя или оставьте значение по умолчанию и нажмите «Добавить».
5.  Скопируйте значение ключа и сохраните в надежном месте. Вы не сможете повторно посмотреть его в интерфейсе в панели.
    

![Witty Cygnus 04 16 2026 10 38 Am](https://content.timeweb.com/assets/28776b7b-7274-4bdc-abec-1ea713b1c0a9.png?width=1751&height=869)

Используйте полученный ключ в своем приложении или веб-сайте для авторизации запросов к агенту.

# Встраивание чат-ботов

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots?utm_source=llms_txt&utm_medium=ai

Чат-боты на базе AI-агентов можно встраивать в ваши приложения и веб-сайты, чтобы пользователи могли взаимодействовать с ними.

Чтобы настроить чат и получить код для его встраивания:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
    
2.  На вкладке «Интеграции» нажмите «Настроить» в блоке «Чат для встраивания».
    

![1ed812f3 9720 4eac B388 0ca38698f571](https://content.timeweb.com/assets/e6b2dbcc-318a-4728-a12e-89f0d38ff068.png?width=1565&height=809)

Откроется интерфейс управления чатом.

## Настройка внешнего вида чата

Во вкладке «Настройки» вы можете включить чат и настроить его внешний вид.

Управлять интерфейсом можно как перед встраиванием чата на сайт, так и в любой момент после.

Доступны следующие параметры:

-   Имя агента
-   Подпись для имени
-   Приветственное сообщение
-   Акцентный цвет
-   Шрифт
-   Иконку
-   Расположение виджета чата на сайте

![Чат](https://content.timeweb.com/assets/ed026d46-b750-4e2c-af09-97f20da0a946.png?width=1592&height=1160)

> [!NOTE]
> Выбранный шрифт не загружается вместе с чатом. Браузер будет использовать шрифт из системы пользователя, если он совпадает с указанным. В противном случае будет использоваться близкий аналог.

## Разрешенные домены

Во вкладке «Домены» вы можете указать, на каких сайтах разрешено использовать виджет. 

По умолчанию агент доступен для встраивания на любом домене. Но если вы добавите хотя бы один домен, использование ограничится только указанными адресами.

![846834d0 0bb4 429e 8bae 7475f034e331](https://content.timeweb.com/assets/465290ef-d8e3-4146-b614-686dddb5e1f7.png?width=1575&height=716)

## Код для вставки

Во вкладке «Вставка» отображается готовый код, который можно разместить на сайте. Просто скопируйте его и вставьте в HTML между тегами `<body></body>`.

![E8d87a52 F83a 4ee5 Bbdb A2c304705e32](https://content.timeweb.com/assets/039a652e-65cd-4e7c-b56b-43ae70bfdfc0.png?width=1571&height=718)

# Вложения в чатах

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/attachments-in-chats?utm_source=llms_txt&utm_medium=ai

При работе с агентом через [чат-бот](https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots), [внешний чат](https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat) или [Telegram](https://timeweb.cloud/docs/ai-agents/manage-agents/telegram-bots) пользователь может прикреплять к сообщениям текстовые файлы и изображения.

Опция полезна в сценариях, где агенту требуется анализ дополнительных материалов — например, скриншотов ошибок, фотографий чеков, накладных и других документов.

## Поддерживаемые форматы

Набор поддерживаемых форматов зависит от используемой модели:

**ChatGPT**: `.bash`, `.bat`, `.cmd`, `.c`, `.cpp`, `.cs`, `.csv`, `.doc`, `.docx`, `.gif`, `.go`, `.html`, `.java`, `.jpeg`, `.jpg`, `.js`, `.json`, `.jsx`, `.kt`, `.md`, `.pdf`, `.php`, `.png`, `.ps1`, `.py`, `.rb`, `.rs`, `.scala`, `.sh`, `.sql`, `.svelte`, `.swift`, `.ts`, `.tsx`, `.txt`, `.vue`, `.webp`, `.xls`, `.xlsx`, `.xml`, `.yaml`, `.yml`, `.zsh`.

**Claude**, **Gemini**: `.jpg`, `.png`, `.webp`, `.gif`.

**Grok**: `.jpg`, `.png`, `.webp`.

**DeepSeek**, **Yandex**, **Qwen**: Вложения в чате не поддерживаются.

Максимальный размер файла — 5 МБ. Можно прикрепить несколько файлов одновременно.

## Расход токенов

При обработке файлов агент расходует токены. **Очень приблизительно** расход токенов можно рассчитать по формулам ниже.

Изображение:

```shell
(Ширина / 512) * (Высота / 512) * 700
```

Текст на русском:

```shell
Количество символов / 3.5
```

Текст на английском: 

```shell
Количество символов / 4
```

# Внешний чат

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat?utm_source=llms_txt&utm_medium=ai

Внешний чат [Timeweb.AI](https://timeweb.ai/) — это интерфейс для общения с AI-агентами вне панели управления. Он позволяет работать с агентами в привычном формате диалога и использовать все их возможности.

При использовании внешнего чата сохраняются настройки агента, заданные в панели управления: системные промпты, подключения к MCP-серверам и база знаний.

## Запуск внешнего чата

Открыть внешний чат можно:

-   **Из панели Timeweb Cloud**

1.  1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и откройте страницу любого существующего агента.
    2.  В окне управления агентом нажмите кнопку «Внешний чат».

![143bf5b8 42ad 4b87 8d20 3db1b03147e2](https://content.timeweb.com/assets/6bad975a-d1b8-45c7-b215-da37d5061bbc.png?width=1565&height=869)

Чат откроется в новой вкладке браузера.

-   **По прямой ссылке**

Для доступа вы должны быть авторизованы в своем аккаунте Timeweb Cloud.

1.  1.  Перейдите на страницу [ai.timeweb.cloud](https://ai.timeweb.cloud/).
    2.  Кликните на любого агента в списке.

## Работа с чатами

Выберите агента, с которым будете работать. В списке отображаются все AI-агенты, созданные на вашем аккаунте.

При необходимости агента можно изменить позже — для этого используйте выпадающее меню в верхней части интерфейса.

![Image2](https://content.timeweb.com/assets/44e164dc-f544-4fd7-ba76-2ae05cabdf66.png?width=1999&height=1142)

Чтобы начать новый диалог, нажмите кнопку «Новый чат». После этого откроется новая сессия общения.

Слева отображается список всех созданных чатов с конкретным агентом. Вы можете переключаться между ними, чтобы продолжить предыдущий диалог или вернуться к более ранним сообщениям.

Нажмите на три точки рядом с именем аккаунта в левом нижнем углу, чтобы открыть меню. В нем можно перейти на [страницу настроек агента](https://timeweb.cloud/docs/ai-agents/manage-agents/playground), изменить тему, удалить все чаты или выйти из аккаунта.

## Настройка доступов

По умолчанию внешний чат доступен только владельцу аккаунта. Чтобы выдать доступ другим людям, например, отдельным сотрудникам или командам, вы можете создать дополнительных пользователей.

Пользователи, которым выдан доступ к внешнему чату, отображаются в разделе «AI-агенты» → «Настройки» → «Управлять».

### Создание нового пользователя

Чтобы выдать доступ:

1.  Перейдите в раздел «ИИ-сервисы» → «Настройки».
2.  Нажмите «Управлять».
3.  Кликните «Добавить» или «Добавить пользователя».
4.  Укажите емейл пользователя — он будет использоваться в качестве логина.
5.  Задайте пароль или оставьте значение по умолчанию. Пароль может быть длиной от 8 до 30 символов и содержать цифры, латинские буквы и спецсимволы.
6.  (Опционально) Укажите комментарий. Он будет виден только вам.
7.  Нажмите «Добавить».

На емейл пользователя придет письмо со ссылкой для входа. При первом логине будет возможность скопировать предложенный пароль и сохранить его.

Теперь пользователь может работать с агентами в интерфейсе [ai.timeweb.cloud](https://ai.timeweb.cloud/).

### Доступ для существующего пользователя

Если нужный пользователь уже [создан](https://timeweb.cloud/docs/iam/upravlenie-polzovatelyami) в панели управления, вы можете выдать ему доступ к внешнему чату:

1.  Перейдите в раздел «Настройки аккаунта» → [«Пользователи»](https://timeweb.cloud/my/account/users).
2.  Кликните на пользователя.
3.  Во вкладке «Права и доступы» выдайте права к разделам:
    -   AI-агенты — «Только просмотр»
    -   Внешний чат AI-агентов — «Управление»
4.  Сохраните изменения.

### Смена пароля

Изменить пароль пользователя может только владелец аккаунта. Это можно сделать напрямую в разделе «AI-агенты»:

1.  Перейдите в раздел «ИИ-сервисы» → «Настройки».
2.  Нажмите «Управлять».
3.  Кликните на три точки рядом с пользователем и нажмите «Редактировать».
4.  Задайте новый пароль и сохраните изменения.
5.  Передайте пароль пользователю — он не будет отправлен с нашей стороны.

Пароль также можно изменить в разделе «Настройки аккаунта» → [«Пользователи»](https://timeweb.cloud/my/account/users).

### Запрет доступа

Чтобы запретить пользователю доступ к внешнему чату, измените его настройки доступа:

1.  Перейдите в раздел «Настройки аккаунта» → [«Пользователи»](https://timeweb.cloud/my/account/users).
2.  Кликните на пользователя.
3.  Во вкладке «Права и доступы» выберите «Нет доступа» в пункте «Внешний чат AI-агентов».
4.  Сохраните изменения.

### Удаление пользователя

> [!NOTE]
> Это действие удалит пользователя **со всего аккаунта**, не только из раздела «AI-агенты». Если нужно сохранить доступ к другим разделам панели, но ограничить доступ к агентам, [поменяйте права](https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat#zapret-dostupa) пользователя.

Чтобы безвозвратно удалить пользователя:

1.  Перейдите в раздел «ИИ-сервисы» → «Настройки».
2.  Нажмите «Управлять».
3.  Кликните на три точки рядом с пользователем и нажмите «Удалить».
4.  Подтвердите действие.

# Подключение Telegram-ботов

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/telegram-bots?utm_source=llms_txt&utm_medium=ai

Вы можете интегрировать AI-агента в Telegram-бот, чтобы ваши клиенты могли общаться с агентом через мессенджер. К одному агенту можно подключить несколько ботов.

Для этого:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
2.  На вкладке «Интеграции» нажмите на карточку «Телеграм-боты».

![Scr 20260626 Oxvw](https://content.timeweb.com/assets/c914dc50-e5ef-49cf-91d1-8972500959f8.png?width=2122&height=1604)

3.  Введите API-токен вашего бота, полученный от BotFather при его создании.
4.  (Опционально) Укажите комментарий для бота. Он будет отображаться в панели управления.
5.  (Опционально) Если нужно, чтобы работать с агентом могли только конкретные Telegram-аккаунты, включите опцию «Ограничить доступ» и укажите их логины (без @). Ограничение действует как в личной переписке с ботом, так и в группах. Если у аккаунта нет доступа, бот ответит: «Создатель агента ограничил круг лиц, которые могут с ним общаться».
6.  Нажмите «Добавить».

![Scr 20260626 Oxzn](https://content.timeweb.com/assets/0ef83275-3a7f-4605-8115-86f3cf8fbe7e.png?width=2806&height=1660)

Теперь с агентом можно работать через ваш Telegram-бот.

# Подключение Макс-ботов

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/max-bots?utm_source=llms_txt&utm_medium=ai

Вы можете интегрировать AI-агента в бот Макс, чтобы ваши клиенты могли общаться с агентом через мессенджер. К одному агенту можно подключить несколько ботов.

Создание чат-ботов в Макс доступно только для и юридических лиц и ИП, у которых есть верифицированный профиль организации на [платформе Макс для партнеров](https://business.max.ru/self).

Создать чат-бот можно по инструкции [в документации Макс](https://dev.max.ru/docs/chatbots/bots-create), после чего необходимо дождаться успешного прохождения модерации. 

## Получение токена в Макс

После того, как модерация пройдена, [получите токен](https://dev.max.ru/docs/chatbots/bots-nocode/create#%D0%A2%D0%BE%D0%BA%D0%B5%D0%BD%20%D0%B1%D0%BE%D1%82%D0%B0) — уникальный идентификатор вашего бота.

1.  Откройте [платформу Макс для партнеров](https://business.max.ru/self) и перейдите в раздел «Чат-боты».
2.  Перейдите в раздел «Интеграция» и нажмите «Получить токен».
3.  Скопируйте значение токена.

## Подключение агента к боту

Теперь все готово к подключению бота Макс к вашему ИИ-агенту.

В панели Timeweb Cloud:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
2.  На вкладке «Интеграции» нажмите на карточку «Макс-боты».

![Scr 20260626 Oxvw](https://content.timeweb.com/assets/14cf1d99-de1a-49cf-a1ac-c0578f855fe9.png?width=2122&height=1604)

3.  Введите токен вашего бота, полученный [по инструкции выше](https://timeweb.cloud/docs/ai-agents/manage-agents/max-bots#poluchenie-tokena-v-maks).
    
4.  (Опционально) Укажите комментарий для бота. Он будет отображаться в панели управления.
    
5.  Нажмите «Добавить».
    

![Scr 20260626 Oyjj](https://content.timeweb.com/assets/55b50678-fae5-409b-b354-cded39066865.png?width=2750&height=1598)

Теперь с агентом можно работать через ваш Макс-бот.

# Интеграция с Jivo

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/jivo?utm_source=llms_txt&utm_medium=ai

AI-агента можно подключить к Jivo-чату, чтобы пользователи могли общаться с ним через канал связи Jivo.

Ограничения интеграции:

-   к одному боту в Jivo можно подключить одного AI-агента;
    
-   одного бота можно подключить к одному каналу связи;
    
-   подключить можно только AI-агентов.
    

## Регистрация в Jivo

Если у вас еще нет аккаунта Jivo, зарегистрируйтесь в сервисе:

1.  Перейдите на сайт [jivo.ru](https://www.jivo.ru/) и нажмите «Зарегистрироваться».
    
2.  Укажите емейл и пароль для аккаунта, затем согласитесь на обработку персональных данных.
    
3.  Заполните поля «Имя» и «Должность или отдел». При необходимости установите аватар и настройте цвета чата. Эти параметры можно будет изменить позднее.
    
4.  Выберите приглашение в чат.
    
5.  Укажите домен сайта или включите опцию «У меня пока нет вебсайта». Укажите номер телефона и страну ведения бизнеса.
    
6.  Выберите, для чего вы планируете использовать Jivo.
    
7.  Скачайте приложение или выберите «Я установлю программу позже».
    

После этого регистрация будет завершена.

При первой авторизации в панели управления Jivo вам будет предложено выбрать канал, через который будет вестись общение с пользователями.

Все каналы связи отображаются в разделе «Управление» → «Каналы связи».

![Интерфейс настройки jivo.ru](https://content.timeweb.com/assets/5109865f-7a44-4fc6-9ba7-b5487394f9fd.png?width=3392&height=1962)

_Интерфейс настройки [Jivo](https://www.jivo.ru/)_

Вы можете изменить имя канала связи: для этого нажмите «Настроить» рядом с нужным каналом. Имя канала потребуется при подключении бота.

## Подключение бота

Для подключения бота нужно получить Provider ID от поддержки Jivo.

Чтобы запросить Provider ID:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на агента, которого хотите подключить к Jivo.
    
2.  Откройте вкладку «Интеграции».
    
3.  Нажмите на карточку Jivo в разделе «Внешние сервисы».
    
4.  В открывшемся окне скопируйте сообщение для поддержки Jivo. В нем уже будут указаны адрес сервера для отправки событий и токен.
    

![Scr 20260626 Oxbb](https://content.timeweb.com/assets/13882c13-c49e-4900-9de6-c38fec87c14d.png?width=2788&height=1580)

5.  Вставьте сообщение в почтовом клиенте и укажите канал связи, к которому нужно подключить бота.
    
6.  Отправьте письмо на [info@jivosite.com](mailto:info@jivosite.com) с емейла администратора в Jivo.
    

В течение нескольких часов поддержка Jivo ответит и пришлет Provider ID.

![Сообщение от поддержки Jivo](https://content.timeweb.com/assets/3aa457f4-ec15-40d7-ae2a-beeedb72ce25.png?width=1550&height=672)

Чтобы завершить подключение:

1.  Скопируйте Provider ID из письма от поддержки Jivo.
    
2.  Вернитесь в настройки агента.
    
3.  Откройте вкладку «Интеграции» и настройки Jivo.
    
4.  Укажите полученное значение в поле «Provider ID».
    
5.  Нажмите «Сохранить».
    

## Проверка интеграции

После сохранения настроек проверьте работу интеграции: отправьте сообщение в чат Jivo.

Первым должен ответить AI-агент. Его ответ также будет отображаться в чате Jivo со стороны администратора.

Подключенного бота можно найти в панели Jivo в разделе «Управление» → «Расширения».

![Интерфейс настройки Jivo](https://content.timeweb.com/assets/ae2bd96c-1ff1-41ca-9062-cf17ff9cc308.png?width=3102&height=1966)

_Интерфейс настройки [Jivo](https://www.jivo.ru/)_

# История чатов

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/chat-history?utm_source=llms_txt&utm_medium=ai

Для оценки качества ответов агента вы можете просматривать все диалоги с ним во вкладке «История чатов».

Диалоги сохраняются при работе с агентом [через виджет чата на вашем сайте](https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots) или [через Telegram](https://timeweb.cloud/docs/ai-agents/manage-agents/telegram-bots), а также при тестировании агента [в плейграунде](https://timeweb.cloud/docs/ai-agents/manage-agents/playground).

При работе через API сообщения не сохраняются.

Для работы с историей чатов доступны фильтры:

1.  По реакциям.
2.  По среднему времени ответа.
3.  По периоду.

![Scr 20260114 Palq 2](https://content.timeweb.com/assets/10eace85-332d-46d5-a08b-31688c872120.png?width=2186&height=1518)

Нажав на кнопку скачивания, вы можете загрузить историю чатов в формате `.csv`. Перед скачиванием можно выбрать нужный период.

При скачивании выгружаются только 2000 последних сообщений.

![Scr 20260114 Ppvs](https://content.timeweb.com/assets/2bfb87a3-05dd-4e0e-b175-64699f6bb58f.png?width=2172&height=1538)

```shell
ID диалога,ID агента,ID сообщения,Время создания сообщения,Автор сообщения,Текст сообщения,Ответ понравился,Время ответа (с)
ai-agent-5755-c0381c41-7583-1824-bbd3-07d1fe32ae80,5755,,"02.12.2025, 7:48",,,,
,,5146985,"02.12.2025, 7:48",Пользователь,,,
,,5146987,"02.12.2025, 7:48",Пользователь,Что изображено на скрине?,,
,,5146993,"02.12.2025, 7:48",Бот,"Это кабинет Timeweb Cloud. Открыта страница виртуального роутера VR1 (статус «Включен») в разделе Сети. Активна вкладка «Статические маршруты» — сейчас маршрутов нет, есть кнопка «Добавить маршрут». Сверху — вкладки «Дашборд», «Приватные сети», «Статические маршруты», «Проброс портов», «Конфигурация». Слева — меню сервисов (облачные серверы, базы данных, Kubernetes и т. п.).",,
```

# Веб-поиск

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/web-search?utm_source=llms_txt&utm_medium=ai

Для того чтобы агент мог искать необходимую информацию в сети, можно подключить опцию веб-поиска.

Стоимость опции составляет 0,49 рублей за один запрос.

## Зачем нужен веб-поиск

Веб-поиск позволяет агенту обращаться к интернету в момент обработки запроса и получать актуальные данные о текущих событиях, ценах и изменившихся фактах. Без веб-поиска агент работает на основе знаний языковой модели, которая обучена на данных до определенной даты.

Веб-поиск полезен при работе с такой информацией, как:

-   Свежие новости и события
-   Текущие цены, курсы валют, рыночные данных
-   Изменяющиеся справочные данные (расписания, тарифы, контакты компаний)
-   Уточнение фактов, которые могли измениться с момента обучения модели
-   Поиск конкретных страниц и источников по запросу пользователя

Для получения информации используется поисковая система Яндекс.

## Когда агент использует веб-поиск

При включенном веб-поиске агент анализирует каждый входящий запрос и определяет, нужно ли искать дополнительную информацию в интернете:

-   Если запрос полностью покрывается знаниями модели, поиск не запускается.
-   Если для качественного ответа нужны актуальные данные, агент выполняет один или несколько поисковых запросов, получает результаты и использует их при формировании ответа.

> [!NOTE]
> Решение о выполнении поиска принимает сама модель. Принудительно запустить или запретить поиск для конкретного запроса нельзя.

## Ограничение области поиска

При создании агента или в дальнейшем [в его настройках](https://timeweb.cloud/docs/ai-agents/manage-agents/web-search#v-nastrojkah-sushchestvuushchego-agenta) вы можете ограничить область веб-поиска определенными доменами. В этом случае вместо поиска по всему интернету агент выполняет запрос только по указанным источникам.

![Witty Cygnus 06 04 2026 01 33 Pm 06 04 2026 01 45 Pm](https://content.timeweb.com/assets/d778161c-c100-4cb0-bd35-b95556c7f642.png?width=1742&height=869)

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

Функция особенно полезна в сценариях, где агент должен опираться на официальные данные или ограниченный перечень внешних ресурсов. 

## Настройка веб-поиска

Управлять настройками веб-поиска можно при создании агента и в его настройках.

### При создании агента

Оставьте опцию «Поиск в интернете» включенной или отключите ее на шаге «Тариф». Вы также можете сразу настроить [ограничение области поиска](https://timeweb.cloud/docs/ai-agents/manage-agents/web-search#ogranichenie-oblasti-poiska) либо сделать это позднее в настройках.

![Создать AI Агента 06 04 2026 01 37 Pm](https://content.timeweb.com/assets/fe352a49-5a3d-4540-9315-3692c2da45fb.png?width=751&height=618)

### В настройках существующего агента

Чтобы настроить поиск в интернете для существующего агента:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
2.  Перейдите на вкладку «Управление».
3.  Включите или выключите опцию «Поиск информации в интернете».

![Witty Cygnus 05 18 2026 09 51 Am](https://content.timeweb.com/assets/644cabb1-7ad2-462b-8d39-a1650143027a.png?width=1574&height=792)

4.  Если необходимо, включите [ограничение области поиска](https://timeweb.cloud/docs/ai-agents/manage-agents/web-search#ogranichenie-oblasti-poiska) и задайте разрешенные домены.
5.  Сохраните изменения.

![Witty Cygnus 06 04 2026 01 33 Pm](https://content.timeweb.com/assets/8bf561f0-d088-4b93-bd60-1d30983d4031.png?width=1742&height=869)

# Генерация изображений

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/image-generation?utm_source=llms_txt&utm_medium=ai

Опция генерации изображений позволяет создавать изображения по текстовому описанию в диалоге с агентом.

Агент самостоятельно определяет, является ли сообщение запросом на генерацию изображения, и передает его на обработку [image-модели](https://timeweb.cloud/docs/ai-agents/manage-agents/image-generation#dostupnye-modeli), выбранной при включении опции.

Если запрос не относится к генерации, агент ответит обычным текстовым сообщением.

Генерация изображений доступна при работе с агентом через [внешний чат](https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat) или [встраиваемый виджет](https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots).

Стоимость зависит от выбранной модели и считается по токенам — отдельно входящим (промпт) и исходящим (сгенерированное изображение).

## Доступные модели

При включении генерации изображений можно выбрать одну из следующих моделей:

-   **Gemini 3.1 Flash Image Preview** — быстрая модель для генерации иллюстраций, набросков и черновиков. Подходит для случаев, когда важна скорость и приемлемое качество. 
    
-   **Gemini 3 Pro Image Preview** — продвинутая модель с лучшей детализацией и качеством. Подходит для production-сценариев и финальных иллюстраций.
    
-   **GPT Image 2** — продвинутая модель для генерации изображений с высокой детализацией и точным следованием инструкциям. Подходит для создания финальных иллюстраций и сложных визуальных материалов.
    

Вы всегда можете изменить свой выбор и переключиться на другую модель [в настройках агента](https://timeweb.cloud/docs/ai-agents/manage-agents/image-generation#v-nastrojkah-sushchestvuushchego-agenta).

## Подключение и отключение генерации изображений

Включить или отключить генерацию изображений можно при создании агента или в настройках существующего агента.

### При создании агента

На шаге «Тариф» включите опцию «Генерация изображений» и выберите предпочтительную модель.

![Group 1321314413 05 21 2026 12 21 Pm](https://content.timeweb.com/assets/fc91f27e-29ad-4cd1-9b54-42e08b0aca5b.png?width=753&height=730)

### В настройках существующего агента

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
2.  Перейдите во вкладку «Управление».
3.  Нажмите «Изменить» в блоке «Генерация изображений».

![Witty Cygnus 05 21 2026 12 22 Pm](https://content.timeweb.com/assets/715caf00-271e-4662-b861-1f31cddf9029.png?width=1574&height=876)

4.  Включите или выключите опцию.
5.  При включении выберите в выпадающем списке модель для генерации изображений.
6.  Нажмите «Сохранить».

![Witty Cygnus 05 21 2026 12 23 Pm](https://content.timeweb.com/assets/5d0b944b-4d90-4e84-9884-039ad302f0b4.png?width=1741&height=868)

# Приостановка и удаление агента

Source: https://timeweb.cloud/docs/ai-agents/manage-agents/pause-remove?utm_source=llms_txt&utm_medium=ai

Вы можете в любой момент:

-   поставить агента на паузу;
-   полностью удалить агента.

## Приостановка агента

Вы можете временно приостановить агента, например, чтобы донастроить его работу и внешний вид, после чего запустить его снова.

После остановки агента виджет чата на вашем сайте перестанет отображаться. При обращении к агенту по API также будет возвращаться ошибка 400.

> [!NOTE]
> При приостановке агента сервис тарифицируется как обычно. Дата списания ежемесячной платы не изменится.

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты».
2.  Наведите курсор на нужного агента и нажмите на значок паузы.

![Без Названия (2)](https://content.timeweb.com/assets/f546c4aa-e5f3-4bb3-9446-72ce4dcf6157.png?width=1569&height=806)

3.  Подтвердите действие.

Другой вариант — кликнуть на нужного агента и нажать значок паузы справа вверху.

![Без Названия (3)](https://content.timeweb.com/assets/c42bd755-7f63-4c9d-9eda-e7f1763812a5.png?width=1535&height=825)

## Возобновление работы агента

Чтобы снова запустить агента после приостановки:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты».
2.  Наведите курсор на нужного агента и нажмите на значок старта.

![B2f4b8e1 D661 4915 80a1 3fd02f527a4b](https://content.timeweb.com/assets/7e2e435a-64d5-4ba9-b0f9-0820fbf41e31.png?width=1543&height=804)

Либо кликните на нужного агента и нажмите на значок старта справа вверху:

![796f87ca A972 4002 Af5b 76b86ab9fd8e](https://content.timeweb.com/assets/089fd2a6-6c47-4c02-9129-3cd46474517f.png?width=1565&height=815)

## Удаление агента

Если агент больше не требуется, вы можете удалить его полностью. Это действие необратимо.

> [!NOTE]
> Базы знаний, подключенные к агенту, удалены не будут. Если какие-то из них больше не нужны, вы можете удалить их вручную на вкладке «Базы знаний». Вместе с базой знаний будет автоматически удалена развернутая для нее [база данных](https://timeweb.cloud/my/database). 

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты».
2.  Наведите курсор на нужного агента, кликните на три точки справа и нажмите «Удалить».

![F2431aad 9e80 40d2 Bda5 7ce8828239c4](https://content.timeweb.com/assets/f1d46c5b-cf14-4144-95f2-96d8bd5c8f71.png?width=1538&height=807)

3.  Подтвердите действие.

Либо кликните на агента и нажмите значок удаления справа вверху.

![D87f9555 F2a4 45db 824d Db127abecbb0](https://content.timeweb.com/assets/c93f5e13-8fb6-44a1-9a79-8c64ed5b8e25.png?width=1565&height=815)

# Использование API

Source: https://timeweb.cloud/docs/ai-agents/api-usage?utm_source=llms_txt&utm_medium=ai

-   [Поддерживаемые типы API](https://timeweb.cloud/docs/ai-agents/api-usage/types-of-api)
-   [Нативный API](https://timeweb.cloud/docs/ai-agents/api-usage/native-api)
-   [OpenAI-совместимый API](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api)
-   [AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway)
-   [Files API в AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/files-api)
-   [Работа с аудио в AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/audio-api)
-   [Open WebUI](https://timeweb.cloud/docs/ai-agents/api-usage/open-webui)

# Поддерживаемые типы API

Source: https://timeweb.cloud/docs/ai-agents/api-usage/types-of-api?utm_source=llms_txt&utm_medium=ai

Мы поддерживаем три типа API для работы с AI-агентами и моделями:

-   [OpenAI-совместимый API](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api) — подходит для интеграции с внешними библиотеками и UI, использует стандартную структуру запросов;
-   [Нативный API](https://timeweb.cloud/docs/ai-agents/api-usage/native-api) — более простой в использовании, особенно если нужен быстрый результат без внешних зависимостей.
-   [AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway) — API для прямой работы с моделями без использования AI-агентов.

## Основные отличия

| **Характеристика** | **OpenAI-совместимый API** | **Нативный API** | **AI Gateway** |
| --- | --- | --- | --- |
| **Объект работы** | Агент | Агент | Модель |
| **Формат запроса** | `messages[]` | `message + parentMessageId` | `messages[], responses` |
| **История сообщений** | Передается в запросе | Сохраняется | Передается в запросе |
| **RAG / MCP** | Есть | Есть | Нет |
| **Настройки модели** | Через панель управления агента | Через параметры запроса | Передаются в каждом запросе |
| **Выбор модели** | Ограничен агентом | Ограничен агентом | Любая доступная |
| **Потоковые ответы** | Поддерживаются | Не поддерживаются | Поддерживаются |

## Какой API выбрать

Используйте OpenAI-совместимый API, если:

-   Вы хотите интегрировать агента с внешними библиотеками (например, LangChain, Open WebUI);
-   Уже используете OpenAI и хотите просто заменить URL;
-   Важно получать usage-статистику (токены, модель);
-   Требуются потоковые ответы;
-   Планируете использовать мультимодальные сообщения.

Используйте нативный API, если:

-   Нужна встроенная история сообщений без явной передачи контекста;
-   Вы создаете простое приложение с минимальной зависимостью от сторонних библиотек;
-   Важно получить ответ в простом формате;
-   Требуется быстрая и легкая интеграция, например, для MVP.

Используйте AI Gateway, если:

-   Нужно работать напрямую с моделями без логики агента;
-   Вы реализуете собственную логику (например, RAG или маршрутизацию запросов);
-   Требуется доступ к нескольким моделям через единый API;
-   Вы используете OpenAI SDK и хотите переключаться между моделями без изменения кода.

# Нативный API

Source: https://timeweb.cloud/docs/ai-agents/api-usage/native-api?utm_source=llms_txt&utm_medium=ai

Вы можете взаимодействовать с AI-агентами при помощи нативного API.

## Аутентификация

В каждом запросе необходимо [указывать API-токен](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key). 

Токен передается в формате:

```shell
--header "authorization: Bearer $TOKEN"
```

В cURL-примерах вы можете:

-   указать токен вручную, заменив `$TOKEN` на ваш реальный токен в каждом запросе;
-   или использовать переменную окружения, чтобы не вставлять токен каждый раз:

```shell
export TOKEN=ваш_токен_доступа
```

В этом случае менять заголовок в примерах не потребуется — переменная `$TOKEN` будет подставляться автоматически.

В примерах на Python и Node.js токен указывается напрямую в коде и обозначается как `{{token}}`. Мы рекомендуем хранить его в переменных окружения или конфигурационных файлах, а не в коде, чтобы избежать утечек.

## ID агента

Для работы с агентом также требуется его Access ID. Вы можете найти его во вкладке «Дашборд» в панели управления агентом.

![Access ID агента](https://content.timeweb.com/assets/db0b0fec-eb95-470b-b5c2-dba90b964c9f.png?width=2170&height=1750)

## Настройка агента

При использовании нативного API применяются настройки, указанные в разделе «[Плейграунд](https://timeweb.cloud/docs/ai-agents/manage-agents/playground)».

## Отправка сообщения агенту

Метод позволяет отправить сообщение AI-агенту и получить ответ.

**Запрос**:

```shell
POST /api/v1/cloud-ai/agents/{access_id}/call
```

cURL

```js
curl --request POST \
  --url https://api.timeweb.cloud/api/v1/cloud-ai/agents/<access_id>/call \
  --header "authorization: Bearer $TOKEN" \
  --header "content-type: application/json" \
  --data '{
    "message": "Привет!",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
  }'
```

Python

```py
import requests

url = "https://api.timeweb.cloud/api/v1/cloud-ai/agents/<access_id>/call"

payload = {
    "message": "Привет",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {{token}}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

Node.js

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.timeweb.cloud/api/v1/cloud-ai/agents/<access_id>/call',
  headers: {'content-type': 'application/json', authorization: 'Bearer {{token}}'},
  body: {message: 'Привет', parent_message_id: '3adfea84-bcdb-44b5-8914-92035e75ec24'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

Параметры:

-   `message` — текст запроса к агенту.
    
-   `parent_message_id` — ID сообщения для продолжения диалога. Параметр необязательный. В качестве значения можно использовать не только последний ответ, но и любой другой ID сообщения из чата.
    

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

```js
{
  "message": "ответ агента",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}
```

Значение `id` из ответа можно использовать как `parent_message_id` в следующих запросах.

Поле `finish_reason` указывает на причину завершения генерации ответа. Возможно четыре значения:

-   `stop` — ответ сгенерирован полностью, без ошибок;
-   `length` — ответ не уместился в [максимальное количество токенов](https://timeweb.cloud/docs/ai-agents/manage-agents/playground#nastrojki-agenta), поэтому генерация была прервана;
-   `content_filter` — сработал фильтр провайдера, предоставляющего доступ к AI (например, OpenAI или xAI), и генерация была остановлена. Под фильтрами подразумевается, например, цензурирование некоторых тем со стороны провайдера;
-   `error` — во время генерации произошла ошибка. Чтобы узнать причину, [создайте тикет в поддержку](https://timeweb.cloud/my/support/help-question) и приложите тело ответа.

# OpenAI-совместимый API

Source: https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api?utm_source=llms_txt&utm_medium=ai

OpenAI-совместимый API — это способ унифицировать структуру запросов и ответов к разным AI-провайдерам. Вместо того чтобы разбираться с десятками разных форматов, вы работаете с единым стандартом, понятным SDK, библиотекам и интерфейсам.

## Зачем нужна унификация

Сравним два варианта нативных API: `agent.timeweb.cloud` и условный `api.somerandomai.com`. Посмотрим, как у них реализована отправка сообщений.

![Aiapi Example](https://content.timeweb.com/assets/e16f7974-1fb9-427b-8f5b-2e021a6273e7.png?width=1316&height=1004)

При одинаковой задаче структура запросов сильно отличается. Например, в одном API для сохранения контекста используется параметр `parent_message_id`, а в другом — вложенный объект:

```js
"context": {
  "thread_id": "abc123",
  "reply_to": "msg789"
 },
```

Кроме того, при работе с нашим API настройки задаются отдельным запросом, а в примере стороннего API — передаются в объекте `settings` вместе с каждым сообщением.

В результате приходится:

-   Писать отдельный клиент под каждый API;
-   Разбираться с названиями полей и особенностями работы;
-   Тестировать все с нуля.

OpenAI-совместимый API решает эту проблему. Структура всегда одна и та же: массив `messages` с полями `role` и `content`, стандартные параметры (`model`, `temperature`, `max_tokens`). Отличия остаются только в URL и названии модели.

![Blue2](https://content.timeweb.com/assets/60563a27-fc57-4d02-9c60-d52398e5512c.png?width=1560&height=1218)

Чем это удобно:

-   Быстрая интеграция в любое ПО, которое поддерживает OpenAI API;
-   Поддержка популярных библиотек (например, LangChain);
-   Работа с готовыми UI (например, [Open WebUI](https://timeweb.cloud/docs/ai-agents/api-usage/open-webui));
-   Минимум усилий при миграции с OpenAI.

## Ограничения и особенности

В текущей реализации API не полностью совместим с OpenAI.

#### Не поддерживается:

-   `Embeddings` — эндпоинт `/v1/embeddings` отсутствует;
-   `Fine-tuning` — обучение и кастомизация моделей;
-   `Images API` — генерация изображений;
-   `Audio API` — преобразование речи в текст и обратно (кроме аудиосообщений в чате);
-   `Assistants API` — создание и управление ассистентами;

#### Особенности реализации:

-   Указанная в запросе модель игнорируется — используется модель, заданная в настройках агента.
-   Некоторые параметры могут игнорироваться в зависимости от выбранной модели агента.
-   [Промпт, указанный в настройках AI-агента](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions), используется при запросах без явного указания.

## Использование

Рассмотрим, как использовать OpenAI-совместимый API.

> [!NOTE]
> Все доступные методы API можно найти [в документации](https://agent.timeweb.cloud/docs).

### Аутентификация

Вне зависимости от выбранного типа API (приватный или публичный), для отправки запросов необходимо [указывать API-токен](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key).

Токен передается в заголовке запроса в следующем формате:

```shell
Authorization: Bearer $TOKEN
```

В cURL-примерах вы можете:

-   указать токен вручную, заменив `$TOKEN` на ваш реальный токен в каждом запросе;
    
-   или использовать переменную окружения, чтобы не вставлять токен каждый раз:
    

```shell
export TOKEN=ваш_токен_доступа
```

В этом случае менять заголовок в примерах не потребуется — переменная `$TOKEN` будет подставляться автоматически.

В примерах на Python и Node.js токен указывается напрямую в коде и обозначается как `{{token}}`. Мы рекомендуем хранить его в переменных окружения или конфигурационных файлах, а не в коде, чтобы избежать утечек.

### Базовый URL

Для работы с API также потребуется базовый URL. Вы можете найти его во вкладке «Дашборд» в панели управления агентом.

![Scr 20251003 Phme](https://content.timeweb.com/assets/7ac4875b-9324-4552-a992-be4953102a21.png?width=1524&height=1750)

### Отправка сообщения агенту

Поддерживается два способа — Chat Completions и Text Completions. Способ Text Completions считается устаревшим и реализован только для поддержания обратной совместимости, мы не рекомендуем его использовать.

#### Пример использования Chat Completions

```shell
POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions
```

cURL

```js
curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "model": "gpt-4.1",
  "messages": [
    {
      "role": "user",
      "content": "Привет!"
    }
  ],
  "temperature": 1,
  "max_tokens": 100,
  "stream": false
}'
```

Python

```py
import requests

url = "https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions"

payload = {
    "model": "gpt.1",
    "messages": [
        {
            "role": "user",
            "content": "Привет!"
        }
    ],
    "temperature": 1,
    "max_tokens": 100,
    "stream": False
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

Node.js

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    model: 'gpt.1',
    messages: [{role: 'user', content: 'Привет!'}],
    temperature: 1,
    max_tokens: 100,
    stream: false
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

**Параметры**:

-   `model` — необязательный, игнорируется (для совместимости).
    
-   `messages` — массив сообщений:
    

-   `role` — [роль отправителя](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#roli) (`user`, `assistant`, `system`),
    
-   `content` — текст сообщения.
    

-   `temperature` — креативность ответа.
    
-   `max_tokens` — ограничение длины ответа.
    
-   `stream` — потоковый вывод (true/false).
    

> [!NOTE]
> Для моделей `gpt-5` параметр `max_tokens` заменен на `max_completion_tokens`, а использование `temperature` вызовет ошибку.

Дополнительные параметры могут отличаться в зависимости от модели. При составлении запроса ориентируйтесь на параметры, доступные в панели управления для выбранной модели: если параметр есть в панели, значит он поддерживается при обращении через API.

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

```js
{
  "id": "fc8cd652-af12-4a89-8ef7-490a0526e8d3",
  "object": "chat.completion",
  "created": 1757601532,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь? 😊"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}
```

#### Пример использования Text Completions

```shell
POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/completions
```

cURL

```bash
curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "prompt": "Привет!",
  "model": "gpt-4.1",
  "max_tokens": 100,
  "temperature": 0.7,
  "top_p": 0.9,
  "n": 1,
  "stream": false,
  "logprobs": null,
  "echo": false,
  "stop": [
    "\n"
  ],
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "best_of": 1,
  "user": "timeweb"
}'
```

Python

```py
import requests

url = "https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions"

payload = {
    "prompt": "Привет!",
    "model": "4.1",
    "max_tokens": 100,
    "temperature": 0.7,
    "top_p": 0.9,
    "n": 1,
    "stream": False,
    "logprobs": None,
    "echo": False,
    "stop": ["
"],
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "best_of": 1,
    "user": "timeweb"
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

Node.js

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    prompt: 'Привет!',
    model: 'gpt-4.1',
    max_tokens: 100,
    temperature: 0.7,
    top_p: 0.9,
    n: 1,
    stream: false,
    logprobs: null,
    echo: false,
    stop: ['\n'],
    presence_penalty: 0,
    frequency_penalty: 0,
    best_of: 1,
    user: 'timeweb'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

**Параметры**:

-   `prompt` — текст запроса.
    
-   `model` — игнорируется, указывается для совместимости.
    
-   `max_tokens` — ограничение длины ответа.
    
-   `temperature` — уровень креативности.
    
-   `top_p` — выборка по вероятностям.
    
-   `n` — количество вариантов ответа (игнорируется).
    
-   `stream` — потоковый вывод.
    

Остальные параметры (`logprobs`, `echo`, `stop`, `presence_penalty`, `frequency_penalty`, `best_of`, `user`) поддерживаются частично и в основном для совместимости.

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

```js
{
  "id": "7f967459-428c-46ad-87f0-213ff951024d",
  "object": "text_completion",
  "created": 1757601892,
  "model": "gpt-4.1",
  "choices": [
    {
      "text": "Привет! Чем могу помочь? 😊",
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  },
  "response_id": "ea9aa124-0c51-467c-9ab6-218ab4ec65e7"
}
```

## Роли

В режиме **Chat Completions** каждое сообщение передается с указанием роли. Существует три типа ролей:

-   **user** — пользовательский запрос;
-   **assistant** — ответ модели;
-   **system** — инструкция, определяющая поведение агента.

### user

Роль `user` используется для передачи обычных запросов пользователя к ИИ.

**Пример**:

```js
{
  "role": "user",
  "content": "Сколько будет 2+5?"
}
```

### assistant

Роль `assistant` применяется при передаче истории сообщений. Она указывает, что это ответ ИИ на предыдущий запрос.

Важно помнить, что при работе с OpenAI-совместимым API история диалога передается в каждом запросе, поэтому необходимо указывать как запросы (`user`), так и ответы (`assistant`), чтобы сохранить контекст.

**Пример**:

```bash
curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Сколько будет 2+5? Напиши только ответ без форматирования"
    },
    {
      "role": "assistant",
      "content": "7"
    },
    {
      "role": "user",
      "content": "Теперь умножь получившееся число на 2. Напиши только ответ без форматирования"
    }
  ]
}'
```

В запросе мы передали предыдущий вопрос и ответ, указав `"role": "user"` для сообщений пользователя и `"role": "assistant"` — для ответов ИИ. Последнее сообщение с ролью `user` остается без ответа — именно на него модель сгенерирует новый ответ.

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

```bash
{
  "index": 0,
  "message": {
    "role": "assistant",
    "content": "14",
    "refusal": null,
    "annotations": []
  },
  "finish_reason": "stop"
}
```

### system

Роль `system` используется для задания системного промпта — инструкции, которая определяет поведение агента: стиль, тон, ограничения, цели. Обычно это первое сообщение в массиве messages.

Подробнее о системных промптах [написали в отдельной статье](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions).

Если посмотреть на пример использования `assistant`, можно заметить, что в запросах пользователя повторяется инструкция:

```shell
Напиши только ответ без форматирования
```

Это дублирование можно избежать, указав инструкцию один раз в системном промпте.

**Пример**:

```bash
curl --request POST \
  --url https://agent.timeweb.cloud/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "При ответе на вопросы отправляй только результат вычислений, без какого-либо форматирования."
    },
    {
      "role": "user",
      "content": "Сколько будет 2+5?"
    },
    {
      "role": "assistant",
      "content": "7"
    },
    {
      "role": "user",
      "content": "Теперь умножь получившееся число на 2"
    }
  ]
}'
```

Теперь модель будет следовать инструкции, даже если она не повторяется в каждом запросе пользователя.

# AI Gateway

Source: https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway?utm_source=llms_txt&utm_medium=ai

AI Gateway — это API для работы напрямую с языковыми моделями без использования AI-агентов.

В отличие от [OpenAI-совместимого API](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api) и [нативного API](https://timeweb.cloud/docs/ai-agents/api-usage/native-api), AI Gateway не предоставляет возможности агентов, такие как:

-   RAG;
-   MCP;
-   Системные настройки (системный промпт, температура, ограничения на длину ответа).

AI Gateway подходит, когда требуется работать с моделями напрямую, без логики AI-агента.

Например:

-   если вы реализуете собственную логику поверх моделей (строите RAG, подключение MCP);
-   если нужна единая точка доступа к нескольким моделям;
-   если вы уже используете OpenAI SDK и хотите переключаться между моделями без изменения кода.

Отличия AI Gateway от OpenAI-совместимого API:

|  | **OpenAI-совместимый API** | **AI Gateway** |
| --- | --- | --- |
| **Объект работы** | Агент | Модель |
| **RAG / MCP** | Есть | Нет |
| **Системные настройки** | Можно задать в панели управления агента | Передаются с каждым запросом |
| **Выбор модели** | Модель агента | Любая доступная |

Для работы с API рекомендуется использовать OpenAI SDK — он абстрагирует различия и упрощает интеграцию.

Поддерживаемые методы и возможности зависят от используемой модели. Например, эндпоинт `responses` доступен только для моделей с поддержкой размышлений.

В AI Gateway не поддерживаются:

-   `Fine-tuning` — обучение и кастомизация моделей;
-   `Video API` — работа с видео.

## Подключение

Для подключения к AI Gateway перейдите во вкладку «AI Gateway» в разделе «ИИ-сервисы».

В интерфейсе доступны две вкладки:

-   «API-ключи»
    
-   «Подключение»
    

### Создание API-ключа

AI Gateway использует отдельные ключи, не связанные с API-ключами аккаунта.

> [!NOTE]
> Каждый API-ключ тарифицируется отдельно и стоит 1 ₽ в месяц.

Для создания ключа перейдите во вкладку «API-ключи» и нажмите кнопку «Добавить». Укажите имя ключа и сохраните его.

![Scr 20260401 Mudf](https://content.timeweb.com/assets/57774c32-37bc-49b7-b317-c6770f2d0f9e.png?width=2498&height=1648)

Скопируйте полученный ключ и сохраните его локально.

### Удаление API-ключа

Чтобы удалить API-ключ, перейдите во вкладку «API-ключи», нажмите на три точки напротив нужного ключа и нажмите кнопку «Удалить». В открывшемся окне подтвердите удаление.

![Scr 20260401 Munj](https://content.timeweb.com/assets/8ead0da7-ec8f-4255-bd0c-62c456c0bc20.png?width=2056&height=1574)

### Получение параметров подключения

После создания API-ключа перейдите во вкладку «Подключение».

Выберите модель и язык программирования. В интерфейсе отобразится стоимость входящих и исходящих токенов для выбранной модели.

Ниже будет приведен пример кода для подключения и команда для установки библиотеки OpenAI.

![Scr 20260401 Muyu](https://content.timeweb.com/assets/6df63a49-57d1-4539-82c1-1580577cf8f7.png?width=2084&height=1612)

## Использование

Для работы с AI Gateway рекомендуем использовать OpenAI SDK — с ним не нужно вручную отправлять HTTP-запросы и интеграция становится проще.

Доступные SDK:

-   [Python](https://github.com/openai/openai-python) 
    
-   [Node.js](https://github.com/openai/openai-node)
    
-   [Java](https://github.com/openai/openai-java)
    
-   [Go](https://github.com/openai/openai-go)
    

Полный список SDK доступен [в репозитории OpenAI](https://github.com/orgs/openai/repositories).

В примерах ниже мы используем Python и библиотеку `openai`. Установить ее можно с помощью `pip`:

```bash
pip install openai
```

### Отправка запроса

Для отправки сообщений используется метод `Chat Completions`. При его использовании сообщения передаются в массиве `messages`.

Каждое сообщение содержит:

-   `role` — [роль отправителя](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#roli) (`user`, `assistant`, `system`);
-   `content` — текст сообщения.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Отвечай кратко и по существу.",
        },
        {
            "role": "user",
            "content": "Объясни, что такое Kubernetes",
        },
    ],
)

print(response.choices[0].message.content)
```

Параметры:

-   `api_key` — API-ключ AI Gateway. Замените значение на ваш ключ.
    
-   `base_url` — базовый URL для подключения к AI Gateway.
    
-   `model` — имя используемой модели. Укажите модель, которую хотите использовать.
    
-   `messages` — массив сообщений с ролями и текстом.
    

### Отправка запроса с историей сообщений

Чтобы сохранить контекст диалога, передавайте предыдущие сообщения в массиве `messages`:

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Отвечай только короткими фразами.",
        },
        {
            "role": "user",
            "content": "Сколько будет 2 + 5?",
        },
        {
            "role": "assistant",
            "content": "7",
        },
        {
            "role": "user",
            "content": "Теперь умножь результат на 2",
        },
    ],
)

print(response.choices[0].message.content)
```

В примере передаются предыдущие сообщения (`assistant` и `user`), чтобы сохранить контекст диалога.

### Отправка запроса (Responses API)

`Responses API` — более новый способ работы с моделями. Он упрощает структуру запроса и не требует явного формирования массива `messages`.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Отвечай кратко и по существу.",
    input="Объясни, что такое Kubernetes"
)

print(response.output_text)
```

Параметры:

-   `model` — имя используемой модели;
    
-   `instructions` — инструкция для модели (аналог системного промпта);
    
-   `input` — текст запроса.
    

### Отправка запроса с историей сообщений (Responses API)

Чтобы сохранить контекст диалога при использовании Responses API, укажите `previous_response_id` — идентификатор предыдущего ответа.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Отвечай только короткими фразами.",
    input="Сколько будет 2 + 5?"
)

next_response = client.responses.create(
    model="MODEL_NAME",
    instructions="Отвечай только короткими фразами.",
    previous_response_id=response.id,
    input="Теперь умножь результат на 2"
)

print(next_response.output_text)
```

В этом примере первый запрос возвращает объект ответа, содержащий уникальный идентификатор `id`. Этот идентификатор передается в параметре `previous_response_id` при следующем запросе, что позволяет продолжить диалог без передачи всей истории сообщений.

Параметр `model` необходимо указывать в каждом запросе, включая последующие вызовы с `previous_response_id`.

### Получение списка моделей

AI Gateway позволяет получить список доступных моделей:

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

models = client.models.list()

for model in models.data:
    print(model.id)
```

Метод `models.list()` возвращает список моделей, которые можно использовать в параметре `model`.

### Использование embeddings

`Embeddings` используются для преобразования текста в векторное представление. Это может применяться, например, для поиска по смыслу, кластеризации или работы с RAG.

В AI Gateway для создания embeddings доступна модель `openai/text-embedding-3-large`.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.timeweb.ai/v1"
)

response = client.embeddings.create(
    model="openai/text-embedding-3-large",
    input="Текст для векторизации",
)

print(response.data[0].embedding)
```

Метод возвращает векторное представление переданного текста.

# Files API в AI Gateway

Source: https://timeweb.cloud/docs/ai-agents/api-usage/files-api?utm_source=llms_txt&utm_medium=ai

Files API позволяет загружать файлы в AI Gateway и передавать их моделям в запросах. Это удобно, когда модели нужно обработать документ, таблицу, текстовый файл или другой материал, который не требуется каждый раз вставлять в тело запроса.

Файл загружается один раз, после чего AI Gateway возвращает его идентификатор. Этот идентификатор можно использовать в последующих запросах к модели.

## Подготовка токена

Для работы с Files API нужен [API-ключ AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#sozdanie-api-klucha). Создать ключ можно в разделе «ИИ-сервисы» во вкладке «AI Gateway» → «API-ключи».

В примерах используется переменная окружения `TIMEWEB_AI_TOKEN`, чтобы не указывать ключ напрямую в каждом запросе. На Linux и macOS переменную можно задать командой:

```bash
export TIMEWEB_AI_TOKEN="ваш_API-ключ"
```

После этого значение переменной будет доступно в текущей сессии терминала. Чтобы переменная сохранялась после перезапуска терминала, добавьте эту же строку в файл конфигурации вашей оболочки, например `~/.zshrc` для zsh или `~/.bashrc` для bash.

## Методы API

Ниже приведены методы для работы с файлами через API. Для запросов к уже загруженному файлу используется идентификатор `file_id`, который возвращается при загрузке.

### Загрузка файла

Чтобы загрузить файл, отправьте POST-запрос на эндпоинт `/v1/files`:

```bash
curl --request POST \
 --url https://api.timeweb.ai/v1/files \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@<file_path>" \
 --form "target_model_names=openai/gpt-4.1"
```

Параметры:

-   `purpose` — назначение файла. В AI Gateway поддерживаются только значения `user_data` и messages. Значение `user_data` используется для работы с файлами в запросах к моделям, `messages` доступно при работе с моделями Claude. Другие значения `purpose` не поддерживаются.
    
-   `file` — путь к локальному файлу. Перед путем указывается символ `@`, например `file=@/Users/timeweb_cloud/test.txt`.
    
-   `target_model_names` — имена моделей, для которых загружается файл. Если файл должен быть доступен нескольким моделям, перечислите их через запятую, например `target_model_names=openai/gpt-4.1,openai/gpt-5`. Корректные имена моделей можно найти во вкладке «Подключение» в разделе AI Gateway.
    

Загруженный файл будет доступен только для модели, указанной в параметре `model`.

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

```js
{
 "id": "file-bGl0ZWxsbTpmaWxlLUdmMWRD1mDEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "testfile.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}
```

Для дальнейшей работы с файлом используйте значение поля `id`.

### Получение информации о файле

Метод позволяет получить метаданные загруженного файла:

```bash
curl --request GET \
 --url https://api.timeweb.ai/v1/files/<file_id> \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN"
```

Где `file_id` — идентификатор файла, полученный при загрузке.

### Получение содержимого файла

Метод `/content` реализован для совместимости с Files API и дальнейшего расширения сценариев работы с файлами:

```bash
curl --request GET \
 --url https://api.timeweb.ai/v1/files/<file_id>/content \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN"
```

Получение содержимого доступно только для подходящих значений purpose, например для сценариев `fine-tuning`. Такие сценарии сейчас не поддерживаются в AI Gateway. Для файлов с `purpose=user_data` или `purpose=messages` метод для чтения содержимого файла не используется.

### Удаление файла

Чтобы удалить файл, отправьте DELETE-запрос:

```bash
curl --request DELETE \
 --url https://api.timeweb.ai/v1/files/<file_id> \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN"
```

После удаления идентификатор файла нельзя использовать в запросах к модели.

## Пример работы с файлом

Рассмотрим пример с загрузкой текстового файла `test.txt`, который расположен по пути `/Users/timeweb_cloud/test.txt`.

```bash
curl --request POST \
 --url https://api.timeweb.ai/v1/files \
 --header "authorization: Bearer $TIMEWEB_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@/Users/timeweb_cloud/test.txt" \
 --form "target_model_names=openai/gpt-4.1"
```

В параметре `file` указан полный путь к файлу на локальном компьютере. Если файл находится в текущей директории терминала, можно указать относительный путь, например `file=@test.txt`.

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

```js
{
 "id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "test.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}
```

После загрузки файл можно передать модели в Responses API. Для этого в запросе используется объект с типом `input_file`, а в поле `file_id` передается идентификатор из ответа на загрузку:

```shell
curl https://api.timeweb.ai/v1/responses \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $TIMEWEB_AI_TOKEN" \
 --data '{
   "model": "openai/gpt-4.1",
   "input": [
     {
       "role": "user",
       "content": [
         {
           "type": "input_text",
           "text": "Прочитай загруженный файл и кратко перескажи, что в нем написано."
         },
         {
           "type": "input_file",
           "file_id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI"
         }
       ]
     }
   ]
 }'
```

Модель в запросе должна совпадать с моделью, для которой файл был загружен.

# Работа с аудио в AI Gateway

Source: https://timeweb.cloud/docs/ai-agents/api-usage/audio-api?utm_source=llms_txt&utm_medium=ai

В AI Gateway доступны модели для синтеза и распознавания речи. С их помощью можно озвучивать тексты, добавлять голосовые ответы в приложения, расшифровывать звонки и преобразовывать другие аудиозаписи в текст.

Для синтеза речи, или TTS (Text-to-Speech), используется модель `openai/gpt-4o-mini-tts`. Для распознавания речи, или STT (Speech-to-Text), доступны модели `openai/gpt-4o-mini-transcribe` и `openai/gpt-4o-transcribe`.

## Возможности синтеза речи

Модель `openai/gpt-4o-mini-tts` создает аудио на основе переданного текста. Модель поддерживает русский и другие языки, а также позволяет управлять звучанием речи с помощью инструкции: например, задать темп, интонацию, эмоциональную окраску или тон.

Для генерации можно выбрать один из голосов:

-   `alloy`;
-   `ash`;
-   `ballad`;
-   `coral`;
-   `echo`;
-   `fable`;
-   `nova`;
-   `onyx`;
-   `sage`;
-   `shimmer`;
-   `verse`;
-   `marin`;
-   `cedar`.

Послушать примеры голосов можно на сайте [OpenAI.fm](https://openai.fm/).

Поддерживаются следующие форматы аудио:

-   `mp3` — используется по умолчанию;
-   `opus` — подходит для потоковой передачи и голосовой связи;
-   `aac` — формат сжатия, который используется, например, на мобильных устройствах;
-   `flac` — формат сжатия без потери качества;
-   `wav` — несжатое аудио;
-   `pcm` — необработанные аудиоданные без заголовка файла.

Форматы `wav` и `pcm` подходят для сценариев, в которых важна минимальная задержка. AI Gateway также поддерживает потоковую передачу: воспроизведение можно начать до завершения генерации всего аудио.

## Возможности транскрибации

Модели `openai/gpt-4o-mini-transcribe` и `openai/gpt-4o-transcribe` преобразуют речь из аудиофайла в текст. Язык записи можно определить автоматически или указать в запросе явно.

Для транскрибации можно использовать файлы следующих форматов: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav` и `webm`. Результат можно получить в формате `json` или обычного текста.

В запросе также можно передать параметр `prompt` с дополнительным контекстом. Он помогает модели правильно распознавать:

-   имена и фамилии;
-   названия продуктов и компаний;
-   аббревиатуры;
-   профессиональные термины;
-   слова, написание которых сложно определить только по произношению.

Если запись разделена на несколько фрагментов, в `prompt` можно передавать текст предыдущего фрагмента. Это помогает модели сохранять контекст между запросами.

## Как считаются токены

В аудиомоделях учитываются текстовые токены и аудиотокены. Текстовые токены зависят от объема текста, а аудиотокены — от продолжительности аудио.

При синтезе речи (TTS-модели):

-   `input_tokens` — текстовые токены переданного текста;
    
-   `output_tokens` — аудиотокены созданной записи. Одна секунда аудио считается за один аудиотокен.
    

Например, если модель создала аудио продолжительностью четыре секунды, будет учтено четыре выходных аудиотокена. Количество входных текстовых токенов зависит от длины исходного текста.

При транскрибации (STT-модели):

-   `input_tokens` — аудиотокены исходной записи: примерно 10 токенов за одну секунду;
    
-   `output_tokens` — текстовые токены расшифровки.
    

Например, для записи продолжительностью 10 секунд будет потрачено примерно 100 входных аудиотокенов. Количество выходных текстовых токенов зависит от длины расшифровки.

## Ограничения и особенности

-   Аудиомодели доступны только в AI Gateway.
    
-   Потоковая генерация и воспроизведение речи поддерживаются только для TTS.
    
-   Транскрибация звука с микрофона в реальном времени не поддерживается.
    
-   Для транскрибации доступны форматы ответа `json` и `plain text`.
    

## Подключение

Для работы с аудиомоделями нужен [API-ключ AI Gateway](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#sozdanie-api-klucha). Создать его можно в разделе «ИИ-сервисы» во вкладке «AI Gateway» → «API-ключи».

В примерах используется переменная окружения `TIMEWEB_AI_TOKEN`, чтобы не указывать ключ непосредственно в коде. В Linux и macOS ее можно задать командой:

```bash
export TIMEWEB_AI_TOKEN="ваш_API-ключ"
```

Установите библиотеку OpenAI:

```bash
pip install openai
```

Создайте клиент и укажите базовый URL AI Gateway:

```py
import os
​
from openai import OpenAI
​
​
client = OpenAI(
   api_key=os.environ["TIMEWEB_AI_TOKEN"],
   base_url="https://api.timeweb.ai/v1",
)
```

## Синтез речи

Для синтеза речи используется метод `audio.speech.create()`.

### Создание аудиофайла

В следующем примере модель озвучивает текст и сохраняет результат в файл `speech.mp3`:

```py
import os
from pathlib import Path
​
from openai import OpenAI
​
​
client = OpenAI(
   api_key=os.environ["TIMEWEB_AI_TOKEN"],
   base_url="https://api.timeweb.ai/v1",
)
​
speech_file = Path("speech.mp3")
​
with client.audio.speech.with_streaming_response.create(
   model="openai/gpt-4o-mini-tts",
   voice="shimmer",
   input="Привет! Это проверка синтеза речи.",
   instructions="Говори спокойно и доброжелательно.",
   response_format="mp3",
) as response:
   response.stream_to_file(speech_file)
```

Параметры:

-   `model` — модель для синтеза речи;
    
-   `voice` — голос, которым будет озвучен текст;
    
-   `input` — текст для озвучивания;
    
-   `instructions` — инструкция, определяющая манеру речи;
    
-   `response_format` — формат созданного аудио.
    

### Потоковое воспроизведение

Чтобы начать воспроизведение до завершения генерации, используйте асинхронный клиент и `LocalAudioPlayer`.

Для работы `LocalAudioPlayer` установите библиотеки `numpy` и `sounddevice`:

```bash
pip install numpy sounddevice
```

Пример потокового воспроизведения:

```py
import asyncio
import os
​
from openai import AsyncOpenAI
from openai.helpers import LocalAudioPlayer
​
​
client = AsyncOpenAI(
   api_key=os.environ["TIMEWEB_AI_TOKEN"],
   base_url="https://api.timeweb.ai/v1",
)
​
​
async def main() -> None:
   async with client.audio.speech.with_streaming_response.create(
       model="openai/gpt-4o-mini-tts",
       voice="shimmer",
       input="Привет! Это проверка потокового синтеза речи.",
       response_format="pcm",
   ) as response:
       await LocalAudioPlayer().play(response)
​
​
if __name__ == "__main__":
   asyncio.run(main())
```

В примере используется формат `pcm`, поэтому аудио можно воспроизводить по мере получения данных от модели.

## Транскрибация аудио

Для преобразования речи в текст используется метод `audio.transcriptions.create()`.

### Транскрибация из файла

В следующем примере модель расшифровывает русскую речь из файла `audio.mp3`:

```py
import os
​
from openai import OpenAI
​
​
client = OpenAI(
   api_key=os.environ["TIMEWEB_AI_TOKEN"],
   base_url="https://api.timeweb.ai/v1",
)
​
with open("audio.mp3", "rb") as audio_file:
   transcription = client.audio.transcriptions.create(
       model="openai/gpt-4o-mini-transcribe",
       file=audio_file,
       language="ru",
       response_format="json",
   )
​
print(transcription.text)
```

Параметры:

-   `model` — модель для транскрибации;
    
-   `file` — аудиофайл, который нужно преобразовать в текст;
    
-   `language` — язык аудио. Если параметр не указан, модель определит язык автоматически;
    
-   `response_format` — формат ответа: `json` или `text`.
    

### Передача контекста

С помощью параметра `prompt` можно передать модели термины, дополнительный контекст и требования к результату. Также, можно попросить ее удалить слова-паразиты:

```py
import os
from openai import OpenAI
​
client = OpenAI(
   api_key=os.environ["TIMEWEB_AI_TOKEN"],
   base_url="https://api.timeweb.ai/v1",
)
​
with open("meeting.mp3", "rb") as audio_file:
   transcription = client.audio.transcriptions.create(
       model="openai/gpt-4o-transcribe",
       file=audio_file,
       language="ru",
       response_format="json",
       prompt=(
           "Запись посвящена Kubernetes и облачной инфраструктуре. "
           "В разговоре упоминаются Timeweb Cloud, kubectl и Ingress. "
           "Удали из расшифровки слова-паразиты и междометия. "
           "Сохрани смысл и не перефразируй остальную речь."
       ),
   )
​
print(transcription.text)
```

В примере `prompt` помогает модели распознать технические термины и задает требования к готовому тексту. Параметр не заменяет содержимое аудио, а дополняет его контекстом и инструкциями.

### Транскрибация звука с микрофона

AI Gateway не поддерживает транскрибацию в реальном времени. Для приближенного к реальному времени результата можно записывать звук короткими фрагментами и отправлять каждый фрагмент в API отдельно.

Установите дополнительные библиотеки:

```shell
pip install numpy sounddevice
```

Пример ниже записывает звук фрагментами по три секунды. Между соседними фрагментами добавляется небольшое перекрытие, чтобы модель не потеряла слова на границе записи:

```py
import io
import os
import queue
import threading
import time
import wave
from dataclasses import dataclass
​
import numpy as np
import sounddevice as sd
from openai import OpenAI
​
​
MODEL = "openai/gpt-4o-mini-transcribe"
​
SAMPLE_RATE = 16_000
CHANNELS = 1
SAMPLE_WIDTH_BYTES = 2
​
CHUNK_SECONDS = 3.0
OVERLAP_SECONDS = 0.4
FRAMES_PER_BLOCK = 1_600
​
​
client = OpenAI(
   api_key=os.environ["TIMEWEB_AI_TOKEN"],
   base_url="https://api.timeweb.ai/v1",
)
​
​
@dataclass
class AudioChunk:
   index: int
   pcm_data: bytes
​
​
audio_queue: queue.Queue[AudioChunk | None] = queue.Queue(maxsize=10)
stop_event = threading.Event()
​
​
def pcm_to_wav_bytes(pcm_data: bytes) -> io.BytesIO:
   wav_buffer = io.BytesIO()
​
   with wave.open(wav_buffer, "wb") as wav_file:
       wav_file.setnchannels(CHANNELS)
       wav_file.setsampwidth(SAMPLE_WIDTH_BYTES)
       wav_file.setframerate(SAMPLE_RATE)
       wav_file.writeframes(pcm_data)
​
   wav_buffer.seek(0)
   wav_buffer.name = "chunk.wav"
​
   return wav_buffer
​
​
def transcription_worker() -> None:
   while True:
       chunk = audio_queue.get()
​
       if chunk is None:
           audio_queue.task_done()
           break
​
       try:
           wav_file = pcm_to_wav_bytes(chunk.pcm_data)
           started_at = time.perf_counter()
​
           transcription = client.audio.transcriptions.create(
               model=MODEL,
               file=wav_file,
               language="ru",
               response_format="json",
           )
​
           elapsed = time.perf_counter() - started_at
           text = getattr(transcription, "text", "").strip()
​
           if text:
               print(
                   f"\n[{chunk.index:04d}] "
                   f"({elapsed:.2f} сек.) {text}",
                   flush=True,
               )
           else:
               print(
                   f"\n[{chunk.index:04d}] "
                   f"({elapsed:.2f} сек.) [тишина]",
                   flush=True,
               )
​
       except Exception as exc:
           print(
               f"\nОшибка транскрибации фрагмента "
               f"{chunk.index}: {exc}",
               flush=True,
           )
​
       finally:
           audio_queue.task_done()
​
​
def record_microphone() -> None:
   chunk_samples = int(SAMPLE_RATE * CHUNK_SECONDS)
   overlap_samples = int(SAMPLE_RATE * OVERLAP_SECONDS)
​
   accumulated = np.empty(0, dtype=np.int16)
   previous_tail = np.empty(0, dtype=np.int16)
   chunk_index = 1
​
   print("Говорите. Для остановки нажмите Ctrl+C.")
​
   with sd.InputStream(
       samplerate=SAMPLE_RATE,
       channels=CHANNELS,
       dtype="int16",
       blocksize=FRAMES_PER_BLOCK,
   ) as stream:
       while not stop_event.is_set():
           block, overflowed = stream.read(FRAMES_PER_BLOCK)
​
           if overflowed:
               print("\nПредупреждение: переполнение аудиобуфера.")
​
           accumulated = np.concatenate((accumulated, block[:, 0]))
​
           while len(accumulated) >= chunk_samples:
               current_samples = accumulated[:chunk_samples]
               accumulated = accumulated[chunk_samples:]
​
               if len(previous_tail) > 0:
                   samples_to_send = np.concatenate(
                       (previous_tail, current_samples)
                   )
               else:
                   samples_to_send = current_samples
​
               if overlap_samples > 0:
                   previous_tail = current_samples[-overlap_samples:].copy()
               else:
                   previous_tail = np.empty(0, dtype=np.int16)
​
               audio_chunk = AudioChunk(
                   index=chunk_index,
                   pcm_data=samples_to_send.astype(
                       "<i2",
                       copy=False,
                   ).tobytes(),
               )
​
               try:
                   audio_queue.put(audio_chunk, timeout=1)
                   print(".", end="", flush=True)
               except queue.Full:
                   print(
                       "\nОчередь заполнена: фрагмент пропущен. "
                       "Увеличьте CHUNK_SECONDS или проверьте скорость API."
                   )
​
               chunk_index += 1
​
       if len(accumulated) >= SAMPLE_RATE // 2:
           if len(previous_tail) > 0:
               accumulated = np.concatenate(
                   (previous_tail, accumulated)
               )
​
           audio_queue.put(
               AudioChunk(
                   index=chunk_index,
                   pcm_data=accumulated.astype(
                       "<i2",
                       copy=False,
                   ).tobytes(),
               )
           )
​
​
def main() -> None:
   worker = threading.Thread(
       target=transcription_worker,
       daemon=True,
   )
   worker.start()
​
   try:
       record_microphone()
   except KeyboardInterrupt:
       print("\nОстанавливаю запись...")
       stop_event.set()
   finally:
       audio_queue.put(None)
       audio_queue.join()
       worker.join(timeout=5)
       print("Готово.")
​
​
if __name__ == "__main__":
   main()
```

Значения `CHUNK_SECONDS` и `OVERLAP_SECONDS` можно изменить. Более короткие фрагменты уменьшают задержку, но увеличивают количество запросов. Из-за перекрытия в результате могут повторяться отдельные слова — при необходимости удаляйте такие повторы при дальнейшей обработке текста.

# Open WebUI

Source: https://timeweb.cloud/docs/ai-agents/api-usage/open-webui?utm_source=llms_txt&utm_medium=ai

Open WebUI — это удобный интерфейс чата для моделей, доступ к которым предоставляется через API. С его помощью можно общаться с AI-агентами в привычном формате диалога.

Разберемся, как установить Open WebUI и подключить к нему AI-агента.

Предполагается, что у вас уже создан AI-агент. Если нет, поможет [наша документация](https://timeweb.cloud/docs/ai-agents), где подробно описано, что такое агент и как его создать.

## Установка

Интерфейс можно развернуть как локально на рабочем компьютере, так и на удаленном сервере, если нужен постоянный доступ к чату.

> [!NOTE]
> Для корректной работы Open WebUI потребуется минимум 2 ГБ ОЗУ.

Убедитесь, что у вас установлены `docker` и `docker compose`:

```bash
docker --version
docker compose version
```

Если вы разворачиваете Open WebUI локально, достаточно создать файл `docker-compose.yaml` с содержимым:

```yaml
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:
```

Если вы хотите развернуть интерфейс на сервере, для удобства доступа стоит использовать домен и SSL-сертификат. Для этого создайте файл `.env`:

```yaml
DOMAIN=openwebui.example.com 
LETSENCRYPT_EMAIL=admin@example.com
TZ=Europe/Moscow
```

В `DOMAIN` укажите домен, на котором будет работать интерфейс. Для домена должна быть настроена A-запись на ваш сервер.

`LETSENCRYPT_EMAIL` — почтовый ящик, который будет использоваться для получения сертификата.

`TZ` — таймзона.

Создайте файл `docker-compose.yaml` со следующим содержимым:

```yaml
version: "3.8"

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "letsencrypt:/letsencrypt"

  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui
    restart: unless-stopped
    environment:
      - TZ=${TZ}
      - WEBUI_URL=https://${DOMAIN}
    volumes:
      - openwebui-data:/app/backend/data
    labels:
      - "traefik.enable=true"

      # HTTPS-роутер
      - "traefik.http.routers.openwebui.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.openwebui.entrypoints=websecure"
      - "traefik.http.routers.openwebui.tls.certresolver=myresolver"
      - "traefik.http.services.openwebui.loadbalancer.server.port=8080"
      - "traefik.http.services.openwebui.loadbalancer.server.scheme=http"

      # HTTP-роутер с редиректом на HTTPS
      - "traefik.http.routers.openwebui-http.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.openwebui-http.entrypoints=web"
      - "traefik.http.routers.openwebui-http.middlewares=redirect-to-https"

      # Middleware для редиректа
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"

volumes:
  openwebui-data:
  letsencrypt:
```

Сохраните манифест и запустите контейнер:

```shell
docker compose up
```

Docker скачает образ и развернет Open WebUI. После появления логотипа в терминале откройте в браузере страницу `http://localhost:3000/` или используйте ваш домен, если интерфейс разворачивается на сервере (в дальнейшем в инструкции будем использовать localhost).

![Scr 20250910 Mnln](https://content.timeweb.com/assets/7778ed8e-34a9-4d32-873a-b23244ee47b6.png?width=2096&height=722)

Если загрузилась приветственная страница — установка прошла успешно.

![Scr 20250910 Mopu](https://content.timeweb.com/assets/0d61dedb-cf4b-4d46-838d-16fd573c71c9.png?width=2742&height=1538)

_Приветственная страница [Open WebUI](https://openwebui.com/)_

Вернитесь в терминал и остановите контейнер сочетанием `Ctrl+C`, а затем запустите его в фоновом режиме:

```bash
docker compose up -d
```

В браузере обновите страницу `http://localhost:3000/`, вы также должны наблюдать приветственную страницу.

## Подключение агента

Нажмите на кнопку «Давайте начнем».

Заполните данные для создания аккаунта администратора. Если приложение разворачивается локально, можно указать простой пароль, но при установке на сервере с внешним доступом рекомендуем использовать стойкий пароль. Почта, введенная при регистрации, используется только как идентификатор и как логин для входа, никакие письма на нее не приходят.

![Image 20250910141353857](https://content.timeweb.com/assets/86ce3a80-c200-4292-aaac-8d9a67529a91.png?width=1204&height=788)

_Создание аккаунта администратора в интерфейсе [Open WebUI](https://openwebui.com/)_

Open WebUI поддерживает два способа подключения агентов:

-   **Через прямое подключение** — для каждого пользователя указывается собственный API-ключ и URL;
-   **Для всех пользователей** — настройки подключения задаются один раз в панели администратора и используются по умолчанию.

Рассмотрим оба варианта.

Прямое подключение

После создания аккаунта вы окажетесь в главном рабочем пространстве. Но чтобы подключить агентов, нужно сделать еще пару шагов.

Нажмите на имя аккаунта в левом нижнем углу и выберите «Панель администратора».

![Image 20250910141455584](https://content.timeweb.com/assets/7e2bfbb3-82e9-455b-8992-baefeea1ff08.png?width=2790&height=1586)

_Интерфейс [Open WebUI](https://openwebui.com/)_

Дальше откройте вкладку «Настройки» → пункт «Подключения» и включите переключатель напротив «Прямые подключения». Сохраните изменения.

![Image 20250910142207787](https://content.timeweb.com/assets/7b50215b-a8e6-4d0d-adb0-4dce2b8b00b7.png?width=2804&height=1590)

_Раздел «Настройки» → «Подключения» в интерфейсе [Open WebUI](https://openwebui.com/)_

Теперь перейдем к подключению модели. Вновь нажмите на имя пользователя, но теперь выберите пункт «Настройки».

![Image 20250910142341297](https://content.timeweb.com/assets/51ec1662-6bfb-4fb3-b686-8bf54a6e745b.png?width=2802&height=1590)

_Раздел «Настройки» → «Подключения» в интерфейсе [Open WebUI](https://openwebui.com/)_

Перейдите в раздел «Подключения» и нажмите на иконку плюсика.

![Image 20250910142504265](https://content.timeweb.com/assets/c1a845ee-3258-4d78-b65a-f5dc17abb1e8.png?width=1974&height=1328)

_Раздел «Подключения» в интерфейсе [Open WebUI](https://openwebui.com/)_

В открывшемся меню укажите:

-   URL — значение из поля «OpenAI URL» во вкладке «Доступ» на странице агента в панели Timeweb Cloud;
    
-   Ключ — [API-токен для доступа к агенту](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key)
    

После этого нажмите на кнопку проверки соединения. Если ошибок нет — сохраните.

![Image 20250910154715217](https://content.timeweb.com/assets/f28aec02-aa8c-48c9-ad90-b5bc0b988d47.png?width=2832&height=1598)

_Добавление соединения в интерфейсе [Open WebUI](https://openwebui.com/)_

Закройте окно с настройками и нажмите на кнопку «Новый чат». В меню выбора модели у вас отобразится модель вашего AI-агента. Если этого не произошло — обновите страницу браузера и проверьте вновь.

![Image 20250910155234645](https://content.timeweb.com/assets/b8b1d899-3aa9-43f8-ad7b-10a00aacec88.png?width=2796&height=1590)

_Окно «Новый чат» в интерфейсе [Open WebUI](https://openwebui.com/)_

  

Общие настройки подключения

Если вы хотите настроить доступ к агенту один раз для всех пользователей, сделайте следующее:

Нажмите на имя аккаунта в левом нижнем углу и выберите «Панель администратора».

![Image5](https://content.timeweb.com/assets/93e7554a-2976-474c-aee9-8f7844b76e9e.png?width=1999&height=1137)

_Интерфейс [Open WebUI](https://openwebui.com/)_

Перейдите во вкладку «Настройки» и нажмите на иконку плюса рядом с пунктом «API OpenAI».

![Image10](https://content.timeweb.com/assets/51ca4d6f-1580-4737-90b1-a4b8a6ae048e.png?width=1999&height=956)

_Раздел «Настройки» → «Подключения» в интерфейсе [Open WebUI](https://openwebui.com/)_

В открывшемся меню укажите:

-   URL — значение из поля «OpenAI URL» во вкладке «Доступ» на странице агента в панели Timeweb Cloud;
-   Ключ — [API-токен для доступа к агенту](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key)

После этого нажмите на кнопку проверки соединения. Если ошибок нет — сохраните.

![Image11](https://content.timeweb.com/assets/3653286d-0d58-46f2-aa3c-b81ad3401f0c.png?width=1999&height=951)

_Добавление соединения в интерфейсе [Open WebUI](https://openwebui.com/)_

Закройте окно с настройками и нажмите на кнопку «Новый чат». В меню выбора модели у вас отобразится модель вашего AI-агента. Если этого не произошло — обновите страницу браузера и проверьте вновь.

![Image8](https://content.timeweb.com/assets/bf90eb29-16fd-4836-92e4-d39ee930a483.png?width=1999&height=1138)

_Окно с новым чатом в интерфейсе [Open WebUI](https://openwebui.com/)_

На этом установка и настройка Open WebUI завершена.

# Управление базами знаний

Source: https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases?utm_source=llms_txt&utm_medium=ai

База знаний — это приватное хранилище неструктурированных файлов, которое используется для генерации, дополненной поиском (Retrieval Augmented Generation, RAG). 

Иными словами, при подключении базы знаний агент не просто генерирует ответы на основе данных, по которым обучалась ИИ-модель, но также выполняет поиск по базе знаний с информацией, релевантной именно для ваших услуг и сервисов.

Примерами баз знаний могут быть документация по продукту, информация о ценах, каталоги товаров.

Для размещения базы знаний используется облачная база данных OpenSearch — она появится в [«Базах данных»](https://timeweb.cloud/my/database) вашей панели управления, когда вы создадите новую базу знаний. 

В качестве источников данных используются локальные файлы. В одну загрузку можно добавить до 100 файлов, размером не более 50 МБ каждый. Их можно загрузить файлы на этапе создания базы знаний, а также в дальнейшем в настройках базы.

После индексации база знаний станет доступна агентам, к которым она подключена.

Несколько агентов могут использовать одну и ту же базу.

# Создание базы знаний

Source: https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases/create?utm_source=llms_txt&utm_medium=ai

1.  Перейдите в раздел «ИИ-сервисы» → «Базы знаний». 
    

2.  Нажмите «Создать» или «Добавить».
    

![Ии Сервисы 2026 08 18 15 34](https://content.timeweb.com/assets/d2bec526-2035-43fe-a35d-be4e28be6cb6.png?width=1576&height=712)

3.  Задайте параметры базы знаний:

-   -   Загрузите источник данных. [Подробнее об источниках](https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases/configure-data-sources#format-istochnikov-dannyh).
    -   Выберите тариф облачной базы OpenSearch, которая будет использоваться для размещения данных. Вы сможете [увеличить тариф](https://timeweb.cloud/docs/dbaas/dbaas-manage#smena-tarifa) в дальнейшем, если потребуется.
    -   Задайте имя базы знаний, чтобы было проще ориентироваться в них в панели управления. Дополнительно можно указать комментарий. 

4.  Нажмите «Заказать».
    

![Scr 20251118 Mejd](https://content.timeweb.com/assets/2c14e368-43b4-4047-89d3-ff4093f07722.png?width=846&height=965)

Начнется процесс создания облачной базы данных и индексации загруженных файлов. 

Для индексации используется [модель встраивания text-embedding-3-large](https://timeweb.cloud/docs/ai-agents/pricing#baza-znanij). Скорость индексации зависит от размера файлов.

# Настройка источников данных

Source: https://timeweb.cloud/docs/ai-agents/manage-knowledge-bases/configure-data-sources?utm_source=llms_txt&utm_medium=ai

Вы можете управлять источниками данных, которые используются в той или иной базе знаний: загружать новые файлы источников или удалять существующие.

## Формат источников данных

Файлы источников данных могут быть в форматах: `.csv`, `.htm`, `.html`, `.md`, `.txt`, `.xml`, `.pdf`,`.doc`, `.docx`, `.xls`, `.xlsx`.

В качестве источников необходимо использовать текстовые данные. Ограничений по содержимому или оформлению нет, кроме нюанса для таблиц: первая строка должна содержать имена колонок.

Если источники данных содержат медиа (видео, изображения и др.), это не помешает индексации, но сами медиаданные распознаны не будут. Агент будет работать только с текстом.

В источниках можно использовать ссылки, например, на вашу собственную документацию или онлайн-каталоги, чтобы агент мог присылать клиентам релевантные ссылки. Однако ссылки тоже будут распознаны как текст — агент не сможет самостоятельно прочитать и проанализировать содержимое веб-страницы по приведенному URL. 

## Добавление источника данных

1.  Перейдите в раздел «ИИ-сервисы» → «Базы знаний»
2.  Выберите нужную базу и откройте вкладку «Источники данных».
3.  Нажмите кнопку «Добавить источник». Выберите способ добавления: загрузка файла или подключение по ссылке.

Поддерживаются форматы: `.csv`, `.doc`, `.docx`, `.htm`, `.html`, `.md`, `.txt`, `.xls`, `.xlsx`, `.xml`, `.pdf`. Максимальный размер каждого файла — 50 МБ.

Для всех форматов используются специализированные парсеры. Например, при обработке HTML-страниц не индексируются JS-скрипты, CSS, мета-теги и другие технические элементы — только содержимое страницы.

### Загрузка файла

Выберите вкладку «Загрузить файл» и добавьте от 1 до 100 файлов.

![Scr 20251215 Ocfy](https://content.timeweb.com/assets/98a5e92d-2ee8-472e-a341-82b0aa81024e.png?width=2216&height=1456)

### Подключение по ссылке

Выберите вкладку «Подключить по ссылке» и вставьте ссылку в поле «Ссылка на источник». Нажмите «Добавить источник» — вы можете добавить сразу несколько.

![Scr 20251215 Oeuy](https://content.timeweb.com/assets/88cc3c46-d7c4-4fbb-901d-768c8eaf407e.png?width=2172&height=1500)

При подключении по ссылке важно:

-   Страница должна быть доступна без авторизации;
    
-   Страница должна загружаться полностью при помощи `curl`, без генерации на клиенте (не SPA).
    

Для источников, добавленных по ссылке, можно включить автоматическую переиндексацию. Для этого включите переключатель «Авто переиндексация по расписанию».

Переиндексация выполняется при изменении заголовка `ETag`. Если `ETag` не передается, индекс обновляется при каждом запуске по расписанию.

## Управление источниками

Во вкладке «Источники данных» отображаются все добавленные источники:

-   Иконка файла — источник загружен вручную;
    
-   Иконка глобуса — источник подключен по ссылке.
    

![Scr 20251215 Ozof](https://content.timeweb.com/assets/181bee58-dab8-4e24-9916-266e76a053e0.png?width=2132&height=1090)

При наведении курсора появляется кнопка переиндексации. Она повторно загрузит содержимое и обновит индекс:

-   Для файлов — проиндексирует текущую версию;
    
-   Для ссылок — загрузит актуальное содержимое по ссылке.
    

Кликнув по иконке с тремя точками напротив источника, вы можете:

-   Скачать файл (для источников, загруженных из файла);
    
-   Отредактировать ссылку или расписание (для источников, подключенных по ссылке);
    
-   Удалить источник — независимо от способа добавления.

# Тарификация агентов и баз знаний

Source: https://timeweb.cloud/docs/ai-agents/pricing?utm_source=llms_txt&utm_medium=ai

Для работы AI-агентов используются языковые модели и база знаний.

В разделе представлены доступные модели, типы тарификации и правила работы с токенами.

-   [Доступные модели](https://timeweb.cloud/docs/ai-agents/pricing/models)
-   [Как работают токены](https://timeweb.cloud/docs/ai-agents/pricing/how-tokens-work)
-   [Тарификация агентов](https://timeweb.cloud/docs/ai-agents/pricing/billing-models)
-   [Тарификация баз знаний](https://timeweb.cloud/docs/ai-agents/pricing/knowledge-base-billing)
-   [Лимит потребления токенов](https://timeweb.cloud/docs/ai-agents/pricing/token-limit)
-   [Смена тарифа агента](https://timeweb.cloud/docs/ai-agents/pricing/change-plan)
-   [Покупка дополнительных токенов](https://timeweb.cloud/docs/ai-agents/pricing/buy-tokens)

# Доступные модели

Source: https://timeweb.cloud/docs/ai-agents/pricing/models?utm_source=llms_txt&utm_medium=ai

## Список доступных моделей

В панели управления можно создать агентов на базе следующих больших языковых моделей:

| **Провайдер** | **Модель** | **Размышления** |
| --- | --- | --- |
| OpenAI | GPT 4.1 | ❌ |
| OpenAI | GPT 4.1 Mini | ❌ |
| OpenAI | GPT 4o | ❌ |
| OpenAI | GPT 5.1 | ✅ |
| OpenAI | GPT 5.2 | ✅ |
| OpenAI | GPT 5.3 Codex | ✅ |
| OpenAI | GPT 5.4 | ✅ |
| OpenAI | GPT 5.4 Mini | ✅ |
| OpenAI | GPT 5.4 Nano | ✅ |
| OpenAI | GPT 5.6 Luna | ✅ |
| OpenAI | GPT 5.6 Sol | ✅ |
| OpenAI | GPT 5.6 Terra | ✅ |
| DeepSeek | DeepSeek V4 Flash | ✅ |
| DeepSeek | DeepSeek V4 Pro | ✅ |
| xAI | grok-code-fast | ✅ |
| xAI | grok-4.3 | ✅ |
| xAI | grok-4.5 | ✅ |
| xAI | grok-4.6 | ✅ |
| Anthropic | Claude Haiku 4.5 | ✅ |
| Anthropic | Claude Sonnet 4.6 | ✅ |
| Anthropic | Claude Sonnet 5 | ✅ |
| Anthropic | Claude Opus 4.6 | ✅ |
| Anthropic | Claude Opus 4.8 | ✅ |
| Anthropic | Claude Opus 5 | ✅ |
| Anthropic | Claude Fable 5 | ✅ |
| Google AI | Gemini-3.5-flash | ✅ |
| Google AI | Gemini-3.1-pro-preview | ✅ |
| Google AI | Gemini-3.1-flash-lite | ✅ |
| Google AI | Gemini-3.6-flash | ✅ |
| Google AI | Gemini-3.7-flash | ✅ |
| Qwen | Qwen 3 Max | ❌ |
| Qwen | Qwen 3.7 Max | ✅ |
| Qwen | Qwen 3.5 Flash | ✅ |
| Qwen | Qwen 3.6 Flash | ✅ |
| Qwen | Qwen 3.5 Plus | ✅ |
| Qwen | Qwen 3.6 Plus | ✅ |
| Qwen | Qwen 3.7 Plus | ✅ |
| Qwen | Qwen 3.8 Max | ✅ |
| Yandex | Alice AI LLM | ✅ |
| Yandex | Yandex GPT 5.1 Lite | ❌ |
| Yandex | Yandex GPT 5.1 Pro | ✅ |
| Moonshot | Kimi K2.6 | ✅ |
| Moonshot | Kimi K2.7 Code | ✅ |
| Moonshot | Kimi K3 | ✅ |
| Z.ai | GLM 4.7 FlashX | ✅ |
| Z.ai | GLM 4.7 | ✅ |
| Z.ai | GLM 5.2 | ✅ |

При работе через API список версий может быть шире. Все доступные варианты можно найти [на сайте](https://timeweb.cloud/services/ai-agents).

## Модели с размышлениями

Если при выборе модели отображается пиктограмма мозга — значит, модель поддерживает режим размышлений (reasoning).

В этом режиме модель перед финальным ответом самостоятельно формулирует промежуточные рассуждения. Модель задает себе уточняющие вопросы и отвечает на них. Это позволяет добиться более точного, аргументированного ответа, особенно в сложных задачах.

Каждая итерация размышлений требует дополнительного ввода и вывода текста, а значит — увеличивает количество затраченных токенов.

Если модель поддерживает оба режима, с размышлениями и без, вы можете управлять ими на вкладке «Плейграунд»:

![Brainy Erinome 2026 08 12 09 35](https://content.timeweb.com/assets/66fd0696-31b3-47a8-815b-6aa353e6e1a8.png?width=1575&height=1280)

# Как работают токены

Source: https://timeweb.cloud/docs/ai-agents/pricing/how-tokens-work?utm_source=llms_txt&utm_medium=ai

Модели работают с текстом, разбивая его на фрагменты — токены. Один токен может быть:

-   частью слова (например, «техно» + «логия»);
-   целым коротким словом (например, «кот»);
-   символом или знаком препинания.

В среднем 1 000 токенов ≈ 750 слов на русском или английском языке.

> [!NOTE]
> Приведенные значения приблизительны и предназначены для общего представления о расходах. Каждая модель использует собственный токенизатор с уникальной логикой разбиения текста

Токены тарифицируются как на входе, так и на выходе. Например, если ваш запрос содержит 20 токенов, а ответ от модели — 30 токенов, то всего будет списано 50 токенов из доступной квоты.

Определить оптимальное количество токенов, необходимое для вашего агента, можно только в процессе работы, понаблюдав за динамикой потребления.

# Тарификация агентов

Source: https://timeweb.cloud/docs/ai-agents/pricing/billing-models?utm_source=llms_txt&utm_medium=ai

AI-агенты тарифицируются по поресурсной модели pay-as-you-go. Все новые агенты создаются именно с этим типом тарификации.

Пакетная тарификация применяется только к небольшой части агентов, которые были созданы вскоре после запуска сервиса.

Поресурсная тарификация

Стоимость агента составляет 1 рубль в месяц, а токены оплачиваются по модели pay-as-you-go. Входящие и исходящие токены учитываются отдельно, по разной стоимости. 

Актуальные цены можно найти в панели управления.

Списания происходят с баланса аккаунта раз в час. Вы можете настроить [лимит потребления токенов](https://timeweb.cloud/docs/ai-agents/pricing/token-limit), чтобы контролировать их расход.

Пакетная тарификация

> [!NOTE]
> Создать нового агента с пакетной тарификацией невозможно.

При пакетной тарификации для агента предоставляется выбранный вами пакет токенов, который действует один месяц. 

Тариф автоматически продлевается раз в месяц единоразовым списанием, и вам становится доступен такой же пакет токенов. Токены, не израсходованные в текущем месяце, сгорают. 

При необходимости тариф можно [увеличить](https://timeweb.cloud/docs/ai-agents/pricing/change-plan?roistat_visit=4278826). Уменьшить его невозможно.

Если токенов недостаточно, вы можете перейти на следующий тариф или докупить [дополнительный пакет токенов](https://timeweb.cloud/docs/ai-agents/pricing/buy-tokens?roistat_visit=4278826), который будет действовать до конца текущего оплаченного периода.

# Тарификация баз знаний

Source: https://timeweb.cloud/docs/ai-agents/pricing/knowledge-base-billing?utm_source=llms_txt&utm_medium=ai

## Расчет стоимости

Стоимость базы знаний складывается из двух составляющих:

-   **Абонентская плата за токены  
    **При создании базы знаний сразу списывается 450 ₽ за 10 млн токенов. Токены расходуются на индексацию базы, а также на все запросы к ней. Этот платеж повторяется ежемесячно.
-   **Почасовая оплата за базу данных OpenSearch  
    **Для работы базы знаний используется [облачная база данных](https://timeweb.cloud/docs/dbaas). После создания базы начинает взиматься почасовая оплата. Размер платы зависит от выбранной конфигурации.

При создании базы данных выбирайте минимальный подходящий тариф — в дальнейшем его можно будет увеличить. Уменьшение тарифа недоступно.

#### Пример расчета

При создании базы знаний с минимальной конфигурацией:

-   Сразу списывается 450 ₽ за 10 млн токенов (ежемесячный платеж).
-   В течение всего месяца с аккаунта списывается 1,23 ₽ каждый час за работу базы данных.

## Дополнительные токены

При необходимости вы можете добавлять токены по цене 60 ₽ за 1 000 000 токенов, нажав кнопку «Добавить токены» в панели управления базой знаний.

![Scr 20251118 Mhxd](https://content.timeweb.com/assets/17ddc73e-cc3f-4fb3-af13-8f51789a7edf.png?width=2006&height=1450)

Дополнительные токены будут добавлены до конца оплаченного периода. То есть, если следующее списание за единый тариф произойдет через два дня, дополнительные токены пропадут через два дня.

## Расход токенов при индексации

Для индексации используется модель встраивания text-embedding-3-large, которая преобразует тексты в векторный формат. Это необходимо для индексации данных и последующей работы с ними. 

Расход токенов при индексации зависит от формата загружаемого файла. Ниже — пример приблизительного потребления токенов при загрузке документов разных объемов:

| **Формат** | **1 МБ** | **10 МБ** | **100 МБ** | **500 МБ** |
| --- | --- | --- | --- | --- |
| `.txt` | 240 000 | 2 400 000 | 24 000 000 | 120 000 000 |
| `.csv` | 450 000 | 4 500 000 | 45 000 000 | 225 000 000 |
| `.xml` | 62 000 | 620 000 | 6 200 000 | 31 000 000 |
| `.htm`, `.html` | 39 000 | 390 000 | 3 900 000 | 19 500 000 |
| `.md` | 221 000 | 2 210 000 | 22 100 000 | 110 500 000 |

Фактический расход может отличаться в зависимости от структуры и содержания файла.

# Лимит потребления токенов

Source: https://timeweb.cloud/docs/ai-agents/pricing/token-limit?utm_source=llms_txt&utm_medium=ai

> [!NOTE]
> Опция доступна только для агентов с [поресурсной](https://timeweb.cloud/docs/ai-agents/pricing/billing-models) тарификацией.

При создании агента и в дальнейшем в его настройках вы можете настроить лимит потребления токенов, чтобы контролировать их расход. 

## При создании агента

На шаге «Тариф» укажите желаемый лимит. Вы сможете изменить его в любое время.

![Создать AI Агента 05 21 2026 01 32 Pm](https://content.timeweb.com/assets/2277b64a-bab9-4a1f-9ebc-f4ef5553d78c.png?width=755&height=560)

## В настройках агента

1.  Кликните на нужного агента в разделе «ИИ-сервисы» → «Агенты».
2.  Перейдите на вкладку «Управление» и кликните «Установить лимиты».

![Witty Cygnus 05 21 2026 01 34 Pm](https://content.timeweb.com/assets/3929b0c7-283d-4759-a2d2-6223b784d804.png?width=1561&height=869)

3.  Включите или отключите лимит и установите нужное значение.
4.  Сохраните изменения.

![Witty Cygnus 05 21 2026 01 34 Pm (1)](https://content.timeweb.com/assets/b3be41ad-0a47-4a29-a8fb-67a09765b15c.png?width=1745&height=869)

# Смена тарифа агента

Source: https://timeweb.cloud/docs/ai-agents/pricing/change-plan?utm_source=llms_txt&utm_medium=ai

> [!NOTE]
> Смена тарифа доступна только для агентов на [пакетной](https://timeweb.cloud/docs/ai-agents/pricing/billing-models) тарификации.

Вы можете увеличить тариф по инструкции ниже или [докупить пакет токенов](https://timeweb.cloud/docs/ai-agents/pricing/buy-tokens) на текущий месяц, не меняя тариф. 

**Важно**: при изменении тарифа неиспользованные токены сгорят. Будет доступно только количество токенов, предусмотренное новым тарифом.

Чтобы изменить тариф:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
    
2.  На вкладке «Управление» нажмите «Изменить» в пункте с текущей конфигурацией.
    

![Image1](https://content.timeweb.com/assets/8d276193-3022-4c4c-8ea2-6ab1bff9cc0f.png?width=1999&height=1095)

3.  Измените тариф и сохраните изменения. 
    

Изменения будут применены мгновенно, и счетчик токенов обновится.

# Покупка дополнительных токенов

Source: https://timeweb.cloud/docs/ai-agents/pricing/buy-tokens?utm_source=llms_txt&utm_medium=ai

> [!NOTE]
> Опция доступна только для агентов на [пакетной](https://timeweb.cloud/docs/ai-agents/pricing/billing-models) тарификации.

Если вам необходимо увеличить количество токенов, вы можете [увеличить тариф](https://timeweb.cloud/docs/ai-agents/pricing/change-plan) или докупить токены отдельно.

-   Используйте смену тарифа, если увеличенное количество токенов требуется вам на постоянной основе — уменьшить тариф будет невозможно.
-   Если дополнительные токены нужны только сейчас — докупите необходимый пакет. Он будет действовать только до конца текущего оплаченного месяца, а в дальнейшем вы будете оплачивать стоимость вашего стандартного тарифа. 

Чтобы купить пакет токенов:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
    
2.  На вкладке «Дашборд» нажмите «Добавить токены».
    

![1b706ebd 0dca 4572 921a A901f9a9bc8c](https://content.timeweb.com/assets/8cee8348-4386-40fc-9d92-a4548aade497.png?width=1527&height=824)

3.  Укажите необходимое количество токенов (шаг — 250 тысяч) и нажмите «Подтвердить».

![D427b137 3693 4089 B684 67e061097779](https://content.timeweb.com/assets/f8a15f50-d6d8-48b5-b098-754838949989.png?width=1537&height=820)

# Интеграция с агентскими средами

Source: https://timeweb.cloud/docs/ai-agents/agent-environments?utm_source=llms_txt&utm_medium=ai

-   [Cline](https://timeweb.cloud/docs/ai-agents/agent-environments/cline)
-   [Codex](https://timeweb.cloud/docs/ai-agents/agent-environments/codex)
-   [OpenCode](https://timeweb.cloud/docs/ai-agents/agent-environments/opencode)
-   [Roo Code](https://timeweb.cloud/docs/ai-agents/agent-environments/roocode)

# Cline

Source: https://timeweb.cloud/docs/ai-agents/agent-environments/cline?utm_source=llms_txt&utm_medium=ai

Cline — это расширение для VS Code, с помощью которого можно работать с AI-моделью прямо из редактора: задавать вопросы по проекту, редактировать код и выполнять команды в терминале.

Cline можно использовать как альтернативу Roo Code, поддержка которого прекращена.

## Установка Cline

Для установки расширения:

1.  Откройте VS Code.
    
2.  Перейдите в раздел «Extensions».
    
3.  Найдите расширение Cline и установите его.
    

![Cline Install](https://content.timeweb.com/assets/6f7a56e6-9a66-433d-817a-0eecf7a51515.png?width=1999&height=1259)

_Страница Cline в разделе «Extensions» интерфейса [VS Code](https://code.visualstudio.com/?roistat_visit=11910906)_

После установки в боковой панели появится вкладка Cline с интерфейсом чата.

## Настройка подключения

При помощи расширения можно подключить как AI-агента, так и AI Gateway.

Если вы хотите подключить AI-агента, вам потребуется:

-   [Базовый URL агента](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#bazovyj-url);
    
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key).
    

Для подключения AI Gateway понадобится:

-   Базовый URL: `https://api.timeweb.ai/v1`;
    
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#sozdanie-api-klucha).
    

Чтобы настроить подключение:

1.  Перейдите во вкладку «Cline».
    
2.  При первом открытии вкладки будет предложено выбрать тип аккаунта. Выберите пункт «Bring my own API key» и нажмите «Continue».
    

![Cline setup](https://content.timeweb.com/assets/932b54a2-7593-4057-b680-55bf108120fd.png?width=1999&height=1260)

_Настройки Cline в интерфейсе [VS Code](https://code.visualstudio.com/?roistat_visit=11910906)_

3.  В настройках провайдера укажите:
    

-   `API Provider`: OpenAI Compatible;
    
-   `Base URL`: базовый URL;
    
-   `API Key`: ваш API-ключ;
    
-   `Model`: если вы используете AI-агента, поле можно оставить пустым или указать имя модели из настроек агента. При использовании AI Gateway укажите имя нужной модели, например `openai/gpt-5-nano`. Корректное имя модели можно найти в разделе «[Подключение](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#poluchenie-parametrov-podklucheniya)».
    

![Интерфейс настройки Cline](https://content.timeweb.com/assets/333b2906-f0d2-4739-a2a9-887962331685.png?width=1999&height=1260)

_Настройки Cline в интерфейсе [VS Code](https://code.visualstudio.com/?roistat_visit=11910906)_

4.  При необходимости настройте параметры генерации. Эти параметры будут учитываться только при использовании подключения AI Gateway. Для настройки разверните вкладку «Model configuration» и укажите:
    

-   `Context Window Size` — объем истории диалога, передаваемой в запросе;
    
-   `Max Output Tokens` — максимальное число токенов в ответе;
    
-   `Temperature` — степень вариативности ответа.
    

6.  Нажмите «Done», затем — стрелку назад, чтобы вернуться к чату.
    

Теперь вы можете отправлять сообщения агенту или модели прямо из редактора.

# Codex

Source: https://timeweb.cloud/docs/ai-agents/agent-environments/codex?utm_source=llms_txt&utm_medium=ai

Codex — это AI-ассистент для разработки от OpenAI. С его помощью можно работать с проектом из десктопного приложения или терминала: задавать вопросы по коду, вносить изменения и запускать команды.

К Codex можно подключить как AI-агента, так и AI Gateway. В первом случае вы работаете с уже настроенным агентом, во втором — обращаетесь к модели напрямую.

## Установка Codex

Codex Desktop доступен для macOS и Windows. Скачать версию для своей ОС можно на [официальном сайте OpenAI](https://openai.com/ru-RU/codex/get-started/).

Codex CLI можно установить на macOS или Linux командой:

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

Для установки Codex CLI на Windows используйте PowerShell:

```shell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

Codex CLI также можно установить через пакетные менеджеры:

npm

```bash
npm install -g @openai/codex
```

brew

```bash
brew install --cask codex
```

## Предварительные требования

Подключить к Codex можно как AI-агента, так и AI Gateway.

Если вы хотите подключить AI-агента, вам потребуется:

-   [Базовый URL агента](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#bazovyj-url);
    
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key).
    

Для подключения AI Gateway понадобится:

-   Базовый URL: `https://api.timeweb.ai/v1`;
    
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#sozdanie-api-klucha).
    

## Настройка подключения

Настройка выполняется в файле `~/.codex/config.toml`.

Если вы ранее использовали Codex, сохраните текущую версию конфигурации:

```bash
mv ~/.codex/config.toml ~/.codex/config.toml_old
```

Переименовав файл конфигурации обратно, вы сможете вернуть прежние настройки.

Создайте или откройте файл конфигурации:

```bash
nano ~/.codex/config.toml
```

Добавьте в файл конфигурацию подключения:

```bash
model_provider = "timeweb_cloud"
model = "openai/gpt-5-mini"

[model_providers.timeweb_cloud]
name = "Timeweb Cloud"

base_url = "https://api.timeweb.ai/v1" 
env_key = "TIMEWEB_CLOUD_API_KEY"
```

В конфигурации измените:

-   `base_url` — базовый URL зависит от типа подключения. Для AI Gateway используйте `https://api.timeweb.ai/v1`, для AI-агента — базовый URL вашего агента;
    
-   `model` — если используете AI-агента, укажите имя модели из настроек агента. При использовании AI Gateway укажите имя нужной модели, например `openai/gpt-5-nano`. Корректное имя модели можно найти в разделе «[Подключение](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#poluchenie-parametrov-podklucheniya)»;
    
-   `env_key` — укажите название переменной окружения, в которой будет храниться API-ключ;
    
-   `name` — при необходимости измените отображаемое имя провайдера.
    

Codex берет ключ из переменной окружения, указанной в параметре `env_key`. Если в конфигурации используется `TIMEWEB_CLOUD_API_KEY`, выполните:

Linux

```shell
export TIMEWEB_CLOUD_API_KEY="ваш_API-ключ"
```

macOS

```bash
launchctl setenv TIMEWEB_CLOUD_API_KEY "ваш_API-ключ"
```

Windows

```bash
setx TIMEWEB_CLOUD_API_KEY "ваш_API-ключ"
```

После этого запустите Codex:

```bash
codex
```

При использовании десктопной версии перезапустите приложение.

Добавленная модель будет доступна как в Codex CLI, так и в десктопном приложении Codex. В десктопной версии модель отобразится в окне чата.

![Выбор модели в Codex](https://content.timeweb.com/assets/ce3dd717-18d3-49e4-bd17-e7b2734d34fa.png?width=2522&height=1546)

_Выбор модели в интерфейсе [Codex](https://openai.com/ru-RU/codex/)_

# OpenCode

Source: https://timeweb.cloud/docs/ai-agents/agent-environments/opencode?utm_source=llms_txt&utm_medium=ai

OpenCode — это AI-ассистент для разработки. С его помощью можно задавать вопросы по проекту, редактировать код и выполнять команды без переключения в отдельный интерфейс.

К OpenCode можно подключить как AI-агента, так и AI Gateway. В первом случае вы работаете с уже настроенным агентом, во втором — обращаетесь к модели напрямую.

## Установка OpenCode

OpenCode можно установить на Windows, Linux или macOS. Доступны два варианта: TUI/CLI и десктопное приложение.

Чтобы установить TUI/CLI-версию, используйте один из способов:

curl

```bash
curl -fsSL https://opencode.ai/install | bash
```

npm

```bash
npm i -g opencode-ai
```

bun

```bash
bun add -g opencode-ai
```

brew

```bash
brew install anomalyco/tap/opencode
```

paru

```bash
paru -S opencode
```

Десктопную версию можно установить через Homebrew:

```bash
brew install --cask opencode-desktop
```

Также можно скачать бинарный файл с [официального сайта OpenCode](https://opencode.ai/ru/download) и установить его вручную.

## Предварительные требования

Подключить к OpenCode можно как AI-агента, так и AI Gateway.

Если вы хотите подключить AI-агента, вам потребуется:

-   [Базовый URL агента](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#bazovyj-url);
    
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key).
    

Для подключения AI Gateway понадобится:

-   Базовый URL: `https://api.timeweb.ai/v1`;
    
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#sozdanie-api-klucha).
    

## Настройка подключения через терминал

Этот способ подойдет, если вы используете TUI/CLI-версию OpenCode.

Создайте или отредактируйте файл конфигурации opencode.json.

Файл можно разместить:

-   в корне проекта — настройки будут применяться только для этого проекта;
    
-   глобально по пути `~/.config/opencode/opencode.json` — настройки будут доступны во всех проектах.
    

В файле укажите конфигурацию для подключения:

```js
{
 "$schema": "https://opencode.ai/config.json",
 "provider": {
   "timeweb-cloud": {
     "npm": "@ai-sdk/openai-compatible",
     "name": "Timeweb Cloud",
     "options": {
       "baseURL": "https://api.timeweb.ai/v1"
     },
     "models": {
       "openai/gpt-5-mini": {
         "name": "openai/gpt-5-mini"
       }
     }
   }
 },
 "model": "openai/gpt-5-mini"
}
```

В конфигурации измените:

-   `baseURL` — если хотите использовать AI-агента, укажите базовый URL вашего агента. При использовании AI Gateway менять не нужно;
    
-   `models` — укажите модели, которые будут доступны в OpenCode;
    
-   `model` — если используете AI-агента, укажите имя модели из настроек агента. При использовании AI Gateway укажите имя нужной модели, например `openai/gpt-5-nano`. Корректное имя модели можно найти в разделе «[Подключение](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#poluchenie-parametrov-podklucheniya)»;
    
-   `name` — при необходимости измените отображаемое имя провайдера.
    

Сохраните и закройте файл.

Теперь необходимо указать API-ключ. Для этого запустите OpenCode в терминале:

```bash
opencode
```

В открывшемся TUI-интерфейсе выполните команду:

```bash
/connect
```

С помощью стрелок прокрутите список провайдеров вниз и выберите пункт «Other».

Укажите идентификатор провайдера. Он должен совпадать с названием провайдера в `opencode.json`, в нашем примере — `timeweb-cloud`.

Вставьте API-ключ в поле ввода.

OpenCode сохранит ключ в зашифрованном глобальном файле авторизации.

После этого можно начать использовать OpenCode. Запустите агента снова, если ранее выходили из него. Чтобы выбрать добавленную модель, введите:

```bash
/model
```

В поиске укажите имя провайдера, которое вы задали при добавлении. Затем проверьте подключение, отправив любое сообщение в чат.

## Настройка подключения в десктопном приложении

Чтобы подключить провайдера в десктопном приложении:

1.  Нажмите на иконку шестеренки.
    
2.  Перейдите во вкладку «Провайдеры».
    
3.  Пролистайте меню вниз и выберите пункт «Пользовательский провайдер».
    
4.  Нажмите «Подключить».
    

![Настройки OpenCode](https://content.timeweb.com/assets/c7bdc033-6fd5-4fcb-8faf-05a53b3e4b63.png?width=2536&height=1510)

_Интерфейс настройки [OpenCode](https://opencode.ai/)_

Укажите параметры подключения:

-   ID провайдера — произвольное имя, по которому можно будет найти провайдера;
    
-   Отображаемое имя — название провайдера в интерфейсе;
    
-   Базовый URL — базовый URL агента или AI Gateway;
    
-   API-ключ — ключ для доступа к агенту или AI Gateway;
    
-   Модели — список моделей, которые будут доступны для выбора.
    

При использовании AI Gateway имя модели нужно указать в формате AI Gateway, например `openai/gpt-5-nano`. Корректное имя модели можно найти в разделе «[Подключение](https://timeweb.cloud/docs/ai-agents/api-usage/ai-gateway#poluchenie-parametrov-podklucheniya)».

При использовании AI-агента можно указать произвольное имя модели.

![Настройка OpenCode](https://content.timeweb.com/assets/6637fd58-0bb0-4a2f-b5f5-6e446ea5b02b.png?width=2548&height=1506)

_Интерфейс настройки [OpenCode](https://opencode.ai/)_

Нажмите «Отправить», чтобы сохранить настройки.

После этого найдите и выберите модель в чате. Проверьте, что подключение настроено корректно, отправив произвольный запрос.

# Roo Code

Source: https://timeweb.cloud/docs/ai-agents/agent-environments/roocode?utm_source=llms_txt&utm_medium=ai

AI-агенты можно подключать к любым инструментам с поддержкой OpenAI API, в том числе к расширениям для VS Code.

Например, через Roo Code агент может взаимодействовать с редактором: видеть файлы проекта, редактировать код и выполнять команды в терминале.

> [!NOTE]
> С 15 мая 2026 года поддержка Roo Code прекращена. В качестве альтернативы можно [использовать Cline](https://timeweb.cloud/docs/ai-agents/agent-environments/cline) — расширение с похожим функционалом и интерфейсом.

## Установка Roo Code

Для установки расширения:

1.  Откройте VS Code.
    
2.  Перейдите в раздел «Extensions».
    
3.  Найдите расширение Roo Code и установите его.
    

![Scr 20260119 Kdpu](https://content.timeweb.com/assets/581b3a15-5886-4dfc-8950-cb7ab95ac052.png?width=2726&height=1626)

_Страница Roo Code в разделе «Extensions» интерфейса [VS Code](https://code.visualstudio.com/)_

После установки в боковой панели появится вкладка Roo Code с интерфейсом чата.

## Настройка подключения к AI-агенту

Для настройки вам понадобится:

-   [Базовый URL агента](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api#bazovyj-url),
-   [API-ключ](https://timeweb.cloud/docs/ai-agents/manage-agents/api-access-key).

Чтобы настроить подключение:

1.  Перейдите во вкладку «Roo Code».
    
2.  Нажмите на иконку шестеренки, чтобы открыть настройки.
    
3.  Перейдите в раздел «Providers».
4.  В настройках провайдера укажите:
    
    -   **API Provider**: `OpenAI Compatible`;
        
    -   **Base URL**: базовый URL;
        
    -   **API Key**: ваш API-ключ;
        
    -   **Model**: имя модели, указанное в настройках агента.
        
5.  При необходимости настройте параметры генерации:
    
    -   **Context Window Size** — объем истории диалога, передаваемой в запросе;
        
    -   **Max Completion Tokens** — максимальное число токенов в ответе.
        

6.  Нажмите «Save», затем — стрелку назад, чтобы вернуться к чату.
    

![Scr 20260119 Kelt 2](https://content.timeweb.com/assets/1a5796c9-57e3-4d65-9304-90a7c94601cc.png?width=2806&height=1812)

_Настройки Roo Code в интерфейсе [VS Code](https://code.visualstudio.com/)_

Теперь вы можете отправлять сообщения агенту прямо из редактора.

Дополнительно вы можете изменить поведение агента, например, чтобы он отвечал по-русски. Для этого:

1.  Перейдите в настройки Roo Code.
    
2.  Откройте раздел «Prompts».
    
3.  Добавьте в промпт фразу: `Отвечай по-русски`.
    

![Scr 20260119 Kkpd](https://content.timeweb.com/assets/4a12bb69-c9b0-4656-b7a2-d84a102bb606.png?width=2798&height=1766)

_Настройки Roo Code в интерфейсе [VS Code](https://code.visualstudio.com/)_

# MCP-серверы

Source: https://timeweb.cloud/docs/ai-agents/mcp-server?utm_source=llms_txt&utm_medium=ai

MCP (Model Context Protocol) — это протокол, который позволяет AI-агенту работать не только с собственными знаниями, но и с внешними инструментами. Например, с его помощью агент может выполнять поиск в интернете, работать с документацией, подключаться к сервисам вроде Notion или управлять браузером и использовать полученные результаты при формировании ответа пользователю.

MCP-сервер выступает посредником между AI-агентом и внешними сервисами. Сам агент не знает, как именно устроены эти сервисы и как с ними работать. Но он знает, что у MCP-сервера есть набор доступных инструментов, которыми можно воспользоваться.

#### Как AI-агент узнает, какие инструменты доступны

Когда AI-агент подключается к MCP-серверу, первое, что он делает, — запрашивает список доступных инструментов. В ответ сервер возвращает описание того, что он умеет: названия функций, их назначение, какие параметры они принимают и в каком формате возвращают результат.

На этом этапе формируется контракт между агентом и MCP-сервером. Агент понимает, какие действия ему доступны, и может выбирать, какой инструмент использовать в той или иной ситуации.

![2](https://content.timeweb.com/assets/23b3f84f-b776-4b04-a0a5-1b241a0ad046.png?width=1920&height=927)

Этот список инструментов можно получить и вручную — обычным HTTP-запросом. Например, у MCP-сервера exa search, который предоставляет AI-агенту доступ к поиску в интернете, можно запросить список инструментов так:

```bash
curl -s https://mcp.exa.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }' \
| sed -n 's/^data: //p' \
| jq
```

В ответ сервер вернет список инструментов. В нем можно увидеть, какие функции доступны, для чего они предназначены и какие параметры ожидают. Например, один инструмент отвечает за поиск по интернету, другой — за исследование компаний, третий — за поиск кода и документации. Для каждого инструмента явно описано, какие данные нужно передать на вход.

Важно, что AI-агент не «угадывает» эти параметры и не придумывает формат запроса. Он работает строго по описанию, которое получил от MCP-сервера.

#### Как выглядит работа с MCP при запросе пользователя

После подключения и получения списка инструментов AI-агент «держит в голове», какие инструменты ему доступны и в каких случаях их можно использовать.

Пользователь задает вопрос AI-агенту. Если агент может ответить на него сразу — он просто формирует ответ. Но если информации не хватает, агент понимает, что ему нужно воспользоваться внешним инструментом, и формирует запрос к MCP-серверу.

> [!NOTE]
> Можно явно указать агенту использовать инструменты. Например, при подключении Context7 в конце промпта можно написать: «Используй Context7», — и агент будет использовать инструменты этого MCP-сервера, а не придумывать информацию.

Рассмотрим взаимодействие с MCP-сервером на примере exa search. Пользователь задает вопрос AI-агенту. Если агент понимает, что не может ответить сразу — например, потому что ему не хватает актуальной информации, — он решает обратиться к инструменту поиска и формирует запрос к MCP-серверу. MCP-сервер выполняет функцию поиска в exa search и возвращает AI-агенту структурированный результат. Дальше агент читает найденное, выбирает главное и уже на основе этих данных формирует ответ пользователю.

![1](https://content.timeweb.com/assets/6e1ff26a-544c-4b08-861d-1ecedff56f97.png?width=1920&height=927)

MCP-сервер не отвечает пользователю напрямую и не принимает решений. Он выполняет конкретные функции и возвращает результат. Вся логика, интерпретация данных и генерация ответа остается на стороне AI-агента.

## Настройка подключения

Вы можете подключить MCP-сервер вручную по этой инструкции или воспользоваться [галереей MCP-серверов](https://timeweb.cloud/docs/ai-agents/mcp-server#galereya-mcp-serverov), если в ней есть нужный вам сервер.

MCP-серверы бывают двух типов: stdio и Streamable HTTP. Условно их можно разделить на локальные (stdio) и удаленные (Streamable HTTP).

Подключать к агентам можно только удаленные серверы — Streamable HTTP.

Чтобы добавить новое подключение:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и откройте вкладку «MCP-серверы».
    
2.  Нажмите «Создать» или «Добавить».
    

![Scr 20260210 Koqx](https://content.timeweb.com/assets/4ed5644c-7b06-45e8-890c-fd181a26e40e.png?width=2080&height=1486)

3.  Заполните поля:
    
    -   Bearer-токен;
        
    -   OAuth 2.0;
        
    -   Кастомные заголовки;
        
    -   Без авторизации.
        

-   Название — произвольное имя подключения;
    
-   Комментарий — необязательное поле;
    
-   Адрес сервера — URL, по которому доступен MCP-сервер;
    
-   Протокол — HTTP или SSE;
    
-   Авторизация — выберите способ аутентификации:
    

5.  Нажмите «Добавить сервер».
    

![Scr 20260210 Kpbp](https://content.timeweb.com/assets/b8eadd6f-8431-4135-bd54-f39e0d180ced.png?width=2508&height=1464)

После этого новое подключение появится в списке инструментов.

## Галерея MCP-серверов

В панели управления доступны готовые к установке MCP-серверы — для их подключения достаточно указать только токены авторизации для нужного сервиса.

![MCP (2)](https://content.timeweb.com/assets/f1d881fb-eec0-4ce2-b6e5-f1573bc7e791.png?width=1666&height=869)

## Управление MCP-серверами агента

Чтобы подключить сервер к конкретному агенту:

1.  Перейдите в раздел «ИИ-сервисы» → «Агенты» и кликните на нужного агента.
2.  Перейдите во вкладку «Управление».
    
3.  В строке «MCP-серверы» нажмите «Изменить».
    

![Scr 20260210 Kpyk](https://content.timeweb.com/assets/7dd4e73b-4390-49cc-abf5-60088571436c.png?width=2140&height=1474)

3.  В открывшемся окне выберите уже созданный MCP-сервер или нажмите «Добавить новый».
    
4.  В этом же окне можно выбрать инструменты, которые будут использоваться агентом. Для этого нажмите на стрелку рядом с подключенным MCP-сервером.
    

![Scr 20260210 Kqvs](https://content.timeweb.com/assets/59cf46ed-e7a8-4632-a884-4b516872fe35.png?width=2526&height=1478)

Чтобы отвязать MCP-сервер от агента, в этом же окне нажмите на кнопку «Удалить MCP-сервер».

К одному агенту можно подключить несколько MCP-серверов. Одно подключение может использоваться несколькими агентами.

## Использование 

После подключения MCP-сервера агент будет использовать его функции как при работе через OpenAI-совместимый API, так и в интерфейсе виджета.

При использовании OpenAI-совместимого API подключенные MCP-серверы применяются только в случае, если в запросе не передается параметр `tools` в явном виде.

Потоковая передача данных (SSE) пока не поддерживается для агентов с подключенными MCP-серверами.

# Timeweb Cloud MCP

Source: https://timeweb.cloud/docs/ai-agents/timeweb-cloud-mcp?utm_source=llms_txt&utm_medium=ai

MCP — это протокол, который позволяет AI-агентам работать с внешними инструментами и сервисами. Timeweb Cloud MCP дает агентам доступ к инфраструктуре в Timeweb Cloud через MCP-интерфейс: агент может получать данные, выполнять действия с ресурсами и использовать эти возможности в продуктах и агентских сценариях.

## Ограничения

При работе с Timeweb Cloud MCP учитывайте, что:

-   методы удаления ресурсов не поддерживаются;
-   мутирующие методы требуют подтверждения перед выполнением;
-   перед выполнением действия агент уточнит в чате, действительно ли вы хотите его совершить.

## Подключение

Для подключения Timeweb Cloud MCP нужен [API-токен Timeweb Cloud](https://timeweb.cloud/docs/account-management/token). Получить его можно во вкладке «[API и Terraform](https://timeweb.cloud/my/api-keys)».

Ограничения прав, заданные для токена, отразятся и на работе MCP. Если агент не должен иметь доступ к какому-либо разделу, ограничьте доступ в настройках токена.

Вы можете подключить Timeweb Cloud MCP к AI-агентам Timeweb Cloud или к сторонним агентам с поддержкой MCP.

## Подключение к AI-агентам Timeweb Cloud

Чтобы подключить Timeweb Cloud MCP к AI-агенту:

1.  Перейдите во вкладку «MCP-серверы» в разделе «ИИ-сервисы».
    
2.  Выберите «Timeweb Cloud MCP».
    

![Scr 20260603 Pxhr](https://content.timeweb.com/assets/5cda5af3-ef75-4c1c-b9b8-90a20b9eea3a.png?width=2196&height=1652)

3.  В открывшемся окне укажите полученный ранее токен в поле «API-токен».
    
4.  Нажмите «Установить».
    

После подключения MCP-сервер будет доступен при работе с агентом в чате и через API. При работе через AI Gateway MCP-сервер доступен не будет.

## Подключение к сторонним агентам

Timeweb Cloud MCP можно подключить к сторонним агентам с поддержкой удаленных MCP-серверов.

URL MCP-сервера:

```shell
https://timeweb.cloud/api/v1/mcp
```

Для авторизации используйте API-токен Timeweb Cloud.

Общий пример конфигурации:

```js
{
  "mcpServers": {
    "timeweb": {
      "type": "http",
      "url": "https://timeweb.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer TIMEWEB_CLOUD_TOKEN"
      }
    }
  }
}
```

### Добавление токена в переменные окружения

Чтобы не указывать токен в каждом конфигурационном файле вручную, добавьте его в переменную окружения `TIMEWEB_CLOUD_TOKEN`.

Замените `ваш_токен` на API-токен, полученный ранее.

macOS

Откройте терминал и выполните команды:

```shell
launchctl setenv TIMEWEB_CLOUD_TOKEN "ваш_токен"
```

Windows

Откройте PowerShell и выполните команду:

```shell
[Environment]::SetEnvironmentVariable(
   "TIMEWEB_CLOUD_TOKEN",
   "ваш_токен",
   "User"
)
```

После этого закройте PowerShell и откройте его заново.

Linux

Откройте терминал и выполните команды:

```shell
echo 'export TIMEWEB_CLOUD_TOKEN="ваш_токен"' >> ~/.bashrc
source ~/.bashrc
```

### Настройка Claude Code

Для настройки MCP нужна консольная версия Claude Code. Это не то же самое, что десктопное приложение Claude Code или Cowork: они могут быть установлены, но команда `claude` при этом может отсутствовать.

Чтобы проверить установку, откройте терминал или PowerShell и выполните команду:

```shell
claude --version
```

Если команда выводит номер версии, переходите к подключению MCP-сервера.

Если терминал пишет, что команда не найдена, установите Claude Code CLI.

#### Установка Claude Code CLI

macOS

Выполните команду:

```shell
curl -fsSL https://claude.ai/install.sh | bash
```

Windows

Откройте PowerShell и выполните команду:

```shell
irm https://claude.ai/install.ps1 | iex
```

После установки закройте терминал, откройте его заново и снова проверьте:

```shell
claude --version
```

Если установщик сообщит, что каталог `.local\bin` не добавлен в `PATH`, добавьте его командой:

```shell
setx PATH "$($env:PATH);C:\Users\$env:USERNAME\.local\bin"
```

Затем закройте PowerShell, откройте его заново и повторите проверку.

#### Подключение MCP-сервера

Добавьте Timeweb Cloud MCP:

```shell
claude mcp add-json timewebCloud '{"type":"http","url":"https://timeweb.cloud/api/v1/mcp","headers":{"Authorization":"Bearer ${TIMEWEB_CLOUD_TOKEN}"}}'
```

Проверьте, что сервер добавлен:

```shell
claude mcp list
```

Внутри Claude Code можно проверить состояние MCP-серверов командой:

```shell
/mcp
```

### Настройка Codex

Codex хранит настройки MCP в файле `~/.codex/config.toml`.

Откройте или создайте этот файл и добавьте конфигурацию:

```shell
[mcp_servers.timewebCloud]
url = "https://timeweb.cloud/api/v1/mcp"
bearer_token_env_var = "TIMEWEB_CLOUD_TOKEN"
```

Проверить подключение можно через настройки. Нажмите «Настройки» → «Настройки» → «Серверы MCP» — в списке должно появиться новое подключение timewebCloud.

### Настройка Cursor

Cursor читает настройки MCP из файла `mcp.json`.

Для глобального подключения создайте или откройте файл:

```shell
~/.cursor/mcp.json
```

Для подключения только в рамках одного проекта создайте файл:

```shell
.cursor/mcp.json
```

Добавьте конфигурацию:

```shell
{
 "mcpServers": {
   "timewebCloud": {
     "url": "https://timeweb.cloud/api/v1/mcp",
     "headers": {
       "Authorization": "Bearer ${env:TIMEWEB_CLOUD_TOKEN}"
     }
   }
 }
}
```

Перезапустите Cursor. После этого агент Cursor сможет использовать инструменты Timeweb Cloud MCP, если они подходят для запроса пользователя.

Проверить подключение можно в настройках MCP:

1.  Нажмите `Ctrl + Shift + P`.
    
2.  Выполните команду MCP: Open MCP Settings.
    
3.  Найдите сервер `timewebCloud` в списке.
    
4.  Проверьте его статус:
    

-   -   `Connected` — сервер подключен;
        
    -   `Connecting` — идет подключение;
        
    -   `Error` или `Disconnected` — есть проблема с подключением.
        

## Проверка подключения

После подключения MCP-сервера проверьте, подключается ли он корректно. В чате с агентом попросите перечислить список доступных инструментов:

```shell
Какие инструменты MCP тебе доступны для работы с Timeweb Cloud? Перечисли все инструменты.
```

При корректном подключении агент выведет список инструментов Timeweb Cloud MCP.

![Scr 20260603 Qcqn](https://content.timeweb.com/assets/8d33c61d-59af-4c0d-8918-0f03fdc5d2f3.png?width=1932&height=1778)

Если что-то не работает, попросите агента проверить настройки MCP и подсказать, в чем ошибка.