OpenAI Responses API — это единый эндпойнт для запуска моделей с встроенными инструментами, многоходовыми вызовами и серверным состоянием. Если вы раньше строили агента на Chat Completions, собирая оркестрацию, память и вызов инструментов вручную, — Responses API забирает эту инфраструктуру на себя.

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

Что это

Responses API — базовый «примитив» (по формулировке OpenAI), на котором строятся все их агентские продукты: Agents SDK, AgentKit, Codex CLI, ChatGPT-агенты. В одном эндпойнте POST /v1/responses собраны три вещи:

  • Генерация ответов. Обычный input/output: даёте промпт — получаете текст, structured output или изображение.
  • Инструменты. Модель сама вызывает ваши function calls, встроенные инструменты OpenAI (web search, file search, computer use, code interpreter) и внешние MCP-серверы — всё в одном запросе.
  • Состояние. OpenAI хранит response с историей reasoning и вызовов инструментов. Вы ссылаетесь на предыдущий ответ через previous_response_id вместо того, чтобы каждый раз досылать весь диалог.

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

Зачем нужно

Практическая ценность Responses API — в сокращении инфраструктуры, которую раньше приходилось строить вокруг LLM-вызовов:

  • RAG без своей векторной базы. File search работает по вашим файлам, загруженным в vector store, без необходимости поднимать Pinecone или PGVector.
  • Веб-поиск без отдельного API. Web search встроен прямо в вызов — модель ходит в интернет и возвращает ответ с цитатами.
  • Многоходовые задачи в одном запросе. Модель может вызвать инструмент, получить результат, вызвать следующий — всё в рамках одного response.
  • Память без своей базы диалогов. Серверное состояние через previous_response_id хранит историю reasoning и вызовов.
  • MCP-интеграции. Любой remote MCP-сервер подключается как инструмент — Notion MCP, ваш собственный, что угодно.

Как устроено

Сравнение с Chat Completions

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

Responses API вбирает эту оркестрацию в себя:

АспектChat CompletionsResponses API
Число ходов модели в одном вызове1Несколько (с инструментами и reasoning)
Состояние разговораНа вашей стороне (таскать history)На стороне OpenAI через previous_response_id
Встроенные инструментыНетweb search, file search, computer use, code interpreter, MCP
Reasoning summary для мыслящих моделейНетДа, включая reasoning_effort и summary
МультимодальностьЧастичноНативно: текст + изображения в input и output
Структурированный выводДаДа, более стабильный в связке с reasoning
StreamingSSESSE и WebSocket-режим
Работа в фоне (background)НетДа, для длительных агентских задач

Это не drop-in replacement. Формат запроса и ответа другой: нет messages, есть input и instructions, инструменты объявляются по-другому. OpenAI выпустила отдельный тулкит completions-responses-migration-pack, который работает вместе с Codex CLI.

Формат запроса

import OpenAI from "openai"
const client = new OpenAI()

const response = await client.responses.create({
    model: "gpt-5.5",
    instructions: "Ты — помощник-рисёрчер. Отвечай кратко и с источниками.",
    input: "Что нового в Notion API в 2025 году?",
    tools: [
        { type: "web_search" },
        { type: "file_search", vector_store_ids: ["vs_..."] },
        {
            type: "mcp",
            server_label: "notion",
            server_url: "https://mcp.notion.com/mcp",
        },
    ],
    reasoning: { effort: "medium", summary: "auto" },
})

console.log(response.output_text)

Что здесь важно:

  • instructions — системная роль, отдельное поле верхнего уровня.
  • input — не messages, а «вход». Может быть строкой, массивом блоков (text, image, file, audio) или «хвостом» диалога.
  • tools — список, в который можно класть как встроенные инструменты OpenAI, так и свои (type: “function”) и MCP-серверы.
  • reasoning — включает режим размышлений для мыслящих моделей с контролем «сколько думать» и «вернуть ли summary».
  • previous\_response\_id (не показан) — ссылка на предыдущий вызов для продолжения разговора без передачи всей истории.

Встроенные инструменты

Часть инструментов живёт внутри OpenAI — не нужно своё обвязывание:

  • Web search — модель ходит в интернет и возвращает ответ с цитатами.
  • File search — векторный поиск по вашим файлам, загруженным в vector store. Заменяет retrieval-часть Assistants API.
  • Computer use — агент управляет браузером в изолированной среде (скриншоты, клики, ввод).
  • Code interpreter — выполняет Python в sandbox, возвращает результат и файлы.
  • MCP — подключение любого remote MCP-сервера. Например, Notion MCP или ваш собственный.
  • Image generation — генерация картинок прямо в рамках response.
  • Function calling — ваши кастомные функции по старой схеме. Работает и мешается с встроенными инструментами в одном вызове.

Если вы раньше своими руками строили RAG над Pinecone или PGVector, попробуйте file search как base case. Для большинства рабочих сценариев этого хватит, и вы экономите неделю инфраструктуры.

Reasoning и состояние

Для мыслящих моделей (gpt-5.5, o4-серия, их mini-варианты) Responses API даёт два рычага:

  • reasoning\_effort: low / medium / high — сколько «думать» перед ответом. Баланс между латенси и качеством.
  • reasoning.summary — краткое резюме рассуждения как отдельный блок output. Режимы: auto, concise, detailed.

Важный эффект хранения состояния: когда вы передаёте previous_response_id, модель видит свои предыдущие рассуждения в исходном виде — точность многоходовых задач вырастает. В Chat Completions этого нет: reasoning-трассы из одного вызова не переживают следующий, даже если вы вручную досылаете history.

Что добавилось в 2026

В марте 2026 OpenAI дорастила Responses до полноценной среды исполнения агентов — теперь не нужно самому городить песочницу под долгие задачи:

  • Agent loop (встроенный цикл исполнения) — модель не выдаёт ответ сразу, а предлагает действие (запустить команду, сходить в сеть, дёрнуть данные), оно выполняется в контролируемой среде, результат возвращается модели, и так по кругу, пока задача не решена.
  • Shell tool — в отличие от code interpreter, который гоняет только Python, shell даёт полноценную командную строку: grep, curl, awk из коробки, можно запустить Go, Java или поднять NodeJS-сервер.
  • Контейнерный воркспейс — размещённая у OpenAI среда с файлами и базами, с сетевым доступом под контролем политик. Секреты в контейнер не кладутся: модель видит только плейсхолдеры, которые подменяются во внешнем слое.
  • Компакция контекста — для долгих задач система сжимает предыдущие шаги в короткое представление, сохраняя главное. Появился отдельный вызов responses.compact.
  • Skills (скиллы) — повторяемые сценарии, упакованные в переиспользуемый бандл: папка с SKILL.md (метаданные и инструкции) плюс вспомогательные файлы вроде API-спеков и ассетов.
  • Tool search и apply patch — поиск по инструментам на лету (только gpt-5.4 и новее) и встроенный инструмент правки файлов патчами.

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

Background и long-running агенты

Responses поддерживает background-режим (background: true). Вы ставите задачу, получаете response.id, и дальше опрашиваете статус или подписываетесь на события. Это особенно важно для агентов с computer use и MCP, которые легко работают по десятку минут и следом рвут синхронное HTTP-соединение.

Когда использовать

Concrete scenarios, где Responses API реально полезен:

  • Research-агент под команду. Web search + file search по внутренней библиотеке + Notion MCP. Одним вызовом получаете ответ с ссылками, цитатами из ваших файлов и автоматически созданной страницей в Notion.
  • Кодовые агенты. Code interpreter + function calling + computer use — модель выдвигает гипотезу, запускает Python в sandbox, проверяет факты в браузере и выдаёт финальный ответ.
  • Клиентский чат с памятью. previous_response_id из последнего сообщения + structured outputs для бизнес-логики. Не нужно ни своей базы диалогов, ни retry-логики вокруг формата.
  • Обработка PDF и сканов. Нативная мультимодальность + file search дают обработку документов без отдельного OCR и векторной базы на своей инфре.
  • Электронная коммерция и поддержка. Один Responses-вызов обрабатывает вопрос клиента, ходит в ERP через MCP, проверяет статус заказа и возвращает структурированный ответ для UI.

Миграция с других API

С Chat Completions

По размеру работ — от пары часов до нескольких дней в зависимости от сложности проекта. OpenAI отдала отдельный репозиторий completions-responses-migration-pack, который под Codex CLI сам находит легаси-вызовы, переписывает импорты и формы запросов и открывает PR. Полезно как стартовая точка, с ручным проходом по каждому месту.

С Assistants API

Assistants API будет выключен 26 августа 2026-го. OpenAI выпустила отдельный migration guide. Основные шаги:

  • Собрать важные assistant-объекты и превратить их в prompt-объекты OpenAI.
  • Перенести vector store для file_search — формат тот же.
  • Заменить thread/run-логику на previous_response_id.
  • Свои tools и instructions перенести в поля Responses.

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

Цена. Токены тарифицируются по выбранной модели: например, у gpt-5.5 — $5 за 1M входных и $30 за 1M выходных токенов на коротком контексте (цифры по состоянию на 07.07.2026, актуальные значения сверяйте с официальным прайсом). Сам эндпойнт надбавки не берёт, но встроенные инструменты стоят отдельно: web search и file search тарифицируются за вызов, контейнеры code interpreter — посессионно. Нюанс с web search: один вызов может развернуться в несколько внутренних под-поисков, и счёт идёт за каждый.

Prompt caching включён по умолчанию — повторяющиеся части instructions/input резко дешевят при повторных вызовах. Согласно официальной документации OpenAI, улучшение утилизации кэша в Responses API достигает 40–80% по сравнению с Chat Completions.

Хранение. Поле store: true включает хранение response на стороне OpenAI (нужно для previous_response_id). Для чувствительных данных есть режим с encrypted reasoning content.

Лимиты. Общие rate limits по моделям — см. в dashboard. Для computer use и MCP есть отдельные ограничения на время сессии.

Вендор-лок. Chat Completions был стандартом, который поддерживают Anthropic, Mistral, Together и другие. Переходя на Responses, вы жёстко привязываетесь к OpenAI. Решение обычно прагматичное: абстрагировать LLM-слой своими руками или через LiteLLM, а Responses-специфичные фичи включать точечно там, где они реально нужны.

Ограничения

Ограничения

Что учитывать

Вендор-лок — Responses API работает только с моделями OpenAI.

Никакой совместимости с Anthropic, Mistral или open-source провайдерами.

Стоимость инструментов — Web search и file search тарифицируются отдельно за каждый вызов.

Один web search может развернуться в несколько внутренних под-поисков.

Хранение данных — store: true хранит response на стороне OpenAI.

Для чувствительных данных нужен режим encrypted reasoning content.

Лимиты сессий

— Для computer use и MCP есть отдельные ограничения на время сессии, сверх общих rate limits по моделям.

Антипаттерны

Антипаттерны

Чего не делать

Не использовать как drop-in replacement — Формат запроса и ответа другой: messages

→ input + instructions, инструменты объявляются по-другому. Миграция требует переписывания кода.

Не откладывать миграцию с Assistants API

— Отключение 26 августа 2026-го, и откладывать нельзя, если вы ещё на нём.

Не строить свой RAG, не попробовав file search

— Для большинства рабочих сценариев встроенного file search хватает, и вы экономите неделю инфраструктуры.

Не игнорировать background-режим для долгих задач

— Синхронные вызовы с computer use и MCP легко рвут HTTP-соединение по таймауту.

Чеклист

Чеклист

Проверка перед запуском

Выбрать модель

— Убедиться, что выбранная модель поддерживает нужные инструменты (не все модели поддерживают reasoning, computer use или MCP).

Настроить tools

— Объявить встроенные инструменты, function calls и MCP-серверы в массиве tools одного запроса.

Определить reasoning_effort

— Выбрать low/medium/high в зависимости от баланса латенси и качества.

Включить store:

true — Если нужен previous_response_id для многоходовых диалогов.

Проверить лимиты

— Свериться с dashboard по rate limits и ограничениям времени сессии для computer use / MCP.

Запланировать миграцию

— Если на Assistants API, использовать migration guide и заложить время до 26 августа 2026-го.

Ссылки

Ссылки

По теме

По теме