openai-agents 0.0.12__tar.gz → 0.0.14__tar.gz

{openai_agents-0.0.12 → openai_agents-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.0.12
+Version: 0.0.14
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://github.com/openai/openai-agents-python
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -20,13 +20,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
 Requires-Dist: mcp<2,>=1.6.0; python_version >= '3.10'
-Requires-Dist: openai>=1.66.5
+Requires-Dist: openai>=1.76.0
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0
 Requires-Dist: typing-extensions<5,>=4.12.2
 Provides-Extra: litellm
-Requires-Dist: litellm<2,>=1.65.0; extra == 'litellm'
+Requires-Dist: litellm<2,>=1.67.4.post1; extra == 'litellm'
 Provides-Extra: viz
 Requires-Dist: graphviz>=0.17; extra == 'viz'
 Provides-Extra: voice

{openai_agents-0.0.12 → openai_agents-0.0.14}/docs/tracing.md

@@ -101,6 +101,7 @@ To customize this default setup, to send traces to alternative or additional bac
 
 -   [Weights & Biases](https://weave-docs.wandb.ai/guides/integrations/openai_agents)
 -   [Arize-Phoenix](https://docs.arize.com/phoenix/tracing/integrations-tracing/openai-agents-sdk)
+-   [Future AGI](https://docs.futureagi.com/future-agi/products/observability/auto-instrumentation/openai_agents)
 -   [MLflow (self-hosted/OSS](https://mlflow.org/docs/latest/tracing/integrations/openai-agent)
 -   [MLflow (Databricks hosted](https://docs.databricks.com/aws/en/mlflow/mlflow-tracing#-automatic-tracing)
 -   [Braintrust](https://braintrust.dev/docs/guides/traces/integrations#openai-agents-sdk)

{openai_agents-0.0.12 → openai_agents-0.0.14}/examples/financial_research_agent/main.py

@@ -4,7 +4,7 @@ from .manager import FinancialResearchManager
 
 
 # Entrypoint for the financial bot example.
-# Run this as `python -m examples.financial_bot.main` and enter a
+# Run this as `python -m examples.financial_research_agent.main` and enter a
 # financial research query, for example:
 # "Write up an analysis of Apple Inc.'s most recent quarter."
 async def main() -> None:

{openai_agents-0.0.12 → openai_agents-0.0.14}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "openai-agents"
-version = "0.0.12"
+version = "0.0.14"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "OpenAI", email = "support@openai.com" }]
 dependencies = [
-    "openai>=1.66.5",
+    "openai>=1.76.0",
     "pydantic>=2.10, <3",
     "griffe>=1.5.6, <2",
     "typing-extensions>=4.12.2, <5",
@@ -36,7 +36,7 @@ Repository = "https://github.com/openai/openai-agents-python"
 [project.optional-dependencies]
 voice = ["numpy>=2.2.0, <3; python_version>='3.10'", "websockets>=15.0, <16"]
 viz = ["graphviz>=0.17"]
-litellm = ["litellm>=1.65.0, <2"]
+litellm = ["litellm>=1.67.4.post1, <2"]
 
 [dependency-groups]
 dev = [

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/extensions/models/litellm_model.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import dataclasses
 import json
 import time
 from collections.abc import AsyncIterator
@@ -75,7 +74,7 @@ class LitellmModel(Model):
     ) -> ModelResponse:
         with generation_span(
             model=str(self.model),
-            model_config=dataclasses.asdict(model_settings)
+            model_config=model_settings.to_json_dict()
             | {"base_url": str(self.base_url or ""), "model_impl": "litellm"},
             disabled=tracing.is_disabled(),
         ) as span_generation:
@@ -147,7 +146,7 @@ class LitellmModel(Model):
     ) -> AsyncIterator[TResponseStreamEvent]:
         with generation_span(
             model=str(self.model),
-            model_config=dataclasses.asdict(model_settings)
+            model_config=model_settings.to_json_dict()
             | {"base_url": str(self.base_url or ""), "model_impl": "litellm"},
             disabled=tracing.is_disabled(),
         ) as span_generation:
@@ -286,7 +285,7 @@ class LitellmModel(Model):
             stream=stream,
             stream_options=stream_options,
             reasoning_effort=reasoning_effort,
-            extra_headers=HEADERS,
+            extra_headers={**HEADERS, **(model_settings.extra_headers or {})},
             api_key=self.api_key,
             base_url=self.base_url,
             **extra_kwargs,

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/mcp/server.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import abc
 import asyncio
 from contextlib import AbstractAsyncContextManager, AsyncExitStack
+from datetime import timedelta
 from pathlib import Path
 from typing import Any, Literal
 
@@ -54,7 +55,7 @@ class MCPServer(abc.ABC):
 class _MCPServerWithClientSession(MCPServer, abc.ABC):
     """Base class for MCP servers that use a `ClientSession` to communicate with the server."""
 
-    def __init__(self, cache_tools_list: bool):
+    def __init__(self, cache_tools_list: bool, client_session_timeout_seconds: float | None):
         """
         Args:
             cache_tools_list: Whether to cache the tools list. If `True`, the tools list will be
@@ -63,12 +64,16 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
             by calling `invalidate_tools_cache()`. You should set this to `True` if you know the
             server will not change its tools list, because it can drastically improve latency
             (by avoiding a round-trip to the server every time).
+
+            client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
         """
         self.session: ClientSession | None = None
         self.exit_stack: AsyncExitStack = AsyncExitStack()
         self._cleanup_lock: asyncio.Lock = asyncio.Lock()
         self.cache_tools_list = cache_tools_list
 
+        self.client_session_timeout_seconds = client_session_timeout_seconds
+
         # The cache is always dirty at startup, so that we fetch tools at least once
         self._cache_dirty = True
         self._tools_list: list[MCPTool] | None = None
@@ -101,7 +106,15 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         try:
             transport = await self.exit_stack.enter_async_context(self.create_streams())
             read, write = transport
-            session = await self.exit_stack.enter_async_context(ClientSession(read, write))
+            session = await self.exit_stack.enter_async_context(
+                ClientSession(
+                    read,
+                    write,
+                    timedelta(seconds=self.client_session_timeout_seconds)
+                    if self.client_session_timeout_seconds
+                    else None,
+                )
+            )
             await session.initialize()
             self.session = session
         except Exception as e:
@@ -183,6 +196,7 @@ class MCPServerStdio(_MCPServerWithClientSession):
         params: MCPServerStdioParams,
         cache_tools_list: bool = False,
         name: str | None = None,
+        client_session_timeout_seconds: float | None = 5,
     ):
         """Create a new MCP server based on the stdio transport.
 
@@ -199,8 +213,9 @@ class MCPServerStdio(_MCPServerWithClientSession):
                 improve latency (by avoiding a round-trip to the server every time).
             name: A readable name for the server. If not provided, we'll create one from the
                 command.
+            client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
         """
-        super().__init__(cache_tools_list)
+        super().__init__(cache_tools_list, client_session_timeout_seconds)
 
         self.params = StdioServerParameters(
             command=params["command"],
@@ -257,6 +272,7 @@ class MCPServerSse(_MCPServerWithClientSession):
         params: MCPServerSseParams,
         cache_tools_list: bool = False,
         name: str | None = None,
+        client_session_timeout_seconds: float | None = 5,
     ):
         """Create a new MCP server based on the HTTP with SSE transport.
 
@@ -274,8 +290,10 @@ class MCPServerSse(_MCPServerWithClientSession):
 
             name: A readable name for the server. If not provided, we'll create one from the
                 URL.
+
+            client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
         """
-        super().__init__(cache_tools_list)
+        super().__init__(cache_tools_list, client_session_timeout_seconds)
 
         self.params = params
         self._name = name or f"sse: {self.params['url']}"

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/model_settings.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import dataclasses
 from dataclasses import dataclass, fields, replace
-from typing import Literal
+from typing import Any, Literal
 
-from openai._types import Body, Query
+from openai._types import Body, Headers, Query
 from openai.types.shared import Reasoning
+from pydantic import BaseModel
 
 
 @dataclass
@@ -67,6 +69,10 @@ class ModelSettings:
     """Additional body fields to provide with the request.
     Defaults to None if not provided."""
 
+    extra_headers: Headers | None = None
+    """Additional headers to provide with the request.
+    Defaults to None if not provided."""
+
     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."""
@@ -79,3 +85,16 @@ class ModelSettings:
             if getattr(override, field.name) is not None
         }
         return replace(self, **changes)
+
+    def to_json_dict(self) -> dict[str, Any]:
+        dataclass_dict = dataclasses.asdict(self)
+
+        json_dict: dict[str, Any] = {}
+
+        for field_name, value in dataclass_dict.items():
+            if isinstance(value, BaseModel):
+                json_dict[field_name] = value.model_dump(mode="json")
+            else:
+                json_dict[field_name] = value
+
+        return json_dict

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/models/chatcmpl_stream_handler.py

@@ -56,7 +56,8 @@ class ChatCmplStreamHandler:
                     type="response.created",
                 )
 
-            usage = chunk.usage
+            # This is always set by the OpenAI API, but not by others e.g. LiteLLM
+            usage = chunk.usage if hasattr(chunk, "usage") else None
 
             if not chunk.choices or not chunk.choices[0].delta:
                 continue
@@ -112,7 +113,8 @@ class ChatCmplStreamHandler:
                 state.text_content_index_and_output[1].text += delta.content
 
             # Handle refusals (model declines to answer)
-            if delta.refusal:
+            # This is always set by the OpenAI API, but not by others e.g. LiteLLM
+            if hasattr(delta, "refusal") and delta.refusal:
                 if not state.refusal_content_index_and_output:
                     # Initialize a content tracker for streaming refusal text
                     state.refusal_content_index_and_output = (

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/models/openai_chatcompletions.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import dataclasses
 import json
 import time
 from collections.abc import AsyncIterator
@@ -56,8 +55,7 @@ class OpenAIChatCompletionsModel(Model):
     ) -> ModelResponse:
         with generation_span(
             model=str(self.model),
-            model_config=dataclasses.asdict(model_settings)
-            | {"base_url": str(self._client.base_url)},
+            model_config=model_settings.to_json_dict() | {"base_url": str(self._client.base_url)},
             disabled=tracing.is_disabled(),
         ) as span_generation:
             response = await self._fetch_response(
@@ -121,8 +119,7 @@ class OpenAIChatCompletionsModel(Model):
         """
         with generation_span(
             model=str(self.model),
-            model_config=dataclasses.asdict(model_settings)
-            | {"base_url": str(self._client.base_url)},
+            model_config=model_settings.to_json_dict() | {"base_url": str(self._client.base_url)},
             disabled=tracing.is_disabled(),
         ) as span_generation:
             response, stream = await self._fetch_response(
@@ -255,7 +252,7 @@ class OpenAIChatCompletionsModel(Model):
             stream_options=self._non_null_or_not_given(stream_options),
             store=self._non_null_or_not_given(store),
             reasoning_effort=self._non_null_or_not_given(reasoning_effort),
-            extra_headers=HEADERS,
+            extra_headers={ **HEADERS, **(model_settings.extra_headers or {}) },
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             metadata=self._non_null_or_not_given(model_settings.metadata),

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/models/openai_responses.py

@@ -253,7 +253,7 @@ class OpenAIResponsesModel(Model):
             tool_choice=tool_choice,
             parallel_tool_calls=parallel_tool_calls,
             stream=stream,
-            extra_headers=_HEADERS,
+            extra_headers={**_HEADERS, **(model_settings.extra_headers or {})},
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             text=response_format,

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/result.py

@@ -15,6 +15,7 @@ from .exceptions import InputGuardrailTripwireTriggered, MaxTurnsExceeded
 from .guardrail import InputGuardrailResult, OutputGuardrailResult
 from .items import ItemHelpers, ModelResponse, RunItem, TResponseInputItem
 from .logger import logger
+from .run_context import RunContextWrapper
 from .stream_events import StreamEvent
 from .tracing import Trace
 from .util._pretty_print import pretty_print_result, pretty_print_run_result_streaming
@@ -50,6 +51,9 @@ class RunResultBase(abc.ABC):
     output_guardrail_results: list[OutputGuardrailResult]
     """Guardrail results for the final output of the agent."""
 
+    context_wrapper: RunContextWrapper[Any]
+    """The context wrapper for the agent run."""
+
     @property
     @abc.abstractmethod
     def last_agent(self) -> Agent[Any]:
@@ -152,6 +156,18 @@ class RunResultStreaming(RunResultBase):
         """
         return self.current_agent
 
+    def cancel(self) -> None:
+        """Cancels the streaming run, stopping all background tasks and marking the run as
+        complete."""
+        self._cleanup_tasks()  # Cancel all running tasks
+        self.is_complete = True  # Mark the run as complete to stop event streaming
+
+        # Optionally, clear the event queue to prevent processing stale events
+        while not self._event_queue.empty():
+            self._event_queue.get_nowait()
+        while not self._input_guardrail_queue.empty():
+            self._input_guardrail_queue.get_nowait()
+
     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

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/run.py

@@ -270,6 +270,7 @@ class Runner:
                             _last_agent=current_agent,
                             input_guardrail_results=input_guardrail_results,
                             output_guardrail_results=output_guardrail_results,
+                            context_wrapper=context_wrapper,
                         )
                     elif isinstance(turn_result.next_step, NextStepHandoff):
                         current_agent = cast(Agent[TContext], turn_result.next_step.new_agent)
@@ -423,6 +424,7 @@ class Runner:
             output_guardrail_results=[],
             _current_agent_output_schema=output_schema,
             trace=new_trace,
+            context_wrapper=context_wrapper,
         )
 
         # Kick off the actual agent loop in the background and return the streamed result object.
@@ -696,6 +698,7 @@ class Runner:
                     usage=usage,
                     response_id=event.response.id,
                 )
+                context_wrapper.usage.add(usage)
 
             streamed_result._event_queue.put_nowait(RawResponsesStreamEvent(data=event))
 

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/voice/__init__.py

@@ -7,6 +7,7 @@ from .model import (
     STTModelSettings,
     TTSModel,
     TTSModelSettings,
+    TTSVoice,
     VoiceModelProvider,
 )
 from .models.openai_model_provider import OpenAIVoiceModelProvider
@@ -30,6 +31,7 @@ __all__ = [
     "STTModelSettings",
     "TTSModel",
     "TTSModelSettings",
+    "TTSVoice",
     "VoiceModelProvider",
     "StreamedAudioResult",
     "SingleAgentVoiceWorkflow",

{openai_agents-0.0.12 → openai_agents-0.0.14}/src/agents/voice/model.py

@@ -14,14 +14,13 @@ DEFAULT_TTS_INSTRUCTIONS = (
 )
 DEFAULT_TTS_BUFFER_SIZE = 120
 
+TTSVoice = Literal["alloy", "ash", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer"]
+"""Exportable type for the TTSModelSettings voice enum"""
 
 @dataclass
 class TTSModelSettings:
     """Settings for a TTS model."""
-
-    voice: (
-        Literal["alloy", "ash", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer"] | None
-    ) = None
+    voice: TTSVoice | None = None
     """
     The voice to use for the TTS model. If not provided, the default voice for the respective model
     will be used.

{openai_agents-0.0.12 → openai_agents-0.0.14}/tests/fake_model.py

@@ -3,7 +3,8 @@ from __future__ import annotations
 from collections.abc import AsyncIterator
 from typing import Any
 
-from openai.types.responses import Response, ResponseCompletedEvent
+from openai.types.responses import Response, ResponseCompletedEvent, ResponseUsage
+from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from agents.agent_output import AgentOutputSchemaBase
 from agents.handoffs import Handoff
@@ -33,6 +34,10 @@ class FakeModel(Model):
         )
         self.tracing_enabled = tracing_enabled
         self.last_turn_args: dict[str, Any] = {}
+        self.hardcoded_usage: Usage | None = None
+
+    def set_hardcoded_usage(self, usage: Usage):
+        self.hardcoded_usage = usage
 
     def set_next_output(self, output: list[TResponseOutputItem] | Exception):
         self.turn_outputs.append(output)
@@ -83,7 +88,7 @@ class FakeModel(Model):
 
             return ModelResponse(
                 output=output,
-                usage=Usage(),
+                usage=self.hardcoded_usage or Usage(),
                 response_id=None,
             )
 
@@ -123,11 +128,15 @@ class FakeModel(Model):
 
             yield ResponseCompletedEvent(
                 type="response.completed",
-                response=get_response_obj(output),
+                response=get_response_obj(output, usage=self.hardcoded_usage),
             )
 
 
-def get_response_obj(output: list[TResponseOutputItem], response_id: str | None = None) -> Response:
+def get_response_obj(
+    output: list[TResponseOutputItem],
+    response_id: str | None = None,
+    usage: Usage | None = None,
+) -> Response:
     return Response(
         id=response_id or "123",
         created_at=123,
@@ -138,4 +147,11 @@ def get_response_obj(output: list[TResponseOutputItem], response_id: str | None
         tools=[],
         top_p=None,
         parallel_tool_calls=False,
+        usage=ResponseUsage(
+            input_tokens=usage.input_tokens if usage else 0,
+            output_tokens=usage.output_tokens if usage else 0,
+            total_tokens=usage.total_tokens if usage else 0,
+            input_tokens_details=InputTokensDetails(cached_tokens=0),
+            output_tokens_details=OutputTokensDetails(reasoning_tokens=0),
+        ),
     )

{openai_agents-0.0.12 → openai_agents-0.0.14}/tests/mcp/test_server_errors.py

@@ -6,7 +6,7 @@ from agents.mcp.server import _MCPServerWithClientSession
 
 class CrashingClientSessionServer(_MCPServerWithClientSession):
     def __init__(self):
-        super().__init__(cache_tools_list=False)
+        super().__init__(cache_tools_list=False, client_session_timeout_seconds=5)
         self.cleanup_called = False
 
     def create_streams(self):

openai_agents-0.0.14/tests/model_settings/test_serialization.py

@@ -0,0 +1,59 @@
+import json
+from dataclasses import fields
+
+from openai.types.shared import Reasoning
+
+from agents.model_settings import ModelSettings
+
+
+def verify_serialization(model_settings: ModelSettings) -> None:
+    """Verify that ModelSettings can be serialized to a JSON string."""
+    json_dict = model_settings.to_json_dict()
+    json_string = json.dumps(json_dict)
+    assert json_string is not None
+
+
+def test_basic_serialization() -> None:
+    """Tests whether ModelSettings can be serialized to a JSON string."""
+
+    # First, lets create a ModelSettings instance
+    model_settings = ModelSettings(
+        temperature=0.5,
+        top_p=0.9,
+        max_tokens=100,
+    )
+
+    # Now, lets serialize the ModelSettings instance to a JSON string
+    verify_serialization(model_settings)
+
+
+def test_all_fields_serialization() -> None:
+    """Tests whether ModelSettings can be serialized to a JSON string."""
+
+    # First, lets create a ModelSettings instance
+    model_settings = ModelSettings(
+        temperature=0.5,
+        top_p=0.9,
+        frequency_penalty=0.0,
+        presence_penalty=0.0,
+        tool_choice="auto",
+        parallel_tool_calls=True,
+        truncation="auto",
+        max_tokens=100,
+        reasoning=Reasoning(),
+        metadata={"foo": "bar"},
+        store=False,
+        include_usage=False,
+        extra_query={"foo": "bar"},
+        extra_body={"foo": "bar"},
+        extra_headers={"foo": "bar"},
+    )
+
+    # Verify that every single field is set to a non-None value
+    for field in fields(model_settings):
+        assert getattr(model_settings, field.name) is not None, (
+            f"You must set the {field.name} field"
+        )
+
+    # Now, lets serialize the ModelSettings instance to a JSON string
+    verify_serialization(model_settings)