openai-agents 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

agents/run_context.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+from .usage import Usage
+
+TContext = TypeVar("TContext", default=Any)
+
+
+@dataclass
+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.
+
+    NOTE: Contexts are not passed to the LLM. They're a way to pass dependencies and data to code
+    you implement, like tool functions, callbacks, hooks, etc.
+    """
+
+    context: TContext
+    """The context object (or None), passed by you to `Runner.run()`"""
+
+    usage: Usage = field(default_factory=Usage)
+    """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.
+    """

agents/stream_events.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Union
+
+from typing_extensions import TypeAlias
+
+from .agent import Agent
+from .items import RunItem, TResponseStreamEvent
+
+
+@dataclass
+class RawResponsesStreamEvent:
+    """Streaming event from the LLM. These are 'raw' events, i.e. they are directly passed through
+    from the LLM.
+    """
+
+    data: TResponseStreamEvent
+    """The raw responses streaming event from the LLM."""
+
+    type: Literal["raw_response_event"] = "raw_response_event"
+    """The type of the event."""
+
+
+@dataclass
+class RunItemStreamEvent:
+    """Streaming events that wrap a `RunItem`. As the agent processes the LLM response, it will
+    generate these events for new messages, tool calls, tool outputs, handoffs, etc.
+    """
+
+    name: Literal[
+        "message_output_created",
+        "handoff_requested",
+        "handoff_occured",
+        "tool_called",
+        "tool_output",
+        "reasoning_item_created",
+    ]
+    """The name of the event."""
+
+    item: RunItem
+    """The item that was created."""
+
+    type: Literal["run_item_stream_event"] = "run_item_stream_event"
+
+
+@dataclass
+class AgentUpdatedStreamEvent:
+    """Event that notifies that there is a new agent running."""
+
+    new_agent: Agent[Any]
+    """The new agent."""
+
+    type: Literal["agent_updated_stream_event"] = "agent_updated_stream_event"
+
+
+StreamEvent: TypeAlias = Union[RawResponsesStreamEvent, RunItemStreamEvent, AgentUpdatedStreamEvent]
+"""A streaming event from an agent."""

agents/strict_schema.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from typing import Any
+
+from openai import NOT_GIVEN
+from typing_extensions import TypeGuard
+
+from .exceptions import UserError
+
+_EMPTY_SCHEMA = {
+    "additionalProperties": False,
+    "type": "object",
+    "properties": {},
+    "required": [],
+}
+
+
+def ensure_strict_json_schema(
+    schema: dict[str, Any],
+) -> dict[str, Any]:
+    """Mutates the given JSON schema to ensure it conforms to the `strict` standard
+    that the OpenAI API expects.
+    """
+    if schema == {}:
+        return _EMPTY_SCHEMA
+    return _ensure_strict_json_schema(schema, path=(), root=schema)
+
+
+# Adapted from https://github.com/openai/openai-python/blob/main/src/openai/lib/_pydantic.py
+def _ensure_strict_json_schema(
+    json_schema: object,
+    *,
+    path: tuple[str, ...],
+    root: dict[str, object],
+) -> dict[str, Any]:
+    if not is_dict(json_schema):
+        raise TypeError(f"Expected {json_schema} to be a dictionary; path={path}")
+
+    defs = json_schema.get("$defs")
+    if is_dict(defs):
+        for def_name, def_schema in defs.items():
+            _ensure_strict_json_schema(def_schema, path=(*path, "$defs", def_name), root=root)
+
+    definitions = json_schema.get("definitions")
+    if is_dict(definitions):
+        for definition_name, definition_schema in definitions.items():
+            _ensure_strict_json_schema(
+                definition_schema, path=(*path, "definitions", definition_name), root=root
+            )
+
+    typ = json_schema.get("type")
+    if typ == "object" and "additionalProperties" not in json_schema:
+        json_schema["additionalProperties"] = False
+    elif (
+        typ == "object"
+        and "additionalProperties" in json_schema
+        and json_schema["additionalProperties"] is True
+    ):
+        raise UserError(
+            "additionalProperties should not be set for object types. This could be because "
+            "you're using an older version of Pydantic, or because you configured additional "
+            "properties to be allowed. If you really need this, update the function or output tool "
+            "to not use a strict schema."
+        )
+
+    # object types
+    # { 'type': 'object', 'properties': { 'a':  {...} } }
+    properties = json_schema.get("properties")
+    if is_dict(properties):
+        json_schema["required"] = list(properties.keys())
+        json_schema["properties"] = {
+            key: _ensure_strict_json_schema(prop_schema, path=(*path, "properties", key), root=root)
+            for key, prop_schema in properties.items()
+        }
+
+    # arrays
+    # { 'type': 'array', 'items': {...} }
+    items = json_schema.get("items")
+    if is_dict(items):
+        json_schema["items"] = _ensure_strict_json_schema(items, path=(*path, "items"), root=root)
+
+    # unions
+    any_of = json_schema.get("anyOf")
+    if is_list(any_of):
+        json_schema["anyOf"] = [
+            _ensure_strict_json_schema(variant, path=(*path, "anyOf", str(i)), root=root)
+            for i, variant in enumerate(any_of)
+        ]
+
+    # intersections
+    all_of = json_schema.get("allOf")
+    if is_list(all_of):
+        if len(all_of) == 1:
+            json_schema.update(
+                _ensure_strict_json_schema(all_of[0], path=(*path, "allOf", "0"), root=root)
+            )
+            json_schema.pop("allOf")
+        else:
+            json_schema["allOf"] = [
+                _ensure_strict_json_schema(entry, path=(*path, "allOf", str(i)), root=root)
+                for i, entry in enumerate(all_of)
+            ]
+
+    # strip `None` defaults as there's no meaningful distinction here
+    # the schema will still be `nullable` and the model will default
+    # to using `None` anyway
+    if json_schema.get("default", NOT_GIVEN) is None:
+        json_schema.pop("default")
+
+    # we can't use `$ref`s if there are also other properties defined, e.g.
+    # `{"$ref": "...", "description": "my description"}`
+    #
+    # so we unravel the ref
+    # `{"type": "string", "description": "my description"}`
+    ref = json_schema.get("$ref")
+    if ref and has_more_than_n_keys(json_schema, 1):
+        assert isinstance(ref, str), f"Received non-string $ref - {ref}"
+
+        resolved = resolve_ref(root=root, ref=ref)
+        if not is_dict(resolved):
+            raise ValueError(
+                f"Expected `$ref: {ref}` to resolved to a dictionary but got {resolved}"
+            )
+
+        # properties from the json schema take priority over the ones on the `$ref`
+        json_schema.update({**resolved, **json_schema})
+        json_schema.pop("$ref")
+        # Since the schema expanded from `$ref` might not have `additionalProperties: false` applied
+        # we call `_ensure_strict_json_schema` again to fix the inlined schema and ensure it's valid
+        return _ensure_strict_json_schema(json_schema, path=path, root=root)
+
+    return json_schema
+
+
+def resolve_ref(*, root: dict[str, object], ref: str) -> object:
+    if not ref.startswith("#/"):
+        raise ValueError(f"Unexpected $ref format {ref!r}; Does not start with #/")
+
+    path = ref[2:].split("/")
+    resolved = root
+    for key in path:
+        value = resolved[key]
+        assert is_dict(value), (
+            f"encountered non-dictionary entry while resolving {ref} - {resolved}"
+        )
+        resolved = value
+
+    return resolved
+
+
+def is_dict(obj: object) -> TypeGuard[dict[str, object]]:
+    # just pretend that we know there are only `str` keys
+    # as that check is not worth the performance cost
+    return isinstance(obj, dict)
+
+
+def is_list(obj: object) -> TypeGuard[list[object]]:
+    return isinstance(obj, list)
+
+
+def has_more_than_n_keys(obj: dict[str, object], n: int) -> bool:
+    i = 0
+    for _ in obj.keys():
+        i += 1
+        if i > n:
+            return True
+    return False

agents/tool.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from typing import Any, Callable, Literal, Union, overload
+
+from openai.types.responses.file_search_tool_param import Filters, RankingOptions
+from openai.types.responses.web_search_tool_param import UserLocation
+from pydantic import ValidationError
+from typing_extensions import Concatenate, ParamSpec
+
+from . import _debug, _utils
+from ._utils import MaybeAwaitable
+from .computer import AsyncComputer, Computer
+from .exceptions import ModelBehaviorError
+from .function_schema import DocstringStyle, function_schema
+from .logger import logger
+from .run_context import RunContextWrapper
+from .tracing import SpanError
+
+ToolParams = ParamSpec("ToolParams")
+
+ToolFunctionWithoutContext = Callable[ToolParams, Any]
+ToolFunctionWithContext = Callable[Concatenate[RunContextWrapper[Any], ToolParams], Any]
+
+ToolFunction = Union[ToolFunctionWithoutContext[ToolParams], ToolFunctionWithContext[ToolParams]]
+
+
+@dataclass
+class FunctionTool:
+    """A tool that wraps a function. In most cases, you should use  the `function_tool` helpers to
+    create a FunctionTool, as they let you easily wrap a Python function.
+    """
+
+    name: str
+    """The name of the tool, as shown to the LLM. Generally the name of the function."""
+
+    description: str
+    """A description of the tool, as shown to the LLM."""
+
+    params_json_schema: dict[str, Any]
+    """The JSON schema for the tool's parameters."""
+
+    on_invoke_tool: Callable[[RunContextWrapper[Any], str], Awaitable[str]]
+    """A function that invokes the tool with the given context and parameters. The params passed
+    are:
+    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. 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).
+    """
+
+    strict_json_schema: bool = True
+    """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True,
+    as it increases the likelihood of correct JSON input."""
+
+
+@dataclass
+class FileSearchTool:
+    """A hosted tool that lets the LLM search through a vector store. Currently only supported with
+    OpenAI models, using the Responses API.
+    """
+
+    vector_store_ids: list[str]
+    """The IDs of the vector stores to search."""
+
+    max_num_results: int | None = None
+    """The maximum number of results to return."""
+
+    include_search_results: bool = False
+    """Whether to include the search results in the output produced by the LLM."""
+
+    ranking_options: RankingOptions | None = None
+    """Ranking options for search."""
+
+    filters: Filters | None = None
+    """A filter to apply based on file attributes."""
+
+    @property
+    def name(self):
+        return "file_search"
+
+
+@dataclass
+class WebSearchTool:
+    """A hosted tool that lets the LLM search the web. Currently only supported with OpenAI models,
+    using the Responses API.
+    """
+
+    user_location: UserLocation | None = None
+    """Optional location for the search. Lets you customize results to be relevant to a location."""
+
+    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"
+
+
+@dataclass
+class ComputerTool:
+    """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.
+    """
+
+    @property
+    def name(self):
+        return "computer_use_preview"
+
+
+Tool = Union[FunctionTool, FileSearchTool, WebSearchTool, ComputerTool]
+"""A tool that can be used in an agent."""
+
+
+def default_tool_error_function(ctx: RunContextWrapper[Any], error: Exception) -> str:
+    """The default tool error function, which just returns a generic error message."""
+    return f"An error occurred while running the tool. Please try again. Error: {str(error)}"
+
+
+ToolErrorFunction = Callable[[RunContextWrapper[Any], Exception], MaybeAwaitable[str]]
+
+
+@overload
+def function_tool(
+    func: ToolFunction[...],
+    *,
+    name_override: str | None = None,
+    description_override: str | None = None,
+    docstring_style: DocstringStyle | None = None,
+    use_docstring_info: bool = True,
+    failure_error_function: ToolErrorFunction | None = None,
+) -> FunctionTool:
+    """Overload for usage as @function_tool (no parentheses)."""
+    ...
+
+
+@overload
+def function_tool(
+    *,
+    name_override: str | None = None,
+    description_override: str | None = None,
+    docstring_style: DocstringStyle | None = None,
+    use_docstring_info: bool = True,
+    failure_error_function: ToolErrorFunction | None = None,
+) -> Callable[[ToolFunction[...]], FunctionTool]:
+    """Overload for usage as @function_tool(...)."""
+    ...
+
+
+def function_tool(
+    func: ToolFunction[...] | None = None,
+    *,
+    name_override: str | None = None,
+    description_override: str | None = None,
+    docstring_style: DocstringStyle | None = None,
+    use_docstring_info: bool = True,
+    failure_error_function: ToolErrorFunction | None = default_tool_error_function,
+) -> FunctionTool | Callable[[ToolFunction[...]], FunctionTool]:
+    """
+    Decorator to create a FunctionTool from a function. By default, we will:
+    1. Parse the function signature to create a JSON schema for the tool's parameters.
+    2. Use the function's docstring to populate the tool's description.
+    3. Use the function's docstring to populate argument descriptions.
+    The docstring style is detected automatically, but you can override it.
+
+    If the function takes a `RunContextWrapper` as the first argument, it *must* match the
+    context type of the agent that uses the tool.
+
+    Args:
+        func: The function to wrap.
+        name_override: If provided, use this name for the tool instead of the function's name.
+        description_override: If provided, use this description for the tool instead of the
+            function's docstring.
+        docstring_style: If provided, use this style for the tool's docstring. If not provided,
+            we will attempt to auto-detect the style.
+        use_docstring_info: If True, use the function's docstring to populate the tool's
+            description and argument descriptions.
+        failure_error_function: If provided, use this function to generate an error message when
+            the tool call fails. The error message is sent to the LLM. If you pass None, then no
+            error message will be sent and instead an Exception will be raised.
+    """
+
+    def _create_function_tool(the_func: ToolFunction[...]) -> FunctionTool:
+        schema = function_schema(
+            func=the_func,
+            name_override=name_override,
+            description_override=description_override,
+            docstring_style=docstring_style,
+            use_docstring_info=use_docstring_info,
+        )
+
+        async def _on_invoke_tool_impl(ctx: RunContextWrapper[Any], input: str) -> str:
+            try:
+                json_data: dict[str, Any] = json.loads(input) if input else {}
+            except Exception as e:
+                if _debug.DONT_LOG_TOOL_DATA:
+                    logger.debug(f"Invalid JSON input for tool {schema.name}")
+                else:
+                    logger.debug(f"Invalid JSON input for tool {schema.name}: {input}")
+                raise ModelBehaviorError(
+                    f"Invalid JSON input for tool {schema.name}: {input}"
+                ) from e
+
+            if _debug.DONT_LOG_TOOL_DATA:
+                logger.debug(f"Invoking tool {schema.name}")
+            else:
+                logger.debug(f"Invoking tool {schema.name} with input {input}")
+
+            try:
+                parsed = (
+                    schema.params_pydantic_model(**json_data)
+                    if json_data
+                    else schema.params_pydantic_model()
+                )
+            except ValidationError as e:
+                raise ModelBehaviorError(f"Invalid JSON input for tool {schema.name}: {e}") from e
+
+            args, kwargs_dict = schema.to_call_args(parsed)
+
+            if not _debug.DONT_LOG_TOOL_DATA:
+                logger.debug(f"Tool call args: {args}, kwargs: {kwargs_dict}")
+
+            if inspect.iscoroutinefunction(the_func):
+                if schema.takes_context:
+                    result = await the_func(ctx, *args, **kwargs_dict)
+                else:
+                    result = await the_func(*args, **kwargs_dict)
+            else:
+                if schema.takes_context:
+                    result = the_func(ctx, *args, **kwargs_dict)
+                else:
+                    result = the_func(*args, **kwargs_dict)
+
+            if _debug.DONT_LOG_TOOL_DATA:
+                logger.debug(f"Tool {schema.name} completed.")
+            else:
+                logger.debug(f"Tool {schema.name} returned {result}")
+
+            return str(result)
+
+        async def _on_invoke_tool(ctx: RunContextWrapper[Any], input: str) -> str:
+            try:
+                return await _on_invoke_tool_impl(ctx, input)
+            except Exception as e:
+                if failure_error_function is None:
+                    raise
+
+                result = failure_error_function(ctx, e)
+                if inspect.isawaitable(result):
+                    return await result
+
+                _utils.attach_error_to_current_span(
+                    SpanError(
+                        message="Error running tool (non-fatal)",
+                        data={
+                            "tool_name": schema.name,
+                            "error": str(e),
+                        },
+                    )
+                )
+                return result
+
+        return FunctionTool(
+            name=schema.name,
+            description=schema.description or "",
+            params_json_schema=schema.params_json_schema,
+            on_invoke_tool=_on_invoke_tool,
+        )
+
+    # If func is actually a callable, we were used as @function_tool with no parentheses
+    if callable(func):
+        return _create_function_tool(func)
+
+    # Otherwise, we were used as @function_tool(...), so return a decorator
+    def decorator(real_func: ToolFunction[...]) -> FunctionTool:
+        return _create_function_tool(real_func)
+
+    return decorator
+    return decorator
+    return decorator

agents/tracing/__init__.py

@@ -0,0 +1,97 @@
+import atexit
+
+from .create import (
+    agent_span,
+    custom_span,
+    function_span,
+    generation_span,
+    get_current_span,
+    get_current_trace,
+    guardrail_span,
+    handoff_span,
+    response_span,
+    trace,
+)
+from .processor_interface import TracingProcessor
+from .processors import default_exporter, default_processor
+from .setup import GLOBAL_TRACE_PROVIDER
+from .span_data import (
+    AgentSpanData,
+    CustomSpanData,
+    FunctionSpanData,
+    GenerationSpanData,
+    GuardrailSpanData,
+    HandoffSpanData,
+    ResponseSpanData,
+    SpanData,
+)
+from .spans import Span, SpanError
+from .traces import Trace
+from .util import gen_span_id, gen_trace_id
+
+__all__ = [
+    "add_trace_processor",
+    "agent_span",
+    "custom_span",
+    "function_span",
+    "generation_span",
+    "get_current_span",
+    "get_current_trace",
+    "guardrail_span",
+    "handoff_span",
+    "response_span",
+    "set_trace_processors",
+    "set_tracing_disabled",
+    "trace",
+    "Trace",
+    "SpanError",
+    "Span",
+    "SpanData",
+    "AgentSpanData",
+    "CustomSpanData",
+    "FunctionSpanData",
+    "GenerationSpanData",
+    "GuardrailSpanData",
+    "HandoffSpanData",
+    "ResponseSpanData",
+    "TracingProcessor",
+    "gen_trace_id",
+    "gen_span_id",
+]
+
+
+def add_trace_processor(span_processor: TracingProcessor) -> None:
+    """
+    Adds a new trace processor. This processor will receive all traces/spans.
+    """
+    GLOBAL_TRACE_PROVIDER.register_processor(span_processor)
+
+
+def set_trace_processors(processors: list[TracingProcessor]) -> None:
+    """
+    Set the list of trace processors. This will replace the current list of processors.
+    """
+    GLOBAL_TRACE_PROVIDER.set_processors(processors)
+
+
+def set_tracing_disabled(disabled: bool) -> None:
+    """
+    Set whether tracing is globally disabled.
+    """
+    GLOBAL_TRACE_PROVIDER.set_disabled(disabled)
+
+
+def set_tracing_export_api_key(api_key: str) -> None:
+    """
+    Set the OpenAI API key for the backend exporter.
+    """
+    default_exporter().set_api_key(api_key)
+
+
+# Add the default processor, which exports traces and spans to the backend in batches. You can
+# change the default behavior by either:
+# 1. calling add_trace_processor(), which adds additional processors, or
+# 2. calling set_trace_processors(), which replaces the default processor.
+add_trace_processor(default_processor())
+
+atexit.register(GLOBAL_TRACE_PROVIDER.shutdown)