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

agents/handoffs.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable, Generic, cast, overload
+
+from pydantic import TypeAdapter
+from typing_extensions import TypeAlias, TypeVar
+
+from . import _utils
+from .exceptions import ModelBehaviorError, UserError
+from .items import RunItem, TResponseInputItem
+from .run_context import RunContextWrapper, TContext
+from .strict_schema import ensure_strict_json_schema
+from .tracing.spans import SpanError
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+
+# The handoff input type is the type of data passed when the agent is called via a handoff.
+THandoffInput = TypeVar("THandoffInput", default=Any)
+
+OnHandoffWithInput = Callable[[RunContextWrapper[Any], THandoffInput], Any]
+OnHandoffWithoutInput = Callable[[RunContextWrapper[Any]], Any]
+
+
+@dataclass(frozen=True)
+class HandoffInputData:
+    input_history: str | tuple[TResponseInputItem, ...]
+    """
+    The input history before `Runner.run()` was called.
+    """
+
+    pre_handoff_items: tuple[RunItem, ...]
+    """
+    The items generated before the agent turn where the handoff was invoked.
+    """
+
+    new_items: tuple[RunItem, ...]
+    """
+    The new items generated during the current agent turn, including the item that triggered the
+    handoff and the tool output message representing the response from the handoff output.
+    """
+
+
+HandoffInputFilter: TypeAlias = Callable[[HandoffInputData], HandoffInputData]
+"""A function that filters the input data passed to the next agent."""
+
+
+@dataclass
+class Handoff(Generic[TContext]):
+    """A handoff is when an agent delegates a task to another agent.
+    For example, in a customer support scenario you might have a "triage agent" that determines
+    which agent should handle the user's request, and sub-agents that specialize in different
+    areas like billing, account management, etc.
+    """
+
+    tool_name: str
+    """The name of the tool that represents the handoff."""
+
+    tool_description: str
+    """The description of the tool that represents the handoff."""
+
+    input_json_schema: dict[str, Any]
+    """The JSON schema for the handoff input. Can be empty if the handoff does not take an input.
+    """
+
+    on_invoke_handoff: Callable[[RunContextWrapper[Any], str], Awaitable[Agent[TContext]]]
+    """The function that invokes the handoff. The parameters passed are:
+    1. The handoff run context
+    2. The arguments from the LLM, as a JSON string. Empty string if input_json_schema is empty.
+
+    Must return an agent.
+    """
+
+    agent_name: str
+    """The name of the agent that is being handed off to."""
+
+    input_filter: HandoffInputFilter | None = None
+    """A function that filters the inputs that are passed to the next agent. By default, the new
+    agent sees the entire conversation history. In some cases, you may want to filter inputs e.g.
+    to remove older inputs, or remove tools from existing inputs.
+
+    The function will receive the entire conversation history so far, including the input item
+    that triggered the handoff and a tool call output item representing the handoff tool's output.
+
+    You are free to modify the input history or new items as you see fit. The next agent that
+    runs will receive `handoff_input_data.all_items`.
+
+    IMPORTANT: in streaming mode, we will not stream anything as a result of this function. The
+    items generated before will already have been streamed.
+    """
+
+    strict_json_schema: bool = True
+    """Whether the input JSON schema is in strict mode. We **strongly** recommend setting this to
+    True, as it increases the likelihood of correct JSON input.
+    """
+
+    def get_transfer_message(self, agent: Agent[Any]) -> str:
+        base = f"{{'assistant': '{agent.name}'}}"
+        return base
+
+    @classmethod
+    def default_tool_name(cls, agent: Agent[Any]) -> str:
+        return _utils.transform_string_function_style(f"transfer_to_{agent.name}")
+
+    @classmethod
+    def default_tool_description(cls, agent: Agent[Any]) -> str:
+        return (
+            f"Handoff to the {agent.name} agent to handle the request. "
+            f"{agent.handoff_description or ''}"
+        )
+
+
+@overload
+def handoff(
+    agent: Agent[TContext],
+    *,
+    tool_name_override: str | None = None,
+    tool_description_override: str | None = None,
+    input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+) -> Handoff[TContext]: ...
+
+
+@overload
+def handoff(
+    agent: Agent[TContext],
+    *,
+    on_handoff: OnHandoffWithInput[THandoffInput],
+    input_type: type[THandoffInput],
+    tool_description_override: str | None = None,
+    tool_name_override: str | None = None,
+    input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+) -> Handoff[TContext]: ...
+
+
+@overload
+def handoff(
+    agent: Agent[TContext],
+    *,
+    on_handoff: OnHandoffWithoutInput,
+    tool_description_override: str | None = None,
+    tool_name_override: str | None = None,
+    input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+) -> Handoff[TContext]: ...
+
+
+def handoff(
+    agent: Agent[TContext],
+    tool_name_override: str | None = None,
+    tool_description_override: str | None = None,
+    on_handoff: OnHandoffWithInput[THandoffInput] | OnHandoffWithoutInput | None = None,
+    input_type: type[THandoffInput] | None = None,
+    input_filter: Callable[[HandoffInputData], HandoffInputData] | None = None,
+) -> Handoff[TContext]:
+    """Create a handoff from an agent.
+
+    Args:
+        agent: The agent to handoff to, or a function that returns an agent.
+        tool_name_override: Optional override for the name of the tool that represents the handoff.
+        tool_description_override: Optional override for the description of the tool that
+            represents the handoff.
+        on_handoff: A function that runs when the handoff is invoked.
+        input_type: the type of the input to the handoff. If provided, the input will be validated
+            against this type. Only relevant if you pass a function that takes an input.
+        input_filter: a function that filters the inputs that are passed to the next agent.
+    """
+    assert (on_handoff and input_type) or not (on_handoff and input_type), (
+        "You must provide either both on_input and input_type, or neither"
+    )
+    type_adapter: TypeAdapter[Any] | None
+    if input_type is not None:
+        assert callable(on_handoff), "on_handoff must be callable"
+        sig = inspect.signature(on_handoff)
+        if len(sig.parameters) != 2:
+            raise UserError("on_handoff must take two arguments: context and input")
+
+        type_adapter = TypeAdapter(input_type)
+        input_json_schema = type_adapter.json_schema()
+    else:
+        type_adapter = None
+        input_json_schema = {}
+        if on_handoff is not None:
+            sig = inspect.signature(on_handoff)
+            if len(sig.parameters) != 1:
+                raise UserError("on_handoff must take one argument: context")
+
+    async def _invoke_handoff(
+        ctx: RunContextWrapper[Any], input_json: str | None = None
+    ) -> Agent[Any]:
+        if input_type is not None and type_adapter is not None:
+            if input_json is None:
+                _utils.attach_error_to_current_span(
+                    SpanError(
+                        message="Handoff function expected non-null input, but got None",
+                        data={"details": "input_json is None"},
+                    )
+                )
+                raise ModelBehaviorError("Handoff function expected non-null input, but got None")
+
+            validated_input = _utils.validate_json(
+                json_str=input_json,
+                type_adapter=type_adapter,
+                partial=False,
+            )
+            input_func = cast(OnHandoffWithInput[THandoffInput], on_handoff)
+            if inspect.iscoroutinefunction(input_func):
+                await input_func(ctx, validated_input)
+            else:
+                input_func(ctx, validated_input)
+        elif on_handoff is not None:
+            no_input_func = cast(OnHandoffWithoutInput, on_handoff)
+            if inspect.iscoroutinefunction(no_input_func):
+                await no_input_func(ctx)
+            else:
+                no_input_func(ctx)
+
+        return agent
+
+    tool_name = tool_name_override or Handoff.default_tool_name(agent)
+    tool_description = tool_description_override or Handoff.default_tool_description(agent)
+
+    # Always ensure the input JSON schema is in strict mode
+    # If there is a need, we can make this configurable in the future
+    input_json_schema = ensure_strict_json_schema(input_json_schema)
+
+    return Handoff(
+        tool_name=tool_name,
+        tool_description=tool_description,
+        input_json_schema=input_json_schema,
+        on_invoke_handoff=_invoke_handoff,
+        input_filter=input_filter,
+        agent_name=agent.name,
+    )

agents/items.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import abc
+import copy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union
+
+from openai.types.responses import (
+    Response,
+    ResponseComputerToolCall,
+    ResponseFileSearchToolCall,
+    ResponseFunctionToolCall,
+    ResponseFunctionWebSearch,
+    ResponseInputItemParam,
+    ResponseOutputItem,
+    ResponseOutputMessage,
+    ResponseOutputRefusal,
+    ResponseOutputText,
+    ResponseStreamEvent,
+)
+from openai.types.responses.response_input_item_param import ComputerCallOutput, FunctionCallOutput
+from openai.types.responses.response_reasoning_item import ResponseReasoningItem
+from pydantic import BaseModel
+from typing_extensions import TypeAlias
+
+from .exceptions import AgentsException, ModelBehaviorError
+from .usage import Usage
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+TResponse = Response
+"""A type alias for the Response type from the OpenAI SDK."""
+
+TResponseInputItem = ResponseInputItemParam
+"""A type alias for the ResponseInputItemParam type from the OpenAI SDK."""
+
+TResponseOutputItem = ResponseOutputItem
+"""A type alias for the ResponseOutputItem type from the OpenAI SDK."""
+
+TResponseStreamEvent = ResponseStreamEvent
+"""A type alias for the ResponseStreamEvent type from the OpenAI SDK."""
+
+T = TypeVar("T", bound=Union[TResponseOutputItem, TResponseInputItem])
+
+
+@dataclass
+class RunItemBase(Generic[T], abc.ABC):
+    agent: Agent[Any]
+    """The agent whose run caused this item to be generated."""
+
+    raw_item: T
+    """The raw Responses item from the run. This will always be a either an output item (i.e.
+    `openai.types.responses.ResponseOutputItem` or an input item
+    (i.e. `openai.types.responses.ResponseInputItemParam`).
+    """
+
+    def to_input_item(self) -> TResponseInputItem:
+        """Converts this item into an input item suitable for passing to the model."""
+        if isinstance(self.raw_item, dict):
+            # We know that input items are dicts, so we can ignore the type error
+            return self.raw_item  # type: ignore
+        elif isinstance(self.raw_item, BaseModel):
+            # All output items are Pydantic models that can be converted to input items.
+            return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
+        else:
+            raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")
+
+
+@dataclass
+class MessageOutputItem(RunItemBase[ResponseOutputMessage]):
+    """Represents a message from the LLM."""
+
+    raw_item: ResponseOutputMessage
+    """The raw response output message."""
+
+    type: Literal["message_output_item"] = "message_output_item"
+
+
+@dataclass
+class HandoffCallItem(RunItemBase[ResponseFunctionToolCall]):
+    """Represents a tool call for a handoff from one agent to another."""
+
+    raw_item: ResponseFunctionToolCall
+    """The raw response function tool call that represents the handoff."""
+
+    type: Literal["handoff_call_item"] = "handoff_call_item"
+
+
+@dataclass
+class HandoffOutputItem(RunItemBase[TResponseInputItem]):
+    """Represents the output of a handoff."""
+
+    raw_item: TResponseInputItem
+    """The raw input item that represents the handoff taking place."""
+
+    source_agent: Agent[Any]
+    """The agent that made the handoff."""
+
+    target_agent: Agent[Any]
+    """The agent that is being handed off to."""
+
+    type: Literal["handoff_output_item"] = "handoff_output_item"
+
+
+ToolCallItemTypes: TypeAlias = Union[
+    ResponseFunctionToolCall,
+    ResponseComputerToolCall,
+    ResponseFileSearchToolCall,
+    ResponseFunctionWebSearch,
+]
+"""A type that represents a tool call item."""
+
+
+@dataclass
+class ToolCallItem(RunItemBase[ToolCallItemTypes]):
+    """Represents a tool call e.g. a function call or computer action call."""
+
+    raw_item: ToolCallItemTypes
+    """The raw tool call item."""
+
+    type: Literal["tool_call_item"] = "tool_call_item"
+
+
+@dataclass
+class ToolCallOutputItem(RunItemBase[Union[FunctionCallOutput, ComputerCallOutput]]):
+    """Represents the output of a tool call."""
+
+    raw_item: FunctionCallOutput | ComputerCallOutput
+    """The raw item from the model."""
+
+    output: str
+    """The output of the tool call."""
+
+    type: Literal["tool_call_output_item"] = "tool_call_output_item"
+
+
+@dataclass
+class ReasoningItem(RunItemBase[ResponseReasoningItem]):
+    """Represents a reasoning item."""
+
+    raw_item: ResponseReasoningItem
+    """The raw reasoning item."""
+
+    type: Literal["reasoning_item"] = "reasoning_item"
+
+
+RunItem: TypeAlias = Union[
+    MessageOutputItem,
+    HandoffCallItem,
+    HandoffOutputItem,
+    ToolCallItem,
+    ToolCallOutputItem,
+    ReasoningItem,
+]
+"""An item generated by an agent."""
+
+
+@dataclass
+class ModelResponse:
+    output: list[TResponseOutputItem]
+    """A list of outputs (messages, tool calls, etc) generated by the model"""
+
+    usage: Usage
+    """The usage information for the response."""
+
+    referenceable_id: str | None
+    """An ID for the response which can be used to refer to the response in subsequent calls to the
+    model. Not supported by all model providers.
+    """
+
+    def to_input_items(self) -> list[TResponseInputItem]:
+        """Convert the output into a list of input items suitable for passing to the model."""
+        # We happen to know that the shape of the Pydantic output items are the same as the
+        # equivalent TypedDict input items, so we can just convert each one.
+        # This is also tested via unit tests.
+        return [it.model_dump(exclude_unset=True) for it in self.output]  # type: ignore
+
+
+class ItemHelpers:
+    @classmethod
+    def extract_last_content(cls, message: TResponseOutputItem) -> str:
+        """Extracts the last text content or refusal from a message."""
+        if not isinstance(message, ResponseOutputMessage):
+            return ""
+
+        last_content = message.content[-1]
+        if isinstance(last_content, ResponseOutputText):
+            return last_content.text
+        elif isinstance(last_content, ResponseOutputRefusal):
+            return last_content.refusal
+        else:
+            raise ModelBehaviorError(f"Unexpected content type: {type(last_content)}")
+
+    @classmethod
+    def extract_last_text(cls, message: TResponseOutputItem) -> str | None:
+        """Extracts the last text content from a message, if any. Ignores refusals."""
+        if isinstance(message, ResponseOutputMessage):
+            last_content = message.content[-1]
+            if isinstance(last_content, ResponseOutputText):
+                return last_content.text
+
+        return None
+
+    @classmethod
+    def input_to_new_input_list(
+        cls, input: str | list[TResponseInputItem]
+    ) -> list[TResponseInputItem]:
+        """Converts a string or list of input items into a list of input items."""
+        if isinstance(input, str):
+            return [
+                {
+                    "content": input,
+                    "role": "user",
+                }
+            ]
+        return copy.deepcopy(input)
+
+    @classmethod
+    def text_message_outputs(cls, items: list[RunItem]) -> str:
+        """Concatenates all the text content from a list of message output items."""
+        text = ""
+        for item in items:
+            if isinstance(item, MessageOutputItem):
+                text += cls.text_message_output(item)
+        return text
+
+    @classmethod
+    def text_message_output(cls, message: MessageOutputItem) -> str:
+        """Extracts all the text content from a single message output item."""
+        text = ""
+        for item in message.raw_item.content:
+            if isinstance(item, ResponseOutputText):
+                text += item.text
+        return text
+
+    @classmethod
+    def tool_call_output_item(
+        cls, tool_call: ResponseFunctionToolCall, output: str
+    ) -> FunctionCallOutput:
+        """Creates a tool call output item from a tool call and its output."""
+        return {
+            "call_id": tool_call.call_id,
+            "output": output,
+            "type": "function_call_output",
+        }

agents/lifecycle.py

@@ -0,0 +1,105 @@
+from typing import Any, Generic
+
+from .agent import Agent
+from .run_context import RunContextWrapper, TContext
+from .tool import Tool
+
+
+class RunHooks(Generic[TContext]):
+    """A class that receives callbacks on various lifecycle events in an agent run. Subclass and
+    override the methods you need.
+    """
+
+    async def on_agent_start(
+        self, context: RunContextWrapper[TContext], agent: Agent[TContext]
+    ) -> None:
+        """Called before the agent is invoked. Called each time the current agent changes."""
+        pass
+
+    async def on_agent_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        output: Any,
+    ) -> None:
+        """Called when the agent produces a final output."""
+        pass
+
+    async def on_handoff(
+        self,
+        context: RunContextWrapper[TContext],
+        from_agent: Agent[TContext],
+        to_agent: Agent[TContext],
+    ) -> None:
+        """Called when a handoff occurs."""
+        pass
+
+    async def on_tool_start(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        tool: Tool,
+    ) -> None:
+        """Called before a tool is invoked."""
+        pass
+
+    async def on_tool_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        tool: Tool,
+        result: str,
+    ) -> None:
+        """Called after a tool is invoked."""
+        pass
+
+
+class AgentHooks(Generic[TContext]):
+    """A class that receives callbacks on various lifecycle events for a specific agent. You can
+    set this on `agent.hooks` to receive events for that specific agent.
+
+    Subclass and override the methods you need.
+    """
+
+    async def on_start(self, context: RunContextWrapper[TContext], agent: Agent[TContext]) -> None:
+        """Called before the agent is invoked. Called each time the running agent is changed to this
+        agent."""
+        pass
+
+    async def on_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        output: Any,
+    ) -> None:
+        """Called when the agent produces a final output."""
+        pass
+
+    async def on_handoff(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        source: Agent[TContext],
+    ) -> None:
+        """Called when the agent is being handed off to. The `source` is the agent that is handing
+        off to this agent."""
+        pass
+
+    async def on_tool_start(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        tool: Tool,
+    ) -> None:
+        """Called before a tool is invoked."""
+        pass
+
+    async def on_tool_end(
+        self,
+        context: RunContextWrapper[TContext],
+        agent: Agent[TContext],
+        tool: Tool,
+        result: str,
+    ) -> None:
+        """Called after a tool is invoked."""
+        pass

agents/logger.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("openai.agents")

agents/model_settings.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class ModelSettings:
+    """Settings to use when calling an LLM.
+
+    This class holds optional model configuration parameters (e.g. temperature,
+    top_p, penalties, truncation, etc.).
+    """
+
+    temperature: float | None = None
+    top_p: float | None = None
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    tool_choice: Literal["auto", "required", "none"] | str | None = None
+    parallel_tool_calls: bool | None = False
+    truncation: Literal["auto", "disabled"] | None = None
+
+    def resolve(self, override: ModelSettings | None) -> ModelSettings:
+        """Produce a new ModelSettings by overlaying any non-None values from the
+        override on top of this instance."""
+        if override is None:
+            return self
+        return ModelSettings(
+            temperature=override.temperature or self.temperature,
+            top_p=override.top_p or self.top_p,
+            frequency_penalty=override.frequency_penalty or self.frequency_penalty,
+            presence_penalty=override.presence_penalty or self.presence_penalty,
+            tool_choice=override.tool_choice or self.tool_choice,
+            parallel_tool_calls=override.parallel_tool_calls or self.parallel_tool_calls,
+            truncation=override.truncation or self.truncation,
+        )

agents/models/_openai_shared.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+
+_default_openai_key: str | None = None
+_default_openai_client: AsyncOpenAI | None = None
+_use_responses_by_default: bool = True
+
+
+def set_default_openai_key(key: str) -> None:
+    global _default_openai_key
+    _default_openai_key = key
+
+
+def get_default_openai_key() -> str | None:
+    return _default_openai_key
+
+
+def set_default_openai_client(client: AsyncOpenAI) -> None:
+    global _default_openai_client
+    _default_openai_client = client
+
+
+def get_default_openai_client() -> AsyncOpenAI | None:
+    return _default_openai_client
+
+
+def set_use_responses_by_default(use_responses: bool) -> None:
+    global _use_responses_by_default
+    _use_responses_by_default = use_responses
+
+
+def get_use_responses_by_default() -> bool:
+    return _use_responses_by_default

agents/models/fake_id.py

@@ -0,0 +1,5 @@
+FAKE_RESPONSES_ID = "__fake_id__"
+"""This is a placeholder ID used to fill in the `id` field in Responses API related objects. It's
+useful when you're creating Responses objects from non-Responses APIs, e.g. the OpenAI Chat
+Completions API or other LLM providers.
+"""