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

OpenAI в марте 2025-го выкатил Responses API — новый базовый интерфейс для работы с их моделями. Для людей, которые годами жили на Chat Completions, это кажется «ещё одним эндпойнтом». На деле это смена парадигмы: из «обмениваемся сообщениями с моделью» в «запускаем агента, который сам ходит в инструменты». Официальный сигнал OpenAI: Responses — рекомендуемый API для всех новых проектов, Assistants API в sunset с августа 2026-го, Chat Completions пока живёт, но «живёт» в режиме легаци.

Что это такое

Responses API — «примитив» (по формулировке OpenAI), на котором строятся все агентские продукты OpenAI: Agents SDK, AgentKit, Codex CLI, ChatGPT-агенты. В нём сложены три вещи:

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

Чем отличается от Chat Completions

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

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

Как выглядит запрос

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 (не показан) — ссылка на предыдущий вызов, чтобы продолжить разговор без передачи всей истории.

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

Отличие от Chat Completions в том, что часть инструментов живёт внутри OpenAI — вам не нужно своё обвязывание.

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

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.

Background и long-running агенты

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

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

С Chat Completions

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

С Assistants API

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

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

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

• Цена. Токены тарифицируются по выбранной модели. Сам эндпойнт ничего не добавляет. Web search и file search имеют свои тарифы за вызов.
• Prompt caching включен по умолчанию — повторяющиеся части instructions/input резко дешевят при повторных вызовах.
• Хранение. Поле store: true включает хранение response на стороне OpenAI (нужно для previous_response_id). Для чувствительных данных есть режим с encrypted reasoning content.
• Лимиты. Общие rate limits по моделям — см. в dashboard. Для computer use и MCP есть отдельные ограничения на время сессии.

Практические сценарии

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.

Ссылки

• Обзор Responses API: developers.openai.com/api/reference/responses/overview
• Migration to Responses: developers.openai.com/api/docs/guides/migrate-to-responses
• Migration pack на GitHub: github.com/openai/completions-responses-migration-pack
• Assistants migration guide: developers.openai.com/api/docs/assistants/migration
• Agents SDK: openai.github.io/openai-agents-python
• New tools and features: openai.com/index/new-tools-and-features-in-the-responses-api

По теме

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

Если вы выбираете между Chat Completions и Responses для нового проекта или думаете, как мигрировать живой продукт без простоев, напишите в Telegram — разберём вместе.