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

agents/models/openai_provider.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import httpx
+from openai import AsyncOpenAI, DefaultAsyncHttpxClient
+
+from . import _openai_shared
+from .interface import Model, ModelProvider
+from .openai_chatcompletions import OpenAIChatCompletionsModel
+from .openai_responses import OpenAIResponsesModel
+
+DEFAULT_MODEL: str = "gpt-4o"
+
+
+_http_client: httpx.AsyncClient | None = None
+
+
+# If we create a new httpx client for each request, that would mean no sharing of connection pools,
+# which would mean worse latency and resource usage. So, we share the client across requests.
+def shared_http_client() -> httpx.AsyncClient:
+    global _http_client
+    if _http_client is None:
+        _http_client = DefaultAsyncHttpxClient()
+    return _http_client
+
+
+class OpenAIProvider(ModelProvider):
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        openai_client: AsyncOpenAI | None = None,
+        organization: str | None = None,
+        project: str | None = None,
+        use_responses: bool | None = None,
+    ) -> None:
+        if openai_client is not None:
+            assert api_key is None and base_url is None, (
+                "Don't provide api_key or base_url if you provide openai_client"
+            )
+            self._client = openai_client
+        else:
+            self._client = _openai_shared.get_default_openai_client() or AsyncOpenAI(
+                api_key=api_key or _openai_shared.get_default_openai_key(),
+                base_url=base_url,
+                organization=organization,
+                project=project,
+                http_client=shared_http_client(),
+            )
+
+        self._is_openai_model = self._client.base_url.host.startswith("api.openai.com")
+        if use_responses is not None:
+            self._use_responses = use_responses
+        else:
+            self._use_responses = _openai_shared.get_use_responses_by_default()
+
+    def get_model(self, model_name: str | None) -> Model:
+        if model_name is None:
+            model_name = DEFAULT_MODEL
+
+        return (
+            OpenAIResponsesModel(model=model_name, openai_client=self._client)
+            if self._use_responses
+            else OpenAIChatCompletionsModel(model=model_name, openai_client=self._client)
+        )

agents/models/openai_responses.py

@@ -0,0 +1,384 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream, NotGiven
+from openai.types import ChatModel
+from openai.types.responses import (
+    Response,
+    ResponseCompletedEvent,
+    ResponseStreamEvent,
+    ResponseTextConfigParam,
+    ToolParam,
+    WebSearchToolParam,
+    response_create_params,
+)
+
+from .. import _debug
+from ..agent_output import AgentOutputSchema
+from ..exceptions import UserError
+from ..handoffs import Handoff
+from ..items import ItemHelpers, ModelResponse, TResponseInputItem
+from ..logger import logger
+from ..tool import ComputerTool, FileSearchTool, FunctionTool, Tool, WebSearchTool
+from ..tracing import SpanError, response_span
+from ..usage import Usage
+from ..version import __version__
+from .interface import Model, ModelTracing
+
+if TYPE_CHECKING:
+    from ..model_settings import ModelSettings
+
+
+_USER_AGENT = f"Agents/Python {__version__}"
+_HEADERS = {"User-Agent": _USER_AGENT}
+
+# From the Responses API
+IncludeLiteral = Literal[
+    "file_search_call.results",
+    "message.input_image.image_url",
+    "computer_call_output.output.image_url",
+]
+
+
+class OpenAIResponsesModel(Model):
+    """
+    Implementation of `Model` that uses the OpenAI Responses API.
+    """
+
+    def __init__(
+        self,
+        model: str | ChatModel,
+        openai_client: AsyncOpenAI,
+    ) -> None:
+        self.model = model
+        self._client = openai_client
+
+    def _non_null_or_not_given(self, value: Any) -> Any:
+        return value if value is not None else NOT_GIVEN
+
+    async def get_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchema | None,
+        handoffs: list[Handoff],
+        tracing: ModelTracing,
+    ) -> ModelResponse:
+        with response_span(disabled=tracing.is_disabled()) as span_response:
+            try:
+                response = await self._fetch_response(
+                    system_instructions,
+                    input,
+                    model_settings,
+                    tools,
+                    output_schema,
+                    handoffs,
+                    stream=False,
+                )
+
+                if _debug.DONT_LOG_MODEL_DATA:
+                    logger.debug("LLM responsed")
+                else:
+                    logger.debug(
+                        "LLM resp:\n"
+                        f"{json.dumps([x.model_dump() for x in response.output], indent=2)}\n"
+                    )
+
+                usage = (
+                    Usage(
+                        requests=1,
+                        input_tokens=response.usage.input_tokens,
+                        output_tokens=response.usage.output_tokens,
+                        total_tokens=response.usage.total_tokens,
+                    )
+                    if response.usage
+                    else Usage()
+                )
+
+                if tracing.include_data():
+                    span_response.span_data.response = response
+                    span_response.span_data.input = input
+            except Exception as e:
+                span_response.set_error(
+                    SpanError(
+                        message="Error getting response",
+                        data={
+                            "error": str(e) if tracing.include_data() else e.__class__.__name__,
+                        },
+                    )
+                )
+                logger.error(f"Error getting response: {e}")
+                raise
+
+        return ModelResponse(
+            output=response.output,
+            usage=usage,
+            referenceable_id=response.id,
+        )
+
+    async def stream_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchema | None,
+        handoffs: list[Handoff],
+        tracing: ModelTracing,
+    ) -> AsyncIterator[ResponseStreamEvent]:
+        """
+        Yields a partial message as it is generated, as well as the usage information.
+        """
+        with response_span(disabled=tracing.is_disabled()) as span_response:
+            try:
+                stream = await self._fetch_response(
+                    system_instructions,
+                    input,
+                    model_settings,
+                    tools,
+                    output_schema,
+                    handoffs,
+                    stream=True,
+                )
+
+                final_response: Response | None = None
+
+                async for chunk in stream:
+                    if isinstance(chunk, ResponseCompletedEvent):
+                        final_response = chunk.response
+                    yield chunk
+
+                if final_response and tracing.include_data():
+                    span_response.span_data.response = final_response
+                    span_response.span_data.input = input
+
+            except Exception as e:
+                span_response.set_error(
+                    SpanError(
+                        message="Error streaming response",
+                        data={
+                            "error": str(e) if tracing.include_data() else e.__class__.__name__,
+                        },
+                    )
+                )
+                logger.error(f"Error streaming response: {e}")
+                raise
+
+    @overload
+    async def _fetch_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchema | None,
+        handoffs: list[Handoff],
+        stream: Literal[True],
+    ) -> AsyncStream[ResponseStreamEvent]: ...
+
+    @overload
+    async def _fetch_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchema | None,
+        handoffs: list[Handoff],
+        stream: Literal[False],
+    ) -> Response: ...
+
+    async def _fetch_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchema | None,
+        handoffs: list[Handoff],
+        stream: Literal[True] | Literal[False] = False,
+    ) -> Response | AsyncStream[ResponseStreamEvent]:
+        list_input = ItemHelpers.input_to_new_input_list(input)
+
+        parallel_tool_calls = (
+            True if model_settings.parallel_tool_calls and tools and len(tools) > 0 else NOT_GIVEN
+        )
+
+        tool_choice = Converter.convert_tool_choice(model_settings.tool_choice)
+        converted_tools = Converter.convert_tools(tools, handoffs)
+        response_format = Converter.get_response_format(output_schema)
+
+        if _debug.DONT_LOG_MODEL_DATA:
+            logger.debug("Calling LLM")
+        else:
+            logger.debug(
+                f"Calling LLM {self.model} with input:\n"
+                f"{json.dumps(list_input, indent=2)}\n"
+                f"Tools:\n{json.dumps(converted_tools.tools, indent=2)}\n"
+                f"Stream: {stream}\n"
+                f"Tool choice: {tool_choice}\n"
+                f"Response format: {response_format}\n"
+            )
+
+        return await self._client.responses.create(
+            instructions=self._non_null_or_not_given(system_instructions),
+            model=self.model,
+            input=list_input,
+            include=converted_tools.includes,
+            tools=converted_tools.tools,
+            temperature=self._non_null_or_not_given(model_settings.temperature),
+            top_p=self._non_null_or_not_given(model_settings.top_p),
+            truncation=self._non_null_or_not_given(model_settings.truncation),
+            tool_choice=tool_choice,
+            parallel_tool_calls=parallel_tool_calls,
+            stream=stream,
+            extra_headers=_HEADERS,
+            text=response_format,
+        )
+
+    def _get_client(self) -> AsyncOpenAI:
+        if self._client is None:
+            self._client = AsyncOpenAI()
+        return self._client
+
+
+@dataclass
+class ConvertedTools:
+    tools: list[ToolParam]
+    includes: list[IncludeLiteral]
+
+
+class Converter:
+    @classmethod
+    def convert_tool_choice(
+        cls, tool_choice: Literal["auto", "required", "none"] | str | None
+    ) -> response_create_params.ToolChoice | NotGiven:
+        if tool_choice is None:
+            return NOT_GIVEN
+        elif tool_choice == "required":
+            return "required"
+        elif tool_choice == "auto":
+            return "auto"
+        elif tool_choice == "none":
+            return "none"
+        elif tool_choice == "file_search":
+            return {
+                "type": "file_search",
+            }
+        elif tool_choice == "web_search_preview":
+            return {
+                "type": "web_search_preview",
+            }
+        elif tool_choice == "computer_use_preview":
+            return {
+                "type": "computer_use_preview",
+            }
+        else:
+            return {
+                "type": "function",
+                "name": tool_choice,
+            }
+
+    @classmethod
+    def get_response_format(
+        cls, output_schema: AgentOutputSchema | None
+    ) -> ResponseTextConfigParam | NotGiven:
+        if output_schema is None or output_schema.is_plain_text():
+            return NOT_GIVEN
+        else:
+            return {
+                "format": {
+                    "type": "json_schema",
+                    "name": "final_output",
+                    "schema": output_schema.json_schema(),
+                    "strict": output_schema.strict_json_schema,
+                }
+            }
+
+    @classmethod
+    def convert_tools(
+        cls,
+        tools: list[Tool],
+        handoffs: list[Handoff[Any]],
+    ) -> ConvertedTools:
+        converted_tools: list[ToolParam] = []
+        includes: list[IncludeLiteral] = []
+
+        computer_tools = [tool for tool in tools if isinstance(tool, ComputerTool)]
+        if len(computer_tools) > 1:
+            raise UserError(f"You can only provide one computer tool. Got {len(computer_tools)}")
+
+        for tool in tools:
+            converted_tool, include = cls._convert_tool(tool)
+            converted_tools.append(converted_tool)
+            if include:
+                includes.append(include)
+
+        for handoff in handoffs:
+            converted_tools.append(cls._convert_handoff_tool(handoff))
+
+        return ConvertedTools(tools=converted_tools, includes=includes)
+
+    @classmethod
+    def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, IncludeLiteral | None]:
+        """Returns converted tool and includes"""
+
+        if isinstance(tool, FunctionTool):
+            converted_tool: ToolParam = {
+                "name": tool.name,
+                "parameters": tool.params_json_schema,
+                "strict": tool.strict_json_schema,
+                "type": "function",
+                "description": tool.description,
+            }
+            includes: IncludeLiteral | None = None
+        elif isinstance(tool, WebSearchTool):
+            ws: WebSearchToolParam = {
+                "type": "web_search_preview",
+                "user_location": tool.user_location,
+                "search_context_size": tool.search_context_size,
+            }
+            converted_tool = ws
+            includes = None
+        elif isinstance(tool, FileSearchTool):
+            converted_tool = {
+                "type": "file_search",
+                "vector_store_ids": tool.vector_store_ids,
+            }
+            if tool.max_num_results:
+                converted_tool["max_num_results"] = tool.max_num_results
+            if tool.ranking_options:
+                converted_tool["ranking_options"] = tool.ranking_options
+            if tool.filters:
+                converted_tool["filters"] = tool.filters
+
+            includes = "file_search_call.results" if tool.include_search_results else None
+        elif isinstance(tool, ComputerTool):
+            converted_tool = {
+                "type": "computer-preview",
+                "environment": tool.computer.environment,
+                "display_width": tool.computer.dimensions[0],
+                "display_height": tool.computer.dimensions[1],
+            }
+            includes = None
+
+        else:
+            raise UserError(f"Unknown tool type: {type(tool)}, tool")
+
+        return converted_tool, includes
+
+    @classmethod
+    def _convert_handoff_tool(cls, handoff: Handoff) -> ToolParam:
+        return {
+            "name": handoff.tool_name,
+            "parameters": handoff.input_json_schema,
+            "strict": handoff.strict_json_schema,
+            "type": "function",
+            "description": handoff.tool_description,
+        }

agents/result.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import abc
+import asyncio
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, cast
+
+from typing_extensions import TypeVar
+
+from ._run_impl import QueueCompleteSentinel
+from .agent import Agent
+from .agent_output import AgentOutputSchema
+from .exceptions import InputGuardrailTripwireTriggered, MaxTurnsExceeded
+from .guardrail import InputGuardrailResult, OutputGuardrailResult
+from .items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem
+from .logger import logger
+from .stream_events import StreamEvent
+from .tracing import Trace
+
+if TYPE_CHECKING:
+    from ._run_impl import QueueCompleteSentinel
+    from .agent import Agent
+
+T = TypeVar("T")
+
+
+@dataclass
+class RunResultBase(abc.ABC):
+    input: str | list[TResponseInputItem]
+    """The original input items i.e. the items before run() was called. This may be a mutated
+    version of the input, if there are handoff input filters that mutate the input.
+    """
+
+    new_items: list[RunItem]
+    """The new items generated during the agent run. These include things like new messages, tool
+    calls and their outputs, etc.
+    """
+
+    raw_responses: list[ModelResponse]
+    """The raw LLM responses generated by the model during the agent run."""
+
+    final_output: Any
+    """The output of the last agent."""
+
+    input_guardrail_results: list[InputGuardrailResult]
+    """Guardrail results for the input messages."""
+
+    output_guardrail_results: list[OutputGuardrailResult]
+    """Guardrail results for the final output of the agent."""
+
+    @property
+    @abc.abstractmethod
+    def last_agent(self) -> Agent[Any]:
+        """The last agent that was run."""
+
+    def final_output_as(self, cls: type[T], raise_if_incorrect_type: bool = False) -> T:
+        """A convenience method to cast the final output to a specific type. By default, the cast
+        is only for the typechecker. If you set `raise_if_incorrect_type` to True, we'll raise a
+        TypeError if the final output is not of the given type.
+
+        Args:
+            cls: The type to cast the final output to.
+            raise_if_incorrect_type: If True, we'll raise a TypeError if the final output is not of
+                the given type.
+
+        Returns:
+            The final output casted to the given type.
+        """
+        if raise_if_incorrect_type and not isinstance(self.final_output, cls):
+            raise TypeError(f"Final output is not of type {cls.__name__}")
+
+        return cast(T, self.final_output)
+
+    def to_input_list(self) -> list[TResponseInputItem]:
+        """Creates a new input list, merging the original input with all the new items generated."""
+        original_items: list[TResponseInputItem] = ItemHelpers.input_to_new_input_list(self.input)
+        new_items = [item.to_input_item() for item in self.new_items]
+
+        return original_items + new_items
+
+
+@dataclass
+class RunResult(RunResultBase):
+    _last_agent: Agent[Any]
+
+    @property
+    def last_agent(self) -> Agent[Any]:
+        """The last agent that was run."""
+        return self._last_agent
+
+
+@dataclass
+class RunResultStreaming(RunResultBase):
+    """The result of an agent run in streaming mode. You can use the `stream_events` method to
+    receive semantic events as they are generated.
+
+    The streaming method will raise:
+    - A MaxTurnsExceeded exception if the agent exceeds the max_turns limit.
+    - A GuardrailTripwireTriggered exception if a guardrail is tripped.
+    """
+
+    current_agent: Agent[Any]
+    """The current agent that is running."""
+
+    current_turn: int
+    """The current turn number."""
+
+    max_turns: int
+    """The maximum number of turns the agent can run for."""
+
+    final_output: Any
+    """The final output of the agent. This is None until the agent has finished running."""
+
+    _current_agent_output_schema: AgentOutputSchema | None = field(repr=False)
+
+    _trace: Trace | None = field(repr=False)
+
+    is_complete: bool = False
+    """Whether the agent has finished running."""
+
+    # Queues that the background run_loop writes to
+    _event_queue: asyncio.Queue[StreamEvent | QueueCompleteSentinel] = field(
+        default_factory=asyncio.Queue, repr=False
+    )
+    _input_guardrail_queue: asyncio.Queue[InputGuardrailResult] = field(
+        default_factory=asyncio.Queue, repr=False
+    )
+
+    # Store the asyncio tasks that we're waiting on
+    _run_impl_task: asyncio.Task[Any] | None = field(default=None, repr=False)
+    _input_guardrails_task: asyncio.Task[Any] | None = field(default=None, repr=False)
+    _output_guardrails_task: asyncio.Task[Any] | None = field(default=None, repr=False)
+    _stored_exception: Exception | None = field(default=None, repr=False)
+
+    @property
+    def last_agent(self) -> Agent[Any]:
+        """The last agent that was run. Updates as the agent run progresses, so the true last agent
+        is only available after the agent run is complete.
+        """
+        return self.current_agent
+
+    async def stream_events(self) -> AsyncIterator[StreamEvent]:
+        """Stream deltas for new items as they are generated. We're using the types from the
+        OpenAI Responses API, so these are semantic events: each event has a `type` field that
+        describes the type of the event, along with the data for that event.
+
+        This will raise:
+        - A MaxTurnsExceeded exception if the agent exceeds the max_turns limit.
+        - A GuardrailTripwireTriggered exception if a guardrail is tripped.
+        """
+        while True:
+            self._check_errors()
+            if self._stored_exception:
+                logger.debug("Breaking due to stored exception")
+                self.is_complete = True
+                break
+
+            if self.is_complete and self._event_queue.empty():
+                break
+
+            try:
+                item = await self._event_queue.get()
+            except asyncio.CancelledError:
+                break
+
+            if isinstance(item, QueueCompleteSentinel):
+                self._event_queue.task_done()
+                # Check for errors, in case the queue was completed due to an exception
+                self._check_errors()
+                break
+
+            yield item
+            self._event_queue.task_done()
+
+        if self._trace:
+            self._trace.finish(reset_current=True)
+
+        self._cleanup_tasks()
+
+        if self._stored_exception:
+            raise self._stored_exception
+
+    def _check_errors(self):
+        if self.current_turn > self.max_turns:
+            self._stored_exception = MaxTurnsExceeded(f"Max turns ({self.max_turns}) exceeded")
+
+        # Fetch all the completed guardrail results from the queue and raise if needed
+        while not self._input_guardrail_queue.empty():
+            guardrail_result = self._input_guardrail_queue.get_nowait()
+            if guardrail_result.output.tripwire_triggered:
+                self._stored_exception = InputGuardrailTripwireTriggered(guardrail_result)
+
+        # Check the tasks for any exceptions
+        if self._run_impl_task and self._run_impl_task.done():
+            exc = self._run_impl_task.exception()
+            if exc and isinstance(exc, Exception):
+                self._stored_exception = exc
+
+        if self._input_guardrails_task and self._input_guardrails_task.done():
+            exc = self._input_guardrails_task.exception()
+            if exc and isinstance(exc, Exception):
+                self._stored_exception = exc
+
+        if self._output_guardrails_task and self._output_guardrails_task.done():
+            exc = self._output_guardrails_task.exception()
+            if exc and isinstance(exc, Exception):
+                self._stored_exception = exc
+
+    def _cleanup_tasks(self):
+        if self._run_impl_task and not self._run_impl_task.done():
+            self._run_impl_task.cancel()
+
+        if self._input_guardrails_task and not self._input_guardrails_task.done():
+            self._input_guardrails_task.cancel()
+
+        if self._output_guardrails_task and not self._output_guardrails_task.done():
+            self._output_guardrails_task.cancel()
+            self._output_guardrails_task.cancel()
+            self._output_guardrails_task.cancel()