Add blocking execution mode for input guardrails

[rvv-karma]

Please read this first

• Have you read the docs? Yes, reviewed Agents SDK docs
• Have you searched for related issues? Yes, related to FileSearchTool runs despite InputGuardrailTripwireTriggered #889 and Input guardrail tripwire allows tool execution to continue after exception is raised #991

Related Issues

This feature addresses the concerns raised in:

• FileSearchTool runs despite InputGuardrailTripwireTriggered #889 - FileSearchTool runs despite InputGuardrailTripwireTriggered
• Input guardrail tripwire allows tool execution to continue after exception is raised #991 - Input guardrail tripwire allows tool execution to continue after exception is raised

Both issues highlight that with parallel execution, tools may start executing before the guardrail triggers, leading to unnecessary token consumption and potential security concerns. The run_in_parallel=False option provides a solution by ensuring guardrails complete before any agent processing begins.

Describe the feature

Feature Request: Configurable execution mode for input guardrails

Currently, input guardrails run in parallel with the agent's execution. While this provides low latency, it can lead to unnecessary token costs when a guardrail triggers after the agent has already started processing and making tool calls (as reported in #889 and #991).

Proposed Solution:

Add a run_in_parallel boolean parameter to InputGuardrail that allows developers to choose between:

1. Parallel execution (default, run_in_parallel=True): Guardrail runs concurrently with the agent for minimal latency
2. Blocking execution (run_in_parallel=False): Guardrail runs and completes before the agent starts, preventing any token consumption or tool execution if the guardrail triggers

Use Cases:

• Cost optimization: When token costs are a concern and latency is acceptable
• Hard validation: When input must be validated before any agent processing begins
• Security checks: When certain inputs must be blocked before any LLM interaction or tool execution
• Preventing race conditions: Ensures guardrails complete before tools are called (addresses FileSearchTool runs despite InputGuardrailTripwireTriggered #889, Input guardrail tripwire allows tool execution to continue after exception is raised #991)

Example Usage:

from agents import Agent, input_guardrail, InputGuardrail

# Using decorator with blocking execution
@input_guardrail(run_in_parallel=False)
async def content_policy_check(input_text: str):
    if contains_prohibited_content(input_text):
        raise TripwireTriggered("Content policy violation")

# Using InputGuardrail directly
guardrail = InputGuardrail(
    guardrail_function=validate_input,
    run_in_parallel=False  # Block agent until validation completes
)

agent = Agent(
    name="MyAgent",
    input_guardrails=[guardrail],
    tools=[FileSearchTool()],  # Tools won't execute if guardrail triggers
    # ...
)

Benefits:

• Backward compatible: Default is True, maintaining current behavior
• Cost efficient: Prevents unnecessary agent token usage when guardrails trigger
• Solves race conditions: Completely prevents tool execution when guardrails trigger (FileSearchTool runs despite InputGuardrailTripwireTriggered #889, Input guardrail tripwire allows tool execution to continue after exception is raised #991)
• Flexible: Developers can choose the right tradeoff for their use case
• Explicit: Clear intent in code about execution order

Implementation Notes:

• Only applies to InputGuardrail, not OutputGuardrail (which always runs after agent completion)
• Works in both streaming and non-streaming modes
• When blocking guardrails raise TripwireTriggered, the agent never starts and no tools are executed