Інтеграція 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. Зв'яжіться з нами для оцінки вашого сценарію — отримайте консультацію з архітектури агентів.