openai-agents 0.0.15__py3-none-any.whl → 0.0.17__py3-none-any.whl

agents/items.py

@@ -18,7 +18,22 @@ from openai.types.responses import (
     ResponseOutputText,
     ResponseStreamEvent,
 )
-from openai.types.responses.response_input_item_param import ComputerCallOutput, FunctionCallOutput
+from openai.types.responses.response_code_interpreter_tool_call import (
+    ResponseCodeInterpreterToolCall,
+)
+from openai.types.responses.response_input_item_param import (
+    ComputerCallOutput,
+    FunctionCallOutput,
+    LocalShellCallOutput,
+    McpApprovalResponse,
+)
+from openai.types.responses.response_output_item import (
+    ImageGenerationCall,
+    LocalShellCall,
+    McpApprovalRequest,
+    McpCall,
+    McpListTools,
+)
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
 from pydantic import BaseModel
 from typing_extensions import TypeAlias
@@ -108,6 +123,10 @@ ToolCallItemTypes: TypeAlias = Union[
     ResponseComputerToolCall,
     ResponseFileSearchToolCall,
     ResponseFunctionWebSearch,
+    McpCall,
+    ResponseCodeInterpreterToolCall,
+    ImageGenerationCall,
+    LocalShellCall,
 ]
 """A type that represents a tool call item."""
 
@@ -123,10 +142,12 @@ class ToolCallItem(RunItemBase[ToolCallItemTypes]):
 
 
 @dataclass
-class ToolCallOutputItem(RunItemBase[Union[FunctionCallOutput, ComputerCallOutput]]):
+class ToolCallOutputItem(
+    RunItemBase[Union[FunctionCallOutput, ComputerCallOutput, LocalShellCallOutput]]
+):
     """Represents the output of a tool call."""
 
-    raw_item: FunctionCallOutput | ComputerCallOutput
+    raw_item: FunctionCallOutput | ComputerCallOutput | LocalShellCallOutput
     """The raw item from the model."""
 
     output: Any
@@ -147,6 +168,36 @@ class ReasoningItem(RunItemBase[ResponseReasoningItem]):
     type: Literal["reasoning_item"] = "reasoning_item"
 
 
+@dataclass
+class MCPListToolsItem(RunItemBase[McpListTools]):
+    """Represents a call to an MCP server to list tools."""
+
+    raw_item: McpListTools
+    """The raw MCP list tools call."""
+
+    type: Literal["mcp_list_tools_item"] = "mcp_list_tools_item"
+
+
+@dataclass
+class MCPApprovalRequestItem(RunItemBase[McpApprovalRequest]):
+    """Represents a request for MCP approval."""
+
+    raw_item: McpApprovalRequest
+    """The raw MCP approval request."""
+
+    type: Literal["mcp_approval_request_item"] = "mcp_approval_request_item"
+
+
+@dataclass
+class MCPApprovalResponseItem(RunItemBase[McpApprovalResponse]):
+    """Represents a response to an MCP approval request."""
+
+    raw_item: McpApprovalResponse
+    """The raw MCP approval response."""
+
+    type: Literal["mcp_approval_response_item"] = "mcp_approval_response_item"
+
+
 RunItem: TypeAlias = Union[
     MessageOutputItem,
     HandoffCallItem,
@@ -154,6 +205,9 @@ RunItem: TypeAlias = Union[
     ToolCallItem,
     ToolCallOutputItem,
     ReasoningItem,
+    MCPListToolsItem,
+    MCPApprovalRequestItem,
+    MCPApprovalResponseItem,
 ]
 """An item generated by an agent."""
 

agents/mcp/server.py

@@ -12,7 +12,7 @@ from mcp import ClientSession, StdioServerParameters, Tool as MCPTool, stdio_cli
 from mcp.client.sse import sse_client
 from mcp.client.streamable_http import GetSessionIdCallback, streamablehttp_client
 from mcp.shared.message import SessionMessage
-from mcp.types import CallToolResult
+from mcp.types import CallToolResult, InitializeResult
 from typing_extensions import NotRequired, TypedDict
 
 from ..exceptions import UserError
@@ -73,6 +73,7 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         self.exit_stack: AsyncExitStack = AsyncExitStack()
         self._cleanup_lock: asyncio.Lock = asyncio.Lock()
         self.cache_tools_list = cache_tools_list
+        self.server_initialize_result: InitializeResult | None = None
 
         self.client_session_timeout_seconds = client_session_timeout_seconds
 
@@ -87,7 +88,7 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         tuple[
             MemoryObjectReceiveStream[SessionMessage | Exception],
             MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None
+            GetSessionIdCallback | None,
         ]
     ]:
         """Create the streams for the server."""
@@ -122,7 +123,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
                     else None,
                 )
             )
-            await session.initialize()
+            server_result = await session.initialize()
+            self.server_initialize_result = server_result
             self.session = session
         except Exception as e:
             logger.error(f"Error initializing MCP server: {e}")
@@ -241,7 +243,7 @@ class MCPServerStdio(_MCPServerWithClientSession):
         tuple[
             MemoryObjectReceiveStream[SessionMessage | Exception],
             MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None
+            GetSessionIdCallback | None,
         ]
     ]:
         """Create the streams for the server."""
@@ -312,7 +314,7 @@ class MCPServerSse(_MCPServerWithClientSession):
         tuple[
             MemoryObjectReceiveStream[SessionMessage | Exception],
             MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None
+            GetSessionIdCallback | None,
         ]
     ]:
         """Create the streams for the server."""
@@ -392,7 +394,7 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
         tuple[
             MemoryObjectReceiveStream[SessionMessage | Exception],
             MemoryObjectSendStream[SessionMessage],
-            GetSessionIdCallback | None
+            GetSessionIdCallback | None,
         ]
     ]:
         """Create the streams for the server."""
@@ -401,7 +403,7 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
             headers=self.params.get("headers", None),
             timeout=self.params.get("timeout", timedelta(seconds=30)),
             sse_read_timeout=self.params.get("sse_read_timeout", timedelta(seconds=60 * 5)),
-            terminate_on_close=self.params.get("terminate_on_close", True)
+            terminate_on_close=self.params.get("terminate_on_close", True),
         )
 
     @property

agents/mcp/util.py

@@ -116,7 +116,7 @@ class MCPUtil:
         if len(result.content) == 1:
             tool_output = result.content[0].model_dump_json()
         elif len(result.content) > 1:
-            tool_output = json.dumps([item.model_dump() for item in result.content])
+            tool_output = json.dumps([item.model_dump(mode="json") for item in result.content])
         else:
             logger.error(f"Errored MCP tool result: {result}")
             tool_output = "Error running tool."

agents/models/chatcmpl_stream_handler.py

@@ -38,6 +38,16 @@ class StreamingState:
     function_calls: dict[int, ResponseFunctionToolCall] = field(default_factory=dict)
 
 
+class SequenceNumber:
+    def __init__(self):
+        self._sequence_number = 0
+
+    def get_and_increment(self) -> int:
+        num = self._sequence_number
+        self._sequence_number += 1
+        return num
+
+
 class ChatCmplStreamHandler:
     @classmethod
     async def handle_stream(
@@ -47,13 +57,14 @@ class ChatCmplStreamHandler:
     ) -> AsyncIterator[TResponseStreamEvent]:
         usage: CompletionUsage | None = None
         state = StreamingState()
-
+        sequence_number = SequenceNumber()
         async for chunk in stream:
             if not state.started:
                 state.started = True
                 yield ResponseCreatedEvent(
                     response=response,
                     type="response.created",
+                    sequence_number=sequence_number.get_and_increment(),
                 )
 
             # This is always set by the OpenAI API, but not by others e.g. LiteLLM
@@ -89,6 +100,7 @@ class ChatCmplStreamHandler:
                         item=assistant_item,
                         output_index=0,
                         type="response.output_item.added",
+                        sequence_number=sequence_number.get_and_increment(),
                     )
                     yield ResponseContentPartAddedEvent(
                         content_index=state.text_content_index_and_output[0],
@@ -100,6 +112,7 @@ class ChatCmplStreamHandler:
                             annotations=[],
                         ),
                         type="response.content_part.added",
+                        sequence_number=sequence_number.get_and_increment(),
                     )
                 # Emit the delta for this segment of content
                 yield ResponseTextDeltaEvent(
@@ -108,6 +121,7 @@ class ChatCmplStreamHandler:
                     item_id=FAKE_RESPONSES_ID,
                     output_index=0,
                     type="response.output_text.delta",
+                    sequence_number=sequence_number.get_and_increment(),
                 )
                 # Accumulate the text into the response part
                 state.text_content_index_and_output[1].text += delta.content
@@ -134,6 +148,7 @@ class ChatCmplStreamHandler:
                         item=assistant_item,
                         output_index=0,
                         type="response.output_item.added",
+                        sequence_number=sequence_number.get_and_increment(),
                     )
                     yield ResponseContentPartAddedEvent(
                         content_index=state.refusal_content_index_and_output[0],
@@ -145,6 +160,7 @@ class ChatCmplStreamHandler:
                             annotations=[],
                         ),
                         type="response.content_part.added",
+                        sequence_number=sequence_number.get_and_increment(),
                     )
                 # Emit the delta for this segment of refusal
                 yield ResponseRefusalDeltaEvent(
@@ -153,6 +169,7 @@ class ChatCmplStreamHandler:
                     item_id=FAKE_RESPONSES_ID,
                     output_index=0,
                     type="response.refusal.delta",
+                    sequence_number=sequence_number.get_and_increment(),
                 )
                 # Accumulate the refusal string in the output part
                 state.refusal_content_index_and_output[1].refusal += delta.refusal
@@ -190,6 +207,7 @@ class ChatCmplStreamHandler:
                 output_index=0,
                 part=state.text_content_index_and_output[1],
                 type="response.content_part.done",
+                sequence_number=sequence_number.get_and_increment(),
             )
 
         if state.refusal_content_index_and_output:
@@ -201,6 +219,7 @@ class ChatCmplStreamHandler:
                 output_index=0,
                 part=state.refusal_content_index_and_output[1],
                 type="response.content_part.done",
+                sequence_number=sequence_number.get_and_increment(),
             )
 
         # Actually send events for the function calls
@@ -216,6 +235,7 @@ class ChatCmplStreamHandler:
                 ),
                 output_index=function_call_starting_index,
                 type="response.output_item.added",
+                sequence_number=sequence_number.get_and_increment(),
             )
             # Then, yield the args
             yield ResponseFunctionCallArgumentsDeltaEvent(
@@ -223,6 +243,7 @@ class ChatCmplStreamHandler:
                 item_id=FAKE_RESPONSES_ID,
                 output_index=function_call_starting_index,
                 type="response.function_call_arguments.delta",
+                sequence_number=sequence_number.get_and_increment(),
             )
             # Finally, the ResponseOutputItemDone
             yield ResponseOutputItemDoneEvent(
@@ -235,6 +256,7 @@ class ChatCmplStreamHandler:
                 ),
                 output_index=function_call_starting_index,
                 type="response.output_item.done",
+                sequence_number=sequence_number.get_and_increment(),
             )
 
         # Finally, send the Response completed event
@@ -258,6 +280,7 @@ class ChatCmplStreamHandler:
                 item=assistant_msg,
                 output_index=0,
                 type="response.output_item.done",
+                sequence_number=sequence_number.get_and_increment(),
             )
 
         for function_call in state.function_calls.values():
@@ -289,4 +312,5 @@ class ChatCmplStreamHandler:
         yield ResponseCompletedEvent(
             response=final_response,
             type="response.completed",
+            sequence_number=sequence_number.get_and_increment(),
         )

agents/models/openai_chatcompletions.py

@@ -9,6 +9,7 @@ from openai import NOT_GIVEN, AsyncOpenAI, AsyncStream
 from openai.types import ChatModel
 from openai.types.chat import ChatCompletion, ChatCompletionChunk
 from openai.types.responses import Response
+from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from .. import _debug
 from ..agent_output import AgentOutputSchemaBase
@@ -70,12 +71,22 @@ class OpenAIChatCompletionsModel(Model):
                 stream=False,
             )
 
+            first_choice = response.choices[0]
+            message = first_choice.message
+
             if _debug.DONT_LOG_MODEL_DATA:
                 logger.debug("Received model response")
             else:
-                logger.debug(
-                    f"LLM resp:\n{json.dumps(response.choices[0].message.model_dump(), indent=2)}\n"
-                )
+                if message is not None:
+                    logger.debug(
+                        "LLM resp:\n%s\n",
+                        json.dumps(message.model_dump(), indent=2),
+                    )
+                else:
+                    logger.debug(
+                        "LLM resp had no message. finish_reason: %s",
+                        first_choice.finish_reason,
+                    )
 
             usage = (
                 Usage(
@@ -83,18 +94,32 @@ class OpenAIChatCompletionsModel(Model):
                     input_tokens=response.usage.prompt_tokens,
                     output_tokens=response.usage.completion_tokens,
                     total_tokens=response.usage.total_tokens,
+                    input_tokens_details=InputTokensDetails(
+                        cached_tokens=getattr(
+                            response.usage.prompt_tokens_details, "cached_tokens", 0
+                        )
+                        or 0,
+                    ),
+                    output_tokens_details=OutputTokensDetails(
+                        reasoning_tokens=getattr(
+                            response.usage.completion_tokens_details, "reasoning_tokens", 0
+                        )
+                        or 0,
+                    ),
                 )
                 if response.usage
                 else Usage()
             )
             if tracing.include_data():
-                span_generation.span_data.output = [response.choices[0].message.model_dump()]
+                span_generation.span_data.output = (
+                    [message.model_dump()] if message is not None else []
+                )
             span_generation.span_data.usage = {
                 "input_tokens": usage.input_tokens,
                 "output_tokens": usage.output_tokens,
             }
 
-            items = Converter.message_to_output_items(response.choices[0].message)
+            items = Converter.message_to_output_items(message) if message is not None else []
 
             return ModelResponse(
                 output=items,
@@ -252,7 +277,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, **(model_settings.extra_headers or {}) },
+            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),

agents/models/openai_responses.py

@@ -10,6 +10,7 @@ from openai.types import ChatModel
 from openai.types.responses import (
     Response,
     ResponseCompletedEvent,
+    ResponseIncludable,
     ResponseStreamEvent,
     ResponseTextConfigParam,
     ToolParam,
@@ -23,7 +24,17 @@ 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 ..tool import (
+    CodeInterpreterTool,
+    ComputerTool,
+    FileSearchTool,
+    FunctionTool,
+    HostedMCPTool,
+    ImageGenerationTool,
+    LocalShellTool,
+    Tool,
+    WebSearchTool,
+)
 from ..tracing import SpanError, response_span
 from ..usage import Usage
 from ..version import __version__
@@ -36,13 +47,6 @@ if TYPE_CHECKING:
 _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):
     """
@@ -98,6 +102,8 @@ class OpenAIResponsesModel(Model):
                         input_tokens=response.usage.input_tokens,
                         output_tokens=response.usage.output_tokens,
                         total_tokens=response.usage.total_tokens,
+                        input_tokens_details=response.usage.input_tokens_details,
+                        output_tokens_details=response.usage.output_tokens_details,
                     )
                     if response.usage
                     else Usage()
@@ -271,7 +277,7 @@ class OpenAIResponsesModel(Model):
 @dataclass
 class ConvertedTools:
     tools: list[ToolParam]
-    includes: list[IncludeLiteral]
+    includes: list[ResponseIncludable]
 
 
 class Converter:
@@ -299,6 +305,18 @@ class Converter:
             return {
                 "type": "computer_use_preview",
             }
+        elif tool_choice == "image_generation":
+            return {
+                "type": "image_generation",
+            }
+        elif tool_choice == "code_interpreter":
+            return {
+                "type": "code_interpreter",
+            }
+        elif tool_choice == "mcp":
+            return {
+                "type": "mcp",
+            }
         else:
             return {
                 "type": "function",
@@ -328,7 +346,7 @@ class Converter:
         handoffs: list[Handoff[Any]],
     ) -> ConvertedTools:
         converted_tools: list[ToolParam] = []
-        includes: list[IncludeLiteral] = []
+        includes: list[ResponseIncludable] = []
 
         computer_tools = [tool for tool in tools if isinstance(tool, ComputerTool)]
         if len(computer_tools) > 1:
@@ -346,7 +364,7 @@ class Converter:
         return ConvertedTools(tools=converted_tools, includes=includes)
 
     @classmethod
-    def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, IncludeLiteral | None]:
+    def _convert_tool(cls, tool: Tool) -> tuple[ToolParam, ResponseIncludable | None]:
         """Returns converted tool and includes"""
 
         if isinstance(tool, FunctionTool):
@@ -357,7 +375,7 @@ class Converter:
                 "type": "function",
                 "description": tool.description,
             }
-            includes: IncludeLiteral | None = None
+            includes: ResponseIncludable | None = None
         elif isinstance(tool, WebSearchTool):
             ws: WebSearchToolParam = {
                 "type": "web_search_preview",
@@ -387,7 +405,20 @@ class Converter:
                 "display_height": tool.computer.dimensions[1],
             }
             includes = None
-
+        elif isinstance(tool, HostedMCPTool):
+            converted_tool = tool.tool_config
+            includes = None
+        elif isinstance(tool, ImageGenerationTool):
+            converted_tool = tool.tool_config
+            includes = None
+        elif isinstance(tool, CodeInterpreterTool):
+            converted_tool = tool.tool_config
+            includes = None
+        elif isinstance(tool, LocalShellTool):
+            converted_tool = {
+                "type": "local_shell",
+            }
+            includes = None
         else:
             raise UserError(f"Unknown tool type: {type(tool)}, tool")
 

agents/result.py

@@ -11,14 +11,22 @@ from typing_extensions import TypeVar
 from ._run_impl import QueueCompleteSentinel
 from .agent import Agent
 from .agent_output import AgentOutputSchemaBase
-from .exceptions import InputGuardrailTripwireTriggered, MaxTurnsExceeded
+from .exceptions import (
+    AgentsException,
+    InputGuardrailTripwireTriggered,
+    MaxTurnsExceeded,
+    RunErrorDetails,
+)
 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
+from .util._pretty_print import (
+    pretty_print_result,
+    pretty_print_run_result_streaming,
+)
 
 if TYPE_CHECKING:
     from ._run_impl import QueueCompleteSentinel
@@ -206,31 +214,53 @@ class RunResultStreaming(RunResultBase):
         if self._stored_exception:
             raise self._stored_exception
 
+    def _create_error_details(self) -> RunErrorDetails:
+        """Return a `RunErrorDetails` object considering the current attributes of the class."""
+        return RunErrorDetails(
+            input=self.input,
+            new_items=self.new_items,
+            raw_responses=self.raw_responses,
+            last_agent=self.current_agent,
+            context_wrapper=self.context_wrapper,
+            input_guardrail_results=self.input_guardrail_results,
+            output_guardrail_results=self.output_guardrail_results,
+        )
+
     def _check_errors(self):
         if self.current_turn > self.max_turns:
-            self._stored_exception = MaxTurnsExceeded(f"Max turns ({self.max_turns}) exceeded")
+            max_turns_exc = MaxTurnsExceeded(f"Max turns ({self.max_turns}) exceeded")
+            max_turns_exc.run_data = self._create_error_details()
+            self._stored_exception = max_turns_exc
 
         # 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)
+                tripwire_exc = InputGuardrailTripwireTriggered(guardrail_result)
+                tripwire_exc.run_data = self._create_error_details()
+                self._stored_exception = tripwire_exc
 
         # 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
+            run_impl_exc = self._run_impl_task.exception()
+            if run_impl_exc and isinstance(run_impl_exc, Exception):
+                if isinstance(run_impl_exc, AgentsException) and run_impl_exc.run_data is None:
+                    run_impl_exc.run_data = self._create_error_details()
+                self._stored_exception = run_impl_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
+            in_guard_exc = self._input_guardrails_task.exception()
+            if in_guard_exc and isinstance(in_guard_exc, Exception):
+                if isinstance(in_guard_exc, AgentsException) and in_guard_exc.run_data is None:
+                    in_guard_exc.run_data = self._create_error_details()
+                self._stored_exception = in_guard_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
+            out_guard_exc = self._output_guardrails_task.exception()
+            if out_guard_exc and isinstance(out_guard_exc, Exception):
+                if isinstance(out_guard_exc, AgentsException) and out_guard_exc.run_data is None:
+                    out_guard_exc.run_data = self._create_error_details()
+                self._stored_exception = out_guard_exc
 
     def _cleanup_tasks(self):
         if self._run_impl_task and not self._run_impl_task.done():