OpenAI Agents SDK — это официальная Python-библиотека с открытым исходным кодом (лицензия MIT) для создания AI-агентов, способных выполнять многошаговые задачи, вызывать внешние инструменты и передавать управление между специализированными агентами. В отличие от сторонних фреймворков, SDK изначально заточен под модели OpenAI (GPT-4, o3, o4-mini), что обеспечивает минимальные задержки и предсказуемое поведение без лишних обёрток. Если вы используете только OpenAI, этот SDK — самый простой способ внедрить агентов.
Архитектура: агенты, раннеры и инструменты
SDK строится на четырёх основных компонентах:
- Agent — главный класс, который объединяет системный промпт, набор инструментов и модель.
- Runner — цикл выполнения, управляющий вызовами инструментов и генерацией ответов (синхронный, асинхронный, стриминговый).
- Tool — функция или API, которую агент может вызывать; определяется через декоратор `@function_tool` или как класс.
- Handoff — механизм передачи задачи другому агенту (например, для обработки платежей или поиска в базе знаний).
Также SDK поддерживает контекстные переменные для краткосрочной памяти, экспериментальные guardrails на базе модели и встроенный трекинг вызовов для отладки.
Пример кода: агент для поиска в документации
Минимальный рабочий пример выглядит так:
python
from agents import Agent, Runner, function_tool
@function_tool
def search_docs(query: str) -> str:
# Имитация поиска
return f”Результаты для ‘{query}’: см. раздел 4.2.”
agent = Agent(
name=”DocHelper”,
instructions=”Ты помогаешь находить информацию в документации. Используй search_docs.”,
tools=[search_docs]
)
result = Runner.run_sync(agent, “Как создать агента?”)
print(result.final_output)
Код наглядно демонстрирует паттерн: инструмент — обычная функция с декоратором, агент получает инструкцию и список инструментов, Runner.run_sync запускает диалог. SDK сам решает, когда и какой инструмент вызывать, и возвращает итоговый ответ.
Сравнение: OpenAI Agents SDK vs AutoGen vs LangGraph
| Критерий | OpenAI Agents SDK | AutoGen (Microsoft) | LangGraph (LangChain) |
|---|---|---|---|
| Модели по умолчанию | Только OpenAI (GPT-4, o3, o4-mini) | Любые через коннекторы | Любые (OpenAI, Anthropic, локальные) |
| Архитектура | Одноагентная / иерархическая | Многоагентная с дебатами | Граф с состояниями |
| Простота старта | Высокая (5 строк кода) | Средняя | Средняя (требует понимания графов) |
| Встроенная память | Контекстные переменные | Через History | LangGraph persistence |
| Handoff (передача задач) | Встроенный механизм | Через асинхронные сообщения | Через узлы графа |
OpenAI Agents SDK выигрывает в простоте, если вы уже используете модели OpenAI. AutoGen лучше подходит для распределённых сценариев (например, код-ревью несколькими агентами). LangGraph — для сложных ветвлений и цепочек с состоянием.
Ограничения, которые стоит знать
Привязка к экосистеме OpenAI. Нельзя использовать Anthropic, Google или локальные модели без дополнительных обёрток. Если вам нужна мультимодельность — выбирайте LangGraph.
2. Нет встроенной поддержки мультимодальности. Изображения и аудио передаются только через инструменты (например, через API Vision). Отдельного класса для этого нет.
3. Долгосрочная память отсутствует. Контекстные переменные живут только в рамках одного запуска. Для постоянного хранения данных сессии потребуется внешняя база (SQLite, Redis).
4. Guardrails пока экспериментальны. В текущей реализации они могут как пропускать нежелательные запросы, так и блокировать корректные. Рекомендуется тестировать на своих данных.
5. Токен-лимиты. Агенты с большим количеством инструментов быстро расходуют контекст (особенно если инструменты возвращают длинные результаты). Следите за usage в трекинге.
Что проверить перед запуском в production
- Убедитесь, что у вас есть API-ключ OpenAI с доступом к моделям (GPT-4, o3, o4-mini). Без него SDK не запустится.
- Изучите официальную документацию: https://platform.openai.com/docs/agents — там есть примеры для чат-ботов, RAG и поиска.
- Для production используйте Runner.run_streamed() вместо синхронного вызова, чтобы избежать блокировки при длительных задачах.
- Включите трекинг: передавайте trace_id в Runner, чтобы логировать все вызовы инструментов и ответы модели.
- Тестируйте handoff-агенты на небольших задачах: неправильная инструкция может привести к циклическим вызовам.
Практические сценарии для автоматизации
- Чат-бот поддержки с доступом к базе знаний (через search_docs или API).
- Агент для извлечения данных из документов (PDF, HTML) с вызовом внешних парсеров.
- Многошаговая обработка заявок: агент-координатор передаёт задачи специализированным агентам (проверка баланса, генерация отчёта, отправка письма).
- Генерация SEO-метаданных для контента: агент получает текст, извлекает ключевые слова и формирует title и description.
Как обновляется SDK
Разработчики OpenAI регулярно обновляют SDK — в мае 2025 года добавили поддержку handoff-агентов и улучшенный трекинг. Следите за changelog на GitHub: https://github.com/openai/openai-agents-python/releases.
Заключение: ваш первый шаг
Попробуйте SDK в своём проекте: установите через `pip install openai-agents`, напишите первого агента с одним инструментом и запустите с простой задачей. Для production используйте стриминг и мониторинг через трекинг. Если вам нужна гибкость в выборе моделей или сложные графы — присмотритесь к LangGraph или AutoGen. Для стандартных задач автоматизации на базе OpenAI официальный SDK часто оказывается самым простым и надёжным выбором.