Principle:Openai Openai agents python Tool Input Guardrail Definition

Overview

Tool input guardrails provide a mechanism for pre-execution validation on the arguments a tool will receive. Before a tool function runs, each configured input guardrail inspects the proposed call arguments and decides whether execution should proceed, be rejected with an error message sent back to the LLM, or be halted entirely via an exception. This enables safety constraints on tool usage without modifying the tool itself.

Core Theory

Pre-Execution Validation

Tool input guardrails sit in the execution pipeline between the LLM's decision to call a tool and the actual invocation of that tool's function. When the LLM produces a tool call with specific arguments, the framework first routes those arguments through every input guardrail attached to the tool. Only if all guardrails allow execution does the tool function actually run.

This separation of concerns means:

The tool function remains focused on its core logic and does not need to contain validation or safety checks.
Guardrails can be developed, tested, and reused independently of the tools they protect.
Multiple guardrails can be stacked on a single tool, each checking for a different class of problem.

Three Behavior Options

Every tool input guardrail must return a ToolGuardrailFunctionOutput that signals one of three outcomes:

allow -- The tool call is safe and execution should proceed normally. This is the "happy path" where no issues are detected.
reject_content -- The tool call is unsafe or invalid, but execution should not be halted entirely. Instead, an error message is sent back to the LLM in place of executing the tool. This gives the model an opportunity to correct its approach.
raise_exception -- The tool call is dangerous enough that the entire run should stop immediately. A ToolInputGuardrailTripwireTriggered exception is raised, which propagates up to the caller.

The choice between reject_content and raise_exception depends on the severity of the violation. For recoverable issues (e.g., an invalid parameter format), rejection is appropriate because the LLM can retry. For security-critical violations (e.g., attempted code injection), raising an exception provides a hard stop.

ToolInputGuardrailData

The guardrail function receives a ToolInputGuardrailData instance that provides access to:

context -- A ToolContext object containing the tool call arguments (tool_input), the tool name, and other contextual information about the invocation.
agent -- The Agent instance that triggered the tool call, allowing guardrails to make decisions based on agent configuration or identity.

This data model gives guardrails sufficient context to make informed decisions about whether a tool call should proceed.

Sync and Async Support

Guardrails can be defined as either synchronous or asynchronous functions. The framework handles both transparently:

Synchronous guardrails are suitable for simple, fast checks like string pattern matching or value range validation.
Asynchronous guardrails are appropriate when validation requires I/O operations such as database lookups or external API calls.

Stacking Multiple Guardrails

Multiple input guardrails can be attached to a single tool via the tool_input_guardrails list on FunctionTool. All guardrails are evaluated, and if any one of them rejects or raises an exception, the tool call is blocked. This allows composing fine-grained, single-purpose guardrails into comprehensive protection layers.

Key Source References

Decorator definition: src/agents/tool_guardrails.py lines 228-243
Class definition: src/agents/tool_guardrails.py lines 152-177

Import

from agents import tool_input_guardrail, ToolInputGuardrail

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment