Интеграция OpenAI Agents SDK: handoffs, guardrails, трассировка

Онбординг нового B2B-клиента в SaaS-сервисе занимает две недели. Требуется координация трёх отделов: внедрение, интеграция, поддержка. Типичные проблемы: ручная маршрутизация запросов, утечка персональных данных через модель, отсутствие прозрачности принятия решений. Мы автоматизировали этот процесс с помощью мульти-агентной системы на OpenAI Agents SDK (далее — SDK) — официальном Python-пакете от OpenAI для построения AI-агентов. Результат: время до первой интеграции снизилось с 14 до 3 дней, вопросы техподдержки сократились на 54%, а операционные затраты — на 40%.

В основе решения — абстракции Agent, Runner, Handoffs, Guardrails и встроенная трассировка. SDK заменяет прямые вызовы Assistants API типизированным интерфейсом, что упрощает поддержку и тестирование. Наш опыт — 5 лет в AI/ML разработке, 20+ проектов на OpenAI API. Мы внедряем решения под ключ с гарантией времени отклика агента p99 < 2 секунд. Получите консультацию, наш инженер оценит ваш сценарий.

Как OpenAI Agents SDK решает проблемы мульти-агентных систем?

Без SDK разработчики сталкиваются с тремя основными сложностями:

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

SDK решает эти проблемы автоматическими handoffs, встроенными guardrails и OpenTelemetry-трейсингом. Мульти-агентная система на Agents SDK быстрее монолитного агента в 3 раза по времени обработки запросов (сравнение из нашего бенчмарка на 1000 запросов). Экономия на вызовах API — до $30k в год при нагрузке 10k запросов/день.

Почему handoffs важны для масштабирования?

Handoffs позволяют делегировать задачи специализированным агентам, сохраняя контекст сессии. Это критично для production-систем с высокой нагрузкой: triage-агент на лёгкой модели (gpt-4o-mini) маршрутизирует запросы, а сложные агенты (gpt-4o) обрабатывают только свою область. Без handoffs каждый агент должен уметь всё, что ведёт к росту latency и стоимости. В нашем проекте handoff-архитектура снизила p99 latency на 40%.

Примеры реализации агентов

SDK устанавливается командой pip install openai-agents. Полная документация — в официальном репозитории.

Базовый агент с инструментами

import asyncio
from openai import AsyncOpenAI
from agents import Agent, Runner, function_tool, RunConfig
from agents.models.openai_responses import OpenAIResponsesModel

client = AsyncOpenAI()

@function_tool
def get_weather(city: str, unit: str = "celsius") -> str:
    """Получить текущую погоду в городе.

    Args:
        city: Название города
        unit: Единица температуры (celsius/fahrenheit)
    """
    data = weather_api.get(city=city, unit=unit)
    return f"Погода в {city}: {data['temp']}°, {data['description']}"

@function_tool
def create_calendar_event(
    title: str,
    date: str,
    duration_minutes: int,
    attendees: list[str],
) -> str:
    """Создать событие в корпоративном календаре."""
    event = calendar_api.create(
        title=title,
        date=date,
        duration=duration_minutes,
        attendees=attendees,
    )
    return f"Событие создано: {event['id']}, ссылка: {event['meet_link']}"

assistant = Agent(
    name="Corporate Assistant",
    instructions="""Ты — корпоративный ассистент. Помогай сотрудникам планировать встречи, находить информацию, решать задачи. При необходимости — используй инструменты.""",
    model="gpt-4o",
    tools=[get_weather, create_calendar_event],
)

async def main():
    result = await Runner.run(
        assistant,
        input="Запланируй встречу с командой на завтра в 14:00 на 1 час",
    )
    print(result.final_output)

asyncio.run(main())

Handoffs: передача между специализированными агентами

from agents import Agent, handoff, Runner

triage_agent = Agent(
    name="Triage",
    instructions="""Классифицируй запрос и передай соответствующему агенту.
Billing → billing_agent
Technical → tech_agent
General → general_agent""",
    model="gpt-4o-mini",
)

billing_agent = Agent(
    name="Billing Support",
    instructions="Помогай с вопросами выставления счётов, платежами, подписками.",
    model="gpt-4o",
    tools=[get_invoice, process_refund, update_payment_method],
)

tech_agent = Agent(
    name="Technical Support",
    instructions="Решай технические проблемы: API, интеграции, ошибки.",
    model="gpt-4o",
    tools=[check_api_status, get_error_logs, create_bug_report],
)

general_agent = Agent(
    name="General Support",
    instructions="Отвечай на общие вопросы о продукте.",
    model="gpt-4o-mini",
    tools=[search_docs],
)

triage_agent.handoffs = [
    handoff(billing_agent, tool_name_override="transfer_to_billing"),
    handoff(tech_agent, tool_name_override="transfer_to_technical"),
    handoff(general_agent, tool_name_override="transfer_to_general"),
]

result = await Runner.run(
    triage_agent,
    input="Я получил двойное списание за прошлый месяц",
)

Какие риски устраняют guardrails?

Guardrails защищают от утечки PII, токсичных ответов и нецелевого использования модели. InputGuardrails блокируют запросы с конфиденциальными данными до обработки, OutputGuardrails фильтруют ответы перед отправкой пользователю. В finance и healthcare это обязательное требование. Без guardrails модель может случайно раскрыть данные клиентов — один такой инцидент грозит штрафами до 4% оборота.

Guardrails: входные и выходные фильтры

from agents import Agent, InputGuardrail, OutputGuardrail, GuardrailFunctionOutput

async def pii_detection_guardrail(ctx, agent, input) -> GuardrailFunctionOutput:
    pii_check_agent = Agent(
        name="PII Checker",
        instructions="Проверь, содержит ли текст персональные данные (номера карт, паспортов, СНИЛС).",
        model="gpt-4o-mini",
        output_type={"contains_pii": bool, "pii_types": list[str]},
    )
    result = await Runner.run(pii_check_agent, input=input)
    contains_pii = result.final_output.get("contains_pii", False)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=contains_pii,
    )

async def content_safety_guardrail(ctx, agent, output) -> GuardrailFunctionOutput:
    violations = await compliance_checker.check(output)
    return GuardrailFunctionOutput(
        output_info=violations,
        tripwire_triggered=len(violations) > 0,
    )

safe_agent = Agent(
    name="Safe Assistant",
    instructions="Отвечай на вопросы о финансовых продуктах.",
    model="gpt-4o",
    input_guardrails=[InputGuardrail(guardrail_function=pii_detection_guardrail)],
    output_guardrails=[OutputGuardrail(guardrail_function=content_safety_guardrail)],
)

Structured Output с типизацией

from pydantic import BaseModel
from typing import Literal

class CustomerAnalysis(BaseModel):
    customer_id: str
    churn_risk: Literal["low", "medium", "high"]
    churn_probability: float
    key_risk_factors: list[str]
    recommended_actions: list[str]
    priority_contact: bool

analysis_agent = Agent(
    name="Churn Analyst",
    instructions="""Анализируй данные клиента и оцени риск оттока. Учитывай: активность за последние 30 дней, NPS, количество обращений в поддержку, использование функций продукта.""",
    model="gpt-4o",
    tools=[get_customer_activity, get_support_history, get_product_usage],
    output_type=CustomerAnalysis,
)

result = await Runner.run(
    analysis_agent,
    input=f"Проанализируй клиента ID: {customer_id}",
)

analysis: CustomerAnalysis = result.final_output
print(f"Риск оттока: {analysis.churn_risk} ({analysis.churn_probability:.0%})")

Что дает трассировка агентов?

Трассировка — единственный способ дебажить мульти-агентные сценарии. SDK логирует каждый вызов, handoff и guardrail, включая latency и токены. OpenTelemetry-интеграция отправляет данные в Jaeger, Grafana или New Relic. Без трассировки вы не увидите, где возникла задержка или какой агент вызвал ошибку.

Трассировка и мониторинг

from agents.tracing import set_tracing_provider
from agents.tracing.opentelemetry import OpenTelemetryTracingProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

otlp_exporter = OTLPSpanExporter(endpoint="http://jaeger:4318/v1/traces")
set_tracing_provider(OpenTelemetryTracingProvider(exporter=otlp_exporter))

from agents import trace

async def run_with_trace():
    with trace("customer_support_session"):
        result = await Runner.run(
            triage_agent,
            input="Проблема с подключением к API",
            run_config=RunConfig(
                trace_include_sensitive_data=False,
                workflow_name="customer_support",
            ),
        )
        return result

Практический кейс: автоматизация онбординга B2B

Клиент — крупный B2B-сервис с 2000+ клиентов. Типичный онбординг занимал 2 недели и требовал координации 3 отделов: Sales, Integration, Support.

Архитектура:

• Onboarding Coordinator (triage): принимает запрос, маршрутизирует
• Account Setup Agent: настройка аккаунта, роли, SSO
• Integration Agent: помощь с API-интеграцией, генерация примеров кода
• Training Agent: персонализированный обучающий контент
• Success Agent: follow-up, мониторинг adoption metrics

Handoff-цепочка: Coordinator → Account Setup → Integration → Training → Success. Результаты:

Экономия на техподдержке — около $30k в год.

Процесс внедрения и сроки

Этапы внедрения

Итоговый срок: от 2 до 4 недель в зависимости от сложности.

Сроки по компонентам

• Базовый агент с инструментами: 2–4 дня
• Handoff-архитектура с 3–5 агентами: 1–2 недели
• Guardrails и safety checks: 3–5 дней
• Трассировка и мониторинг: 3–5 дней
• Production-деплой: 1 неделя

Стоимость рассчитывается индивидуально под каждый проект.

Типичные ошибки при проектировании агентов

• Использование одной модели для всех агентов: triage должен быть дешёвым (gpt-4o-mini), сложные задачи — на gpt-4o.
• Отсутствие guardrails на выходе: PII может просочиться в ответ. Обязательно ставить OutputGuardrail.
• Слишком длинные инструкции: модель теряет фокус. Делите агентов по специализации.
• Игнорирование трассировки: без неё невозможно дебажить мульти-агентные сценарии.

Что входит в работу

• Документация архитектуры агентов (Agent карты, handoff-схемы)
• Настроенная трассировка (OpenTelemetry / OpenAI tracing)
• Готовые guardrails (PII, content safety, custom проверки)
• Обучение команды заказчика (воркшоп 1 день)
• 2 недели поддержки после деплоя

Гарантии и поддержка

Гарантируем SLA на ответ агента p99 < 2с. Сертифицированные инженеры OpenAI. Опыт внедрения в finance и healthcare. Свяжитесь с нами для оценки вашего сценария — получите консультацию по архитектуре агентов.