Principle:Openai Openai agents python Guardrail Attachment

Overview

Guardrail attachment is the configuration pattern for wiring guardrail instances to the entities they protect. The OpenAI Agents SDK provides two attachment points: tool-level (on FunctionTool) and agent-level (on Agent). Understanding how to attach guardrails correctly is essential for building safe agent systems, as a guardrail that is not properly attached will never execute.

Core Theory

Two Attachment Points

The SDK offers guardrail attachment at two levels, each serving a distinct purpose:

Tool-level attachment -- Guardrails are attached directly to a FunctionTool instance via the tool_input_guardrails and tool_output_guardrails fields. These guardrails run every time that specific tool is invoked, regardless of which agent invokes it.
Agent-level attachment -- Guardrails are attached to an Agent instance via the input_guardrails and output_guardrails fields. Input guardrails run on the user's input to the starting agent; output guardrails run on the final agent's response.

Tool-Level Attachment

Tool-level guardrails are configured as lists on the FunctionTool dataclass:

tool_input_guardrails -- A list of ToolInputGuardrail instances that validate the tool call arguments before execution.
tool_output_guardrails -- A list of ToolOutputGuardrail instances that validate the tool's return value after execution.

These fields are defined in src/agents/tool.py on the FunctionTool class. There are two ways to populate them:

Via the function_tool function/decorator -- Pass guardrail lists as keyword arguments when creating the tool.
Direct construction -- Build a FunctionTool instance manually and populate the guardrail lists.

Tool-level guardrails travel with the tool. If the same FunctionTool instance is shared across multiple agents, the guardrails apply to every invocation regardless of which agent triggers it.

Agent-Level Attachment

Agent-level guardrails are configured as lists on the Agent dataclass:

input_guardrails -- A list of InputGuardrail instances that validate the user's input on the first turn.
output_guardrails -- A list of OutputGuardrail instances that validate the agent's final output.

These fields are defined in src/agents/agent.py. They can be populated via:

Direct class construction -- Pass guardrail lists when instantiating an Agent.
Decorator-created guardrails -- Use the @input_guardrail and @output_guardrail decorators to create guardrail objects, then pass them in the agent's constructor lists.

Creation Methods

Guardrail instances can be created through two equivalent mechanisms:

Decorators -- The @tool_input_guardrail, @tool_output_guardrail, @input_guardrail, and @output_guardrail decorators transform a function into a guardrail object. The function name becomes the guardrail name by default.
Class constructors -- The ToolInputGuardrail, ToolOutputGuardrail, InputGuardrail, and OutputGuardrail dataclasses can be instantiated directly, passing the guardrail function and an optional name.

Both approaches produce identical guardrail objects. The decorator syntax is more concise for simple cases; the class constructor is useful when you need to configure additional parameters or create guardrails dynamically.

Stacking Guardrails

Multiple guardrails of the same type can be attached to a single tool or agent. The attachment fields are lists, and all guardrails in the list are evaluated during execution. This enables a composition pattern where each guardrail checks for a single concern:

One guardrail checks for SQL injection in tool inputs.
Another guardrail validates that arguments are within acceptable ranges.
A third guardrail verifies that the calling agent has permission to use the tool.

All guardrails must pass for execution to proceed. If any guardrail rejects or triggers a tripwire, the operation is blocked.

This Is a Configuration Pattern

Guardrail attachment is a configuration pattern, not a separate API. There are no special methods for adding or removing guardrails at runtime. Guardrails are specified at construction time as part of the tool or agent definition. To change which guardrails are active, you create a new tool or agent instance with different guardrail lists.

Key Source References

FunctionTool guardrail fields: src/agents/tool.py lines 247-251
Agent guardrail fields: src/agents/agent.py lines 269-277

Page Connections

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

Principle

Implementation

Heuristic

Environment