Как собрать ИИ-агента
на OpenAI Agents SDK
tools · handoffs · MCP

OpenAI Agents SDK vs режим агента в ChatGPT

Путаница здесь частая. «ChatGPT агент», «Agent Builder» и «OpenAI Agents SDK» — это разные пути.

SDK, Agent Builder и UI-агент — три разных пути

Agents SDK — это code-first стек: вы пишете логику в Python и запускаете её у себя или на сервере. Документация позиционирует SDK как production-ready развитие эксперимента Swarm: мало абстракций, есть Agents, handoffs / agents-as-tools, guardrails и tracing.

Из России доступ к API OpenAI часто упирается в оплату и регистрацию. Честно: без зарубежной карты или посредника ключ может быть недоступен. Рабочие обходы на старте:

1. прогнать логику на бесплатных локальных моделях и перенести схему на OpenAI позже;
2. держать финальную публикацию в Make/n8n/Telegram отдельно от LLM;
3. если API недоступен — собрать похожий пайплайн ролей в no-code (n8n) и вернуться к SDK, когда ключ появится.

Этот гайд всё равно полезен: роли, tools, handoffs и MCP — одни и те же идеи, даже если движок позже сменится.

Почему Assistants API больше не стартовая точка

Agents SDK по умолчанию опирается на Responses API — современный транспорт запросов к моделям OpenAI. Assistants API (Assistants / Threads / Runs) официально устаревает: отключение запланировано на 26 августа 2026. Новые интеграции на Assistants начинать не стоит.

Когда брать что:

• короткий сценарий на 1–2 вызова tool — можно Responses API напрямую;
• несколько ролей, approvals, MCP, сессии — берите Agents SDK.

Function tools: даём агенту руки, а не только текст

Без tools агент — умный чат. С tools он может считать, читать файл, дергать ваш сервис.

@function_tool и схема аргументов

Минимальный пример:

from agents import Agent, Runner, function_tool

@function_tool
def save_draft(title: str, body: str) -> str:
    """Сохраняет черновик статьи в локальный файл drafts.txt."""
    with open("drafts.txt", "a", encoding="utf-8") as f:
        f.write(f"# {title}\n{body}\n\n")
    return f"Черновик «{title}» сохранён"

agent = Agent(
    name="Writer",
    instructions="Пиши коротко. Когда черновик готов — сохрани через save_draft.",
    tools=[save_draft],
)

result = Runner.run_sync(agent, "Тема: 3 ошибки в ТЗ на статью. Сохрани черновик.")
print(result.final_output)

Что важно новичку:

• docstring читает модель — пишите по-русски, что делает функция и когда её звать;
• типы аргументов (str, int) помогают не сломать вызов;
• для опасных действий (отправка, удаление) позже включите needs_approval — человек подтверждает шаг.

Кроме своих функций есть hosted tools OpenAI (web search, file search, code interpreter и др.) — их выполняет сторона OpenAI, без вашего локального callback.

Сколько tools достаточно, чтобы агент не «плавал»

Ориентир: 2–5 tools на одного агента. Если список длинный, модель чаще выбирает не тот инструмент или «забывает» нужный.

Практика:

• researcher — поиск + чтение базы;
• writer — сохранение черновика;
• executor — публикация (только с approval).

Не давайте одному агенту сразу CRM, почту, оплату, диск и Telegram. Раздутый список tools — главный способ сжечь бюджет и получить хаос.

MCP: подключаем внешние инструменты к агенту

Свои function tools покрывают то, что вы написали в Python. MCP нужен, когда инструменты уже живут снаружи: файловая система, вики, CRM-коннектор, сервер в Cursor.

Stdio, Streamable HTTP и HostedMCPTool — как выбрать транспорт

Как выбрать:

1. быстрый локальный эксперимент → stdio;
2. свой сервер в сети → Streamable HTTP;
3. хотите, чтобы OpenAI сам ходил в MCP URL → HostedMCPTool.

Подключение в общем виде: либо tools=[HostedMCPTool(...)], либо mcp_servers=[MCPServerStdio(...)] / MCPServerStreamableHttp(...). Классы и параметры — в разделе MCP официальной документации SDK (ссылка в конце статьи).

Approvals и фильтр tools, чтобы не открыть лишнее

MCP-сервер может отдать десятки tools. Агенту это вредно.

Делайте так:

• включите фильтр tools (tool_filter / static allow-list) — только нужные имена;
• на запись, отправку, удаление — require_approval / needs_approval;
• не учите SSE как основной путь: протокол уходит от SSE к Streamable HTTP и stdio.

Признак успеха MCP. В tracing видно list_tools и конкретный MCP tool call, а агент не видит «лишние» действия вне allow-list.

Сценарий research → draft → review под контент и лиды

Соберём мини-контент-завод на идеях SDK — без пересказа чужих travel-demo.

Роли triage / research / writer / critic / executor

Рекомендуемая схема для контента:

Оркестрация:

• внутри контент-цикла — manager + agents-as-tools (один владелец ответа + critic);
• на ветке «опубликовать» — handoff или отдельный executor с approval.

Псевдо-каркас ролей:

Manager
  ├─ research.as_tool(...)
  ├─ writer.as_tool(...)
  ├─ critic.as_tool(...)
  └─ publish_draft (function_tool, needs_approval=True)

Так вы не теряете контроль и не плодите бесконечные handoffs.

Вывод в файл, Telegram или Make/n8n без переписывания гайда конкурента

Финальный шаг агента — не «ещё один абзац», а артефакт:

• дописать drafts/slug.md;
• отправить HTTP webhook в Make/n8n;
• положить текст в очередь Telegram-бота.

Agents SDK здесь остаётся мозгом. Make/n8n — руками публикации, которые у вас уже настроены. Не нужно переносить весь гайд n8n внутрь этой статьи: достаточно endpoint’а «принял JSON → опубликовал».

Что должно получиться за один прогон: бриф → факты → черновик → замечания critic → пауза HITL → файл или webhook. Если паузы нет — в прод не пускайте.

Чеклист запуска и куда расти дальше

Мини-чеклист перед продом

• Python ≥ 3.10, openai-agents 0.19.x, ключ в env
• Hello World через Agent + Runner проходит
• У каждого агента 2–5 tools, есть docstring
• Выбран паттерн: handoff или as_tool (не «всё сразу без правил»)
• Есть лимит ходов
• MCP: выбран транспорт, SSE не default, включён tool filter
• Publish / delete / pay — только с HITL
• Sessions не смешаны с чужими id диалога в одном run
• Секреты не в git
• Есть tracing/логи на первый боевой прогон

От одного SDK-агента к контент-заводу и обучению

Когда Hello World и один writer стабильны, наращивайте так:

1. researcher + writer;
2. critic;
3. executor с approval;
4. мост в Telegram / WordPress / Make.

Дальше упираетесь не в «ещё фреймворк», а в процесс: брифы, статусы, календарь, QA. Если нужна система целиком — обучение работе с агентами и контент-заводом закрывает как раз этот слой: роли, автоматизация, публикация, а не только вызов модели.

Что проверяли по источникам