Интеграция 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. Свяжитесь с нами для оценки вашего сценария — получите консультацию по архитектуре агентов.