OpenAI Agents SDK Integration: Handoffs, Guardrails, Tracing

Onboarding a new B2B client in a SaaS service takes two weeks. It requires coordination between three departments: implementation, integration, and support. Typical problems: manual request routing, personal data leakage through the model, and lack of decision transparency. We automated this process using a multi-agent system based on the OpenAI Agents SDK (hereinafter SDK) — an official Python package from OpenAI for building AI agents. Result: time to first integration dropped from 14 to 3 days, support queries decreased by 54%, and operational costs by 40%.

The solution is built on the Agent, Runner, Handoffs, Guardrails abstractions and built-in tracing. The SDK replaces direct calls to the Assistants API with a typed interface, simplifying maintenance and testing. Our experience: 5 years in AI/ML development, 20+ projects on OpenAI API. We implement turnkey solutions with a guaranteed agent response time of p99 < 2 seconds. Get a consultation — our engineer will evaluate your scenario.

How OpenAI Agents SDK Solves Multi-Agent System Problems?

Without the SDK, developers face three main challenges:

• Chaos with multiple agents: manual request routing and context passing.
• PII leakage: the model may expose card numbers or passport details without additional filters.
• No transparency: impossible to understand why an agent made a decision.

The SDK solves these with automatic handoffs, built-in guardrails, and OpenTelemetry tracing. A multi-agent system on Agents SDK processes requests 3x faster than a monolithic agent (based on our benchmark of 1000 requests). API call savings: up to $30k per year at 10k request/day load.

Why Handoffs Matter for Scaling?

Handoffs allow delegating tasks to specialized agents while preserving session context. This is critical for production systems with high load: a triage agent on a lightweight model (gpt-4o-mini) routes requests, while complex agents (gpt-4o) handle only their domain. Without handoffs, each agent must be able to do everything, leading to increased latency and cost. In our project, the handoff architecture reduced p99 latency by 40%.

Agent Implementation Examples

The SDK is installed with pip install openai-agents. Full documentation is in the official repository.

Basic Agent with Tools

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:
    """Get current weather in a city.

    Args:
        city: City name
        unit: Temperature unit (celsius/fahrenheit)
    """
    data = weather_api.get(city=city, unit=unit)
    return f"Weather in {city}: {data['temp']}°, {data['description']}"

@function_tool
def create_calendar_event(
    title: str,
    date: str,
    duration_minutes: int,
    attendees: list[str],
) -> str:
    """Create an event in the corporate calendar."""
    event = calendar_api.create(
        title=title,
        date=date,
        duration=duration_minutes,
        attendees=attendees,
    )
    return f"Event created: {event['id']}, link: {event['meet_link']}"

assistant = Agent(
    name="Corporate Assistant",
    instructions="""You are a corporate assistant.
Help employees schedule meetings, find information, solve tasks.
Use tools when necessary.""",
    model="gpt-4o",
    tools=[get_weather, create_calendar_event],
)

async def main():
    result = await Runner.run(
        assistant,
        input="Schedule a meeting with the team for tomorrow at 2:00 PM for 1 hour",
    )
    print(result.final_output)

asyncio.run(main())

Handoffs: Transfer Between Specialized Agents

from agents import Agent, handoff, Runner

triage_agent = Agent(
    name="Triage",
    instructions="""Classify the request and transfer to the appropriate agent.
Billing → billing_agent
Technical → tech_agent
General → general_agent""",
    model="gpt-4o-mini",
)

billing_agent = Agent(
    name="Billing Support",
    instructions="Help with invoicing, payments, subscriptions.",
    model="gpt-4o",
    tools=[get_invoice, process_refund, update_payment_method],
)

tech_agent = Agent(
    name="Technical Support",
    instructions="Solve technical issues: API, integrations, errors.",
    model="gpt-4o",
    tools=[check_api_status, get_error_logs, create_bug_report],
)

general_agent = Agent(
    name="General Support",
    instructions="Answer general product questions.",
    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="I got a double charge last month",
)

What Risks Do Guardrails Mitigate?

Guardrails protect against PII leakage, toxic responses, and misuse of the model. InputGuardrails block requests with sensitive data before processing; OutputGuardrails filter responses before sending to the user. In finance and healthcare, this is a mandatory requirement. Without guardrails, the model may accidentally expose client data — a single such incident can result in fines up to 4% of turnover.

Guardrails: Input and Output Filters

from agents import Agent, InputGuardrail, OutputGuardrail, GuardrailFunctionOutput

async def pii_detection_guardrail(ctx, agent, input) -> GuardrailFunctionOutput:
    pii_check_agent = Agent(
        name="PII Checker",
        instructions="Check if the text contains personal data (card numbers, passports, SNILS).",
        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="Answer questions about financial products.",
    model="gpt-4o",
    input_guardrails=[InputGuardrail(guardrail_function=pii_detection_guardrail)],
    output_guardrails=[OutputGuardrail(guardrail_function=content_safety_guardrail)],
)

Structured Output with Typing

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="""Analyze customer data and assess churn risk.
Consider: activity over last 30 days, NPS, number of support tickets,
product feature usage.""",
    model="gpt-4o",
    tools=[get_customer_activity, get_support_history, get_product_usage],
    output_type=CustomerAnalysis,
)

result = await Runner.run(
    analysis_agent,
    input=f"Analyze customer ID: {customer_id}",
)
analysis: CustomerAnalysis = result.final_output
print(f"Churn risk: {analysis.churn_risk} ({analysis.churn_probability:.0%})")

What Does Agent Tracing Provide?

Tracing is the only way to debug multi-agent scenarios. The SDK logs every call, handoff, and guardrail, including latency and tokens. OpenTelemetry integration sends data to Jaeger, Grafana, or New Relic. Without tracing, you won't see where a delay occurred or which agent caused an error.

Tracing and Monitoring

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="Problem with API connection",
            run_config=RunConfig(
                trace_include_sensitive_data=False,
                workflow_name="customer_support",
            ),
        )
    return result

Practical Case: B2B Onboarding Automation

Client: a large B2B service with 2000+ clients. Typical onboarding took 2 weeks and required coordination of 3 departments: Sales, Integration, Support.

Architecture:

• Onboarding Coordinator (triage): receives request, routes
• Account Setup Agent: configure account, roles, SSO
• Integration Agent: help with API integration, generate code examples
• Training Agent: personalized training content
• Success Agent: follow-up, monitor adoption metrics

Handoff chain: Coordinator → Account Setup → Integration → Training → Success.

Results:

Support cost savings: approximately $30k per year.

Implementation Process and Timeline

Implementation Stages

Total timeline: from 2 to 4 weeks depending on complexity.

Timeline by Component

• Basic agent with tools: 2–4 days
• Handoff architecture with 3–5 agents: 1–2 weeks
• Guardrails and safety checks: 3–5 days
• Tracing and monitoring: 3–5 days
• Production deployment: 1 week

Cost is calculated individually for each project.

Common Design Mistakes

• Using the same model for all agents: triage should be cheap (gpt-4o-mini), complex tasks on gpt-4o.
• Lack of output guardrails: PII may leak into responses. Always add OutputGuardrail.
• Instructions too long: model loses focus. Split agents by specialization.
• Ignoring tracing: impossible to debug multi-agent scenarios without it.

What's Included in the Work

• Agent architecture documentation (Agent maps, handoff diagrams)
• Configured tracing (OpenTelemetry / OpenAI tracing)
• Ready guardrails (PII, content safety, custom checks)
• Client team training (1-day workshop)
• 2 weeks of post-deployment support

Guarantees and Support

We guarantee an agent response SLA of p99 < 2s. Certified OpenAI engineers. Implementation experience in finance and healthcare. Contact us to evaluate your scenario — get a consultation on agent architecture.

LLM Development: Fine-Tuning, RAG, Agents, and Production Deployment

Using GPT‑4 or Claude 3.5 Sonnet through a public API is not a solution — it's just a tool. When the requirement is to "make it like ChatGPT, but on our data," there is a real engineering challenge behind it: from prompt engineering to training a 70B model on your own infrastructure. End-to-end LLM solution development is a complex stack, and we have been doing it for over 5 years. During this time, we have completed over 20 projects in generative AI: from RAG systems for legal departments to custom support agents. Where exactly your task falls depends on data, latency requirements, budget, and how critical confidentiality is.

A typical situation: the client has already tried ChatGPT, but results are unstable — sometimes accurate, sometimes hallucinating. Or they need integration into a corporate portal while complying with security policies. Let's break down each layer of the stack in detail — from RAG to production deployment.

Why Do RAG Systems Break and How to Fix It?

RAG (Retrieval-Augmented Generation) looks simple: find relevant documents, put them in context, get an answer. In practice, it fails in several places.

Chunking without overlap. Classic mistake: chunk_size=512, overlap=0. If the answer lies across two chunks, retrieval won't find either with sufficient confidence. Solution: overlap 15–25% of chunk_size, or better yet, sentence-aware splitting with spaCy or NLTK instead of naive character splitting.

Poor embedder. text-embedding-ada-002 is good for general use, but on legal or medical texts, specialized models like E5-large-v2, BGE-M3, or fine-tuned sentence-transformers on domain data outperform it. Recall@5 differences can be 15–25%.

No re-ranking. Vector search optimizes for speed, not relevance. A cross-encoder re-ranker (ms-marco-MiniLM-L-6-v2, bge-reranker-large) after initial retrieval improves top-3 accuracy with acceptable latency (+50–150ms). This is often more impactful than improving the embedding model.

Hybrid search. Dense vectors alone work poorly on exact queries: names, SKUs, codes. BM25 (sparse) finds exact matches but misses semantics. Hybrid via RRF (Reciprocal Rank Fusion) is the optimal compromise. Qdrant, Weaviate, and pgvector 0.7+ support hybrid search natively.

When to Fine-Tune Instead of Prompt Engineering?

Prompt engineering solves ~70% of LLM adaptation tasks for a domain. The remaining 30% require fine-tuning. Three indicators: the model ignores a specific output format even with detailed prompting; the task requires deep knowledge of specialized vocabulary (medicine, law); you need to significantly reduce token costs by replacing a large model with a smaller specialized one.

LoRA and QLoRA are the standard for SFT. LoRA adds trainable low-rank matrices to attention layers. A typical configuration for Llama-3 8B: r=64, lora_alpha=128, target_modules=["q_proj","v_proj","k_proj","o_proj"] yields ~0.8% trainable parameters, training on one A100 40GB. QLoRA adds 4-bit quantization (NF4) and allows fine-tuning 70B models on two A100 40GB, though speed drops by half compared to bf16.

DPO instead of RLHF. Direct Preference Optimization requires only (chosen, rejected) pairs, not scalar reward signals. DPOTrainer from the trl library (Hugging Face) implements it in a few dozen lines.

Common mistake. A dataset of 500 examples, 5 epochs, validation loss 0.8 — seems fine. But on test, the model degrades on general instructions. Cause: catastrophic forgetting. Solution: add 10–20% general instruction-following examples (Alpaca, FLAN) to the training set to preserve original capabilities.

How to Choose a Base Model: 8B or 70B?

For most tasks, fine-tuning an 8B model is sufficient. 70B is needed when deep reasoning is required or the 8B baseline does not reach the required quality even after fine-tuning. Inference cost for Llama-3 8B via vLLM on A100 is efficient; the exact cost depends on volume.

What Does PagedAttention Bring to Production?

vLLM is the first choice for serving open-source models. PagedAttention is the key technical innovation: KV-cache is managed like virtual memory in an OS, without fragmentation. This yields 2–4x higher throughput compared to naive HuggingFace Transformers inference. The vLLM documentation confirms that continuous batching and PagedAttention are the standard for high-load LLM services.

Typical numbers on A100 80GB for Llama-3 8B (bf16): 400–600 req/s, P50 latency 200–400ms, P99 latency 600–900ms at concurrency 64. For 70B on two A100 with tensor parallelism: 80–120 req/s, P99 latency 1.5–2.5s. AWQ or GPTQ quantization reduces memory consumption by 2x with quality loss within 1–3%.

Multi-Agent Systems

Agents are LLMs with access to tools: search, code execution, API calls, database interaction. Common patterns:

• ReAct (Reason + Act): the model reasons → chooses a tool → observes the result → reasons again. LangChain and LlamaIndex implement it out of the box.
• Multi-agent orchestration: multiple specialized agents with a coordinator on top. Example: coordinator → researcher (search + summarization) → coder (code generation and execution) → critic (verification). Tools: AutoGen (Microsoft), CrewAI, custom implementation on LangGraph.

In production, agent systems are non-deterministic. Essential: guardrails, step limits, logging of each step, human-in-the-loop for critical actions.

How We Work: Stages, Timeline, Deliverables

What Is Included

We deliver:

• Technical documentation (model card, configs, deployment instructions)
• Access to infrastructure (code repository, trained weights)
• 1 month of post-deployment support (consultations, bug fixes)
• Customer team training (2–3 sessions on system operation)

Timeline: basic RAG prototype — 1–2 weeks. Fine-tuning with customer data — 3–6 weeks (including data preparation). Production system with monitoring and retraining — 2–4 months. Cost is calculated individually based on data volume, model complexity, and infrastructure requirements.

We guarantee the quality of the final model with performance benchmarks and ongoing monitoring. Our engineers have hands‑on experience with dozens of production LLM systems.

Want to evaluate your project? Leave a request — we will prepare a preliminary summary within 1–2 business days. Or get a consultation on choosing the approach: RAG, fine-tuning, or hybrid — we will tell you what works best for you. Contact us to discuss your LLM development needs. Schedule a free consultation today.