openai-agents 0.3.2__py3-none-any.whl → 0.3.3__py3-none-any.whl

agents/tool_guardrails.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, overload
+
+from typing_extensions import TypedDict, TypeVar
+
+from .exceptions import UserError
+from .tool_context import ToolContext
+from .util._types import MaybeAwaitable
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+@dataclass
+class ToolInputGuardrailResult:
+    """The result of a tool input guardrail run."""
+
+    guardrail: ToolInputGuardrail[Any]
+    """The guardrail that was run."""
+
+    output: ToolGuardrailFunctionOutput
+    """The output of the guardrail function."""
+
+
+@dataclass
+class ToolOutputGuardrailResult:
+    """The result of a tool output guardrail run."""
+
+    guardrail: ToolOutputGuardrail[Any]
+    """The guardrail that was run."""
+
+    output: ToolGuardrailFunctionOutput
+    """The output of the guardrail function."""
+
+
+class RejectContentBehavior(TypedDict):
+    """Rejects the tool call/output but continues execution with a message to the model."""
+
+    type: Literal["reject_content"]
+    message: str
+
+
+class RaiseExceptionBehavior(TypedDict):
+    """Raises an exception to halt execution."""
+
+    type: Literal["raise_exception"]
+
+
+class AllowBehavior(TypedDict):
+    """Allows normal tool execution to continue."""
+
+    type: Literal["allow"]
+
+
+@dataclass
+class ToolGuardrailFunctionOutput:
+    """The output of a tool guardrail function."""
+
+    output_info: Any
+    """
+    Optional data about checks performed. For example, the guardrail could include
+    information about the checks it performed and granular results.
+    """
+
+    behavior: RejectContentBehavior | RaiseExceptionBehavior | AllowBehavior = field(
+        default_factory=lambda: AllowBehavior(type="allow")
+    )
+    """
+    Defines how the system should respond when this guardrail result is processed.
+    - allow: Allow normal tool execution to continue without interference (default)
+    - reject_content: Reject the tool call/output but continue execution with a message to the model
+    - raise_exception: Halt execution by raising a ToolGuardrailTripwireTriggered exception
+    """
+
+    @classmethod
+    def allow(cls, output_info: Any = None) -> ToolGuardrailFunctionOutput:
+        """Create a guardrail output that allows the tool execution to continue normally.
+
+        Args:
+            output_info: Optional data about checks performed.
+
+        Returns:
+            ToolGuardrailFunctionOutput configured to allow normal execution.
+        """
+        return cls(output_info=output_info, behavior=AllowBehavior(type="allow"))
+
+    @classmethod
+    def reject_content(cls, message: str, output_info: Any = None) -> ToolGuardrailFunctionOutput:
+        """Create a guardrail output that rejects the tool call/output but continues execution.
+
+        Args:
+            message: Message to send to the model instead of the tool result.
+            output_info: Optional data about checks performed.
+
+        Returns:
+            ToolGuardrailFunctionOutput configured to reject the content.
+        """
+        return cls(
+            output_info=output_info,
+            behavior=RejectContentBehavior(type="reject_content", message=message),
+        )
+
+    @classmethod
+    def raise_exception(cls, output_info: Any = None) -> ToolGuardrailFunctionOutput:
+        """Create a guardrail output that raises an exception to halt execution.
+
+        Args:
+            output_info: Optional data about checks performed.
+
+        Returns:
+            ToolGuardrailFunctionOutput configured to raise an exception.
+        """
+        return cls(output_info=output_info, behavior=RaiseExceptionBehavior(type="raise_exception"))
+
+
+@dataclass
+class ToolInputGuardrailData:
+    """Input data passed to a tool input guardrail function."""
+
+    context: ToolContext[Any]
+    """
+    The tool context containing information about the current tool execution.
+    """
+
+    agent: Agent[Any]
+    """
+    The agent that is executing the tool.
+    """
+
+
+@dataclass
+class ToolOutputGuardrailData(ToolInputGuardrailData):
+    """Input data passed to a tool output guardrail function.
+
+    Extends input data with the tool's output.
+    """
+
+    output: Any
+    """
+    The output produced by the tool function.
+    """
+
+
+TContext_co = TypeVar("TContext_co", bound=Any, covariant=True)
+
+
+@dataclass
+class ToolInputGuardrail(Generic[TContext_co]):
+    """A guardrail that runs before a function tool is invoked."""
+
+    guardrail_function: Callable[
+        [ToolInputGuardrailData], MaybeAwaitable[ToolGuardrailFunctionOutput]
+    ]
+    """
+    The function that implements the guardrail logic.
+    """
+
+    name: str | None = None
+    """
+    Optional name for the guardrail. If not provided, uses the function name.
+    """
+
+    def get_name(self) -> str:
+        return self.name or self.guardrail_function.__name__
+
+    async def run(self, data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
+        if not callable(self.guardrail_function):
+            raise UserError(f"Guardrail function must be callable, got {self.guardrail_function}")
+
+        result = self.guardrail_function(data)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+
+@dataclass
+class ToolOutputGuardrail(Generic[TContext_co]):
+    """A guardrail that runs after a function tool is invoked."""
+
+    guardrail_function: Callable[
+        [ToolOutputGuardrailData], MaybeAwaitable[ToolGuardrailFunctionOutput]
+    ]
+    """
+    The function that implements the guardrail logic.
+    """
+
+    name: str | None = None
+    """
+    Optional name for the guardrail. If not provided, uses the function name.
+    """
+
+    def get_name(self) -> str:
+        return self.name or self.guardrail_function.__name__
+
+    async def run(self, data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
+        if not callable(self.guardrail_function):
+            raise UserError(f"Guardrail function must be callable, got {self.guardrail_function}")
+
+        result = self.guardrail_function(data)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+
+# Decorators
+_ToolInputFuncSync = Callable[[ToolInputGuardrailData], ToolGuardrailFunctionOutput]
+_ToolInputFuncAsync = Callable[[ToolInputGuardrailData], Awaitable[ToolGuardrailFunctionOutput]]
+
+
+@overload
+def tool_input_guardrail(func: _ToolInputFuncSync): ...
+
+
+@overload
+def tool_input_guardrail(func: _ToolInputFuncAsync): ...
+
+
+@overload
+def tool_input_guardrail(
+    *, name: str | None = None
+) -> Callable[[_ToolInputFuncSync | _ToolInputFuncAsync], ToolInputGuardrail[Any]]: ...
+
+
+def tool_input_guardrail(
+    func: _ToolInputFuncSync | _ToolInputFuncAsync | None = None,
+    *,
+    name: str | None = None,
+) -> (
+    ToolInputGuardrail[Any]
+    | Callable[[_ToolInputFuncSync | _ToolInputFuncAsync], ToolInputGuardrail[Any]]
+):
+    """Decorator to create a ToolInputGuardrail from a function."""
+
+    def decorator(f: _ToolInputFuncSync | _ToolInputFuncAsync) -> ToolInputGuardrail[Any]:
+        return ToolInputGuardrail(guardrail_function=f, name=name or f.__name__)
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+_ToolOutputFuncSync = Callable[[ToolOutputGuardrailData], ToolGuardrailFunctionOutput]
+_ToolOutputFuncAsync = Callable[[ToolOutputGuardrailData], Awaitable[ToolGuardrailFunctionOutput]]
+
+
+@overload
+def tool_output_guardrail(func: _ToolOutputFuncSync): ...
+
+
+@overload
+def tool_output_guardrail(func: _ToolOutputFuncAsync): ...
+
+
+@overload
+def tool_output_guardrail(
+    *, name: str | None = None
+) -> Callable[[_ToolOutputFuncSync | _ToolOutputFuncAsync], ToolOutputGuardrail[Any]]: ...
+
+
+def tool_output_guardrail(
+    func: _ToolOutputFuncSync | _ToolOutputFuncAsync | None = None,
+    *,
+    name: str | None = None,
+) -> (
+    ToolOutputGuardrail[Any]
+    | Callable[[_ToolOutputFuncSync | _ToolOutputFuncAsync], ToolOutputGuardrail[Any]]
+):
+    """Decorator to create a ToolOutputGuardrail from a function."""
+
+    def decorator(f: _ToolOutputFuncSync | _ToolOutputFuncAsync) -> ToolOutputGuardrail[Any]:
+        return ToolOutputGuardrail(guardrail_function=f, name=name or f.__name__)
+
+    if func is not None:
+        return decorator(func)
+    return decorator

{openai_agents-0.3.2.dist-info → openai_agents-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.3.2
+Version: 0.3.3
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -32,6 +32,8 @@ Provides-Extra: litellm
 Requires-Dist: litellm<2,>=1.67.4.post1; extra == 'litellm'
 Provides-Extra: realtime
 Requires-Dist: websockets<16,>=15.0; extra == 'realtime'
+Provides-Extra: redis
+Requires-Dist: redis>=6.4.0; extra == 'redis'
 Provides-Extra: sqlalchemy
 Requires-Dist: asyncpg>=0.29.0; extra == 'sqlalchemy'
 Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
@@ -75,6 +77,8 @@ pip install openai-agents
 
 For voice support, install with the optional `voice` group: `pip install 'openai-agents[voice]'`.
 
+For Redis session support, install with the optional `redis` group: `pip install 'openai-agents[redis]'`.
+
 ### uv
 
 If you're familiar with [uv](https://docs.astral.sh/uv/), using the tool would be even similar:
@@ -86,6 +90,8 @@ uv add openai-agents
 
 For voice support, install with the optional `voice` group: `uv add 'openai-agents[voice]'`.
 
+For Redis session support, install with the optional `redis` group: `uv add 'openai-agents[redis]'`.
+
 ## Hello world example
 
 ```python
@@ -255,8 +261,13 @@ print(result.final_output)  # "Approximately 39 million"
 ```python
 from agents import Agent, Runner, SQLiteSession
 
-# Custom SQLite database file
+# SQLite - file-based or in-memory database
 session = SQLiteSession("user_123", "conversations.db")
+
+# Redis - for scalable, distributed deployments
+# from agents.extensions.memory import RedisSession
+# session = RedisSession.from_url("user_123", url="redis://localhost:6379/0")
+
 agent = Agent(name="Assistant")
 
 # Different session IDs maintain separate conversation histories

{openai_agents-0.3.2.dist-info → openai_agents-0.3.3.dist-info}/RECORD

@@ -1,11 +1,11 @@
-agents/__init__.py,sha256=Kr6-8HItTfnz5HFS9x7PVD99v_Lu9VxlE27UjX3BH8M,8000
+agents/__init__.py,sha256=ckLaHgy95UvhXWWfqYUW0uBO1PKMNcf3GUqnRBDifIs,8728
 agents/_config.py,sha256=ANrM7GP2VSQehDkMc9qocxkUlPwqU-i5sieMJyEwxpM,796
 agents/_debug.py,sha256=dRe2dUlA9bCLp6f8bAdiX7JfGyJuHyS_DRdW0kZshl0,856
-agents/_run_impl.py,sha256=9mW1kh9_WC9GvTgo4GyroMhthzaH-qKpTKIZxE15kEE,46352
+agents/_run_impl.py,sha256=hGkagVDsrh4XU-eOtoopHDXDZRisGPHE3ddmKiwswF0,54690
 agents/agent.py,sha256=P5AzwKz3FiQJjzfautF0R9JzxkTXEeItcEkJgn8z5mM,19832
 agents/agent_output.py,sha256=teTFK8unUN3esXhmEBO0bQGYQm1Axd5rYleDt9TFDgw,7153
 agents/computer.py,sha256=XD44UgiUWSfniv-xKwwDP6wFKVwBiZkpaL1hO-0-7ZA,2516
-agents/exceptions.py,sha256=NHMdHE0cZ6AdA6UgUylTzVHAX05Ol1CkO814a0FdZcs,2862
+agents/exceptions.py,sha256=roJsYttB5i7FQlzRQNg8QSVdALZFz5u7kUeVvJdaitE,4156
 agents/function_schema.py,sha256=njtbLt44DOkIU0a0U8TeDNEx-iQZU8oohwy3k7-k4A8,14855
 agents/guardrail.py,sha256=7P-kd9rKPhgB8rtI31MCV5ho4ZrEaNCQxHvE8IK3EOk,9582
 agents/handoffs.py,sha256=kDTM3nj3E_0khiJPMJAIN00gektMTRNbaYSbc5ZCnBM,11411
@@ -16,24 +16,27 @@ agents/model_settings.py,sha256=7Ul-Xg-aNVXIbK6V4Rm2t5EEfNR0tsy_A9ac_wFqLLk,6828
 agents/prompts.py,sha256=Ss5y_7s2HFcRAOAKu4WTxQszs5ybI8TfbxgEYdnj9sg,2231
 agents/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 agents/repl.py,sha256=NX0BE5YDnmGQ2rdQsmLm3CKkQZ5m4GC95xXmUsAXJVs,2539
-agents/result.py,sha256=Ykf5V-DyufMgLEi2YhKFecMr_G8XDEiL-aIBBRcL5Zg,12050
-agents/run.py,sha256=RyaFenUly9XXzdB70FAW2p_qpxSbavv9B5B_KdSdSk0,65257
+agents/result.py,sha256=i3AtgXMRDiqPOnaflZrusVT9pS98kC8atlrRFKEgk20,12428
+agents/run.py,sha256=Pu1OBFz-h8MKt03cytKsgsXoHX4pfT7nZnIwxxaf178,66030
 agents/run_context.py,sha256=vuSUQM8O4CLensQY27-22fOqECnw7yvwL9U3WO8b_bk,851
 agents/stream_events.py,sha256=VFyTu-DT3ZMnHLtMbg-X_lxec0doQxNfx-hVxLB0BpI,1700
 agents/strict_schema.py,sha256=_KuEJkglmq-Fj3HSeYP4WqTvqrxbSKu6gezfz5Brhh0,5775
-agents/tool.py,sha256=mk4mKWy-K2eHIygLTNZf447oyIRqLz8Ex1R-wEQ9vS8,17023
+agents/tool.py,sha256=RqEMkX47-LyHDBINyL3iHP7cOsf4DwlNT70S-X4mE9I,17425
 agents/tool_context.py,sha256=g53mgaeX7kCwPaIReiwuUejD8qC7QejMS-F3Wnkuhhg,1866
+agents/tool_guardrails.py,sha256=2uXEr_R5AWy9NHtBjd7G7upc3uZSuoP86Hfsc-qTadM,8344
 agents/usage.py,sha256=Tb5udGd3DPgD0JBdRD8fDctTE4M-zKML5uRn8ZG1yBc,1675
 agents/version.py,sha256=_1knUwzSK-HUeZTpRUkk6Z-CIcurqXuEplbV5TLJ08E,230
 agents/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agents/extensions/handoff_filters.py,sha256=CS-k7TGCtT8TW3GeXb04OoFBXKdjg8-85QXswWAYBmI,2095
 agents/extensions/handoff_prompt.py,sha256=oGWN0uNh3Z1L7E-Ev2up8W084fFrDNOsLDy7P6bcmic,1006
 agents/extensions/visualization.py,sha256=sf9D_C-HMwkbWdZccTZvvMPRy_NSiwbm48tRJlESQBI,5144
-agents/extensions/memory/__init__.py,sha256=m2LezCvjjo1PgbdA-grEMCQBnzVKuTpaxfQgioJbnZg,1459
+agents/extensions/memory/__init__.py,sha256=CJqBzkU6knvDKHhM7H4VrFw9DygLuZikgKJqcLKji2Y,2233
+agents/extensions/memory/advanced_sqlite_session.py,sha256=rCrXM878foAuBN-rN2fibP2GHs-1hTtRx-TQcDKIfGI,52883
 agents/extensions/memory/encrypt_session.py,sha256=PVnZIEj50bjUq16OLnMKrbZiinLkrVpamPPEw8RnUCA,6485
+agents/extensions/memory/redis_session.py,sha256=JwXY6zUTMgq9bRezlyFZ4Tze7DO7T0hioTc23qjSHjU,9838
 agents/extensions/memory/sqlalchemy_session.py,sha256=H0aykdB4lUikmzKgwWQqI1PSYZBvHA4TDnaj9rP4HDI,11583
 agents/extensions/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-agents/extensions/models/litellm_model.py,sha256=N4EVgii2d1oVvYQKptJ0QdjelfgujRm9kfPW_T5sBXg,18031
+agents/extensions/models/litellm_model.py,sha256=FM4wIouSWIqXHoksZodoWsMLYTF4CT3j0IeFSWf-8oo,23642
 agents/extensions/models/litellm_provider.py,sha256=ZHgh1nMoEvA7NpawkzLh3JDuDFtwXUV94Rs7UrwWqAk,1083
 agents/mcp/__init__.py,sha256=yHmmYlrmEHzUas1inRLKL2iPqbb_-107G3gKe_tyg4I,750
 agents/mcp/server.py,sha256=4T58xiWCLiCm6JoUy_3jYWz5A8ZNsHiV1hIxjahoedU,26624
@@ -45,7 +48,7 @@ agents/memory/sqlite_session.py,sha256=6HGzSL70mQgutITIPZUC2x2Qtj6U4hXiZTceu3Da7
 agents/memory/util.py,sha256=ZAHOrNVA36xICFzuNgHgEA1_s_oEMO6Wsu6-EecY8JU,586
 agents/models/__init__.py,sha256=E0XVqWayVAsFqxucDLBW30siaqfNQsVrAnfidG_C3ok,287
 agents/models/_openai_shared.py,sha256=4Ngwo2Fv2RXY61Pqck1cYPkSln2tDnb8Ai-ao4QG-iE,836
-agents/models/chatcmpl_converter.py,sha256=anhAfw_5fRO3JtGGSPFbX_A6TKW0t-dK6orIffvaUpU,24514
+agents/models/chatcmpl_converter.py,sha256=yPf8AbCm43hpkB37zd3gdPtD-wHdcCDQS9vSeAmBPk4,24748
 agents/models/chatcmpl_helpers.py,sha256=YC2krp_-uBgRCrCEImLjNvONTWRWfwLlPKHI4kBmNXE,1483
 agents/models/chatcmpl_stream_handler.py,sha256=r8nc-4hJg1plw87y24MD48O23xnfC_2gHKowtOYgO3M,28896
 agents/models/default_models.py,sha256=mlvBePn8H4UkHo7lN-wh7A3k2ciLgBUFKpROQxzdTfs,2098
@@ -105,7 +108,7 @@ agents/voice/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 agents/voice/models/openai_model_provider.py,sha256=Khn0uT-VhsEbe7_OhBMGFQzXNwL80gcWZyTHl3CaBII,3587
 agents/voice/models/openai_stt.py,sha256=eZ0dmX_uDywpR1H3Q2N5jrV7NK3bR9l2a1InWM3yegk,17151
 agents/voice/models/openai_tts.py,sha256=4KoLQuFDHKu5a1VTJlu9Nj3MHwMlrn9wfT_liJDJ2dw,1477
-openai_agents-0.3.2.dist-info/METADATA,sha256=LSs6G1M2jEDrXEGTP_S__4F5cmifoRvEMOJ7AZH4hMU,12462
-openai_agents-0.3.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-openai_agents-0.3.2.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
-openai_agents-0.3.2.dist-info/RECORD,,
+openai_agents-0.3.3.dist-info/METADATA,sha256=hFUaemXENkZOPW-c06PatiRUDp19Mx0yj8LQ74eyHOk,12933
+openai_agents-0.3.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openai_agents-0.3.3.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
+openai_agents-0.3.3.dist-info/RECORD,,