Heli + OpenAI Agents SDK: агенты через Chat Completions

Настройка

• Зарегистрируйтесь на getheli.ru (подтверждение почты или вход через Google / Яндекс ID) и создайте ключ на вкладке «Ключи» кабинета.
• Установите пакет: pip install openai-agents.
• Создайте AsyncOpenAI с base_url https://getheli.ru/v1 и ключом из переменной окружения.
• Передайте модель как OpenAIChatCompletionsModel с этим клиентом. Строковое имя вида openai/gpt-5.5 SDK по умолчанию трактует как модель OpenAI и отрезает префикс, поэтому явный объект модели надёжнее.
• Отключите трейсинг через set_tracing_disabled(True): трейсы выгружаются на серверы OpenAI и требуют ключа platform.openai.com.

Пример агента с инструментом

Если все агенты проекта работают через Heli, клиент можно задать глобально через set_default_openai_client и переключить SDK на Chat Completions вызовом set_default_openai_api("chat_completions"). Функции, которые есть только в Responses API, например hosted tools OpenAI, через Chat Completions недоступны.

Для отладки смотрите result.new_items: там видно, какие инструменты вызывал агент и с какими аргументами. Потоковый вывод даёт Runner.run_streamed — он работает через тот же клиент Heli без дополнительной настройки.

import asyncio
import os

from openai import AsyncOpenAI
from agents import (Agent, ModelSettings, OpenAIChatCompletionsModel, Runner,
                    function_tool, set_tracing_disabled)

set_tracing_disabled(True)

heli = AsyncOpenAI(base_url="https://getheli.ru/v1",
                   api_key=os.environ["HELI_API_KEY"])


@function_tool
def get_order_status(order_id: str) -> str:
    """Статус заказа по номеру."""
    return "Заказ " + order_id + ": передан в доставку"


agent = Agent(
    name="Support",
    instructions="Отвечай кратко. Статус заказа узнавай только через инструмент.",
    model=OpenAIChatCompletionsModel(model="anthropic/claude-sonnet-5",
                                     openai_client=heli),
    model_settings=ModelSettings(timeout=60.0),
    tools=[get_order_status],
)


async def main():
    result = await Runner.run(agent, "Где мой заказ 1042?")
    print(result.final_output)


asyncio.run(main())

Какие модели выбрать

Агенту нужна модель с надёжным tool calling: она должна правильно выбирать инструмент и заполнять аргументы по схеме. Для маршрутизирующего агента подойдёт недорогая модель, для исполнителя сложных задач — сильная.

Claude Sonnet 5 — сложные агентные цепочки.

GPT-5.5 — рассуждения и планирование.

GPT-5.4 mini — быстрая маршрутизация и простые инструменты.

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

• Ошибка трассировки 401 — не отключён трейсинг; вызовите set_tracing_disabled(True).
• 401 от Heli — ключ неверный или отозван; создайте новый на вкладке «Ключи».
• 402 insufficient_balance — закончился баланс; пополните его в кабинете.
• Модель не найдена или 404 — модель передана строкой и ушла в Responses API OpenAI; используйте OpenAIChatCompletionsModel.
• ModelTimeoutError — увеличьте ModelSettings(timeout=…) или сократите контекст агента.
• Агент ходит по кругу и тратит баланс — ограничьте число шагов параметром max_turns в Runner.run.

Документация API

Оплата — пополнение баланса.

Tool calling в Heli API