Input Guardrails: Validating User Requests Before Agent Processing

Why Input Validation Is the First Line of Defense

Every production agent system faces the same challenge: users will send unexpected, malicious, or nonsensical input. Without guardrails, your agent will attempt to process everything — wasting tokens, producing unsafe outputs, or triggering downstream tool calls that should never have happened.

The OpenAI Agents SDK provides a structured mechanism called input guardrails that intercept user messages before the agent begins its main reasoning loop. Think of them as middleware for your agent: they inspect the incoming request and decide whether to allow it, modify it, or reject it entirely.

Input guardrails are not just about security. They also improve cost efficiency (rejecting bad requests early saves tokens), user experience (fast rejection with a helpful message beats a slow, confused response), and system reliability (preventing nonsensical tool calls that pollute your logs).

How Input Guardrails Work

An input guardrail is a function that receives the user's input and returns a GuardrailFunctionOutput. This output contains two key fields: whether the guardrail passed and an optional tripwire_triggered flag that halts execution immediately.

flowchart TD
    START["Input Guardrails: Validating User Requests Before…"] --> A
    A["Why Input Validation Is the First Line …"]
    A --> B
    B["How Input Guardrails Work"]
    B --> C
    C["Parallel vs Blocking Guardrail Modes"]
    C --> D
    D["The GuardrailFunctionOutput in Detail"]
    D --> E
    E["Handling InputGuardrailTripwireTriggered"]
    E --> F
    F["Stacking Multiple Input Guardrails"]
    F --> G
    G["Best Practices for Input Guardrails"]
    G --> DONE["Key Takeaways"]
    style START fill:#4f46e5,stroke:#4338ca,color:#fff
    style DONE fill:#059669,stroke:#047857,color:#fff

from agents import Agent, Runner, InputGuardrail, GuardrailFunctionOutput
from pydantic import BaseModel
import asyncio

class TopicCheckOutput(BaseModel):
    is_on_topic: bool
    reasoning: str

topic_checker = Agent(
    name="TopicChecker",
    instructions="""Determine if the user message is related to customer
    support for a software product. Return is_on_topic=True if the
    message is about product features, bugs, billing, or account
    management. Return False for anything else.""",
    model="gpt-4o-mini",
    output_type=TopicCheckOutput,
)

async def topic_guardrail(ctx, agent, input) -> GuardrailFunctionOutput:
    result = await Runner.run(topic_checker, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=not result.final_output.is_on_topic,
    )

support_agent = Agent(
    name="SupportAgent",
    instructions="You are a customer support agent for Acme Software.",
    model="gpt-4o",
    input_guardrails=[
        InputGuardrail(guardrail_function=topic_guardrail),
    ],
)

async def main():
    try:
        result = await Runner.run(support_agent, "How do I reset my password?")
        print(result.final_output)
    except Exception as e:
        print(f"Blocked: {e}")

asyncio.run(main())

When the guardrail sets tripwire_triggered=True, the SDK raises an InputGuardrailTripwireTriggered exception. This immediately stops the agent run — no tokens are spent on the main agent, no tools are called, and no output is generated.

Parallel vs Blocking Guardrail Modes

The OpenAI Agents SDK supports two execution modes for input guardrails, and the distinction matters for both latency and safety.

Parallel Mode (Default)

In parallel mode, guardrails run concurrently with the agent's first LLM call. The agent starts processing while guardrails are still evaluating. If a guardrail trips its wire, the agent run is canceled mid-flight.

support_agent = Agent(
    name="SupportAgent",
    instructions="You are a customer support agent.",
    model="gpt-4o",
    input_guardrails=[
        InputGuardrail(
            guardrail_function=topic_guardrail,
            # Parallel is the default — guardrail runs alongside agent
        ),
    ],
)

Parallel mode optimizes for latency: in the happy path (guardrail passes), the agent has already started processing, so the user gets a faster response. The trade-off is that if the guardrail fails, some tokens were wasted on the agent's partial execution.

Blocking Mode

In blocking mode, all guardrails must complete before the agent begins. This is the safer option when guardrail failure is common or when you absolutely cannot afford any agent processing on bad input.

from agents import RunConfig

async def main():
    config = RunConfig(input_guardrails_run_in_parallel=False)
    result = await Runner.run(
        support_agent,
        "Tell me a joke instead of helping me",
        run_config=config,
    )

Use blocking mode when: your guardrail rejection rate is high (more than 20%), you are paying for an expensive model and want zero wasted tokens, or security requirements demand that no processing occurs on untrusted input.

The GuardrailFunctionOutput in Detail

The GuardrailFunctionOutput gives you fine-grained control over what happens when a guardrail evaluates input.

from agents import GuardrailFunctionOutput

async def language_guardrail(ctx, agent, input) -> GuardrailFunctionOutput:
    # Simple heuristic check — no LLM needed
    blocked_phrases = ["ignore previous instructions", "system prompt", "jailbreak"]
    input_lower = input.lower() if isinstance(input, str) else str(input).lower()

    is_suspicious = any(phrase in input_lower for phrase in blocked_phrases)

    return GuardrailFunctionOutput(
        output_info={
            "checked_phrases": len(blocked_phrases),
            "suspicious": is_suspicious,
        },
        tripwire_triggered=is_suspicious,
    )

The output_info field accepts any serializable data. This is useful for logging and debugging — you can inspect what the guardrail evaluated and why it made its decision. In production, pipe this into your observability system so you can track guardrail trigger rates and tune thresholds.

Handling InputGuardrailTripwireTriggered

When a tripwire fires, the SDK raises InputGuardrailTripwireTriggered. Your application layer must catch this and return an appropriate response to the user.

from agents.exceptions import InputGuardrailTripwireTriggered

async def handle_user_message(user_input: str) -> str:
    try:
        result = await Runner.run(support_agent, user_input)
        return result.final_output
    except InputGuardrailTripwireTriggered as e:
        # Log the guardrail details for monitoring
        guardrail_info = e.guardrail_result.output_info
        print(f"Guardrail triggered: {guardrail_info}")

        # Return a user-friendly message
        return (
            "I can only help with questions about our software products. "
            "Could you rephrase your question?"
        )

Never expose the guardrail's internal reasoning to the user. An attacker probing your guardrails would use that information to craft inputs that evade detection. Return a generic, helpful message and log the details server-side.

Stacking Multiple Input Guardrails

Production systems typically need multiple guardrails. You can attach several to a single agent, and they all run (either in parallel or sequentially based on your configuration).

support_agent = Agent(
    name="SupportAgent",
    instructions="You are a customer support agent.",
    model="gpt-4o",
    input_guardrails=[
        InputGuardrail(guardrail_function=topic_guardrail),
        InputGuardrail(guardrail_function=language_guardrail),
        InputGuardrail(guardrail_function=length_guardrail),
    ],
)

Guardrails are evaluated in order. If any one of them triggers its tripwire, the entire run is halted. Order matters in blocking mode: put your cheapest, fastest guardrails first (like the heuristic-based language_guardrail above) so you avoid unnecessary LLM calls from more expensive guardrails.

Best Practices for Input Guardrails

Layer heuristic and LLM-based checks. Use fast string matching or regex for obvious violations. Use an LLM-based guardrail only for nuanced checks that require semantic understanding.

Keep guardrail agents small and fast. Use gpt-4o-mini for guardrail agents. They need to classify intent, not generate long-form responses. A fast model with a focused prompt will outperform a powerful model with a vague prompt.

Monitor guardrail metrics. Track how often each guardrail triggers, what the trigger rate trend looks like over time, and what the false positive rate is. A guardrail that triggers on 40% of legitimate requests is worse than no guardrail at all.

Test with adversarial inputs. Maintain a test suite of known jailbreak attempts, prompt injections, and boundary cases. Run this suite in CI against your guardrails to catch regressions.

Input guardrails are the cheapest safety investment you can make. They prevent bad input from consuming expensive compute, protect your tools from unintended invocation, and give your users fast feedback when they go off track.