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

agents/_utils.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable
+from typing import Any, Literal, Union
+
+from pydantic import TypeAdapter, ValidationError
+from typing_extensions import TypeVar
+
+from .exceptions import ModelBehaviorError
+from .logger import logger
+from .tracing import Span, SpanError, get_current_span
+
+T = TypeVar("T")
+
+MaybeAwaitable = Union[Awaitable[T], T]
+
+
+def transform_string_function_style(name: str) -> str:
+    # Replace spaces with underscores
+    name = name.replace(" ", "_")
+
+    # Replace non-alphanumeric characters with underscores
+    name = re.sub(r"[^a-zA-Z0-9]", "_", name)
+
+    return name.lower()
+
+
+def validate_json(json_str: str, type_adapter: TypeAdapter[T], partial: bool) -> T:
+    partial_setting: bool | Literal["off", "on", "trailing-strings"] = (
+        "trailing-strings" if partial else False
+    )
+    try:
+        validated = type_adapter.validate_json(json_str, experimental_allow_partial=partial_setting)
+        return validated
+    except ValidationError as e:
+        attach_error_to_current_span(
+            SpanError(
+                message="Invalid JSON provided",
+                data={},
+            )
+        )
+        raise ModelBehaviorError(
+            f"Invalid JSON when parsing {json_str} for {type_adapter}; {e}"
+        ) from e
+
+
+def attach_error_to_span(span: Span[Any], error: SpanError) -> None:
+    span.set_error(error)
+
+
+def attach_error_to_current_span(error: SpanError) -> None:
+    span = get_current_span()
+    if span:
+        attach_error_to_span(span, error)
+    else:
+        logger.warning(f"No span to add error {error} to")
+
+
+async def noop_coroutine() -> None:
+    pass

agents/agent.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from collections.abc import Awaitable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Generic, cast
+
+from . import _utils
+from ._utils import MaybeAwaitable
+from .guardrail import InputGuardrail, OutputGuardrail
+from .handoffs import Handoff
+from .items import ItemHelpers
+from .logger import logger
+from .model_settings import ModelSettings
+from .models.interface import Model
+from .run_context import RunContextWrapper, TContext
+from .tool import Tool, function_tool
+
+if TYPE_CHECKING:
+    from .lifecycle import AgentHooks
+    from .result import RunResult
+
+
+@dataclass
+class Agent(Generic[TContext]):
+    """An agent is an AI model configured with instructions, tools, guardrails, handoffs and more.
+
+    We strongly recommend passing `instructions`, which is the "system prompt" for the agent. In
+    addition, you can pass `description`, which is a human-readable description of the agent, used
+    when the agent is used inside tools/handoffs.
+
+    Agents are generic on the context type. The context is a (mutable) object you create. It is
+    passed to tool functions, handoffs, guardrails, etc.
+    """
+
+    name: str
+    """The name of the agent."""
+
+    instructions: (
+        str
+        | Callable[
+            [RunContextWrapper[TContext], Agent[TContext]],
+            MaybeAwaitable[str],
+        ]
+        | None
+    ) = None
+    """The instructions for the agent. Will be used as the "system prompt" when this agent is
+    invoked. Describes what the agent should do, and how it responds.
+
+    Can either be a string, or a function that dynamically generates instructions for the agent. If
+    you provide a function, it will be called with the context and the agent instance. It must
+    return a string.
+    """
+
+    handoff_description: str | None = None
+    """A description of the agent. This is used when the agent is used as a handoff, so that an
+    LLM knows what it does and when to invoke it.
+    """
+
+    handoffs: list[Agent[Any] | Handoff[TContext]] = field(default_factory=list)
+    """Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs,
+    and the agent can choose to delegate to them if relevant. Allows for separation of concerns and
+    modularity.
+    """
+
+    model: str | Model | None = None
+    """The model implementation to use when invoking the LLM.
+
+    By default, if not set, the agent will use the default model configured in
+    `model_settings.DEFAULT_MODEL`.
+    """
+
+    model_settings: ModelSettings = field(default_factory=ModelSettings)
+    """Configures model-specific tuning parameters (e.g. temperature, top_p).
+    """
+
+    tools: list[Tool] = field(default_factory=list)
+    """A list of tools that the agent can use."""
+
+    input_guardrails: list[InputGuardrail[TContext]] = field(default_factory=list)
+    """A list of checks that run in parallel to the agent's execution, before generating a
+    response. Runs only if the agent is the first agent in the chain.
+    """
+
+    output_guardrails: list[OutputGuardrail[TContext]] = field(default_factory=list)
+    """A list of checks that run on the final output of the agent, after generating a response.
+    Runs only if the agent produces a final output.
+    """
+
+    output_type: type[Any] | None = None
+    """The type of the output object. If not provided, the output will be `str`."""
+
+    hooks: AgentHooks[TContext] | None = None
+    """A class that receives callbacks on various lifecycle events for this agent.
+    """
+
+    def clone(self, **kwargs: Any) -> Agent[TContext]:
+        """Make a copy of the agent, with the given arguments changed. For example, you could do:
+        ```
+        new_agent = agent.clone(instructions="New instructions")
+        ```
+        """
+        return dataclasses.replace(self, **kwargs)
+
+    def as_tool(
+        self,
+        tool_name: str | None,
+        tool_description: str | None,
+        custom_output_extractor: Callable[[RunResult], Awaitable[str]] | None = None,
+    ) -> Tool:
+        """Transform this agent into a tool, callable by other agents.
+
+        This is different from handoffs in two ways:
+        1. In handoffs, the new agent receives the conversation history. In this tool, the new agent
+           receives generated input.
+        2. In handoffs, the new agent takes over the conversation. In this tool, the new agent is
+           called as a tool, and the conversation is continued by the original agent.
+
+        Args:
+            tool_name: The name of the tool. If not provided, the agent's name will be used.
+            tool_description: The description of the tool, which should indicate what it does and
+                when to use it.
+            custom_output_extractor: A function that extracts the output from the agent. If not
+                provided, the last message from the agent will be used.
+        """
+
+        @function_tool(
+            name_override=tool_name or _utils.transform_string_function_style(self.name),
+            description_override=tool_description or "",
+        )
+        async def run_agent(context: RunContextWrapper, input: str) -> str:
+            from .run import Runner
+
+            output = await Runner.run(
+                starting_agent=self,
+                input=input,
+                context=context.context,
+            )
+            if custom_output_extractor:
+                return await custom_output_extractor(output)
+
+            return ItemHelpers.text_message_outputs(output.new_items)
+
+        return run_agent
+
+    async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> str | None:
+        """Get the system prompt for the agent."""
+        if isinstance(self.instructions, str):
+            return self.instructions
+        elif callable(self.instructions):
+            if inspect.iscoroutinefunction(self.instructions):
+                return await cast(Awaitable[str], self.instructions(run_context, self))
+            else:
+                return cast(str, self.instructions(run_context, self))
+        elif self.instructions is not None:
+            logger.error(f"Instructions must be a string or a function, got {self.instructions}")
+
+        return None

agents/agent_output.py

@@ -0,0 +1,144 @@
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel, TypeAdapter
+from typing_extensions import TypedDict, get_args, get_origin
+
+from . import _utils
+from .exceptions import ModelBehaviorError, UserError
+from .strict_schema import ensure_strict_json_schema
+from .tracing import SpanError
+
+_WRAPPER_DICT_KEY = "response"
+
+
+@dataclass(init=False)
+class AgentOutputSchema:
+    """An object that captures the JSON schema of the output, as well as validating/parsing JSON
+    produced by the LLM into the output type.
+    """
+
+    output_type: type[Any]
+    """The type of the output."""
+
+    _type_adapter: TypeAdapter[Any]
+    """A type adapter that wraps the output type, so that we can validate JSON."""
+
+    _is_wrapped: bool
+    """Whether the output type is wrapped in a dictionary. This is generally done if the base
+    output type cannot be represented as a JSON Schema object.
+    """
+
+    _output_schema: dict[str, Any]
+    """The JSON schema of the output."""
+
+    strict_json_schema: bool
+    """Whether the JSON schema is in strict mode. We **strongly** recommend setting this to True,
+    as it increases the likelihood of correct JSON input.
+    """
+
+    def __init__(self, output_type: type[Any], strict_json_schema: bool = True):
+        """
+        Args:
+            output_type: The type of the output.
+            strict_json_schema: Whether the JSON schema is in strict mode. We **strongly** recommend
+                setting this to True, as it increases the likelihood of correct JSON input.
+        """
+        self.output_type = output_type
+        self.strict_json_schema = strict_json_schema
+
+        if output_type is None or output_type is str:
+            self._is_wrapped = False
+            self._type_adapter = TypeAdapter(output_type)
+            self._output_schema = self._type_adapter.json_schema()
+            return
+
+        # We should wrap for things that are not plain text, and for things that would definitely
+        # not be a JSON Schema object.
+        self._is_wrapped = not _is_subclass_of_base_model_or_dict(output_type)
+
+        if self._is_wrapped:
+            OutputType = TypedDict(
+                "OutputType",
+                {
+                    _WRAPPER_DICT_KEY: output_type,  # type: ignore
+                },
+            )
+            self._type_adapter = TypeAdapter(OutputType)
+            self._output_schema = self._type_adapter.json_schema()
+        else:
+            self._type_adapter = TypeAdapter(output_type)
+            self._output_schema = self._type_adapter.json_schema()
+
+        if self.strict_json_schema:
+            self._output_schema = ensure_strict_json_schema(self._output_schema)
+
+    def is_plain_text(self) -> bool:
+        """Whether the output type is plain text (versus a JSON object)."""
+        return self.output_type is None or self.output_type is str
+
+    def json_schema(self) -> dict[str, Any]:
+        """The JSON schema of the output type."""
+        if self.is_plain_text():
+            raise UserError("Output type is plain text, so no JSON schema is available")
+        return self._output_schema
+
+    def validate_json(self, json_str: str, partial: bool = False) -> Any:
+        """Validate a JSON string against the output type. Returns the validated object, or raises
+        a `ModelBehaviorError` if the JSON is invalid.
+        """
+        validated = _utils.validate_json(json_str, self._type_adapter, partial)
+        if self._is_wrapped:
+            if not isinstance(validated, dict):
+                _utils.attach_error_to_current_span(
+                    SpanError(
+                        message="Invalid JSON",
+                        data={"details": f"Expected a dict, got {type(validated)}"},
+                    )
+                )
+                raise ModelBehaviorError(
+                    f"Expected a dict, got {type(validated)} for JSON: {json_str}"
+                )
+
+            if _WRAPPER_DICT_KEY not in validated:
+                _utils.attach_error_to_current_span(
+                    SpanError(
+                        message="Invalid JSON",
+                        data={"details": f"Could not find key {_WRAPPER_DICT_KEY} in JSON"},
+                    )
+                )
+                raise ModelBehaviorError(
+                    f"Could not find key {_WRAPPER_DICT_KEY} in JSON: {json_str}"
+                )
+            return validated[_WRAPPER_DICT_KEY]
+        return validated
+
+    def output_type_name(self) -> str:
+        """The name of the output type."""
+        return _type_to_str(self.output_type)
+
+
+def _is_subclass_of_base_model_or_dict(t: Any) -> bool:
+    if not isinstance(t, type):
+        return False
+
+    # If it's a generic alias, 'origin' will be the actual type, e.g. 'list'
+    origin = get_origin(t)
+
+    allowed_types = (BaseModel, dict)
+    # If it's a generic alias e.g. list[str], then we should check the origin type i.e. list
+    return issubclass(origin or t, allowed_types)
+
+
+def _type_to_str(t: type[Any]) -> str:
+    origin = get_origin(t)
+    args = get_args(t)
+
+    if origin is None:
+        # It's a simple type like `str`, `int`, etc.
+        return t.__name__
+    elif args:
+        args_str = ", ".join(_type_to_str(arg) for arg in args)
+        return f"{origin.__name__}[{args_str}]"
+    else:
+        return str(t)

agents/computer.py

@@ -0,0 +1,107 @@
+import abc
+from typing import Literal
+
+Environment = Literal["mac", "windows", "ubuntu", "browser"]
+Button = Literal["left", "right", "wheel", "back", "forward"]
+
+
+class Computer(abc.ABC):
+    """A computer implemented with sync operations. The Computer interface abstracts the
+    operations needed to control a computer or browser."""
+
+    @property
+    @abc.abstractmethod
+    def environment(self) -> Environment:
+        pass
+
+    @property
+    @abc.abstractmethod
+    def dimensions(self) -> tuple[int, int]:
+        pass
+
+    @abc.abstractmethod
+    def screenshot(self) -> str:
+        pass
+
+    @abc.abstractmethod
+    def click(self, x: int, y: int, button: Button) -> None:
+        pass
+
+    @abc.abstractmethod
+    def double_click(self, x: int, y: int) -> None:
+        pass
+
+    @abc.abstractmethod
+    def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None:
+        pass
+
+    @abc.abstractmethod
+    def type(self, text: str) -> None:
+        pass
+
+    @abc.abstractmethod
+    def wait(self) -> None:
+        pass
+
+    @abc.abstractmethod
+    def move(self, x: int, y: int) -> None:
+        pass
+
+    @abc.abstractmethod
+    def keypress(self, keys: list[str]) -> None:
+        pass
+
+    @abc.abstractmethod
+    def drag(self, path: list[tuple[int, int]]) -> None:
+        pass
+
+
+class AsyncComputer(abc.ABC):
+    """A computer implemented with async operations. The Computer interface abstracts the
+    operations needed to control a computer or browser."""
+
+    @property
+    @abc.abstractmethod
+    def environment(self) -> Environment:
+        pass
+
+    @property
+    @abc.abstractmethod
+    def dimensions(self) -> tuple[int, int]:
+        pass
+
+    @abc.abstractmethod
+    async def screenshot(self) -> str:
+        pass
+
+    @abc.abstractmethod
+    async def click(self, x: int, y: int, button: Button) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def double_click(self, x: int, y: int) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def scroll(self, x: int, y: int, scroll_x: int, scroll_y: int) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def type(self, text: str) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def wait(self) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def move(self, x: int, y: int) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def keypress(self, keys: list[str]) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def drag(self, path: list[tuple[int, int]]) -> None:
+        pass

agents/exceptions.py

@@ -0,0 +1,63 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .guardrail import InputGuardrailResult, OutputGuardrailResult
+
+
+class AgentsException(Exception):
+    """Base class for all exceptions in the Agents SDK."""
+
+
+class MaxTurnsExceeded(AgentsException):
+    """Exception raised when the maximum number of turns is exceeded."""
+
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+
+
+class ModelBehaviorError(AgentsException):
+    """Exception raised when the model does something unexpected, e.g. calling a tool that doesn't
+    exist, or providing malformed JSON.
+    """
+
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+
+
+class UserError(AgentsException):
+    """Exception raised when the user makes an error using the SDK."""
+
+    message: str
+
+    def __init__(self, message: str):
+        self.message = message
+
+
+class InputGuardrailTripwireTriggered(AgentsException):
+    """Exception raised when a guardrail tripwire is triggered."""
+
+    guardrail_result: "InputGuardrailResult"
+    """The result data of the guardrail that was triggered."""
+
+    def __init__(self, guardrail_result: "InputGuardrailResult"):
+        self.guardrail_result = guardrail_result
+        super().__init__(
+            f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire"
+        )
+
+
+class OutputGuardrailTripwireTriggered(AgentsException):
+    """Exception raised when a guardrail tripwire is triggered."""
+
+    guardrail_result: "OutputGuardrailResult"
+    """The result data of the guardrail that was triggered."""
+
+    def __init__(self, guardrail_result: "OutputGuardrailResult"):
+        self.guardrail_result = guardrail_result
+        super().__init__(
+            f"Guardrail {guardrail_result.guardrail.__class__.__name__} triggered tripwire"
+        )

agents/extensions/handoff_filters.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from ..handoffs import HandoffInputData
+from ..items import (
+    HandoffCallItem,
+    HandoffOutputItem,
+    RunItem,
+    ToolCallItem,
+    ToolCallOutputItem,
+    TResponseInputItem,
+)
+
+"""Contains common handoff input filters, for convenience. """
+
+
+def remove_all_tools(handoff_input_data: HandoffInputData) -> HandoffInputData:
+    """Filters out all tool items: file search, web search and function calls+output."""
+
+    history = handoff_input_data.input_history
+    new_items = handoff_input_data.new_items
+
+    filtered_history = (
+        _remove_tool_types_from_input(history) if isinstance(history, tuple) else history
+    )
+    filtered_pre_handoff_items = _remove_tools_from_items(handoff_input_data.pre_handoff_items)
+    filtered_new_items = _remove_tools_from_items(new_items)
+
+    return HandoffInputData(
+        input_history=filtered_history,
+        pre_handoff_items=filtered_pre_handoff_items,
+        new_items=filtered_new_items,
+    )
+
+
+def _remove_tools_from_items(items: tuple[RunItem, ...]) -> tuple[RunItem, ...]:
+    filtered_items = []
+    for item in items:
+        if (
+            isinstance(item, HandoffCallItem)
+            or isinstance(item, HandoffOutputItem)
+            or isinstance(item, ToolCallItem)
+            or isinstance(item, ToolCallOutputItem)
+        ):
+            continue
+        filtered_items.append(item)
+    return tuple(filtered_items)
+
+
+def _remove_tool_types_from_input(
+    items: tuple[TResponseInputItem, ...],
+) -> tuple[TResponseInputItem, ...]:
+    tool_types = [
+        "function_call",
+        "function_call_output",
+        "computer_call",
+        "computer_call_output",
+        "file_search_call",
+        "web_search_call",
+    ]
+
+    filtered_items: list[TResponseInputItem] = []
+    for item in items:
+        itype = item.get("type")
+        if itype in tool_types:
+            continue
+        filtered_items.append(item)
+    return tuple(filtered_items)

agents/extensions/handoff_prompt.py

@@ -0,0 +1,19 @@
+# A recommended prompt prefix for agents that use handoffs. We recommend including this or
+# similar instructions in any agents that use handoffs.
+RECOMMENDED_PROMPT_PREFIX = (
+    "# System context\n"
+    "You are part of a multi-agent system called the Agents SDK, designed to make agent "
+    "coordination and execution easy. Agents uses two primary abstraction: **Agents** and "
+    "**Handoffs**. An agent encompasses instructions and tools and can hand off a "
+    "conversation to another agent when appropriate. "
+    "Handoffs are achieved by calling a handoff function, generally named "
+    "`transfer_to_<agent_name>`. Transfers between agents are handled seamlessly in the background;"
+    " do not mention or draw attention to these transfers in your conversation with the user.\n"
+)
+
+
+def prompt_with_handoff_instructions(prompt: str) -> str:
+    """
+    Add recommended instructions to the prompt for agents that use handoffs.
+    """
+    return f"{RECOMMENDED_PROMPT_PREFIX}\n\n{prompt}"