Интеграция 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 — около $0.001/1K токенов, что в 15 раз дешевле 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 для критических действий.

Как мы работаем: этапы, сроки, результат

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

Мы передаём:

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

Сроки: базовый RAG‑прототип — 1–2 недели. Fine‑tuning с данными заказчика — 3–6 недель (с учётом подготовки данных). Production‑система с мониторингом и переобучением — 2–4 месяца. Стоимость рассчитывается индивидуально, зависит от объёма данных, сложности модели и требований к инфраструктуре.

Хотите оценить свой проект? Оставьте заявку — мы подготовим предварительное резюме за 1–2 рабочих дня. Или получите консультацию по выбору подхода: RAG, fine‑tuning или гибрид — расскажем, что подойдёт именно вам.