0
# Guardrails
1

2
Guardrails provide configurable safety checks for agent inputs, outputs, and tool usage. They enable content filtering, validation, and safety enforcement with tripwire mechanisms that can halt execution when violations are detected.
3

4
## Capabilities
5

6
### Input Guardrails
7

8
Validate and check agent inputs before processing.
9

10
```python { .api }
11
class InputGuardrail[TContext]:
12
    """
13
    Input guardrail for checking agent input.
14

15
    Type Parameters:
16
    - TContext: Type of context object
17

18
    Attributes:
19
    - guardrail_function: Callable - Guardrail logic
20
    - name: str | None - Guardrail name for identification
21
    - run_in_parallel: bool - Run concurrently with agent
22
    """
23

24
    def get_name() -> str:
25
        """
26
        Get guardrail name.
27

28
        Returns:
29
        - str: Guardrail name (function name if not specified)
30
        """
31

32
    async def run(
33
        agent: Agent,
34
        input: str | list[TResponseInputItem],
35
        context: TContext | None
36
    ) -> InputGuardrailResult:
37
        """
38
        Execute guardrail check.
39

40
        Parameters:
41
        - agent: Agent receiving input
42
        - input: Input to check
43
        - context: Context object
44

45
        Returns:
46
        - InputGuardrailResult: Guardrail result
47
        """
48

49
class InputGuardrailResult:
50
    """
51
    Result of input guardrail.
52

53
    Attributes:
54
    - guardrail: InputGuardrail - The guardrail that ran
55
    - output: GuardrailFunctionOutput - Check output
56
    """
57

58
def input_guardrail(
59
    func: Callable | None = None,
60
    *,
61
    name: str | None = None,
62
    run_in_parallel: bool = False
63
):
64
    """
65
    Decorator to create InputGuardrail from function.
66

67
    Parameters:
68
    - func: Function to wrap
69
    - name: Custom guardrail name
70
    - run_in_parallel: Run concurrently with agent
71

72
    Returns:
73
    - InputGuardrail or decorator
74
    """
75
```
76

77
Usage example:
78

79
```python
80
from agents import Agent, Runner, input_guardrail, GuardrailFunctionOutput
81

82
@input_guardrail
83
def content_filter(input: str) -> GuardrailFunctionOutput:
84
    """Filter inappropriate content from input."""
85
    if "offensive_word" in input.lower():
86
        return GuardrailFunctionOutput(
87
            output_info={"reason": "Inappropriate content detected"},
88
            tripwire_triggered=True
89
        )
90
    return GuardrailFunctionOutput(
91
        output_info={"status": "clean"},
92
        tripwire_triggered=False
93
    )
94

95
@input_guardrail(name="length_check", run_in_parallel=True)
96
async def check_input_length(input: str) -> GuardrailFunctionOutput:
97
    """Check if input is too long."""
98
    if len(input) > 1000:
99
        return GuardrailFunctionOutput(
100
            output_info={"length": len(input), "max": 1000},
101
            tripwire_triggered=True
102
        )
103
    return GuardrailFunctionOutput(
104
        output_info={"length": len(input)},
105
        tripwire_triggered=False
106
    )
107

108
agent = Agent(
109
    name="Assistant",
110
    instructions="Help users.",
111
    input_guardrails=[content_filter, check_input_length]
112
)
113

114
try:
115
    result = Runner.run_sync(agent, "User input here")
116
except InputGuardrailTripwireTriggered as e:
117
    print(f"Input blocked: {e.guardrail_result.output.output_info}")
118
```
119

120
### Output Guardrails
121

122
Validate and check agent outputs before returning to user.
123

124
```python { .api }
125
class OutputGuardrail[TContext]:
126
    """
127
    Output guardrail for checking agent output.
128

129
    Type Parameters:
130
    - TContext: Type of context object
131

132
    Attributes:
133
    - guardrail_function: Callable - Guardrail logic
134
    - name: str | None - Guardrail name for identification
135
    """
136

137
    def get_name() -> str:
138
        """
139
        Get guardrail name.
140

141
        Returns:
142
        - str: Guardrail name
143
        """
144

145
    async def run(
146
        context: TContext | None,
147
        agent: Agent,
148
        agent_output: Any
149
    ) -> OutputGuardrailResult:
150
        """
151
        Execute guardrail check.
152

153
        Parameters:
154
        - context: Context object
155
        - agent: Agent that produced output
156
        - agent_output: Output to check
157

158
        Returns:
159
        - OutputGuardrailResult: Guardrail result
160
        """
161

162
class OutputGuardrailResult:
163
    """
164
    Result of output guardrail.
165

166
    Attributes:
167
    - guardrail: OutputGuardrail - The guardrail that ran
168
    - agent_output: Any - The checked output
169
    - agent: Agent - Agent that produced output
170
    - output: GuardrailFunctionOutput - Check output
171
    """
172

173
def output_guardrail(
174
    func: Callable | None = None,
175
    *,
176
    name: str | None = None
177
):
178
    """
179
    Decorator to create OutputGuardrail from function.
180

181
    Parameters:
182
    - func: Function to wrap
183
    - name: Custom guardrail name
184

185
    Returns:
186
    - OutputGuardrail or decorator
187
    """
188
```
189

190
Usage example:
191

192
```python
193
from agents import Agent, Runner, output_guardrail, GuardrailFunctionOutput
194

195
@output_guardrail
196
def pii_filter(output: str) -> GuardrailFunctionOutput:
197
    """Filter personally identifiable information from output."""
198
    if contains_email(output) or contains_phone(output):
199
        return GuardrailFunctionOutput(
200
            output_info={"reason": "PII detected in output"},
201
            tripwire_triggered=True
202
        )
203
    return GuardrailFunctionOutput(
204
        output_info={"status": "clean"},
205
        tripwire_triggered=False
206
    )
207

208
@output_guardrail(name="quality_check")
209
async def quality_validator(output: str) -> GuardrailFunctionOutput:
210
    """Validate output quality."""
211
    if len(output) < 10:
212
        return GuardrailFunctionOutput(
213
            output_info={"reason": "Output too short"},
214
            tripwire_triggered=True
215
        )
216
    return GuardrailFunctionOutput(
217
        output_info={"quality_score": calculate_quality(output)},
218
        tripwire_triggered=False
219
    )
220

221
agent = Agent(
222
    name="Assistant",
223
    instructions="Provide helpful responses.",
224
    output_guardrails=[pii_filter, quality_validator]
225
)
226

227
try:
228
    result = Runner.run_sync(agent, "Tell me about yourself")
229
    print(result.final_output)
230
except OutputGuardrailTripwireTriggered as e:
231
    print(f"Output blocked: {e.guardrail_result.output.output_info}")
232
```
233

234
### Guardrail Function Output
235

236
Result type for guardrail checks.
237

238
```python { .api }
239
class GuardrailFunctionOutput:
240
    """
241
    Output of guardrail function.
242

243
    Attributes:
244
    - output_info: Any - Information about checks performed
245
    - tripwire_triggered: bool - Whether to halt execution
246
    """
247
```
248

249
Usage example:
250

251
```python
252
from agents import GuardrailFunctionOutput
253

254
def create_guardrail_result(is_safe: bool, details: dict):
255
    """Helper to create guardrail results."""
256
    return GuardrailFunctionOutput(
257
        output_info=details,
258
        tripwire_triggered=not is_safe
259
    )
260

261
@input_guardrail
262
def safety_check(input: str) -> GuardrailFunctionOutput:
263
    is_safe, details = perform_safety_check(input)
264
    return create_guardrail_result(is_safe, details)
265
```
266

267
### Tool Input Guardrails
268

269
Guardrails for tool inputs before execution.
270

271
```python { .api }
272
class ToolInputGuardrail[TContext]:
273
    """
274
    Guardrail for tool input.
275

276
    Type Parameters:
277
    - TContext: Type of context object
278

279
    Attributes:
280
    - guardrail_function: Callable - Guardrail logic
281
    - name: str | None - Guardrail name
282
    """
283

284
    def get_name() -> str:
285
        """
286
        Get guardrail name.
287

288
        Returns:
289
        - str: Guardrail name
290
        """
291

292
    async def run(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
293
        """
294
        Execute guardrail check.
295

296
        Parameters:
297
        - data: Tool input data
298

299
        Returns:
300
        - ToolGuardrailFunctionOutput: Check result
301
        """
302

303
class ToolInputGuardrailResult:
304
    """
305
    Result of tool input guardrail.
306

307
    Attributes:
308
    - guardrail: ToolInputGuardrail - The guardrail that ran
309
    - output: ToolGuardrailFunctionOutput - Check output
310
    """
311

312
class ToolInputGuardrailData:
313
    """
314
    Data for tool input guardrail.
315

316
    Attributes:
317
    - context: TContext | None - Context object
318
    - agent: Agent - Current agent
319
    """
320

321
def tool_input_guardrail(
322
    func: Callable | None = None,
323
    *,
324
    name: str | None = None
325
):
326
    """
327
    Create ToolInputGuardrail from function.
328

329
    Parameters:
330
    - func: Function to wrap
331
    - name: Custom guardrail name
332

333
    Returns:
334
    - ToolInputGuardrail or decorator
335
    """
336
```
337

338
Usage example:
339

340
```python
341
from agents import function_tool, tool_input_guardrail, ToolGuardrailFunctionOutput
342

343
@tool_input_guardrail
344
def validate_file_path(data) -> ToolGuardrailFunctionOutput:
345
    """Ensure file operations are within allowed directories."""
346
    tool_input = data.tool_input
347
    if "path" in tool_input:
348
        path = tool_input["path"]
349
        if not is_safe_path(path):
350
            return ToolGuardrailFunctionOutput.reject_content(
351
                message="File path not allowed",
352
                output_info={"path": path}
353
            )
354
    return ToolGuardrailFunctionOutput.allow(
355
        output_info={"validation": "passed"}
356
    )
357

358
@function_tool
359
def read_file(path: str) -> str:
360
    """Read file contents."""
361
    with open(path) as f:
362
        return f.read()
363

364
# Apply guardrail to tool
365
read_file.tool_input_guardrails = [validate_file_path]
366

367
agent = Agent(
368
    name="File Agent",
369
    tools=[read_file]
370
)
371
```
372

373
### Tool Output Guardrails
374

375
Guardrails for tool outputs after execution.
376

377
```python { .api }
378
class ToolOutputGuardrail[TContext]:
379
    """
380
    Guardrail for tool output.
381

382
    Type Parameters:
383
    - TContext: Type of context object
384

385
    Attributes:
386
    - guardrail_function: Callable - Guardrail logic
387
    - name: str | None - Guardrail name
388
    """
389

390
    def get_name() -> str:
391
        """
392
        Get guardrail name.
393

394
        Returns:
395
        - str: Guardrail name
396
        """
397

398
    async def run(data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
399
        """
400
        Execute guardrail check.
401

402
        Parameters:
403
        - data: Tool output data
404

405
        Returns:
406
        - ToolGuardrailFunctionOutput: Check result
407
        """
408

409
class ToolOutputGuardrailResult:
410
    """
411
    Result of tool output guardrail.
412

413
    Attributes:
414
    - guardrail: ToolOutputGuardrail - The guardrail that ran
415
    - output: ToolGuardrailFunctionOutput - Check output
416
    """
417

418
class ToolOutputGuardrailData:
419
    """
420
    Data for tool output guardrail.
421

422
    Extends ToolInputGuardrailData with output.
423

424
    Attributes:
425
    - context: TContext | None - Context object
426
    - agent: Agent - Current agent
427
    - output: Any - Tool output to check
428
    """
429

430
def tool_output_guardrail(
431
    func: Callable | None = None,
432
    *,
433
    name: str | None = None
434
):
435
    """
436
    Create ToolOutputGuardrail from function.
437

438
    Parameters:
439
    - func: Function to wrap
440
    - name: Custom guardrail name
441

442
    Returns:
443
    - ToolOutputGuardrail or decorator
444
    """
445
```
446

447
Usage example:
448

449
```python
450
from agents import function_tool, tool_output_guardrail, ToolGuardrailFunctionOutput
451

452
@tool_output_guardrail
453
def sanitize_output(data) -> ToolGuardrailFunctionOutput:
454
    """Remove sensitive data from tool output."""
455
    output = data.output
456
    if isinstance(output, str) and contains_secrets(output):
457
        return ToolGuardrailFunctionOutput.reject_content(
458
            message="Tool output contains sensitive data",
459
            output_info={"sanitized": True}
460
        )
461
    return ToolGuardrailFunctionOutput.allow(
462
        output_info={"check": "passed"}
463
    )
464

465
@function_tool
466
def fetch_data(query: str) -> dict:
467
    """Fetch data from API."""
468
    return api_call(query)
469

470
# Apply guardrail to tool
471
fetch_data.tool_output_guardrails = [sanitize_output]
472

473
agent = Agent(
474
    name="Data Agent",
475
    tools=[fetch_data]
476
)
477
```
478

479
### Tool Guardrail Function Output
480

481
Result type for tool guardrail checks with behavior specification.
482

483
```python { .api }
484
class ToolGuardrailFunctionOutput:
485
    """
486
    Output of tool guardrail function.
487

488
    Attributes:
489
    - output_info: Any - Check information
490
    - behavior: RejectContentBehavior | RaiseExceptionBehavior | AllowBehavior - Response behavior
491
    """
492

493
    @classmethod
494
    def allow(output_info: Any) -> ToolGuardrailFunctionOutput:
495
        """
496
        Allow normal execution.
497

498
        Parameters:
499
        - output_info: Information about check
500

501
        Returns:
502
        - ToolGuardrailFunctionOutput: Allow result
503
        """
504

505
    @classmethod
506
    def reject_content(
507
        message: str,
508
        output_info: Any
509
    ) -> ToolGuardrailFunctionOutput:
510
        """
511
        Reject with message to LLM.
512

513
        Parameters:
514
        - message: Message explaining rejection
515
        - output_info: Information about check
516

517
        Returns:
518
        - ToolGuardrailFunctionOutput: Reject result
519
        """
520

521
    @classmethod
522
    def raise_exception(output_info: Any) -> ToolGuardrailFunctionOutput:
523
        """
524
        Halt execution with exception.
525

526
        Parameters:
527
        - output_info: Information about check
528

529
        Returns:
530
        - ToolGuardrailFunctionOutput: Exception result
531
        """
532
```
533

534
Behavior types:
535

536
```python { .api }
537
class RejectContentBehavior:
538
    """
539
    Reject tool call behavior.
540

541
    Attributes:
542
    - type: Literal["reject_content"]
543
    - message: str - Rejection message for LLM
544
    """
545

546
class RaiseExceptionBehavior:
547
    """
548
    Raise exception behavior.
549

550
    Attributes:
551
    - type: Literal["raise_exception"]
552
    """
553

554
class AllowBehavior:
555
    """
556
    Allow normal execution behavior.
557

558
    Attributes:
559
    - type: Literal["allow"]
560
    """
561
```
562

563
Usage example:
564

565
```python
566
from agents import tool_input_guardrail, ToolGuardrailFunctionOutput
567

568
@tool_input_guardrail
569
def validate_api_call(data) -> ToolGuardrailFunctionOutput:
570
    """Validate API calls against rate limits."""
571
    if rate_limit_exceeded():
572
        # Reject with message to LLM
573
        return ToolGuardrailFunctionOutput.reject_content(
574
            message="Rate limit exceeded. Please try again later.",
575
            output_info={"rate_limit": True}
576
        )
577

578
    if critical_failure():
579
        # Halt execution completely
580
        return ToolGuardrailFunctionOutput.raise_exception(
581
            output_info={"error": "Critical failure"}
582
        )
583

584
    # Allow execution
585
    return ToolGuardrailFunctionOutput.allow(
586
        output_info={"status": "ok"}
587
    )
588
```
589

590
## Guardrail Exceptions
591

592
Exceptions raised when guardrail tripwires are triggered.
593

594
```python { .api }
595
class InputGuardrailTripwireTriggered(AgentsException):
596
    """
597
    Raised when input guardrail trips.
598

599
    Attributes:
600
    - guardrail_result: InputGuardrailResult - Guardrail result
601
    """
602

603
class OutputGuardrailTripwireTriggered(AgentsException):
604
    """
605
    Raised when output guardrail trips.
606

607
    Attributes:
608
    - guardrail_result: OutputGuardrailResult - Guardrail result
609
    """
610

611
class ToolInputGuardrailTripwireTriggered(AgentsException):
612
    """
613
    Raised when tool input guardrail trips.
614

615
    Attributes:
616
    - guardrail: ToolInputGuardrail - The guardrail
617
    - output: ToolGuardrailFunctionOutput - Check output
618
    """
619

620
class ToolOutputGuardrailTripwireTriggered(AgentsException):
621
    """
622
    Raised when tool output guardrail trips.
623

624
    Attributes:
625
    - guardrail: ToolOutputGuardrail - The guardrail
626
    - output: ToolGuardrailFunctionOutput - Check output
627
    """
628
```
629

630
## Run-Level Guardrails
631

632
Apply guardrails across all agents in a run.
633

634
```python
635
from agents import Agent, Runner, RunConfig, input_guardrail, output_guardrail
636

637
@input_guardrail
638
def global_input_filter(input: str):
639
    """Apply to all agents in run."""
640
    ...
641

642
@output_guardrail
643
def global_output_filter(output: str):
644
    """Apply to all agents in run."""
645
    ...
646

647
config = RunConfig(
648
    input_guardrails=[global_input_filter],
649
    output_guardrails=[global_output_filter]
650
)
651

652
result = Runner.run_sync(agent, "Hello", run_config=config)
653
```
654

655
## Parallel Guardrails
656

657
Run input guardrails in parallel with agent processing.
658

659
```python
660
from agents import input_guardrail
661

662
@input_guardrail(run_in_parallel=True)
663
async def async_moderation_check(input: str):
664
    """
665
    Run moderation API call in parallel.
666
    Results checked before returning final output.
667
    """
668
    result = await moderation_api.check(input)
669
    if result.flagged:
670
        return GuardrailFunctionOutput(
671
            output_info=result.categories,
672
            tripwire_triggered=True
673
        )
674
    return GuardrailFunctionOutput(
675
        output_info={"safe": True},
676
        tripwire_triggered=False
677
    )
678

679
agent = Agent(
680
    name="Assistant",
681
    input_guardrails=[async_moderation_check]
682
)
683
```
684

685
## Best Practices
686

687
1. **Use Specific Names**: Provide clear guardrail names for debugging and logging
688
2. **Provide Context**: Include detailed `output_info` for understanding guardrail decisions
689
3. **Choose Right Behavior**: Use `reject_content` for recoverable issues, `raise_exception` for critical failures
690
4. **Layer Guardrails**: Combine input, output, and tool guardrails for defense in depth
691
5. **Parallel Execution**: Use `run_in_parallel=True` for expensive checks that don't block agent startup
692
6. **Test Thoroughly**: Ensure guardrails don't block legitimate use cases
693
7. **Monitor Performance**: Track guardrail execution time and false positive rates
694