removed docs. Added non-blocking behavior

Author: steven10a

docs/guardrails.md

@@ -151,84 +151,4 @@ async def main():
 1. This is the actual agent's output type.
 2. This is the guardrail's output type.
 3. This is the guardrail function that receives the agent's output, and returns the result.
-4. This is the actual agent that defines the workflow.
-
-## Tool guardrails
-
-Tool guardrails provide fine-grained control over individual tool calls, allowing you to validate inputs and outputs at the tool level. This is particularly useful for:
-
-- Blocking sensitive data in tool arguments
-- Preventing unauthorized access to certain tools
-- Sanitizing tool outputs before they're returned
-- Implementing custom validation logic for specific tools
-
-There are two types of tool guardrails:
-
-1. **Tool input guardrails** run before a tool is executed, validating the tool call arguments
-2. **Tool output guardrails** run after a tool is executed, validating the tool's output
-
-### Tool input guardrails
-
-Tool input guardrails run in 3 steps:
-
-1. First, the guardrail receives the tool call data including arguments, context, and agent information
-2. Next, the guardrail function runs to produce a [`ToolGuardrailFunctionOutput`][agents.tool_guardrails.ToolGuardrailFunctionOutput]
-3. Finally, we check if [`.tripwire_triggered`][agents.tool_guardrails.ToolGuardrailFunctionOutput.tripwire_triggered] is true. If true, a [`ToolInputGuardrailTripwireTriggered`][agents.exceptions.ToolInputGuardrailTripwireTriggered] exception is raised
-
-### Tool output guardrails
-
-Tool output guardrails run in 3 steps:
-
-1. First, the guardrail receives the tool call data plus the tool's output
-2. Next, the guardrail function runs to produce a [`ToolGuardrailFunctionOutput`][agents.tool_guardrails.ToolGuardrailFunctionOutput]
-3. Finally, we check if [`.tripwire_triggered`][agents.tool_guardrails.ToolGuardrailFunctionOutput.tripwire_triggered] is true. If true, a [`ToolOutputGuardrailTripwireTriggered`][agents.exceptions.ToolOutputGuardrailTripwireTriggered] exception is raised
-
-### Implementing tool guardrails
-
-You can create tool guardrails using the `@tool_input_guardrail` and `@tool_output_guardrail` decorators:
-
-```python
-from agents import (
-    ToolGuardrailFunctionOutput,
-    ToolInputGuardrailData,
-    ToolOutputGuardrailData,
-    tool_input_guardrail,
-    tool_output_guardrail,
-)
-
-@tool_input_guardrail
-def block_sensitive_words(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
-    """Block tool calls that contain sensitive words in arguments."""
-    # Check arguments for sensitive content
-    if "password" in data.tool_call.arguments.lower():
-        return ToolGuardrailFunctionOutput(
-            tripwire_triggered=True,
-            model_message="🚨 Tool call blocked: contains sensitive word",
-            output_info={"blocked_word": "password"},
-        )
-    return ToolGuardrailFunctionOutput(tripwire_triggered=False, output_info="Input validated")
-
-@tool_output_guardrail
-def block_sensitive_output(data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
-    """Block tool outputs that contain sensitive data."""
-    if "ssn" in str(data.output).lower():
-        return ToolGuardrailFunctionOutput(
-            tripwire_triggered=True,
-            model_message="🚨 Tool output blocked: contains sensitive data",
-            output_info={"blocked_pattern": "SSN"},
-        )
-    return ToolGuardrailFunctionOutput(tripwire_triggered=False, output_info="Output validated")
-
-# Apply guardrails to tools
-my_tool.tool_input_guardrails = [block_sensitive_words]
-my_tool.tool_output_guardrails = [block_sensitive_output]
-```
-
-For a complete working example, see [tool_guardrails.py](https://github.com/openai/openai-agents-python/blob/main/examples/basic/tool_guardrails.py).
-
-### Key differences from agent guardrails
-
-- **Scope**: Tool guardrails operate on individual tool calls, while agent guardrails operate on the entire agent input/output
-- **Timing**: Tool guardrails run immediately before/after tool execution, while agent guardrails run at the beginning/end of agent execution
-- **Data access**: Tool guardrails have access to the specific tool call arguments and outputs, plus the tool context
-- **Application**: Tool guardrails are applied directly to function tools via the `tool_input_guardrails` and `tool_output_guardrails` attributes
+4. This is the actual agent that defines the workflow.

docs/ref/tool_guardrails.md

@@ -6,7 +6,6 @@
     Runner,
     ToolGuardrailFunctionOutput,
     ToolInputGuardrailData,
-    ToolInputGuardrailTripwireTriggered,
     ToolOutputGuardrailData,
     ToolOutputGuardrailTripwireTriggered,
     function_tool,
@@ -33,36 +32,44 @@ def get_user_data(user_id: str) -> dict[str, str]:
         "phone": "555-1234",
     }
 
+@function_tool
+def get_contact_info(user_id: str) -> dict[str, str]:
+    """Get contact info by ID."""
+    return {
+        "user_id": user_id,
+        "name": "Jane Smith",
+        "email": "[email protected]",
+        "phone": "555-1234",
+    }
+
 
 @tool_input_guardrail
-def block_sensitive_words(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
-    """Block tool calls that contain sensitive words in arguments."""
+def reject_sensitive_words(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
+    """Reject tool calls that contain sensitive words in arguments."""
     try:
-        args = json.loads(data.tool_call.arguments)
+        args = json.loads(data.context.tool_arguments) if data.context.tool_arguments else {}
     except json.JSONDecodeError:
-        return ToolGuardrailFunctionOutput(
-            tripwire_triggered=False, output_info="Invalid JSON arguments"
-        )
+        return ToolGuardrailFunctionOutput(output_info="Invalid JSON arguments")
 
     # Check for suspicious content
     sensitive_words = [
         "password",
         "hack",
         "exploit",
         "malware",
-        "orange",
-    ]  # to mock sensitive words
+        "ACME",
+    ]
     for key, value in args.items():
         value_str = str(value).lower()
         for word in sensitive_words:
-            if word in value_str:
-                return ToolGuardrailFunctionOutput(
-                    tripwire_triggered=True,
-                    model_message=f"🚨 Tool call blocked: contains '{word}'",
+            if word.lower() in value_str:
+                # Reject tool call and inform the model the function was not called
+                return ToolGuardrailFunctionOutput.reject_content(
+                    message=f"🚨 Tool call blocked: contains '{word}'",
                     output_info={"blocked_word": word, "argument": key},
                 )
 
-    return ToolGuardrailFunctionOutput(tripwire_triggered=False, output_info="Input validated")
+    return ToolGuardrailFunctionOutput(output_info="Input validated")
 
 
 @tool_output_guardrail
@@ -72,57 +79,71 @@ def block_sensitive_output(data: ToolOutputGuardrailData) -> ToolGuardrailFuncti
 
     # Check for sensitive data patterns
     if "ssn" in output_str or "123-45-6789" in output_str:
-        return ToolGuardrailFunctionOutput(
-            tripwire_triggered=True,
-            model_message="🚨 Tool output blocked: contains sensitive data",
-            output_info={"blocked_pattern": "SSN", "tool": data.tool_call.name},
+        # Use raise_exception to halt execution completely for sensitive data
+        return ToolGuardrailFunctionOutput.raise_exception(
+            output_info={"blocked_pattern": "SSN", "tool": data.context.tool_name},
         )
 
-    return ToolGuardrailFunctionOutput(tripwire_triggered=False, output_info="Output validated")
+    return ToolGuardrailFunctionOutput(output_info="Output validated")
+
+
+@tool_output_guardrail
+def reject_phone_numbers(data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
+    """Reject function output containing phone numbers."""
+    output_str = str(data.output)
+    if "555-1234" in output_str:
+        return ToolGuardrailFunctionOutput.reject_content(
+            message="User data not retrieved as it contains a phone number which is restricted.",
+            output_info={"redacted": "phone_number"},
+        )
+    return ToolGuardrailFunctionOutput()
 
 
 # Apply guardrails to tools
-send_email.tool_input_guardrails = [block_sensitive_words]
+send_email.tool_input_guardrails = [reject_sensitive_words]
 get_user_data.tool_output_guardrails = [block_sensitive_output]
+get_contact_info.tool_output_guardrails = [reject_phone_numbers]
 
 agent = Agent(
     name="Secure Assistant",
     instructions="You are a helpful assistant with access to email and user data tools.",
-    tools=[send_email, get_user_data],
+    tools=[send_email, get_user_data, get_contact_info],
 )
 
 
 async def main():
     print("=== Tool Guardrails Example ===\n")
 
-    # Example 1: Normal operation - should work fine
-    print("1. Normal email sending:")
     try:
+        # Example 1: Normal operation - should work fine
+        print("1. Normal email sending:")
         result = await Runner.run(agent, "Send a welcome email to [email protected]")
-        print(f"✅ Success: {result.final_output}\n")
-    except Exception as e:
-        print(f"❌ Error: {e}\n")
+        print(f"✅ Successful tool execution: {result.final_output}\n")
 
-    # Example 2: Input guardrail triggers - should block suspicious content
-    print("2. Attempting to send email with suspicious content:")
-    try:
-        result = await Runner.run(
-            agent, "Send an email to [email protected] with the subject: orange"
-        )
-        print(f"✅ Success: {result.final_output}\n")
-    except ToolInputGuardrailTripwireTriggered as e:
-        print(f"🚨 Input guardrail triggered: {e.output.model_message}")
-        print(f"   Details: {e.output.output_info}\n")
+        # Example 2: Input guardrail triggers - function tool call is rejected but execution continues
+        print("2. Attempting to send email with suspicious content:")
+        result = await Runner.run(agent, "Send an email to [email protected] introducing the company ACME corp.")
+        print(f"❌ Guardrail rejected function tool call: {result.final_output}\n")
+    except Exception as e:
+        print(f"Error: {e}\n")
 
-    # Example 3: Output guardrail triggers - should block sensitive data
-    print("3. Attempting to get user data (contains SSN):")
     try:
+        # Example 3: Output guardrail triggers - should raise exception for sensitive data
+        print("3. Attempting to get user data (contains SSN). Execution blocked:")
         result = await Runner.run(agent, "Get the data for user ID user123")
-        print(f"✅ Success: {result.final_output}\n")
+        print(f"✅ Successful tool execution: {result.final_output}\n")
     except ToolOutputGuardrailTripwireTriggered as e:
-        print(f"🚨 Output guardrail triggered: {e.output.model_message}")
-        print(f"   Details: {e.output.output_info}\n")
+        print("🚨 Output guardrail triggered: Execution halted for sensitive data")
+        print(f"Details: {e.output.output_info}\n")
 
+    
+    try:
+        # Example 4: Output guardrail triggers - reject returning function tool output but continue execution
+        print("4. Rejecting function tool output containing phone numbers:")
+        result = await Runner.run(agent, "Get contact info for user456")
+        print(f"❌ Guardrail rejected function tool output: {result.final_output}\n")
+    except Exception as e:
+        print(f"Error: {e}\n")
 
 if __name__ == "__main__":
     asyncio.run(main())
@@ -133,13 +154,15 @@ async def main():
 === Tool Guardrails Example ===
 
 1. Normal email sending:
-✅ Success: I've sent a welcome email to [email protected] with an appropriate subject and greeting message.
+✅ Successful tool execution: I've sent a welcome email to [email protected] with an appropriate subject and greeting message.
 
 2. Attempting to send email with suspicious content:
-🚨 Input guardrail triggered: 🚨 Tool call blocked: contains 'orange'
-   Details: {'blocked_word': 'orange', 'argument': 'subject'}
+❌ Guardrail rejected function tool call: I'm unable to send the email mentioning ACME Corp as it was blocked by security guardrails.
 
-3. Attempting to get user data (contains SSN):
-🚨 Output guardrail triggered: 🚨 Tool output blocked: contains sensitive data
+3. Attempting to get user data (contains SSN). Execution blocked:
+🚨 Output guardrail triggered: Execution halted for sensitive data
    Details: {'blocked_pattern': 'SSN', 'tool': 'get_user_data'}
+
+4. Rejecting function tool output containing sensitive data:
+✅ Successful tool execution: User data retrieved (phone number redacted for privacy)
 """

examples/basic/tool_guardrails.py

@@ -18,7 +18,6 @@ def get_weather(city: Annotated[str, "The city to get the weather for"]) -> Weat
     print("[debug] get_weather called")
     return Weather(city=city, temperature_range="14-20C", conditions="Sunny with wind.")
 
-
 agent = Agent(
     name="Hello world",
     instructions="You are a helpful agent.",

examples/basic/tools.py

@@ -101,7 +101,6 @@ plugins:
                     - ref/usage.md
                     - ref/exceptions.md
                     - ref/guardrail.md
-                    - ref/tool_guardrails.md
                     - ref/model_settings.md
                     - ref/agent_output.md
                     - ref/function_schema.md

mkdocs.yml

@@ -89,8 +89,10 @@
     ToolGuardrailFunctionOutput,
     ToolInputGuardrail,
     ToolInputGuardrailData,
+    ToolInputGuardrailResult,
     ToolOutputGuardrail,
     ToolOutputGuardrailData,
+    ToolOutputGuardrailResult,
     tool_input_guardrail,
     tool_output_guardrail,
 )
@@ -221,7 +223,9 @@ def enable_verbose_stdout_logging():
     "ToolOutputGuardrail",
     "ToolGuardrailFunctionOutput",
     "ToolInputGuardrailData",
+    "ToolInputGuardrailResult",
     "ToolOutputGuardrailData",
+    "ToolOutputGuardrailResult",
     "tool_input_guardrail",
     "tool_output_guardrail",
     "handoff",