OpenAI Agents SDK

Короткая версия

OpenAI Agents SDK в 2026 нужен, когда вам нужен agent runtime, а не просто один вызов модели.

Что он закрывает лучше всего:

• agent loop и tool execution без ручного while-цикла;
• handoffs и agents as tools;
• sessions и working memory между turns;
• guardrails, human-in-the-loop и tracing;
• MCP и voice/realtime сценарии.

Что важно уточнить относительно старых обзоров:

• это уже не только Python: есть и TypeScript SDK;
• это уже не только Agent + Runner, а более широкий runtime;
• для сложных state graphs это всё ещё не замена LangGraph;
• для multi-provider portability abstraction tax остаётся на вас.

Когда OpenAI Agents SDK лучше plain Responses API?

1. Что такое OpenAI Agents SDK в 2026

По текущей official documentation SDK включает такие базовые слои:

• agent loop;
• function tools;
• agents as tools и handoffs;
• sessions;
• human-in-the-loop;
• guardrails;
• tracing;
• MCP server tool calling;
• realtime agents.

Это и есть главное отличие от старой рамки "минималистичный обвес вокруг Chat Completions". В current version SDK уже описывается как runtime, а не как просто набор sugar-helpers.

2. Главные primitives

Agent

Agent всё ещё остаётся основной сущностью:

• инструкции;
• модель;
• tools;
• handoffs;
• output schema;
• memory/session behavior.

Но практическая ценность в 2026 уже не в том, что можно создать агента в пять строк, а в том, что этот объект живёт внутри полноценного orchestration runtime.

Run / Runner

SDK берёт на себя типовой agent loop:

1. вызывает модель;
2. получает tool calls или финальный ответ;
3. исполняет tools;
4. возвращает результаты модели;
5. продолжает цикл до stop condition.

Это особенно полезно, когда run уже не single-turn, а включает:

• несколько tools;
• делегирование specialist agent;
• HITL approval;
• session continuity.

Handoffs и agents as tools

Это одна из сильнейших частей OpenAI stack.

Полезная mental model:

• agents as tools подходят, когда specialist делает bounded subtask;
• handoff подходит, когда specialist должен стать владельцем следующей части разговора.

SDK прямо разводит эти два паттерна, и это делает архитектуру чище, чем старая самодельная manager-loop оркестрация.

Sessions

В current docs sessions поданы как встроенный persistent working-context layer. Это не long-term memory platform, но хороший runtime-primitive для continuity внутри agent loop.

Практически это нужно для:

• многоходовых support flows;
• research sessions;
• coding/helpdesk agents;
• voice agents, где continuity критична.

Human-in-the-loop

Старые обзоры часто пропускали этот слой, а в current SDK он уже first-class.

Он нужен там, где run не должен самовольно:

• выполнять рискованные actions;
• подтверждать внешние изменения;
• отправлять sensitive outputs;
• завершать длинный run без approval.

Guardrails и tracing

Guardrails и tracing делают SDK ближе к production runtime, а не к tutorial package.

Практический смысл:

• guardrails проверяют входы, выходы и risky tool behavior;
• traces раскладывают run на inspectable spans;
• дальше это можно использовать для debugging, evals и regression analysis.

3. MCP и voice path

Это ещё одно важное отличие текущего состояния SDK от старых статей.

MCP

OpenAI Agents SDK now supports several MCP paths:

• hosted MCP tools;
• Streamable HTTP servers;
• HTTP+SSE servers;
• stdio servers.

То есть речь уже не о "можно прикрутить MCP когда-нибудь", а о нормальной встроенной поверхности для MCP-based tools.

Realtime / voice agents

Отдельная линия SDK закрывает spoken interactions:

• low-latency voice loop;
• interruptions;
• realtime context management;
• guardrails;
• voice-oriented orchestration.

Поэтому current article про OpenAI Agents SDK должна учитывать не только text agents, но и voice path.

4. Python и TypeScript

Старое утверждение Python-only уже устарело.

В current docs OpenAI поддерживает:

• openai-agents-python;
• @openai/agents для TypeScript.

Из этого следуют два practical consequences:

• SDK уже легче вписывать в web/backend stacks на Node;
• сравнение с Claude Agent SDK и LangGraph теперь корректнее делать не только на Python.

5. Когда брать OpenAI Agents SDK

SDK обычно оправдан, если вам нужны:

• provider-native OpenAI runtime;
• built-in handoffs;
• built-in tracing;
• sessions;
• MCP;
• realtime/voice agents;
• управляемый loop без ручной orchestration plumbing.

Типовые сценарии:

• support triage;
• research and browsing agents;
• coding assistants;
• internal operations copilots;
• voice/realtime assistants.

6. Когда не брать

SDK не всегда лучший выбор.

Не берите его по инерции, если вам нужен в первую очередь:

• vendor-neutral orchestration;
• сложный deterministic state graph;
• очень строгий workflow с малой автономностью;
• полностью custom memory/runtime layer;
• один простой tool-enabled workflow без реального agent loop.

В этих случаях лучше могут подойти:

• plain Responses API;
• LangGraph;
• свой workflow runtime;
• другой provider-native SDK, если core stack не OpenAI-first.

Минимальный Python path

from agents import Agent, Runner, function_tool


@function_tool
def get_ticket_status(ticket_id: str) -> str:
    return f"Ticket {ticket_id}: waiting for user response"


triage = Agent(
    name="Support triage",
    instructions="Help the user and use tools when needed.",
    model="gpt-5.2",
    tools=[get_ticket_status],
)

result = Runner.run_sync(triage, "Check ticket INC-4421")
print(result.final_output)

Это нормальный entry point, если вам нужен один agent loop и несколько bounded tools.

Handoff pattern

from agents import Agent, Runner

billing = Agent(
    name="Billing specialist",
    instructions="Handle invoices, refunds, and payment issues.",
)

technical = Agent(
    name="Technical specialist",
    instructions="Handle login, API, and product issues.",
)

router = Agent(
    name="Router",
    instructions="Route the user to the right specialist.",
    handoffs=[billing, technical],
)

result = Runner.run_sync(router, "The API key stopped working after rotation")
print(result.final_output)

handoff нужен именно тогда, когда specialist должен продолжить ownership диалога, а не просто вернуть маленький sub-result.

TypeScript path

import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const getBuildStatus = tool({
  name: 'get_build_status',
  description: 'Check CI build status',
  parameters: z.object({
    buildId: z.string(),
  }),
  async execute({ buildId }) {
    return `Build ${buildId}: passed`;
  },
});

const agent = new Agent({
  name: 'Engineering assistant',
  instructions: 'Use tools when needed and answer briefly.',
  model: 'gpt-5.2',
  tools: [getBuildStatus],
});

const result = await run(agent, 'Check build 8451');
console.log(result.finalOutput);

Практический вывод простой: OpenAI Agents SDK теперь уместен и в Node-centric production stacks, а не только в Python automation.

Частые ошибки

У нас internal support agent на OpenAI, нужны handoffs, traces и voice path. OpenAI Agents SDK уместен?

Проверьте себя