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