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

Практичний розбір LLM: fine-tuning, RAG, агенти, деплой

Модель GPT‑4 або Claude 3.5 Sonnet через публічне API — не рішення, а просто інструмент. Коли приходить вимога «зробити як ChatGPT, але на наших даних», за нею стоїть реальна інженерна задача: від налаштування промптів до навчання 70B‑моделі на власній інфраструктурі. LLM розробка під ключ — це складний стек, і ми займаємося цим понад 5 років. За цей час реалізовано понад 20 проєктів у галузі генеративного AI: від RAG‑систем для юридичних департаментів до кастомних агентів для техпідтримки. Де саме знаходиться ваша задача — залежить від даних, latency‑вимог, бюджету та того, наскільки критична конфіденційність.

Типова ситуація: клієнт уже спробував ChatGPT, але результати нестабільні — то відповідає точно, то галюцинує. Або потрібна інтеграція в корпоративний портал з дотриманням політик безпеки. Розберемо кожен шар стеку в деталях — від RAG до production‑деплою.

Чому RAG‑системи ламаються і як це виправити?

RAG (Retrieval‑Augmented Generation) виглядає просто: знайшли релевантні документи, поклали в контекст, модель відповіла. На практиці збоїть у кількох місцях.

Chunking без перекриття. Класична помилка: chunk_size=512, overlap=0. Якщо відповідь лежить на межі двох чанків, retrieval не знайде жодного з достатньою впевненістю. Рішення: overlap 15–25% від chunk_size, а краще sentence‑aware splitting через spaCy або NLTK, а не наївне розбиття за символами.

Поганий embedder. Текст‑embedding‑ada‑002 — хороший для загального випадку, але на юридичних або медичних текстах програє спеціалізованим моделям: E5‑large‑v2, BGE‑M3 або fine‑tuned sentence‑transformers на доменних даних. Різниця в Recall@5 може становити 15–25%.

Відсутність re‑ranking. Векторний пошук оптимізований за швидкістю, не за релевантністю. Cross‑encoder re‑ranker (ms‑marco‑MiniLM‑L‑6‑v2, bge‑reranker‑large) після первинного retrieval піднімає точність топ‑3 при прийнятній затримці (+50–150 ms). Це часто важливіше за покращення embedding‑моделі.

Гібридний пошук. Тільки dense вектори погано працюють на точних запитах: імена, артикули, коди. BM25 (sparse) добре знаходить точні збіги, але не розуміє семантику. Гібрид через RRF (Reciprocal Rank Fusion) — оптимальний компроміс. Qdrant, Weaviate та pgvector 0.7+ підтримують гібридний пошук нативно.

Коли варто fine‑tune, а не промпт‑інжиніринг?

Промпт‑інжиніринг вирішує ~70% завдань адаптації LLM під домен. Решта 30% вимагають донавчання. Три ознаки: модель ігнорує специфічний формат виведення навіть при детальному описі в промпті; задача вимагає глибокого знання спеціалізованої лексики (медицина, право); потрібно значно знизити витрати на токени, замінивши велику модель меншою спеціалізованою.

LoRA та QLoRA — стандарт для SFT. LoRA додає trainable low‑rank матриці до attention‑шарів. Типова конфігурація для Llama‑3 8B: r=64, lora_alpha=128, target_modules=["q_proj","v_proj","k_proj","o_proj"] — параметрів, що навчаються, ~0.8%, навчання на одній A100 40GB. QLoRA додає 4‑бітну квантизацію (NF4) і дозволяє fine‑tune 70B модель на двох A100 40GB, хоча швидкість падає вдвічі порівняно з bf16.

DPO замість RLHF. Direct Preference Optimization вимагає лише пари (chosen, rejected), а не скалярні reward‑сигнали. DPOTrainer з бібліотеки trl (Hugging Face) реалізує це кількома десятками рядків.

Типова помилка. Датасет з 500 прикладів, 5 епох, validation loss 0.8 — здається норм. Але на тесті модель деградувала на загальних інструкціях. Причина: catastrophic forgetting. Рішення — додати 10–20% загальних instruction‑following прикладів (Alpaca, FLAN) у навчальну вибірку, щоб не зруйнувати вихідні здібності.

Як обрати базову модель: 8B чи 70B?

Для більшості задач fine‑tuning 8B моделі достатньо. 70B потрібен, коли потрібне глибоке міркування або baseline 8B не досягає потрібної якості навіть після донавчання. Вартість інференсу Llama‑3 8B через vLLM на A100 значно нижча, ніж у GPT‑4, що робить його економічно вигідним.

Що дає PagedAttention в production?

vLLM — перший вибір для serving open‑source моделей. PagedAttention — ключове технічне рішення: KV‑cache керується як virtual memory в ОС, без фрагментації. Це дає throughput у 2–4 рази вище порівняно з наївним HuggingFace Transformers inference. Документація vLLM підтверджує: continuous batching та PagedAttention — стандарт для високонавантажених LLM‑сервісів.

Типові числа на A100 80GB для Llama‑3 8B (bf16): 400–600 req/s, P50 latency 200–400ms, P99 latency 600–900ms при concurrency 64. Для 70B на двох A100 з tensor parallelism: 80–120 req/s, P99 latency 1.5–2.5s. Квантизація AWQ або GPTQ знижує споживання пам'яті в 2 рази при втраті якості в межах 1–3%.

Мультиагентні системи

Агенти — LLM з доступом до інструментів: пошук, виконання коду, запити до API, робота з БД. Основні патерни:

• ReAct (Reason + Act): модель розмірковує → обирає інструмент → спостерігає результат → знову розмірковує. LangChain та LlamaIndex реалізують з коробки.
• Multi‑agent orchestration: кілька спеціалізованих агентів з координатором зверху. Приклад: coordinator → researcher (пошук + summarization) → coder (генерація та виконання коду) → critic (перевірка). Інструменти: AutoGen (Microsoft), CrewAI, кастомна реалізація на LangGraph.

В продакшені агентні системи недетерміновані. Обов'язкові guardrails, ліміти кроків, логування кожного кроку, human‑in‑the‑loop для критичних дій.

Як ми гарантуємо якість LLM рішення?

Ми використовуємо RAGAS для автоматичної оцінки відповідей: faithfulness, answer relevancy, context precision. Система трекінгу експериментів на базі MLflow фіксує всі метрики, датасети та конфіги. Це дозволяє порівнювати різні гіпотези та доводити покращення з цифрами. Гарантію стабільної роботи забезпечує continuous integration з тестами на специфічних сценаріях (prompt injection, edge‑cases).

Як почати LLM розробку: наступні кроки

Ми передаємо:

• Технічну документацію (model card, конфіги, інструкції з розгортання)
• Доступ до інфраструктури (репозиторій з кодом, навчені ваги)
• 1 місяць підтримки після деплою (консультації, виправлення багів)
• Навчання команди замовника (2–3 заняття з експлуатації системи)

Терміни: базовий RAG‑прототип — 1–2 тижні. Fine‑tuning з даними замовника — 3–6 тижнів (з урахуванням підготовки даних). Production‑система з моніторингом та перенавчанням — 2–4 місяці.

Вартість розраховується індивідуально і залежить від обсягу даних, складності моделі та вимог до інфраструктури. Хочете оцінити свій проєкт? Зв'яжіться з нами — ми підготуємо попереднє резюме за 1–2 робочі дні. Або замовте консультацію фахівця з вибору підходу: RAG, fine‑tuning або гібрид — розповімо, що підійде саме вам.