Protecting Agents with Input Guardrails

Protecting Agents with Input Guardrails | CodeSignal Learn

Introduction & Context

In the previous lessons, you learned how to securely handle sensitive data using RunContextWrapper and monitor agent workflows with lifecycle hooks. Now you're ready to tackle the next critical layer of agent security: input guardrails . While context management protects your internal data and hooks give you visibility into agent behavior, input guardrails protect your agents from potentially harmful, inappropriate, or malicious user inputs before they even begin processing. Think about real-world scenarios where your agents might face problematic inputs. A travel assistant might receive requests for illegal activities, a customer service bot could be asked to perform tasks outside its scope, or a content creation agent might be prompted to generate inappropriate material. Without proper input validation, your agents could waste computational resources, violate company policies, or even expose security vulnerabilities. The most common and critical use of guardrails is at the input stage—validating user requests before your agent begins processing. Input guardrails serve as your first line of defense, ensuring that only safe, appropriate, and policy-compliant inputs are allowed to reach your agents.

Understanding Guardrails

As you build more capable and autonomous OpenAI agents, security becomes a multi-layered challenge. Guardrails are a foundational security mechanism designed to protect your agents from a wide range of problematic scenarios—whether that’s malicious user input, requests that violate business policies, or attempts to push your agent outside its intended scope. Guardrails act as checkpoints that enforce your rules and policies before, during, or after agent execution. They can validate, block, or even rewrite data at critical points in your workflow, ensuring that your agents operate safely and predictably. For example, input guardrails can prevent agents from processing requests for illegal activities or block attempts to access sensitive information, while output guardrails can sanitize or filter agent responses before they reach end users, ensuring that no inappropriate or policy-violating content is returned. By implementing guardrails, you create a proactive defense system that reduces the risk of security breaches, policy violations, and unintended agent behavior. This approach is essential for maintaining trust, compliance, and reliability in any production AI system.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

The @input_guardrail Decorator and Function Structure

Simple Rule-Based Input Validation

Now that you understand the basic structure of input guardrails, let's implement a simple example that demonstrates these concepts in action. Before moving to sophisticated LLM-based validation, we'll start with a straightforward rule-based approach using keyword detection. Here's a basic input guardrail that checks for inappropriate travel-related content: Python@input_guardrail async def simple_content_filter( ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] ) -> GuardrailFunctionOutput: # List of prohibited terms for requests prohibited_terms = ["prostitution", "drugs", "strip club"] # Convert input to lowercase string input_text = str(input).lower() # Check for prohibited terms for term in prohibited_terms: if term in input_text: return GuardrailFunctionOutput( output_info=f"Blocked: inappropriate travel request containing '{term}'", tripwire_triggered=True ) # Allow input if no prohibited terms found return GuardrailFunctionOutput( output_info="Travel request approved", tripwire_triggered=False )@input_guardrail async def simple_content_filter( ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] ) -> GuardrailFunctionOutput: # List of prohibited terms for requests prohibited_terms = ["prostitution", "drugs", "strip club"] # Convert input to lowercase string input_text = str(input).lower() # Check for prohibited terms for term in prohibited_terms: if term in input_text: return GuardrailFunctionOutput( output_info=f"Blocked: inappropriate travel request containing '{term}'", tripwire_triggered=True ) # Allow input if no prohibited terms found return GuardrailFunctionOutput( output_info="Travel request approved", tripwire_triggered=False ) This simple guardrail follows the exact function signature you learned about: it uses the @input_guardrail decorator, accepts the required ctx, agent, and input parameters, and returns a GuardrailFunctionOutput object with appropriate output_info and tripwire_triggered values.

Attaching Guardrails to Agents

Once you've created your input guardrail function, you need to attach it to your agent so that it runs automatically before the agent processes any input. You do this by including your guardrail function in the input_guardrails parameter when creating your agent: Python travel_genie = Agent(name="Travel Genie", instructions="You are a helpful travel assistant.", input_guardrails=[simple_content_filter], # Attach the guardrail to validate inputs model="gpt-4.1") travel_genie = Agent(name="Travel Genie", instructions="You are a helpful travel assistant.", input_guardrails=[simple_content_filter], # Attach the guardrail to validate inputs model="gpt-4.1") When you attach guardrails to an agent, they become an integral part of that agent's processing pipeline. Every time someone tries to run that agent with user input, the guardrails will automatically execute first, ensuring that your validation logic is consistently applied without requiring manual intervention or remembering to call validation functions.

Testing Guardrail Behavior with Blocked Inputs

Let's see what happens when you try to run your agent with an input that triggers the guardrail. When your guardrail sets tripwire_triggered=True, the SDK raises an InputGuardrailTripwireTriggered exception instead of proceeding with normal agent execution. Here's how to test and handle this behavior: Python from agents import InputGuardrailTripwireTriggered try: result = await Runner.run(starting_agent=travel_genie, input="Where can I find drugs in Amsterdam?") print(result.final_output) except InputGuardrailTripwireTriggered: print("Content guardrail tripped: Request blocked") from agents import InputGuardrailTripwireTriggered try: result = await Runner.run(starting_agent=travel_genie, input="Where can I find drugs in Amsterdam?") print(result.final_output) except InputGuardrailTripwireTriggered: print("Content guardrail tripped: Request blocked") When you run this code, you'll see that the request gets blocked because it contains the prohibited term "drugs", and the output will be: text Content guardrail tripped: Request blocked Content guardrail tripped: Request blocked The InputGuardrailTripwireTriggered exception allows you to handle blocked inputs gracefully and provide appropriate feedback to users. This exception handling pattern is essential for production applications where you need to differentiate between successful agent execution and blocked requests, allowing you to log security incidents, provide user feedback, or redirect users to alternative resources.

Creating LLM-Based Content Validation

Implementing LLM-Based Guardrail Functions

Now let's implement the actual guardrail function that uses your guardrail agent to validate inputs: Python@input_guardrail async def llm_content_guardrail( ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] ) -> GuardrailFunctionOutput: # Run the guardrail agent to analyze the input result = await Runner.run(guardrail_agent, input, context=ctx.context) # Print the guardrail agent's response for visibility print("Guardrail Agent response:\n" + str(result.final_output), "\n") # Return the validation decision return GuardrailFunctionOutput( output_info=result.final_output.reasoning, tripwire_triggered=result.final_output.contains_prohibited_content, )@input_guardrail async def llm_content_guardrail( ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem] ) -> GuardrailFunctionOutput: # Run the guardrail agent to analyze the input result = await Runner.run(guardrail_agent, input, context=ctx.context) # Print the guardrail agent's response for visibility print("Guardrail Agent response:\n" + str(result.final_output), "\n") # Return the validation decision return GuardrailFunctionOutput( output_info=result.final_output.reasoning, tripwire_triggered=result.final_output.contains_prohibited_content, ) This function demonstrates the complete flow of LLM-based input validation. You use Runner.run() to execute your guardrail agent with the user's input, just like running any other agent. The guardrail agent analyzes the input and returns a structured response containing both the decision and reasoning. The GuardrailFunctionOutput object you return uses the guardrail agent's reasoning as the output_info and its boolean decision as the tripwire_triggered value. When tripwire_triggered=True, the SDK will prevent the input from reaching your main agent and raise an InputGuardrailTripwireTriggered exception.

Testing LLM-Based Validation

Combining Multiple Guardrails

The input_guardrails parameter accepts a list of guardrail functions, which means you can attach multiple guardrails to a single agent for layered validation. When multiple guardrails are attached, they execute in the order they appear in the list, and all guardrails must pass for the input to proceed: Python travel_genie = Agent(name="Travel Genie", instructions=("You are Travel Genie, a friendly and knowledgeable travel assistant. " "Recommend exciting destinations and offer helpful travel tips."), input_guardrails=[simple_content_filter, llm_content_guardrail], model="gpt-4.1") travel_genie = Agent(name="Travel Genie", instructions=("You are Travel Genie, a friendly and knowledgeable travel assistant. " "Recommend exciting destinations and offer helpful travel tips."), input_guardrails=[simple_content_filter, llm_content_guardrail], model="gpt-4.1") This design allows you to create layered validation strategies where fast rule-based checks catch obvious violations first, followed by more sophisticated LLM-based analysis for nuanced content evaluation. Each guardrail can focus on a specific aspect of validation while working together to provide comprehensive input protection.

Introduction & Context

Understanding Guardrails

Join the 1M+ learners on CodeSignal

Guardrails vs. Hooks

The @input_guardrail Decorator and Function Structure

Simple Rule-Based Input Validation

Attaching Guardrails to Agents

Testing Guardrail Behavior with Blocked Inputs

Understanding Concurrent Execution with Guardrails

Creating LLM-Based Content Validation

Implementing LLM-Based Guardrail Functions

Testing LLM-Based Validation

Combining Multiple Guardrails

Summary & Preparing for Practice