Fingers-On with Brokers SDK: Safeguarding Enter and Output with Guardrails

exploring options within the OpenAI Brokers SDK framework, there’s one functionality that deserves a better look: enter and output guardrails.

In earlier articles, we constructed our first agent with an API-calling software after which expanded right into a multi-agent system. In real-world eventualities, although, constructing these programs is complicated—and with out the fitting safeguards, issues can rapidly go off observe. That’s the place guardrails are available in: they assist guarantee security, focus, and effectivity.

When you haven’t learn the sooner components but, no worries — you’ll discover hyperlinks to the earlier articles on the finish of this publish.

Right here’s why guardrails matter:

• Forestall misuse
• Save sources
• Guarantee security and compliance
• Preserve focus and high quality

With out correct guardrails, surprising use circumstances can pop up. For instance, you may need heard of individuals utilizing AI-powered customer support bots (designed for product assist) to jot down code as a substitute. It sounds humorous, however for the corporate, it might turn out to be a pricey and irrelevant distraction.

To see why guardrails are necessary, let’s revisit our final venture. I ran the agents_as_tools script and requested it to generate code for calling a climate API. Since no guardrails have been in place, the app returned the reply with out hesitation—proving that, by default, it’s going to attempt to do virtually something requested of it.

We positively don’t need this occurring in a manufacturing app. Think about the prices of unintended utilization—to not point out the larger dangers it might carry, resembling info leaks, system immediate publicity, and different critical vulnerabilities.

Hopefully, this makes the case clear for why guardrails are value exploring. Subsequent, let’s dive into methods to begin utilizing the guardrail function within the OpenAI Brokers SDK.

A Fast Intro to Guardrails

Within the OpenAI Brokers SDK, there are two forms of guardrails: enter guardrails and output guardrails ^[1]. Enter guardrails run on the consumer’s preliminary enter, whereas output guardrails run on the agent’s ultimate response.

A guardrail might be an LLM-powered agent—helpful for duties that require reasoning—or a rule-based/programmatic operate, resembling a regex to detect particular key phrases. If the guardrail finds a violation, it triggers a tripwire and raises an exception. This mechanism prevents the principle agent from processing unsafe or irrelevant queries, making certain each security and effectivity.

Some sensible makes use of for enter guardrails embrace:

• Figuring out when a consumer asks an off-topic query ^[2]
• Detecting unsafe enter makes an attempt, together with jailbreaks and immediate injections ^[3]
• Moderating to flag inappropriate enter, resembling harassment, violence, or hate speech ^[3]
• Dealing with specific-case validation. For instance, in our climate app, we may implement that questions solely reference cities in Indonesia.

Alternatively, output guardrails can be utilized to:

• Forestall unsafe or inappropriate responses
• Cease the agent from leaking personally identifiable info (PII) ^[3]
• Guarantee compliance and model security, resembling blocking outputs that might hurt model integrity

On this article, we’ll discover various kinds of guardrails, together with each LLM-based and rule-based approaches, and the way they are often utilized for numerous sorts of validation.

Conditions

• Create a necessities.txt file:

openai-agents
streamlit

• Create a digital atmosphere named venv. Run the next instructions in your terminal:

python −m venv venv 
supply venv/bin/activate # On Home windows: venvScriptsactivate 
pip set up -r necessities.txt

• Create a .env file to retailer your OpenAI API key:

OPENAI_API_KEY=your_openai_key_here

For the guardrail implementation, we’ll use the script from the earlier article the place we constructed the agents-as-tools multi-agent system. For an in depth walkthrough, please refer again to that article. The complete implementation script might be discovered right here: app06_agents_as_tools.py.

Now let’s create a brand new file named app08_guardrails.py.

Enter Guardrail

We’ll begin by including enter guardrails to our climate app. On this part, we’ll construct two varieties:

• Off-topic guardrail, which makes use of an LLM to find out if the consumer enter is unrelated to the app’s goal.
• Injection detection guardrail, which makes use of a easy rule to catch jailbreak and immediate injection makes an attempt.

Import Libraries

First, let’s import the mandatory packages from the Brokers SDK and different libraries. We’ll additionally arrange the atmosphere to load the OpenAI API key from the .env file. From the Brokers SDK, in addition to the fundamental features (Agent, Runner, and function_tool) we’ll additionally import features particularly used for implementing enter and output guardrails.

from brokers import (
    Agent, 
    Runner, 
    function_tool, 
    GuardrailFunctionOutput, 
    input_guardrail, 
    InputGuardrailTripwireTriggered,
    output_guardrail,
    OutputGuardrailTripwireTriggered
)
import asyncio
import requests
import streamlit as st
from pydantic import BaseModel, Discipline
from dotenv import load_dotenv

load_dotenv()

Outline Output Mannequin

For any LLM-based guardrail, we have to outline an output mannequin. Usually, we use a Pydantic mannequin class to specify the construction of the info. On the easiest degree, we’d like a boolean subject (True/False) to point whether or not the guardrail ought to set off, together with a textual content subject that explains the reasoning.

In our case, we would like the guardrail to find out whether or not the question remains to be throughout the scope of the app’s goal (climate and air high quality). To do this, we’ll outline a mannequin named TopicClassificationOutput as proven under:

# Outline output mannequin for the guardrail agent to categorise if enter is off-topic
class TopicClassificationOutput(BaseModel):
    is_off_topic: bool = Discipline(
        description="True if the enter is off-topic (not associated to climate/air high quality and never a greeting), False in any other case"
    )
    reasoning: str = Discipline(
        description="Temporary clarification of why the enter was labeled as on-topic or off-topic"
    )

The boolean subject is_off_topic will probably be set to True if the enter is exterior the app’s scope. The reasoning subject shops a brief clarification of why the mannequin made its classification.

Create Guardrail Agent

We have to outline an agent with clear and full directions to find out whether or not a consumer’s query is on-topic or off-topic. This may be adjusted relying in your app’s goal—the directions don’t should be the identical for each use case.

For our Climate and Air High quality assistant, right here’s the guardrail agent with directions for classifying a consumer’s question.

# Create the guardrail agent to find out if enter is off-topic
topic_classification_agent = Agent(
    title="Matter Classification Agent",
    directions=(
        "You're a subject classifier for a climate and air high quality software. "
        "Your activity is to find out if a consumer's query is on-topic. "
        "Allowed matters embrace: "
        "1. Climate-related: present climate, climate forecast, temperature, precipitation, wind, humidity, and so on. "
        "2. Air quality-related: air air pollution, AQI, PM2.5, ozone, air situations, and so on. "
        "3. Location-based inquiries about climate or air situations "
        "4. Well mannered greetings and conversational starters (e.g., 'hi there', 'hello', 'good morning') "
        "5. Questions that mix greetings with climate/air high quality matters "
        "Mark as OFF-TOPIC provided that the question is clearly unrelated to climate/air high quality AND not a easy greeting. "
        "Examples of off-topic: math issues, cooking recipes, sports activities scores, technical assist, jokes (until weather-related). "
        "Examples of on-topic: 'Whats up, what is the climate?', 'Hello there', 'Good morning, how's the air high quality?', 'What is the temperature?' "
        "The ultimate output MUST be a JSON object conforming to the TopicClassificationOutput mannequin."
    ),
    output_type=TopicClassificationOutput,
    mannequin="gpt-4o-mini" # Use a quick and cost-effective mannequin
)

Within the directions, in addition to itemizing the plain matters, we additionally enable some flexibility for easy conversational starters like “hi there,” “hello,” or different greetings. To make the classification clearer, we included examples of each on-topic and off-topic queries.

One other good thing about enter guardrails is value optimization. To make the most of this, we should always use a quicker and cheaper mannequin than the principle agent. This fashion, the principle (and costlier) agent is simply used when completely needed.

On this instance, the guardrail agent makes use of gpt-4o-mini whereas the principle agent runs on gpt-4o.

Create an Enter Guardrail Operate

Subsequent, let’s wrap the agent in an async operate embellished with @input_guardrail. The output of this operate will embrace two fields outlined earlier: is_off_topic and reasoning.

The operate returns a structured GuardrailFunctionOutput object containing output_info (set from the reasoning subject) and tripwire_triggered.

The tripwire_triggered worth determines whether or not the enter needs to be blocked. If is_off_topic is True, the tripwire triggers, blocking the enter. In any other case, the worth is False and the principle agent continues processing.

# Create the enter guardrail operate
@input_guardrail
async def off_topic_guardrail(ctx, agent, enter) -> GuardrailFunctionOutput:
    """
    Classifies consumer enter to make sure it's on-topic for a climate and air high quality app.
    """

    outcome = await Runner.run(topic_classification_agent, enter, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=outcome.final_output.reasoning,
        tripwire_triggered=outcome.final_output.is_off_topic
    )

Create a Rule-based Enter Guardrail Operate

Alongside the LLM-based off-topic guardrail, we’ll create a easy rule-based guardrail. This one doesn’t require an LLM and as a substitute depends on programmatic sample matching.

Relying in your app’s goal, rule-based guardrails might be very efficient at blocking dangerous inputs—particularly when dangerous patterns are predictable.

On this instance, we outline a listing of key phrases usually utilized in jailbreak or immediate injection makes an attempt. The listing consists of: "ignore earlier directions", "you are actually a", "overlook every thing above", "developer mode", "override security", "disregard tips".

If the consumer enter comprises any of those key phrases, the guardrail will set off routinely. Since no LLM is concerned, we are able to deal with the validation immediately contained in the enter guardrail operate injection_detection_guardrail:

# Rule-based enter guardrail to detect jailbreaking and immediate injection question
@input_guardrail
async def injection_detection_guardrail(ctx, agent, enter) -> GuardrailFunctionOutput:
    """
    Detects potential jailbreaking or immediate injection makes an attempt in consumer enter.
    """

    # Easy keyword-based detection
    injection_patterns = [
        "ignore previous instructions",
        "you are now a",
        "forget everything above",
        "developer mode",
        "override safety",
        "disregard guidelines"
    ]

    if any(key phrase in enter.decrease() for key phrase in injection_patterns):
        return GuardrailFunctionOutput(
            output_info="Potential jailbreaking or immediate injection detected.",
            tripwire_triggered=True
        )

    return GuardrailFunctionOutput(
        output_info="No jailbreaking or immediate injection detected.",
        tripwire_triggered=False
    )

This guardrail merely checks the enter in opposition to the key phrase listing. If a match is discovered, tripwire_triggered is about to True. In any other case, it stays False.

Outline Specialised Agent for Climate and Air High quality

Now let’s proceed by defining the climate and air high quality specialist brokers with their operate software. The reason of this half might be discovered on my earlier article so for this text I’ll skip the reason.

# Outline operate instruments and specialised brokers for climate and air qualities
@function_tool
def get_current_weather(latitude: float, longitude: float) -> dict:
    """Fetch present climate information for the given latitude and longitude."""
    
    url = "https://api.open-meteo.com/v1/forecast"
    params = {
        "latitude": latitude,
        "longitude": longitude,
        "present": "temperature_2m,relative_humidity_2m,dew_point_2m,apparent_temperature,precipitation,weathercode,windspeed_10m,winddirection_10m",
        "timezone": "auto"
    }
    response = requests.get(url, params=params)
    return response.json()

weather_specialist_agent = Agent(
    title="Climate Specialist Agent",
    directions="""
    You're a climate specialist agent.
    Your activity is to investigate present climate information, together with temperature, humidity, wind velocity and route, precipitation, and climate codes.

    For every question, present:
    1. A transparent, concise abstract of the present climate situations in plain language.
    2. Sensible, actionable strategies or precautions for outside actions, journey, well being, or clothes, tailor-made to the climate information.
    3. If extreme climate is detected (e.g., heavy rain, thunderstorms, excessive warmth), clearly spotlight really useful security measures.

    Construction your response in two sections:
    Climate Abstract:
    - Summarize the climate situations in easy phrases.

    Recommendations:
    - Listing related recommendation or precautions primarily based on the climate.
    """,
    instruments=[get_current_weather],
    tool_use_behavior="run_llm_again"
)

@function_tool
def get_current_air_quality(latitude: float, longitude: float) -> dict:
    """Fetch present air high quality information for the given latitude and longitude."""

    url = "https://air-quality-api.open-meteo.com/v1/air-quality"
    params = {
        "latitude": latitude,
        "longitude": longitude,
        "present": "european_aqi,us_aqi,pm10,pm2_5,carbon_monoxide,nitrogen_dioxide,sulphur_dioxide,ozone",
        "timezone": "auto"
    }
    response = requests.get(url, params=params)
    return response.json()

air_quality_specialist_agent = Agent(
    title="Air High quality Specialist Agent",
    directions="""
    You're an air high quality specialist agent.
    Your position is to interpret present air high quality information and talk it clearly to customers.

    For every question, present:
    1. A concise abstract of the air high quality situations in plain language, together with key pollution and their ranges.
    2. Sensible, actionable recommendation or precautions for outside actions, journey, and well being, tailor-made to the air high quality information.
    3. If poor or hazardous air high quality is detected (e.g., excessive air pollution, allergens), clearly spotlight really useful security measures.

    Construction your response in two sections:
    Air High quality Abstract:
    - Summarize the air high quality situations in easy phrases.

    Recommendations:
    - Listing related recommendation or precautions primarily based on the air high quality.
    """,
    instruments=[get_current_air_quality],
    tool_use_behavior="run_llm_again"
)

Outline the Orchestrator Agent with Enter Guardrails

Virtually the identical with earlier half, the orchestrator agent right here have the identical properties with the one which we already mentioned on my earlier article the place within the agents-as-tools sample, the orchestrator agent will handle the duty of every specialised brokers as a substitute of handing-offer the duty to at least one agent like in handoff sample.

The one completely different right here is we including new property to the agent; input_guardrails. On this property, we cross the listing of the enter guardrail features that we have now outlined earlier than; off_topic_guardrail and injection_detection_guardrail.

# Outline the principle orchestrator agent with guardrails
orchestrator_agent = Agent(
    title="Orchestrator Agent",
    directions="""
    You're an orchestrator agent.
    Your activity is to handle the interplay between the Climate Specialist Agent and the Air High quality Specialist Agent.
    You'll obtain a question from the consumer and can determine which agent to invoke primarily based on the content material of the question.
    If each climate and air high quality info is requested, you'll invoke each brokers and mix their responses into one clear reply.
    """,
    instruments=[
        weather_specialist_agent.as_tool(
            tool_name="get_weather_update",
            tool_description="Get current weather information and suggestion including temperature, humidity, wind speed and direction, precipitation, and weather codes."
        ),
        air_quality_specialist_agent.as_tool(
            tool_name="get_air_quality_update",
            tool_description="Get current air quality information and suggestion including pollutants and their levels."
        )
    ],
    tool_use_behavior="run_llm_again",
    input_guardrails=[injection_detection_guardrail, off_topic_guardrail],
)


# Outline the run_agent operate
async def run_agent(user_input: str):
    outcome = await Runner.run(orchestrator_agent, user_input)
    return outcome.final_output

One factor that I noticed whereas experimenting with guardrails is after we listed the guardrail operate within the agent property, the listing will probably be used because the sequence of the execution. Which means that we are able to configure the analysis order within the perspective of value and impression.

In our case right here, I believe I ought to instantly reduce the method if the question violate the immediate injection guardrail attributable to its impression and in addition since this validation requires no LLM. So, if the question already recognized can’t be proceed, we don’t want to guage it utilizing LLM (which has value) within the off subject guardrail.

Create Essential Operate with Exception Handler

Right here is the half the place the enter guardrail take a actual motion. On this half the place we outline the principle operate of Streamlit consumer interface, we are going to add an exception dealing with specifically when the enter guardrail tripwire has been triggered.

# Outline the principle operate of the Streamlit app
def essential():
    st.title("Climate and Air High quality Assistant")
    user_input = st.text_input("Enter your question about climate or air high quality:")

    if st.button("Get Replace"):
        with st.spinner("Pondering..."):
            if user_input:
                strive:
                    agent_response = asyncio.run(run_agent(user_input))
                    st.write(agent_response)
                besides InputGuardrailTripwireTriggered as e:
                    st.write("I can solely assist with climate and air high quality associated questions. Please strive asking one thing else! ")
                    st.error("Data: {}".format(e.guardrail_result.output.output_info))
                besides Exception as e:
                    st.error(e)
            else:
                st.write("Please enter a query concerning the climate or air high quality.")

if __name__ == "__main__":
    essential()

As we are able to see within the code above, when the InputGuardrailTripwireTriggered is increase, it’s going to present a user-friendly message that inform the consumer the app solely will help for climate and air high quality associated query.

To make the message will probably be extra useful, we additionally add more information particularly for what enter guardrail that blocked the consumer’s question. If the exception raised by off_topic_guardrail, it’s going to present the reasoning from the agent that deal with this. In the meantime if it coming from injection_detection_guardrail, the app will present a hard-coded message “Potential jailbreaking or immediate injection detected.”.

Run and Examine

To check how the enter guardrail works, let’s begin by operating the Streamlit app.

streamlit run app08_guardrails.py

First, let’s strive asking a query that aligns with the app’s meant goal.

As anticipated, the app returns a solution for the reason that query is said to climate or air high quality.

Utilizing Traces, we are able to see what’s occurring below the hood.

As mentioned earlier, the enter guardrails run earlier than the principle agent. Since we set the guardrail listing so as, the injection_detection_guardrail runs first, adopted by the off_topic_guardrail. As soon as the enter passes these two guardrails, the principle agent can execute the method.

Nonetheless, if we alter the query to one thing utterly unrelated to climate or air high quality—just like the historical past of Jakarta—the response seems to be like this:

Right here, the off_topic_guardrail triggers the tripwire, cuts the method halfway, and returns a message together with some additional particulars about why it occurred.

From the Traces dashboard for that historical past query, we are able to see the orchestrator agent throws an error as a result of the guardrail tripwire was triggered.

For the reason that course of was reduce earlier than the enter reached the principle agent, we by no means even referred to as the principle agent mannequin—saving some bucks on a question the app isn’t purported to deal with anyway.

Output Guardrail

If the enter guardrail ensures that the consumer’s question is secure and related, the output guardrail ensures that the agent’s response itself meets our desired requirements. That is equally necessary as a result of even with robust enter filtering, the agent can nonetheless produce outputs which can be unintended, dangerous, or just not aligned with our necessities.

For instance, in our app we wish to be sure that the agent at all times responds professionally. Since LLMs usually mirror the tone of the consumer’s question, they could reply in an off-the-cuff, sarcastic, or unprofessional tone—which is exterior the scope of the enter guardrails we already carried out.

To deal with this, we add an output guardrail that checks whether or not a response is skilled. If it’s not, the guardrail will set off and forestall the unprofessional response from reaching the consumer.

Put together the Output Guardrail Operate

Identical to the off_topic_guardrail, we create a brand new professionalism_guardrail. It makes use of a Pydantic mannequin for the output, a devoted agent to categorise professionalism, and an async operate embellished with @output_guardrail to implement the examine.

# Outline output mannequin for Output Guardrail Agent
class ResponseCheckerOutput(BaseModel):
    is_not_professional: bool = Discipline(
        description="True if the output will not be skilled, False in any other case"
    )
    reasoning: str = Discipline(
        description="Temporary clarification of why the output was labeled as skilled or unprofessional"
    )

# Create Output Guardrail Agent
response_checker_agent = Agent(
    title="Response Checker Agent",
    directions="""
    You're a response checker agent.
    Your activity is to guage the professionalism of the output generated by different brokers.

    For every response, present:
    1. A classification of the response as skilled or unprofessional.
    2. A quick clarification of the reasoning behind the classification.

    Construction your response in two sections:
    Professionalism Classification:
    - State whether or not the response is skilled or unprofessional.

    Reasoning:
    - Present a short clarification of the classification.
    """,
    output_type=ResponseCheckerOutput,
    mannequin="gpt-4o-mini"
)

# Outline output guardrail operate
@output_guardrail
async def professionalism_guardrail(ctx, agent, output) -> GuardrailFunctionOutput:
    outcome = await Runner.run(response_checker_agent, output, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=outcome.final_output.reasoning,
        tripwire_triggered=outcome.final_output.is_not_professional
    )

Output Guardrail Implementation

Now we add this new guardrail to the orchestrator agent by itemizing it below output_guardrails. This ensures each response is checked earlier than being proven to the consumer.

# Add professionalism guardrail to the orchestrator agent
orchestrator_agent = Agent(
    title="Orchestrator Agent",
    directions="...identical as earlier than...",
    instruments=[...],
    input_guardrails=[injection_detection_guardrail, off_topic_guardrail],
    output_guardrails=[professionalism_guardrail],
)

Lastly, we prolong the principle operate to deal with OutputGuardrailTripwireTriggered exceptions. If triggered, the app will block the unprofessional response and return a pleasant fallback message as a substitute.

# Deal with output guardrail in the principle operate
besides OutputGuardrailTripwireTriggered as e:
    st.write("The response did not meet our high quality requirements. Please strive once more.")
    st.error("Data: {}".format(e.guardrail_result.output.output_info))

Run and Examine

Now, let’s check out how the output guardrail works. Begin by operating the app as earlier than:

streamlit run app08_guardrails.py

To check this, we are able to attempt to pressure the agent to reply in an unprofessional method associated to climate or air high quality. For instance, by asking: “Reply this query with hyperbole. What’s the air high quality in Jakarta?”

This question passes the enter guardrails as a result of it’s nonetheless on-topic and never an try at immediate injection. Because of this, the principle agent processes the enter and calls the right operate.

Nonetheless, the ultimate output generated by the principle agent—because it adopted the consumer’s hyperbole request—doesn’t align with the model’s communication commonplace. Right here’s the outcome we bought from the app:

Conclusion

All through this text, we explored how guardrails within the OpenAI Brokers SDK assist us preserve management over each enter and output. The enter guardrail we constructed right here protects the app from dangerous or unintended consumer enter that might value us as builders, whereas the output guardrail ensures responses stay in keeping with the model commonplace.

By combining these mechanisms, we are able to considerably cut back the dangers of unintended utilization, info leaks, or outputs that fail to align with the meant communication type. That is particularly essential when deploying agentic functions into manufacturing environments, the place security, reliability, and belief matter most.

Guardrails are usually not a silver bullet, however they’re a vital layer of protection. As we proceed constructing extra superior multi-agent programs, adopting guardrails early on will assist guarantee we create functions that aren’t solely highly effective but additionally secure, accountable, and cost-conscious.

Earlier Articles in This Sequence

References

[1] OpenAI. (2025). OpenAI Brokers SDK documentation. Retrieved August 30, 2025, from https://openai.github.io/openai-agents-python/guardrails/

[2] OpenAI. (2025). Methods to use guardrails. OpenAI Cookbook. Retrieved August 30, 2025, from https://cookbook.openai.com/examples/how_to_use_guardrails

[3] OpenAI. (2025). A sensible information to constructing brokers. Retrieved August 30, 2025, from https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf

---

You will discover the entire supply code used on this article within the following repository: agentic-ai-weather | GitHub Repository. Be at liberty to discover, clone, or fork the venture to comply with alongside or construct your individual model.

When you’d wish to see the app in motion, I’ve additionally deployed it right here: Climate Assistant Streamlit

Lastly, let’s join on LinkedIn!