Как управлять контекстом и агентами в Responses API Yandex AI Studio

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

Из каких слоёв состоит Yandex AI Studio для разработки агентов

Для разработки текстовых агентов платформу удобно представить в виде трёх слоёв:

• API. Основная работа с платформой идёт через Responses API, Realtime API и Chat Completions API.
• Встроенные инструменты. Готовые компоненты, которые работают поверх Responses API, а частично — поверх Realtime API: поиск по файлам, веб-поиск, MCP, генерация изображений и интерпретатор кода.
• Специализированные API для узких задач: например, для эмбеддингов, генерации изображений вне агентского сценария, классификации текстов и управления MCP-серверами. Полный список — в обзоре API.

Responses API, Realtime API и Chat Completions API: в чём разница

• Responses API — основной API для текстовых сценариев. Вокруг него мы развиваем платформу: сборку агентов, RAG-сценарии, веб-поиск. Он подходит и для простого запроса к модели без инструментов.
• Realtime API — для голосовых агентов, которым нужна минимальная задержка между репликой человека и ответом. Он работает через WebSocket и устроен по-своему — подробнее о нём — в статье про голосовых агентов.
• Chat Completions API — интерфейс генерации, в котором приложение самостоятельно передаёт историю диалога в массиве messages. API поддерживает вызов пользовательских функций и опциональное сохранение результатов, но для новых агентских сценариев Yandex AI Studio рекомендует Responses API.

Все три API совместимы с форматом OpenAI API. Мы сделали так намеренно: опенсорс-фреймворки подключаются к Yandex AI Studio без доработок, и большинство из них поддерживает все три API. Как настроить подключение из популярных инструментов, мы показываем в серии коротких видеоинструкций.

Для работы из кода подойдёт OpenAI SDK: он совместим с Responses API, Realtime API и Chat Completions API. Если нужна логика с несколькими агентами и передачей задач между ними, можно взять OpenAI Agents SDK — он реализует такие механизмы поверх Responses API.

Как выбрать API под сценарий:

• Разовый запрос — суммаризация длинного текста, классификация отзыва. Подойдёт Responses API с параметром store: false, чтобы запрос не сохранялся, или Chat Completions API, который ничего не хранит.
• Чат с историей переписки — Responses API с store: true, это значение по умолчанию. Запросы и ответы сохраняются, модель учитывает историю диалога.
• Агентский цикл с вызовом инструментов — Responses API. Достаточно передать в параметре tools встроенные инструменты платформы или собственные функции, и цикл вызовов API выполнит сам.
• Много запросов без спешки — для длительных операций в Responses API предусмотрен фоновый режим. Запрос может находиться в очереди до 24 часов, а после начала выполнения действует тайм-аут два часа. Статус и результат можно получить по идентификатору запроса.

Структурированный вывод — ответ строго по заданной JSON-схеме — поддерживают и Responses API, и Chat Completions API.

Какие инструменты доступны агенту в Responses API

В отличие от Chat Completions API, Responses API даёт агенту доступ к встроенным инструментам. Их вызывает сама платформа, поэтому отдельная интеграция не нужна: достаточно перечислить нужные инструменты в параметре tools.

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

Веб-поиск мы обновили: качество результатов выросло, а число токенов, которые расходуются после обращения к инструменту, заметно снизилось. Если раньше какие-то запросы с веб-поиском работали не так, как хотелось, их стоит проверить ещё раз.

Внешние системы подключаются через MCP Hub. Этот компонент позволяет подключить к платформе готовые MCP-серверы или создать собственный поверх API уже работающей системы. Работать с MCP Hub можно в интерфейсе или через API — например, если нужно автоматизировать добавление серверов.

Как собрать агента в интерфейсе и перейти к работе через API

Быстрее всего начать с интерфейса Agent Atelier: выберите модель, напишите инструкцию, подключите инструменты — MCP, веб-поиск, поиск по файлам — и протестируйте агента. Интерфейс предназначен для экспериментов, отладки и подбора конфигурации. Когда результат устроит, нажмите «Посмотреть код»: платформа покажет готовый код для вызова агента через API и через SDK на разных языках.

Сохранённая конфигурация получает идентификатор: в интерфейсе это agent ID, в API — prompt ID. За ним стоят инструкция, подключённые инструменты и остальные параметры. Достаточно передать идентификатор в запросе responses.create, и настройки подтянутся автоматически. Создать prompt ID можно только в интерфейсе. Если работать сразу через API, модель, инструкцию и инструменты придётся передавать в каждом запросе.

Из каких параметров состоит запрос к Responses API

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

• Параметры модели. model — модель: в Yandex AI Studio доступны разработки Яндекса и опенсорс-модели. instructions — системный промпт, который задаёт поведение агента. input — пользовательский ввод, то есть то, что агент должен обработать.
• Параметры генерации. temperature — температура, max_output_tokens — максимальное число токенов в ответе, stream — потоковая передача ответа. Режим рассуждений задаёт reasoning_effort, но поддерживают его не все модели: это можно проверить в документации или в Model Gallery.
• Параметры инструментов. tools — список инструментов, доступных агенту, включая описания собственных функций. Здесь же можно ограничить максимальное число вызовов инструментов.
• Формат ответа и работа с контекстом. response_format задаёт формат ответа, например JSON-схему. previous_response_id и store отвечают за контекст диалога, о них подробнее ниже.

Как выбрать модель и температуру для агента

Для сценариев с частыми вызовами инструментов — поиска по файлам, веб-поиска и других — мы рекомендуем начать с DeepSeek V4 Flash или Qwen3.6 35B. Если инструменты не нужны, а важнее скорость ответа, попробуйте Alice AI LLM Flash или более лёгкие модели семейства Qwen.

С температурой есть нюанс. Её привыкли считать параметром креативности в диапазоне от 0 до 1, но для новых моделей это уже не так: некоторым нужны значения выше 1, а рекомендации заметно различаются от модели к модели. Например, для Qwen3.6 35B мы советуем тестировать температуру от 1 и выше.

Параметр max_output_tokens ограничивает длину ответа, но пользоваться им стоит осторожно. Если модель не уложится в лимит, ответ оборвётся на полуслове, и пользователь это сразу заметит.

Ещё одно ограничение: в одном запросе к Responses API нельзя одновременно подключить инструмент, например поиск по файлам, и задать строгую JSON-схему ответа. Такой запрос вернёт ошибку, поэтому придётся выбрать что-то одно.

Как хранить контекст диалога: store, previous_response_id и Conversations API

Если управлять контекстом не нужно, подойдёт Chat Completions API. Он ничего не хранит, поэтому историю переписки приложение передаёт само — так обычно и делают во фреймворках вроде LangChain и LangGraph.

Responses API умеет работать с контекстом сам: сохраняет сообщения, выстраивает историю и учитывает её в следующих ответах. За это отвечает параметр store. При store: false запросы не сохраняются, и продолжить диалог средствами платформы не получится. При store: true запрос и ответ сохраняются, а использовать историю можно двумя способами:

• Через Conversations API. Разработчик явно создаёт объект диалога — Conversation — и указывает его в запросах к Responses API. В Conversation попадают запросы, ответы и вызовы инструментов. В диалог можно добавлять собственные элементы — например, выгрузить историю, суммаризировать её и загрузить обратно одним сообщением.
• Через previous_response_id. Каждый ответ Responses API приходит со своим идентификатором. Если передать его в следующем запросе, платформа сама подтянет предыдущий запрос и всю связанную с ним цепочку.

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

Обе цепочки видно в интерфейсе Yandex AI Studio, в разделе Логирование. Там есть список сохранённых ответов с параметрами и ссылкой на предыдущий ответ цепочки, а также список диалогов Conversations с исходным контекстом, связанными запросами и идентификатором диалога.

Как работает автоматическая обрезка контекста

Чтобы история не переполнила контекстное окно модели, в Responses API есть параметр truncation. Со значением auto платформа удаляет самые старые сообщения и вызовы инструментов, но не трогает системную инструкцию и список инструментов. Вызов инструмента и его результат всегда удаляются парой.

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

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

Как повысить долю кешированных токенов

Yandex AI Studio поддерживает кеширование промптов для части моделей. Оно работает автоматически: если начало запроса совпадает с предыдущими, эта часть может попасть в кеш.

Здесь и проявляется связь с truncation. Обрезка удаляет самую старую часть истории, поэтому начало запроса меняется от обращения к обращению, и шансов попасть в кеш становится меньше.

Что помогает:

• Переносите в системную инструкцию как можно больше неизменной информации. Инструкция и описание инструментов стоят в начале запроса и повторяются при каждом обращении, поэтому у них больше шансов закешироваться.
• Проверяйте кеширование на практике. Отправьте достаточно много запросов и посмотрите, как часто срабатывает кеш.
• Смотрите результат в биллинге и мониторинге. Кешированные токены тарифицируются отдельно, поэтому в детализации они видны отдельной строкой. Теперь их число показывает и раздел мониторинга.

Сколько хранятся данные в Yandex AI Studio

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

Сроки хранения остальных данных зависят от API:

• ответы Responses API при store: true — 30 дней, если не удалить их раньше;
• ответы при store: false не сохраняются, но и продолжить диалог средствами платформы нельзя;
• диалоги Conversations и привязанные к ним ответы — 365 дней или до удаления через API или интерфейс.

Управлять можно и другими данными: историей диалогов — через Conversations API и Responses API, поисковыми индексами — через Vector Stores API, файлами — через Files API. Это касается и загруженных файлов, и тех, что создали инструменты, например интерпретатор кода. Подробнее — в политике хранения данных.

Какие логи есть в Yandex AI Studio

В Yandex AI Studio три вида логов, и задачи у них разные:

• Аудитные логи фиксируют действия пользователей и сервисных аккаунтов с ресурсами платформы. Их можно выгружать в Yandex Audit Trails для расследований и анализа.
• Логи сервиса нужны нам, чтобы следить за работой платформы и диагностировать неполадки. Пользователям они недоступны ни в интерфейсе, ни через API. Если нужно разобраться в инциденте, обратитесь в техническую поддержку — там предоставят часть логов, которая касается ваших ресурсов.
• Трейсы — самый новый вид логов. Yandex AI Studio отправляет в Yandex Monium запросы и ответы Chat Completions API и Responses API для мониторинга, оценки качества и отладки.

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

Что показывает трейсинг агента

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

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

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

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

По умолчанию трейсинг выключен. Включить его можно переключателем на плитке трейсинга в разделе Логирование, там же его можно выключить. Трейсы тарифицируются по правилам Yandex Monium и не используются для улучшения сервиса или обучения моделей.

Вывод: какой инструмент выбрать под задачу