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.