OpenAI Responses API — единый интерфейс для агентских приложений

Что это такое

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

Оглавление

1. Основные возможности — из чего состоит Responses API.
2. Отличия от Chat Completions — формат, состояние и инструменты.
3. Интеграция и подключение — минимальный запрос через JavaScript SDK.
4. Инструменты и среда выполнения — hosted tools, контейнер и компакция.
5. Reasoning и состояние — усилие рассуждения и варианты хранения контекста.
6. Миграция, тарифы и ограничения — что проверить перед внедрением.
7. Полезные сценарии и проверка результата — практические способы применения.

Основные возможности

Responses API объединяет несколько компонентов:

• Генерация ответа. Модель может вернуть текст или структурированные JSON-данные. Изображения создаются через инструмент image generation.
• Типизированные элементы (Items). Вход и результат состоят из элементов разных типов: сообщений, reasoning, вызовов функций, результатов инструментов и других действий модели.
• Инструменты. В одном запросе можно объявить встроенные инструменты OpenAI, собственные функции и MCP-подключения.
• Состояние. Диалог можно продолжить через previous_response_id, объект Conversations API или явную передачу предыдущих элементов.
• Агентский цикл. Размещённые инструменты могут выполнить несколько шагов между моделью и инструментом внутри одного API-вызова. Собственные функции по-прежнему выполняет приложение.

Responses API — базовый API-примитив для агентских приложений. Agents SDK, Codex и другие оболочки добавляют собственную оркестрацию, интерфейс и правила выполнения задач.

Отличия от Chat Completions

Интеграция и подключение

Для JavaScript нужен пакет openai и API-ключ, переданный через переменную окружения OPENAI_API_KEY. Не вставляйте ключ непосредственно в исходный код.

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const response = await client.responses.create({
  model: 'gpt-5.5',
  instructions: 'Отвечай кратко и указывай источники.',
  input: 'Какие основные отличия Responses API от Chat Completions?',
  tools: [{ type: 'web_search' }],
  reasoning: {
    effort: 'medium',
    generate_summary: 'auto',
  },
})

console.log(response.output_text)

Ключевые поля:

• model — модель, которая поддерживает нужные входы и инструменты;
• instructions — системные или developer-инструкции верхнего уровня;
• input — строка либо массив текстовых, графических, файловых и других поддерживаемых элементов;
• tools — инструменты, доступные модели;
• reasoning — настройки reasoning-модели;
• background — выполнение длительного запроса в фоне;
• previous_response_id — идентификатор предыдущего ответа для продолжения диалога;
• store — управление сохранением ответа;
• include — дополнительные данные в результате, включая зашифрованное содержимое reasoning.

Ответы Responses API по умолчанию сохраняются. Для отключения хранения передайте store: false. В stateless-сценарии зашифрованный reasoning-контекст можно запросить через include: ['reasoning.encrypted_content'] и перенести в следующий запрос.

Инструменты и среда выполнения

Набор инструментов зависит от модели. На странице GPT-5.5, проверенной 2 сентября 2026 года, для Responses API перечислены web search, file search, image generation, code interpreter, hosted shell, apply patch, skills, computer use, MCP и tool search.

• Веб-поиск (web_search). Ищет актуальную информацию и может возвращать источники для ответа.
• Поиск по файлам (file_search). Выполняет поиск по файлам в vector store.
• Code interpreter. Запускает Python в изолированной среде и может создавать файлы.
• Hosted shell. Выполняет команды в размещённом контейнере. Поддерживает стандартные Unix-утилиты и запуск программ на разных языках.
• Управление компьютером (computer use). Позволяет модели работать с графическим интерфейсом через снимки экрана и управляющие действия.
• MCP. Подключает совместимые удалённые серверы и предусмотренные платформой коннекторы.
• Image generation. Создаёт изображения как часть инструментального сценария.
• Apply patch. Предназначен для изменения файлов патчами.
• Tool search. Помогает находить и подгружать подходящие инструменты по мере необходимости.
• Skills. Упаковывают повторяемый процесс в версионируемый набор с SKILL.md и вспомогательными ресурсами.
• Вызов функций (function calling). Передаёт вызов вашему приложению. Клиент выполняет функцию и возвращает результат модели как function_call_output.

Контейнер, сеть и агентский цикл

В публикации OpenAI от 11 марта 2026 года описана связка Responses API, shell tool и размещённого контейнерного рабочего пространства. Модель предлагает команды, платформа выполняет их в изолированной среде и возвращает результат в следующий шаг контекста.

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

Этот внутренний цикл относится к размещённым инструментам. Вызовы функций вашего приложения требуют клиентского обработчика.

Компакция контекста

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

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

Reasoning и состояние

Конкретные значения reasoning.effort зависят от модели. GPT-5.5 поддерживает none, low, medium, high и xhigh; значением по умолчанию является medium.

В текущей схеме API настройка генерации резюме задаётся через reasoning.generate_summary; доступны режимы auto, concise и detailed. Резюме формируется системой и не является полной скрытой цепочкой рассуждений.

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

1. Передавать previous_response_id, если достаточно связать следующий ответ с предыдущим.
2. Возвращать нужные элементы output в новый input, если приложение самостоятельно сокращает и хранит контекст.
3. Использовать Conversations API для постоянного объекта разговора.

При связанном хранении Responses API сохраняет reasoning- и инструментальный контекст между ходами. Бизнес-состояние, права доступа и данные для аудита приложение должно хранить отдельно.

Фоновый режим

Параметр background: true переводит запрос в фоновое выполнение. Клиент получает идентификатор ответа и затем проверяет его статус. Возможные состояния включают queued, in_progress, completed, failed, cancelled и incomplete.

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

Миграция

С Chat Completions

Миграция состоит из трёх частей:

1. Заменить POST /v1/chat/completions на POST /v1/responses.
2. Читать типизированный массив output или использовать SDK-помощник output_text.
3. Выбрать способ переноса состояния между ходами.

Дополнительно проверьте:

• text.format вместо response_format;
• новую форму объявления функций и обработки function_call;
• отсутствие параметра n в Responses API;
• повторную передачу instructions при использовании previous_response_id;
• поведение хранения и требования вашей политики данных.

Простые массивы сообщений совместимы с input, если сценарий не использует функции или мультимодальные элементы. Chat Completions продолжает поддерживаться, поэтому работающие интеграции можно переносить поэтапно. Для новых агентских функций OpenAI рекомендует Responses API.

С Assistants API

Assistants API отключён 26 августа 2026 года. Миграцию выполняйте по актуальному руководству OpenAI, отдельно проверяя перенос prompts, threads, runs, vector stores и инструментов.

После отключения нельзя рассчитывать на старые Assistants-вызовы как на резервный производственный путь. Перед переключением проверьте полный сценарий в Responses API и сохранность необходимых данных приложения.

Тарифы и лимиты

На 2 сентября 2026 года GPT-5.5 стоит $5 за 1 млн входных токенов, $0,50 за 1 млн кэшированных входных токенов и $30 за 1 млн выходных токенов. Для промптов длиннее 272 тысяч входных токенов действуют коэффициенты 2× для входа и 1,5× для выхода на всю сессию.

Контекстное окно GPT-5.5 составляет 1 050 000 токенов, максимальный вывод — 128 000 токенов. Лимиты запросов и токенов зависят от уровня использования проекта.

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

Prompt caching применяется для совпадающих префиксов запросов. Экономию проверяйте по полям usage, включая сведения о кэшированных токенах.

Ограничения и архитектурные компромиссы

• Responses-специфичные элементы, hosted tools и состояние усложняют перенос приложения к другому провайдеру.
• Внешние MCP-серверы и пользовательские функции требуют отдельной авторизации и проверки разрешений.
• Агентский цикл может выполнить больше действий, чем ожидает разработчик. max_tool_calls ограничивает общее число вызовов встроенных инструментов в одном ответе; для собственных функций нужны отдельные лимиты и политики приложения.
• Для чувствительных данных заранее выберите режим хранения и проверьте требования организации к retention и Zero Data Retention.
• Действия с финансовыми, пользовательскими или производственными данными должны иметь подтверждения, журналы и предсказуемый способ остановки.

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

Полезные сценарии

Исследовательский помощник

Задача: ответить на вопрос с учётом актуальных внешних данных и внутренних документов. Вход: вопрос пользователя и файлы в vector store. Действие: подключить web search и file search, затем обработать источники и найденные фрагменты. Результат: ответ с проверяемыми ссылками. Ограничение: автоматическая публикация без проверки источников и прав доступа не подходит.

Длительная обработка файлов

Задача: преобразовать документы или таблицы в итоговый файл. Вход: загруженные данные в контейнере. Действие: использовать shell или code interpreter, сохранить промежуточные результаты и сформировать файл. Результат: завершённый ответ с выходными элементами и созданным файлом. Ограничение: для больших задач учитывайте лимиты, background и компакцию.

Клиентский диалог с состоянием

Задача: продолжить разговор без передачи всей истории. Вход: последний response.id и новое сообщение. Действие: передать previous_response_id и повторить instructions. Результат: продолжение разговора с учётом предыдущего контекста. Ограничение: бизнес-данные, согласия и история операций должны храниться отдельно в системе приложения.

Работа с внешней системой через MCP

Задача: получить данные или выполнить разрешённую операцию во внешней системе. Вход: запрос пользователя и права доступа к MCP-серверу. Действие: модель выбирает инструмент, сервер выполняет операцию и возвращает результат. Результат: структурированный ответ инструмента и независимое повторное чтение изменённого объекта. Ограничение: для операций записи нужны явные разрешения и подтверждение пользователя.

Проверка результата

Минимальная проверка интеграции:

1. Выполните запрос без инструментов с коротким input.
2. Убедитесь, что статус ответа равен completed.
3. Проверьте непустой response.output_text.
4. Просмотрите response.output и убедитесь, что приложение обрабатывает элементы по type.
5. Добавьте один инструмент и проверьте его вызов отдельно.
6. Для второго хода передайте previous_response_id и повторите instructions.
7. Проверьте usage, ошибки, incomplete_details и поведение при достижении лимитов.
8. Для действий во внешних системах выполните независимое повторное чтение результата.

if (response.status !== 'completed') {
  throw new Error(`Response status: ${response.status}`)
}

if (!response.output_text?.trim()) {
  throw new Error('Model returned no text')
}

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

Официальные ссылки

• Обзор и миграция на Responses API
• Справочник метода создания response
• Миграция с Assistants API
• GPT-5.5: возможности, цены и лимиты
• Компьютерная среда Responses API
• Практическое руководство по агентам

Следующий шаг

OpenAI — линейка моделей GPT, Realtime и Images

Связанные материалы

• Статья: Codex, Саркис и два месяца боли — инфраструктура ИИ-агентов
• База знаний: Notion MCP — официальный сервер Notion для подключения ИИ-агентов
• База знаний: MCP — стандарт подключения ИИ к внешним системам

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov