chore: import upstream snapshot with attribution

2026-07-13 12:39:17 +08:00
commit 4ed4e9ff99
1368 changed files with 334957 additions and 0 deletions
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import asyncio
+
+from pydantic import BaseModel
+
+from agents import (
+    Agent,
+    GuardrailFunctionOutput,
+    InputGuardrailTripwireTriggered,
+    RunContextWrapper,
+    Runner,
+    TResponseInputItem,
+    input_guardrail,
+)
+from examples.auto_mode import input_with_fallback, is_auto_mode
+
+"""
+This example shows how to use guardrails.
+
+Guardrails are checks that run in parallel to the agent's execution.
+They can be used to do things like:
+- Check if input messages are off-topic
+- Check that input messages don't violate any policies
+- Take over control of the agent's execution if an unexpected input is detected
+
+In this example, we'll setup an input guardrail that trips if the user is asking to do math homework.
+If the guardrail trips, we'll respond with a refusal message.
+"""
+
+
+### 1. An agent-based guardrail that is triggered if the user is asking to do math homework
+class MathHomeworkOutput(BaseModel):
+    reasoning: str
+    is_math_homework: bool
+
+
+guardrail_agent = Agent(
+    name="Guardrail check",
+    instructions="Check if the user is asking you to do their math homework.",
+    output_type=MathHomeworkOutput,
+)
+
+
+@input_guardrail
+async def math_guardrail(
+    context: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
+) -> GuardrailFunctionOutput:
+    """This is an input guardrail function, which happens to call an agent to check if the input
+    is a math homework question.
+    """
+    result = await Runner.run(guardrail_agent, input, context=context.context)
+    final_output = result.final_output_as(MathHomeworkOutput)
+
+    return GuardrailFunctionOutput(
+        output_info=final_output,
+        tripwire_triggered=final_output.is_math_homework,
+    )
+
+
+### 2. The run loop
+
+
+async def main():
+    agent = Agent(
+        name="Customer support agent",
+        instructions="You are a customer support agent. You help customers with their questions.",
+        input_guardrails=[math_guardrail],
+    )
+
+    input_data: list[TResponseInputItem] = []
+    auto_mode = is_auto_mode()
+    scripted_inputs = [
+        "What's the capital of California?",
+        "Can you help me solve for x: 2x + 5 = 11",
+    ]
+
+    while True:
+        if auto_mode:
+            if not scripted_inputs:
+                break
+            user_input = scripted_inputs.pop(0)
+            print(f"[auto-input] Enter a message: -> {user_input}")
+        else:
+            user_input = input_with_fallback(
+                "Enter a message: ",
+                "What's the capital of California?",
+            )
+        input_data.append(
+            {
+                "role": "user",
+                "content": user_input,
+            }
+        )
+
+        try:
+            result = await Runner.run(agent, input_data)
+            print(result.final_output)
+            # If the guardrail didn't trigger, we use the result as the input for the next run
+            input_data = result.to_input_list()
+        except InputGuardrailTripwireTriggered:
+            # If the guardrail triggered, we instead add a refusal message to the input
+            message = "Sorry, I can't help you with your math homework."
+            print(message)
+            input_data.append(
+                {
+                    "role": "assistant",
+                    "content": message,
+                }
+            )
+        if auto_mode and not scripted_inputs:
+            break
+
+    # Sample run:
+    # Enter a message: What's the capital of California?
+    # The capital of California is Sacramento.
+    # Enter a message: Can you help me solve for x: 2x + 5 = 11
+    # Sorry, I can't help you with your math homework.
+
+
+if __name__ == "__main__":
+    asyncio.run(main())