# OpenAI Agents SDK Guardrails: Input, Output and Tool Checks

> The OpenAI Agents SDK has three guardrail layers that run at different points of a workflow. Here is when each fires, why parallel input checks can let a tool run anyway, and how a tool guardrail stops a journal entry posting to the wrong branch.

URL: https://www.matthewswong.com/en/blog/openai-agents-sdk-guardrails-tripwires/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** OpenAI Agents SDK guardrails come in three layers: input guardrails run only on the first agent, output guardrails only on the last, and tool guardrails on every guarded function-tool call. Input checks run in parallel by default, so the agent may spend tokens and call tools before a tripwire fires. Use blocking mode or a tool guardrail for side effects.

The first version of a finance assistant I sketched for an ERP back-office had one guardrail: an input check that refused anything that was not about the ledger. It looked complete until I read the execution-mode section of the docs. By default that check runs at the same time as the agent, and the documentation says plainly that if the tripwire fires, the agent may already have consumed tokens and executed tools. For an agent whose main tool posts journal entries, may already have executed tools is the whole problem.

This post walks through the three guardrail layers of the OpenAI Agents SDK as documented for openai-agents 0.22.3, the PyPI release of 17 September 2026: input guardrails, output guardrails and the per-call tool guardrails. Each one is applied to a real risk in an accounting workflow, an off-topic request, personal data leaking from a reply, and a tool call that would post to the wrong branch, with the exceptions you need to catch. The TypeScript SDK documents the same three layers with camelCase names, such as runInParallel and toolExecution, so the design carries over unchanged.

## OpenAI Agents SDK guardrails: three layers, three boundaries

The single most useful fact about guardrails is where they run, because it is not where most people assume. Guardrails are configured on the agent or the tool, but the runner only fires them at specific workflow boundaries.

| Layer | When it runs | What it sees and can do | Exception on tripwire |
| --- | --- | --- | --- |
| Input guardrail, on Agent.input_guardrails | Only when the agent is the first agent in the run. Parallel with the agent by default, or before it with run_in_parallel=False | The same input passed to the agent. Returns GuardrailFunctionOutput with tripwire_triggered and output_info | InputGuardrailTripwireTriggered |
| Output guardrail, on Agent.output_guardrails | Only on the agent that produces the final output, always after it completes. No parallel option | The final output, typed as the agent's output_type. Same GuardrailFunctionOutput shape | OutputGuardrailTripwireTriggered |
| Tool guardrail, on a FunctionTool | On every invocation of that tool, input check before execution and output check after, whichever agent calls it | The tool name and raw argument string, or the tool's result. Returns allow, reject_content or raise_exception | ToolInputGuardrailTripwireTriggered or ToolOutputGuardrailTripwireTriggered |

Read the second column twice. In a triage setup where a front-desk agent hands off to a finance specialist, the specialist's input guardrails never run, because it is not the first agent, and the triage agent's output guardrails never run, because it does not produce the final answer. The docs say it directly: if you need checks around each custom function-tool call in a workflow with managers, handoffs or delegated specialists, use tool guardrails instead of relying only on agent-level ones.

## Parallel vs blocking input guardrails: latency against side effects

An input guardrail is any function that takes the run context, the agent and the input, and returns a GuardrailFunctionOutput. The common pattern is a small classifier agent with a typed output_type, run from inside the guardrail. The only decision that really matters is the execution mode, which you set on the decorator.

Parallel mode, the default, starts the guardrail and the agent together, so a clean request pays no extra latency. Blocking mode makes the agent wait for the verdict, which costs one classifier round-trip on every request, but when the tripwire fires the agent never executes: no tokens on the expensive model and no tool calls. I chose blocking for any agent that owns a side-effecting tool, and kept parallel for read-only assistants where a cancelled run only wastes a few tokens.

> Parallel mode is a cost optimisation, not a safety boundary. The SDK documents that when a parallel input guardrail trips, the agent may already have consumed tokens and executed tools before being cancelled. If the first turn can call a tool that writes to the ledger, sends an email or calls a payment API, either set run_in_parallel=False or put the real check on the tool itself.

## Output guardrails: stopping personal data before it leaves

Output guardrails receive the final output after the last agent finishes, which is why there is no parallel mode to choose. A model-based check works here too, but for personal data a deterministic pattern is faster and easier to reason about. The example below trips on a 16-digit NIK or an email address in the reply.

Two behaviours from the docs shape how you use this. First, a tripwire and a crash are treated differently: when the tripwire fires, the session keeps the completed tool calls and outputs but drops the rejected final answer, while an exception raised inside the guardrail is treated as an unknown verdict and the final-turn items are persisted before the error surfaces. So return a verdict, do not raise. Second, when tool_use_behavior makes a tool's result the final output and the guardrail rejects it, the SDK replaces the stored payload with the placeholder Output withheld by an output guardrail. You can change that text with RunConfig.output_guardrail_blocked_message, but keep it free of data, because it is persisted and replayed.

## Tool guardrails: checking a journal entry's branch before it posts

Tool guardrails are the layer built for the ERP case. They attach to the tool, so they run on every call regardless of which agent made it, and they see the arguments the model actually produced. The input guardrail below reads the raw tool_arguments string and the caller's own context object, then decides between three outcomes.

The two rejection paths do different jobs. reject_content skips the call and hands the model a message in place of a tool result, so the run continues and the agent can ask the user which branch they meant. raise_exception halts the whole run with ToolInputGuardrailTripwireTriggered, which is right for a state the model should never have reached, such as debits that do not equal credits. Note that the branch list comes from your context object, never from the prompt, so the model cannot talk its way into another branch.

> If the tool also has needs_approval, input tool guardrails normally run after a human approves and just before execution. Set RunConfig.tool_execution to ToolExecutionConfig with pre_approval_tool_input_guardrails=True and the same check also runs before the approval request is raised, so nobody is asked to approve an entry that was going to be rejected anyway. It still runs again after approval.

## Where guardrails do not run

The gaps are documented, and each one is a place where an agent can act without the check you think is in front of it.

- Handoffs go through the SDK's handoff pipeline, not the function-tool pipeline, so tool guardrails do not apply to the handoff call itself.
- Hosted and built-in tools, including WebSearchTool, FileSearchTool, HostedMCPTool, CodeInterpreterTool, ComputerTool and ShellTool, do not use the tool guardrail pipeline at all.
- Agent.as_tool() does not currently expose tool guardrail options, so a specialist wrapped as a tool needs its checks on the function tools it calls.
- Local MCP servers can opt in: setting tool_input_guardrails and tool_output_guardrails on the server attaches them to every tool it exposes.

The practical rule I took from this list: anything that writes must be a function tool you own, with a tool guardrail on it. If a write goes through a hosted tool or a remote MCP server, the guardrail has to live on the server side, because the SDK cannot see inside that call.

## Catching the four tripwire exceptions

Each layer raises its own exception, and they carry their data in different places. Agent-level tripwires expose guardrail_result, which names the guardrail and holds its output. Tool tripwires expose the guardrail and its ToolGuardrailFunctionOutput directly on the exception. All four are importable from the agents package.

Map each one to a distinct response, because they mean different things to the caller: an out-of-scope request is a client error, a withheld answer is a server-side refusal, and a blocked journal entry is a conflict nothing was written for. The docs also note that exception.run_data keeps the guardrail results gathered before the run stopped, including tool guardrail results from completed turns, which is the right thing to send to your audit log. run_data can be None when the exception is raised outside a runner-managed path, so guard for that before reading it.

## Guardrails or human approval: choosing the right control

OpenAI's own guide separates the two cleanly: guardrails validate input, output or tool behaviour automatically, while human review pauses the run so a person or policy can approve a sensitive action. In practice I layer them in this order for any agent that touches money.

1. A blocking input guardrail with a cheap classifier, so out-of-scope requests never reach the expensive model or a tool.
2. A tool input guardrail on every writing tool, for rules a machine can check: branch permissions, balanced entries, amount limits.
3. needs_approval on the same tools for amounts above a threshold, where a person has to own the decision.
4. A deterministic output guardrail for personal data, because it is the last point before text reaches the user.

None of these replaces permissions in the ERP itself. A guardrail is a check inside your process; the ledger's own role and branch permissions are the boundary that still holds when the agent, the SDK or your guardrail code has a bug.

The rule I carry from this: put a check on the boundary where the action happens, not where the conversation starts. Input guardrails keep cost and scope under control, output guardrails protect what leaves, but only a tool guardrail is guaranteed to stand in front of every write, whichever agent makes it.

## Sources

- OpenAI Agents SDK for Python: Guardrails guide
- OpenAI Agents SDK for Python: tool_guardrails API reference
- OpenAI Agents SDK for JavaScript and TypeScript: Guardrails guide
- OpenAI API docs: Guardrails and human review for agents
- openai-agents package on PyPI

## Source links

- https://openai.github.io/openai-agents-python/guardrails/
- https://openai.github.io/openai-agents-python/ref/tool_guardrails/
- https://openai.github.io/openai-agents-js/guides/guardrails/
- https://developers.openai.com/api/docs/guides/agents/guardrails-approvals
- https://pypi.org/project/openai-agents/

## FAQ

### What are guardrails in the OpenAI Agents SDK?

Guardrails are checks the SDK runs on an agent's input, its final output, or individual function-tool calls. Each guardrail returns a verdict, and if its tripwire is triggered the runner raises an exception and halts the run. Input and output guardrails are attached to an agent, while tool guardrails are attached to a specific tool.

### Do input guardrails run in parallel with the agent?

Yes, by default. With run_in_parallel=True the guardrail and the agent start together, which keeps latency low, but the agent may already have used tokens and called tools before a tripwire cancels it. Setting run_in_parallel=False makes the guardrail finish first, so a blocked request never reaches the model or any tool.

### Why did my input guardrail not run after a handoff?

Input guardrails only run for the first agent in a run, and output guardrails only for the agent that produces the final output. A specialist that receives a handoff is not the first agent, so its input guardrails are skipped. For checks that must apply whichever agent acts, put a tool guardrail on the function tool itself.

### What is the difference between reject_content and raise_exception in a tool guardrail?

reject_content skips the tool call, or replaces its output, with a message the model reads instead, so the run continues and the agent can correct itself. raise_exception halts the whole run with ToolInputGuardrailTripwireTriggered or ToolOutputGuardrailTripwireTriggered. Use the first for recoverable mistakes and the second for states the agent should never reach.

### Do tool guardrails work with hosted tools like web search or hosted MCP?

No. Tool guardrails use the function-tool pipeline, so hosted tools such as WebSearchTool, FileSearchTool and HostedMCPTool, and built-in tools such as ComputerTool and ShellTool, bypass them. Handoff calls and Agent.as_tool() also lack tool guardrail options. Local MCP servers can attach guardrails to every tool they expose.

---

- HTML version: https://www.matthewswong.com/en/blog/openai-agents-sdk-guardrails-tripwires/
- Bahasa Indonesia: https://www.matthewswong.com/id/blog/openai-agents-sdk-guardrails-tripwires/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
