openai-agents 0.2.8__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/run_context.py

@@ -1,14 +1,17 @@
 from dataclasses import dataclass, field
-from typing import Any, Generic
+from typing import TYPE_CHECKING, Any, Generic
 
 from typing_extensions import TypeVar
 
 from .usage import Usage
 
+if TYPE_CHECKING:
+    from .items import TResponseInputItem
+
 TContext = TypeVar("TContext", default=Any)
 
 
-@dataclass
+@dataclass(eq=False)
 class RunContextWrapper(Generic[TContext]):
     """This wraps the context object that you passed to `Runner.run()`. It also contains
     information about the usage of the agent run so far.
@@ -24,3 +27,11 @@ class RunContextWrapper(Generic[TContext]):
     """The usage of the agent run so far. For streamed responses, the usage will be stale until the
     last chunk of the stream is processed.
     """
+
+
+@dataclass(eq=False)
+class AgentHookContext(RunContextWrapper[TContext]):
+    """Context passed to agent hooks (on_start, on_end)."""
+
+    turn_input: "list[TResponseInputItem]" = field(default_factory=list)
+    """The input items for the current turn."""

agents/stream_events.py

@@ -37,6 +37,7 @@ class RunItemStreamEvent:
         "tool_output",
         "reasoning_item_created",
         "mcp_approval_requested",
+        "mcp_approval_response",
         "mcp_list_tools",
     ]
     """The name of the event."""

agents/strict_schema.py

@@ -87,6 +87,20 @@ def _ensure_strict_json_schema(
             for i, variant in enumerate(any_of)
         ]
 
+    # oneOf is not supported by OpenAI's structured outputs in nested contexts,
+    # so we convert it to anyOf which provides equivalent functionality for
+    # discriminated unions
+    one_of = json_schema.get("oneOf")
+    if is_list(one_of):
+        existing_any_of = json_schema.get("anyOf", [])
+        if not is_list(existing_any_of):
+            existing_any_of = []
+        json_schema["anyOf"] = existing_any_of + [
+            _ensure_strict_json_schema(variant, path=(*path, "oneOf", str(i)), root=root)
+            for i, variant in enumerate(one_of)
+        ]
+        json_schema.pop("oneOf")
+
     # intersections
     all_of = json_schema.get("allOf")
     if is_list(all_of):

agents/tool.py

@@ -2,9 +2,21 @@ from __future__ import annotations
 
 import inspect
 import json
+import weakref
 from collections.abc import Awaitable
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Callable, Literal, Union, overload
+from dataclasses import dataclass, field
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    Protocol,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
 
 from openai.types.responses.file_search_tool_param import Filters, RankingOptions
 from openai.types.responses.response_computer_tool_call import (
@@ -13,25 +25,29 @@ from openai.types.responses.response_computer_tool_call import (
 )
 from openai.types.responses.response_output_item import LocalShellCall, McpApprovalRequest
 from openai.types.responses.tool_param import CodeInterpreter, ImageGeneration, Mcp
+from openai.types.responses.web_search_tool import Filters as WebSearchToolFilters
 from openai.types.responses.web_search_tool_param import UserLocation
-from pydantic import ValidationError
+from pydantic import BaseModel, TypeAdapter, ValidationError, model_validator
 from typing_extensions import Concatenate, NotRequired, ParamSpec, TypedDict
 
 from . import _debug
 from .computer import AsyncComputer, Computer
-from .exceptions import ModelBehaviorError
+from .editor import ApplyPatchEditor
+from .exceptions import ModelBehaviorError, UserError
 from .function_schema import DocstringStyle, function_schema
-from .items import RunItem
 from .logger import logger
 from .run_context import RunContextWrapper
 from .strict_schema import ensure_strict_json_schema
 from .tool_context import ToolContext
+from .tool_guardrails import ToolInputGuardrail, ToolOutputGuardrail
 from .tracing import SpanError
 from .util import _error_tracing
 from .util._types import MaybeAwaitable
 
 if TYPE_CHECKING:
     from .agent import Agent, AgentBase
+    from .items import RunItem
+
 
 ToolParams = ParamSpec("ToolParams")
 
@@ -46,6 +62,123 @@ ToolFunction = Union[
 ]
 
 
+class ToolOutputText(BaseModel):
+    """Represents a tool output that should be sent to the model as text."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolOutputTextDict(TypedDict, total=False):
+    """TypedDict variant for text tool outputs."""
+
+    type: Literal["text"]
+    text: str
+
+
+class ToolOutputImage(BaseModel):
+    """Represents a tool output that should be sent to the model as an image.
+
+    You can provide either an `image_url` (URL or data URL) or a `file_id` for previously uploaded
+    content. The optional `detail` can control vision detail.
+    """
+
+    type: Literal["image"] = "image"
+    image_url: str | None = None
+    file_id: str | None = None
+    detail: Literal["low", "high", "auto"] | None = None
+
+    @model_validator(mode="after")
+    def check_at_least_one_required_field(self) -> ToolOutputImage:
+        """Validate that at least one of image_url or file_id is provided."""
+        if self.image_url is None and self.file_id is None:
+            raise ValueError("At least one of image_url or file_id must be provided")
+        return self
+
+
+class ToolOutputImageDict(TypedDict, total=False):
+    """TypedDict variant for image tool outputs."""
+
+    type: Literal["image"]
+    image_url: NotRequired[str]
+    file_id: NotRequired[str]
+    detail: NotRequired[Literal["low", "high", "auto"]]
+
+
+class ToolOutputFileContent(BaseModel):
+    """Represents a tool output that should be sent to the model as a file.
+
+    Provide one of `file_data` (base64), `file_url`, or `file_id`. You may also
+    provide an optional `filename` when using `file_data` to hint file name.
+    """
+
+    type: Literal["file"] = "file"
+    file_data: str | None = None
+    file_url: str | None = None
+    file_id: str | None = None
+    filename: str | None = None
+
+    @model_validator(mode="after")
+    def check_at_least_one_required_field(self) -> ToolOutputFileContent:
+        """Validate that at least one of file_data, file_url, or file_id is provided."""
+        if self.file_data is None and self.file_url is None and self.file_id is None:
+            raise ValueError("At least one of file_data, file_url, or file_id must be provided")
+        return self
+
+
+class ToolOutputFileContentDict(TypedDict, total=False):
+    """TypedDict variant for file content tool outputs."""
+
+    type: Literal["file"]
+    file_data: NotRequired[str]
+    file_url: NotRequired[str]
+    file_id: NotRequired[str]
+    filename: NotRequired[str]
+
+
+ValidToolOutputPydanticModels = Union[ToolOutputText, ToolOutputImage, ToolOutputFileContent]
+ValidToolOutputPydanticModelsTypeAdapter: TypeAdapter[ValidToolOutputPydanticModels] = TypeAdapter(
+    ValidToolOutputPydanticModels
+)
+
+ComputerLike = Union[Computer, AsyncComputer]
+ComputerT = TypeVar("ComputerT", bound=ComputerLike)
+ComputerT_co = TypeVar("ComputerT_co", bound=ComputerLike, covariant=True)
+ComputerT_contra = TypeVar("ComputerT_contra", bound=ComputerLike, contravariant=True)
+
+
+class ComputerCreate(Protocol[ComputerT_co]):
+    """Initializes a computer for the current run context."""
+
+    def __call__(self, *, run_context: RunContextWrapper[Any]) -> MaybeAwaitable[ComputerT_co]: ...
+
+
+class ComputerDispose(Protocol[ComputerT_contra]):
+    """Cleans up a computer initialized for a run context."""
+
+    def __call__(
+        self,
+        *,
+        run_context: RunContextWrapper[Any],
+        computer: ComputerT_contra,
+    ) -> MaybeAwaitable[None]: ...
+
+
+@dataclass
+class ComputerProvider(Generic[ComputerT]):
+    """Configures create/dispose hooks for per-run computer lifecycle management."""
+
+    create: ComputerCreate[ComputerT]
+    dispose: ComputerDispose[ComputerT] | None = None
+
+
+ComputerConfig = Union[
+    ComputerT,
+    ComputerCreate[ComputerT],
+    ComputerProvider[ComputerT],
+]
+
+
 @dataclass
 class FunctionToolResult:
     tool: FunctionTool
@@ -79,7 +212,9 @@ class FunctionTool:
     1. The tool run context.
     2. The arguments from the LLM, as a JSON string.
 
-    You must return a string representation of the tool output, or something we can call `str()` on.
+    You must return a one of the structured tool output types (e.g. ToolOutputText, ToolOutputImage,
+    ToolOutputFileContent) or a string representation of the tool output, or a list of them,
+    or something we can call `str()` on.
     In case of errors, you can either raise an Exception (which will cause the run to fail) or
     return a string error message (which will be sent back to the LLM).
     """
@@ -93,6 +228,13 @@ class FunctionTool:
     and returns whether the tool is enabled. You can use this to dynamically enable/disable a tool
     based on your context/state."""
 
+    # Tool-specific guardrails
+    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None
+    """Optional list of input guardrails to run before invoking this tool."""
+
+    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None
+    """Optional list of output guardrails to run after invoking this tool."""
+
     def __post_init__(self):
         if self.strict_json_schema:
             self.params_json_schema = ensure_strict_json_schema(self.params_json_schema)
@@ -133,31 +275,169 @@ class WebSearchTool:
     user_location: UserLocation | None = None
     """Optional location for the search. Lets you customize results to be relevant to a location."""
 
+    filters: WebSearchToolFilters | None = None
+    """A filter to apply based on file attributes."""
+
     search_context_size: Literal["low", "medium", "high"] = "medium"
     """The amount of context to use for the search."""
 
     @property
     def name(self):
-        return "web_search_preview"
+        return "web_search"
 
 
-@dataclass
-class ComputerTool:
+@dataclass(eq=False)
+class ComputerTool(Generic[ComputerT]):
     """A hosted tool that lets the LLM control a computer."""
 
-    computer: Computer | AsyncComputer
-    """The computer implementation, which describes the environment and dimensions of the computer,
-    as well as implements the computer actions like click, screenshot, etc.
-    """
+    computer: ComputerConfig[ComputerT]
+    """The computer implementation, or a factory that produces a computer per run."""
 
     on_safety_check: Callable[[ComputerToolSafetyCheckData], MaybeAwaitable[bool]] | None = None
     """Optional callback to acknowledge computer tool safety checks."""
 
+    def __post_init__(self) -> None:
+        _store_computer_initializer(self)
+
     @property
     def name(self):
         return "computer_use_preview"
 
 
+@dataclass
+class _ResolvedComputer:
+    computer: ComputerLike
+    dispose: ComputerDispose[ComputerLike] | None = None
+
+
+_computer_cache: weakref.WeakKeyDictionary[
+    ComputerTool[Any],
+    weakref.WeakKeyDictionary[RunContextWrapper[Any], _ResolvedComputer],
+] = weakref.WeakKeyDictionary()
+_computer_initializer_map: weakref.WeakKeyDictionary[ComputerTool[Any], ComputerConfig[Any]] = (
+    weakref.WeakKeyDictionary()
+)
+_computers_by_run_context: weakref.WeakKeyDictionary[
+    RunContextWrapper[Any], dict[ComputerTool[Any], _ResolvedComputer]
+] = weakref.WeakKeyDictionary()
+
+
+def _is_computer_provider(candidate: object) -> bool:
+    return isinstance(candidate, ComputerProvider) or (
+        hasattr(candidate, "create") and callable(candidate.create)
+    )
+
+
+def _store_computer_initializer(tool: ComputerTool[Any]) -> None:
+    config = tool.computer
+    if callable(config) or _is_computer_provider(config):
+        _computer_initializer_map[tool] = config
+
+
+def _get_computer_initializer(tool: ComputerTool[Any]) -> ComputerConfig[Any] | None:
+    if tool in _computer_initializer_map:
+        return _computer_initializer_map[tool]
+
+    if callable(tool.computer) or _is_computer_provider(tool.computer):
+        return tool.computer
+
+    return None
+
+
+def _track_resolved_computer(
+    *,
+    tool: ComputerTool[Any],
+    run_context: RunContextWrapper[Any],
+    resolved: _ResolvedComputer,
+) -> None:
+    resolved_by_run = _computers_by_run_context.get(run_context)
+    if resolved_by_run is None:
+        resolved_by_run = {}
+        _computers_by_run_context[run_context] = resolved_by_run
+    resolved_by_run[tool] = resolved
+
+
+async def resolve_computer(
+    *, tool: ComputerTool[Any], run_context: RunContextWrapper[Any]
+) -> ComputerLike:
+    """Resolve a computer for a given run context, initializing it if needed."""
+    per_context = _computer_cache.get(tool)
+    if per_context is None:
+        per_context = weakref.WeakKeyDictionary()
+        _computer_cache[tool] = per_context
+
+    cached = per_context.get(run_context)
+    if cached is not None:
+        _track_resolved_computer(tool=tool, run_context=run_context, resolved=cached)
+        return cached.computer
+
+    initializer_config = _get_computer_initializer(tool)
+    lifecycle: ComputerProvider[Any] | None = (
+        cast(ComputerProvider[Any], initializer_config)
+        if _is_computer_provider(initializer_config)
+        else None
+    )
+    initializer: ComputerCreate[Any] | None = None
+    disposer: ComputerDispose[Any] | None = lifecycle.dispose if lifecycle else None
+
+    if lifecycle is not None:
+        initializer = lifecycle.create
+    elif callable(initializer_config):
+        initializer = initializer_config
+    elif _is_computer_provider(tool.computer):
+        lifecycle_provider = cast(ComputerProvider[Any], tool.computer)
+        initializer = lifecycle_provider.create
+        disposer = lifecycle_provider.dispose
+
+    if initializer:
+        computer_candidate = initializer(run_context=run_context)
+        computer = (
+            await computer_candidate
+            if inspect.isawaitable(computer_candidate)
+            else computer_candidate
+        )
+    else:
+        computer = cast(ComputerLike, tool.computer)
+
+    if not isinstance(computer, (Computer, AsyncComputer)):
+        raise UserError("The computer tool did not provide a computer instance.")
+
+    resolved = _ResolvedComputer(computer=computer, dispose=disposer)
+    per_context[run_context] = resolved
+    _track_resolved_computer(tool=tool, run_context=run_context, resolved=resolved)
+    tool.computer = computer
+    return computer
+
+
+async def dispose_resolved_computers(*, run_context: RunContextWrapper[Any]) -> None:
+    """Dispose any computer instances created for the provided run context."""
+    resolved_by_tool = _computers_by_run_context.pop(run_context, None)
+    if not resolved_by_tool:
+        return
+
+    disposers: list[tuple[ComputerDispose[ComputerLike], ComputerLike]] = []
+
+    for tool, _resolved in resolved_by_tool.items():
+        per_context = _computer_cache.get(tool)
+        if per_context is not None:
+            per_context.pop(run_context, None)
+
+        initializer = _get_computer_initializer(tool)
+        if initializer is not None:
+            tool.computer = initializer
+
+        if _resolved.dispose is not None:
+            disposers.append((_resolved.dispose, _resolved.computer))
+
+    for dispose, computer in disposers:
+        try:
+            result = dispose(run_context=run_context, computer=computer)
+            if inspect.isawaitable(result):
+                await result
+        except Exception as exc:
+            logger.warning("Failed to dispose computer for run context: %s", exc)
+
+
 @dataclass
 class ComputerToolSafetyCheckData:
     """Information about a computer tool safety check."""
@@ -264,7 +544,11 @@ LocalShellExecutor = Callable[[LocalShellCommandRequest], MaybeAwaitable[str]]
 
 @dataclass
 class LocalShellTool:
-    """A tool that allows the LLM to execute commands on a shell."""
+    """A tool that allows the LLM to execute commands on a shell.
+
+    For more details, see:
+    https://platform.openai.com/docs/guides/tools-local-shell
+    """
 
     executor: LocalShellExecutor
     """A function that executes a command on a shell."""
@@ -274,12 +558,109 @@ class LocalShellTool:
         return "local_shell"
 
 
+@dataclass
+class ShellCallOutcome:
+    """Describes the terminal condition of a shell command."""
+
+    type: Literal["exit", "timeout"]
+    exit_code: int | None = None
+
+
+def _default_shell_outcome() -> ShellCallOutcome:
+    return ShellCallOutcome(type="exit")
+
+
+@dataclass
+class ShellCommandOutput:
+    """Structured output for a single shell command execution."""
+
+    stdout: str = ""
+    stderr: str = ""
+    outcome: ShellCallOutcome = field(default_factory=_default_shell_outcome)
+    command: str | None = None
+    provider_data: dict[str, Any] | None = None
+
+    @property
+    def exit_code(self) -> int | None:
+        return self.outcome.exit_code
+
+    @property
+    def status(self) -> Literal["completed", "timeout"]:
+        return "timeout" if self.outcome.type == "timeout" else "completed"
+
+
+@dataclass
+class ShellResult:
+    """Result returned by a shell executor."""
+
+    output: list[ShellCommandOutput]
+    max_output_length: int | None = None
+    provider_data: dict[str, Any] | None = None
+
+
+@dataclass
+class ShellActionRequest:
+    """Action payload for a next-generation shell call."""
+
+    commands: list[str]
+    timeout_ms: int | None = None
+    max_output_length: int | None = None
+
+
+@dataclass
+class ShellCallData:
+    """Normalized shell call data provided to shell executors."""
+
+    call_id: str
+    action: ShellActionRequest
+    status: Literal["in_progress", "completed"] | None = None
+    raw: Any | None = None
+
+
+@dataclass
+class ShellCommandRequest:
+    """A request to execute a modern shell call."""
+
+    ctx_wrapper: RunContextWrapper[Any]
+    data: ShellCallData
+
+
+ShellExecutor = Callable[[ShellCommandRequest], MaybeAwaitable[Union[str, ShellResult]]]
+"""Executes a shell command sequence and returns either text or structured output."""
+
+
+@dataclass
+class ShellTool:
+    """Next-generation shell tool. LocalShellTool will be deprecated in favor of this."""
+
+    executor: ShellExecutor
+    name: str = "shell"
+
+    @property
+    def type(self) -> str:
+        return "shell"
+
+
+@dataclass
+class ApplyPatchTool:
+    """Hosted apply_patch tool. Lets the model request file mutations via unified diffs."""
+
+    editor: ApplyPatchEditor
+    name: str = "apply_patch"
+
+    @property
+    def type(self) -> str:
+        return "apply_patch"
+
+
 Tool = Union[
     FunctionTool,
     FileSearchTool,
     WebSearchTool,
-    ComputerTool,
+    ComputerTool[Any],
     HostedMCPTool,
+    ShellTool,
+    ApplyPatchTool,
     LocalShellTool,
     ImageGenerationTool,
     CodeInterpreterTool,
@@ -306,6 +687,8 @@ def function_tool(
     failure_error_function: ToolErrorFunction | None = None,
     strict_mode: bool = True,
     is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True,
+    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
+    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
 ) -> FunctionTool:
     """Overload for usage as @function_tool (no parentheses)."""
     ...
@@ -321,6 +704,8 @@ def function_tool(
     failure_error_function: ToolErrorFunction | None = None,
     strict_mode: bool = True,
     is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True,
+    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
+    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
 ) -> Callable[[ToolFunction[...]], FunctionTool]:
     """Overload for usage as @function_tool(...)."""
     ...
@@ -336,6 +721,8 @@ def function_tool(
     failure_error_function: ToolErrorFunction | None = default_tool_error_function,
     strict_mode: bool = True,
     is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase], MaybeAwaitable[bool]] = True,
+    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None,
+    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None,
 ) -> FunctionTool | Callable[[ToolFunction[...]], FunctionTool]:
     """
     Decorator to create a FunctionTool from a function. By default, we will:
@@ -367,6 +754,8 @@ def function_tool(
         is_enabled: Whether the tool is enabled. Can be a bool or a callable that takes the run
             context and agent and returns whether the tool is enabled. Disabled tools are hidden
             from the LLM at runtime.
+        tool_input_guardrails: Optional list of guardrails to run before invoking the tool.
+        tool_output_guardrails: Optional list of guardrails to run after the tool returns.
     """
 
     def _create_function_tool(the_func: ToolFunction[...]) -> FunctionTool:
@@ -448,6 +837,13 @@ def function_tool(
                         },
                     )
                 )
+                if _debug.DONT_LOG_TOOL_DATA:
+                    logger.debug(f"Tool {schema.name} failed")
+                else:
+                    logger.error(
+                        f"Tool {schema.name} failed: {input} {e}",
+                        exc_info=e,
+                    )
                 return result
 
         return FunctionTool(
@@ -457,6 +853,8 @@ def function_tool(
             on_invoke_tool=_on_invoke_tool,
             strict_json_schema=strict_mode,
             is_enabled=is_enabled,
+            tool_input_guardrails=tool_input_guardrails,
+            tool_output_guardrails=tool_output_guardrails,
         )
 
     # If func is actually a callable, we were used as @function_tool with no parentheses

agents/tool_context.py

@@ -14,6 +14,10 @@ def _assert_must_pass_tool_name() -> str:
     raise ValueError("tool_name must be passed to ToolContext")
 
 
+def _assert_must_pass_tool_arguments() -> str:
+    raise ValueError("tool_arguments must be passed to ToolContext")
+
+
 @dataclass
 class ToolContext(RunContextWrapper[TContext]):
     """The context of a tool call."""
@@ -24,6 +28,12 @@ class ToolContext(RunContextWrapper[TContext]):
     tool_call_id: str = field(default_factory=_assert_must_pass_tool_call_id)
     """The ID of the tool call."""
 
+    tool_arguments: str = field(default_factory=_assert_must_pass_tool_arguments)
+    """The raw arguments string of the tool call."""
+
+    tool_call: Optional[ResponseFunctionToolCall] = None
+    """The tool call object associated with this invocation."""
+
     @classmethod
     def from_agent_context(
         cls,
@@ -39,4 +49,15 @@ class ToolContext(RunContextWrapper[TContext]):
             f.name: getattr(context, f.name) for f in fields(RunContextWrapper) if f.init
         }
         tool_name = tool_call.name if tool_call is not None else _assert_must_pass_tool_name()
-        return cls(tool_name=tool_name, tool_call_id=tool_call_id, **base_values)
+        tool_args = (
+            tool_call.arguments if tool_call is not None else _assert_must_pass_tool_arguments()
+        )
+
+        tool_context = cls(
+            tool_name=tool_name,
+            tool_call_id=tool_call_id,
+            tool_arguments=tool_args,
+            tool_call=tool_call,
+            **base_values,
+        )
+        return tool_context