Учебник по OpenAI Agents API: создаём агента, который пишет и запускает код в облаке

Большинство приложений на базе LLM работают по простому сценарию: отправьте подсказку, получите ответ и используйте его в своём приложении.

Это хорошо подходит для простых задач, но всё усложняется, когда модели нужно написать код, запустить его, проверить результат, поработать с файлами, исправить ошибки и продолжать, пока задача действительно не будет завершена.

Именно здесь становится по-настоящему полезным Agents API от OpenAI.

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

В этом руководстве пример будет простым. Мы создадим небольшой вымышленный датасет продаж кафе и передадим его агенту. Агент напишет и выполнит анализ, проверит результаты и создаст для нас три выходных файла.

Когда вы увидите, как всё это работает «за кулисами», вы начнёте понимать, какая часть привычного процесса разработки кода автоматизируется за вас. 

Если вы новичок в агентах ИИ, рекомендуем ознакомиться с нашим карьерным треком «Основы AI-агентов». 

Что такое OpenAI Agents API?

С OpenAI Agents API вы передаёте агенту задачу, нужные файлы и рабочую среду, а затем позволяете ему заняться остальным.

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

Дальше большую часть работы выполняет Agents API.

Под капотом OpenAI управляет средой Codex, включая оркестрацию, контекст, использование инструментов, выполнение и длительные сессии. Это можно воспринимать почти как OpenAI Codex, работающий в облаке для вашего приложения. 

Вам меньше нужно беспокоиться о настройке вычислительных ресурсов, управлении рабочей средой, отслеживании сессии или построении полного цикла агента самостоятельно.

Это особенно полезно для более сложных и долгих задач, где агенту нужно действительно выполнить работу, а не просто выдать ответ.

В этом учебнике мы будем использовать песочницу, размещённую в OpenAI:

Мы отправляем один запрос с CSV‑файлом, задачей и конфигурацией агента. 

Затем Agents API создаёт и управляет сессией и песочницей за нас.

Внутри песочницы агент может изучить файл, определить подход к анализу, сгенерировать код на Python, выполнить его, проверить результаты и исправить недочёты, если что-то пойдёт не так.

Когда всё готово, результаты сохраняются как артефакты сессии. 

Это могут быть графики, очищенные датасеты, отчёты или любые другие файлы, созданные агентом. Мы можем получить эти файлы и дать пользователю возможность их скачать и просмотреть.

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

OpenAI Responses API vs Agents SDK vs Agents API: что выбрать?

Главное различие между этими тремя вариантами — какую часть процесса вы хотите контролировать самостоятельно.

Используйте Responses API, когда нужно, чтобы модель выполнила узкую задачу: суммаризацию, извлечение, классификацию, ответы на вопросы, сформировала структурированный вывод или сделала несколько вызовов инструментов.

Используйте Agents SDK, когда вы самостоятельно создаёте агентное приложение и хотите больше контроля над агентами, инструментами, передачами, защитными механизмами и мультиагентными процессами.

Используйте Agents API, когда задача сложнее и требует собственной рабочей среды. Это полезно, когда агенту нужно работать с файлами, запускать код, проверять результаты, исправлять ошибки и двигаться дальше через несколько шагов.

Пошаговое руководство: создаём агента для анализа данных с OpenAI

В этом руководстве мы используем Agents API, потому что агенту нужно работать с файлом, продумывать анализ, запускать код, проверять результаты и сохранять итоговые артефакты для пользователя.

Приступим

1. Настройте Python‑среду для Agents API

В этом руководстве мы будем использовать Jupyter Notebook, чтобы пошагово протестировать Agents API и понять, как работает каждая часть. 

Начнём с установки пакета OpenAI и импорта библиотек, которые понадобятся дальше.

Сначала установите или обновите пакет OpenAI для Python:

%pip install -q --upgrade openai

Затем импортируйте нужные библиотеки:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Теперь создайте клиент OpenAI:

client = OpenAI()

Убедитесь, что переменная OPENAI_API_KEY уже задана в вашей среде. Клиент OpenAI подхватит её автоматически.

2. Сгенерируйте пример данных для AI‑агента

Мы создадим небольшой фейковый датасет продаж, чтобы было что передать агенту.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Этот код создаёт 50 фейковых заказов кафе по разным товарам, локациям, датам и скидкам. Мы используем фиксированное начальное значение генератора случайных чисел, чтобы при каждом запуске ноутбука генерировался один и тот же датасет.

3. Создайте и закодируйте CSV‑файл для песочницы агента

Далее преобразуем сгенерированные данные в CSV‑файл, который можно передать агенту.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Вывод:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

Мы также кодируем CSV в Base64, потому что отправим файл непосредственно вместе с запросом к агенту.

4. Определите задачу агента и ожидаемые результаты

Теперь опишем, что мы хотим, чтобы агент сделал с CSV‑файлом.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

Важно, что мы описываем цель и ожидаемые результаты, а не пишем код анализа сами.

Агент сам решает, как выполнить работу, запускает код и проверяет результаты перед завершением.

5. Запустите агента в размещённой песочнице OpenAI

Теперь отправим всё в Agents API одним запросом и позволим агенту выполнить реальную работу в облаке.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

Именно здесь происходит основная работа.

Мы делаем один запрос, содержащий конфигурацию агента, размещённую среду, CSV‑файл и задачу. 

OpenAI создаёт управляемую сессию и запускает агента в размещённой песочнице. После этого агент может изучить файл, написать analyze_sales.py, выполнить его, проверить результаты, исправить проблемы и создать итоговые файлы. 

Endpoint создания сессии поддерживает и среду, и исходный ввод в одном запросе.

В запросе три основных части:

• agent указывает OpenAI, какую модель использовать и как должен вести себя агент.
• environment предоставляет агенту его рабочее пространство и помещает в него наш CSV‑файл.
• input передаёт агенту задачу, определённую в предыдущем разделе.

Мы также устанавливаем stream=True. 

Это не меняет способ выполнения задачи. Это просто позволяет получать события, пока агент работает, вместо того чтобы ждать завершения всего шага, прежде чем что-то увидеть.

В этом примере мы слушаем события agent.session.turn.output_text.delta и постоянно обновляем ноутбук последним текстом.

То есть появляющийся выше текст — это отчёт агента о ходе выполнения и финальный ответ. 

Сама задача продолжает выполняться в размещённой среде, пока мы не получим событие agent.session.turn.completed.

В моём запуске агент создал и выполнил analyze_sales.py, проверил сгенерированные файлы и подтвердил общий объём чистых продаж в 600.55.

Важно, что модель не просто сказала нам, какой Python‑код запустить. Агент сам написал код, выполнил его, проверил результат и подтвердил вывод.

6. Получите и скачайте файловые артефакты агента

Теперь, когда агент завершил работу, мы можем скачать файлы, созданные в этом шаге.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Вывод:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Здесь мы перечисляем артефакты из сессии, оставляем те, что были созданы завершённым шагом, и скачиваем их в локальную папку cloud_bean_results.

7. Удалите сессию, чтобы сократить расходы на вычисления в песочнице

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

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Вывод:

Session deleted: True

Это удаляет управляемую сессию из API. 

OpenAI отмечает, что физическая очистка нижележащих ресурсов может продолжаться асинхронно после возврата ответа на запрос удаления.

Этот шаг особенно важен при использовании песочницы, размещённой в OpenAI. 

Песочница — это вычислительная среда, где агент запускает код и работает с файлами; размещённые песочницы используют контейнерные вычисления, которые тарифицируются отдельно от использования модели. 

Поэтому если держать сессии и среды дольше, чем нужно, расходы на вычисления будут расти.

Итоги: стоит ли OpenAI Agents API своих денег?

Что меня особенно впечатлило в Agents API — сколько он может сделать по одному простому вызову API.

Мы передали файл, задачу, конфигурацию модели и размещённую среду. 

Дальше он сделал всё остальное: создал рабочее пространство, изучил данные, написал код на Python, выполнил его, проверил результаты, при необходимости всё исправил и выдал итоговые артефакты.

Это действительно похоже на Codex, работающий в облаке для вашего приложения. 

Мне не пришлось думать о настройке вычислительных ресурсов, управлении циклом выполнения, обработке промежуточных файлов или отслеживании каждого шага. По сути, нужно было хорошо определить задачу и потом изучить результат.

Сам запуск занял около двух минут, но за это время агент сделал очень много «за кулисами».

В этом и отличие от обычного запроса к API. 

Вы ждёте не просто генерации текста моделью. Вы ждёте, пока агент действительно выполнит часть работы.

В моих тестах три запуска этого примера стоили около $1.52 суммарно, включая использование модели и размещённой среды. 

Для такой небольшой задачи это недёшево, поэтому в продакшене я бы в первую очередь протестировал более компактные или дешёвые модели.

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