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

agents/__init__.py

@@ -54,10 +54,19 @@ from .stream_events import (
     StreamEvent,
 )
 from .tool import (
+    CodeInterpreterTool,
     ComputerTool,
     FileSearchTool,
     FunctionTool,
     FunctionToolResult,
+    HostedMCPTool,
+    ImageGenerationTool,
+    LocalShellCommandRequest,
+    LocalShellExecutor,
+    LocalShellTool,
+    MCPToolApprovalFunction,
+    MCPToolApprovalFunctionResult,
+    MCPToolApprovalRequest,
     Tool,
     WebSearchTool,
     default_tool_error_function,
@@ -206,8 +215,17 @@ __all__ = [
     "FunctionToolResult",
     "ComputerTool",
     "FileSearchTool",
+    "CodeInterpreterTool",
+    "ImageGenerationTool",
+    "LocalShellCommandRequest",
+    "LocalShellExecutor",
+    "LocalShellTool",
     "Tool",
     "WebSearchTool",
+    "HostedMCPTool",
+    "MCPToolApprovalFunction",
+    "MCPToolApprovalRequest",
+    "MCPToolApprovalFunctionResult",
     "function_tool",
     "Usage",
     "add_trace_processor",

agents/_run_impl.py

@@ -14,6 +14,9 @@ from openai.types.responses import (
     ResponseFunctionWebSearch,
     ResponseOutputMessage,
 )
+from openai.types.responses.response_code_interpreter_tool_call import (
+    ResponseCodeInterpreterToolCall,
+)
 from openai.types.responses.response_computer_tool_call import (
     ActionClick,
     ActionDoubleClick,
@@ -25,7 +28,13 @@ from openai.types.responses.response_computer_tool_call import (
     ActionType,
     ActionWait,
 )
-from openai.types.responses.response_input_param import ComputerCallOutput
+from openai.types.responses.response_input_param import ComputerCallOutput, McpApprovalResponse
+from openai.types.responses.response_output_item import (
+    ImageGenerationCall,
+    LocalShellCall,
+    McpApprovalRequest,
+    McpListTools,
+)
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
 
 from .agent import Agent, ToolsToFinalOutputResult
@@ -38,6 +47,9 @@ from .items import (
     HandoffCallItem,
     HandoffOutputItem,
     ItemHelpers,
+    MCPApprovalRequestItem,
+    MCPApprovalResponseItem,
+    MCPListToolsItem,
     MessageOutputItem,
     ModelResponse,
     ReasoningItem,
@@ -52,7 +64,16 @@ from .model_settings import ModelSettings
 from .models.interface import ModelTracing
 from .run_context import RunContextWrapper, TContext
 from .stream_events import RunItemStreamEvent, StreamEvent
-from .tool import ComputerTool, FunctionTool, FunctionToolResult, Tool
+from .tool import (
+    ComputerTool,
+    FunctionTool,
+    FunctionToolResult,
+    HostedMCPTool,
+    LocalShellCommandRequest,
+    LocalShellTool,
+    MCPToolApprovalRequest,
+    Tool,
+)
 from .tracing import (
     SpanError,
     Trace,
@@ -112,15 +133,29 @@ class ToolRunComputerAction:
     computer_tool: ComputerTool
 
 
+@dataclass
+class ToolRunMCPApprovalRequest:
+    request_item: McpApprovalRequest
+    mcp_tool: HostedMCPTool
+
+
+@dataclass
+class ToolRunLocalShellCall:
+    tool_call: LocalShellCall
+    local_shell_tool: LocalShellTool
+
+
 @dataclass
 class ProcessedResponse:
     new_items: list[RunItem]
     handoffs: list[ToolRunHandoff]
     functions: list[ToolRunFunction]
     computer_actions: list[ToolRunComputerAction]
+    local_shell_calls: list[ToolRunLocalShellCall]
     tools_used: list[str]  # Names of all tools used, including hosted tools
+    mcp_approval_requests: list[ToolRunMCPApprovalRequest]  # Only requests with callbacks
 
-    def has_tools_to_run(self) -> bool:
+    def has_tools_or_approvals_to_run(self) -> bool:
         # Handoffs, functions and computer actions need local processing
         # Hosted tools have already run, so there's nothing to do.
         return any(
@@ -128,6 +163,8 @@ class ProcessedResponse:
                 self.handoffs,
                 self.functions,
                 self.computer_actions,
+                self.local_shell_calls,
+                self.mcp_approval_requests,
             ]
         )
 
@@ -226,7 +263,16 @@ class RunImpl:
         new_step_items.extend([result.run_item for result in function_results])
         new_step_items.extend(computer_results)
 
-        # Second, check if there are any handoffs
+        # Next, run the MCP approval requests
+        if processed_response.mcp_approval_requests:
+            approval_results = await cls.execute_mcp_approval_requests(
+                agent=agent,
+                approval_requests=processed_response.mcp_approval_requests,
+                context_wrapper=context_wrapper,
+            )
+            new_step_items.extend(approval_results)
+
+        # Next, check if there are any handoffs
         if run_handoffs := processed_response.handoffs:
             return await cls.execute_handoffs(
                 agent=agent,
@@ -240,7 +286,7 @@ class RunImpl:
                 run_config=run_config,
             )
 
-        # Third, we'll check if the tool use should result in a final output
+        # Next, we'll check if the tool use should result in a final output
         check_tool_use = await cls._check_for_final_output_from_tools(
             agent=agent,
             tool_results=function_results,
@@ -295,7 +341,7 @@ class RunImpl:
             )
         elif (
             not output_schema or output_schema.is_plain_text()
-        ) and not processed_response.has_tools_to_run():
+        ) and not processed_response.has_tools_or_approvals_to_run():
             return await cls.execute_final_output(
                 agent=agent,
                 original_input=original_input,
@@ -343,10 +389,20 @@ class RunImpl:
         run_handoffs = []
         functions = []
         computer_actions = []
+        local_shell_calls = []
+        mcp_approval_requests = []
         tools_used: list[str] = []
         handoff_map = {handoff.tool_name: handoff for handoff in handoffs}
         function_map = {tool.name: tool for tool in all_tools if isinstance(tool, FunctionTool)}
         computer_tool = next((tool for tool in all_tools if isinstance(tool, ComputerTool)), None)
+        local_shell_tool = next(
+            (tool for tool in all_tools if isinstance(tool, LocalShellTool)), None
+        )
+        hosted_mcp_server_map = {
+            tool.tool_config["server_label"]: tool
+            for tool in all_tools
+            if isinstance(tool, HostedMCPTool)
+        }
 
         for output in response.output:
             if isinstance(output, ResponseOutputMessage):
@@ -375,6 +431,54 @@ class RunImpl:
                 computer_actions.append(
                     ToolRunComputerAction(tool_call=output, computer_tool=computer_tool)
                 )
+            elif isinstance(output, McpApprovalRequest):
+                items.append(MCPApprovalRequestItem(raw_item=output, agent=agent))
+                if output.server_label not in hosted_mcp_server_map:
+                    _error_tracing.attach_error_to_current_span(
+                        SpanError(
+                            message="MCP server label not found",
+                            data={"server_label": output.server_label},
+                        )
+                    )
+                    raise ModelBehaviorError(f"MCP server label {output.server_label} not found")
+                else:
+                    server = hosted_mcp_server_map[output.server_label]
+                    if server.on_approval_request:
+                        mcp_approval_requests.append(
+                            ToolRunMCPApprovalRequest(
+                                request_item=output,
+                                mcp_tool=server,
+                            )
+                        )
+                    else:
+                        logger.warning(
+                            f"MCP server {output.server_label} has no on_approval_request hook"
+                        )
+            elif isinstance(output, McpListTools):
+                items.append(MCPListToolsItem(raw_item=output, agent=agent))
+            elif isinstance(output, ImageGenerationCall):
+                items.append(ToolCallItem(raw_item=output, agent=agent))
+                tools_used.append("image_generation")
+            elif isinstance(output, ResponseCodeInterpreterToolCall):
+                items.append(ToolCallItem(raw_item=output, agent=agent))
+                tools_used.append("code_interpreter")
+            elif isinstance(output, LocalShellCall):
+                items.append(ToolCallItem(raw_item=output, agent=agent))
+                tools_used.append("local_shell")
+                if not local_shell_tool:
+                    _error_tracing.attach_error_to_current_span(
+                        SpanError(
+                            message="Local shell tool not found",
+                            data={},
+                        )
+                    )
+                    raise ModelBehaviorError(
+                        "Model produced local shell call without a local shell tool."
+                    )
+                local_shell_calls.append(
+                    ToolRunLocalShellCall(tool_call=output, local_shell_tool=local_shell_tool)
+                )
+
             elif not isinstance(output, ResponseFunctionToolCall):
                 logger.warning(f"Unexpected output type, ignoring: {type(output)}")
                 continue
@@ -416,7 +520,9 @@ class RunImpl:
             handoffs=run_handoffs,
             functions=functions,
             computer_actions=computer_actions,
+            local_shell_calls=local_shell_calls,
             tools_used=tools_used,
+            mcp_approval_requests=mcp_approval_requests,
         )
 
     @classmethod
@@ -489,6 +595,30 @@ class RunImpl:
             for tool_run, result in zip(tool_runs, results)
         ]
 
+    @classmethod
+    async def execute_local_shell_calls(
+        cls,
+        *,
+        agent: Agent[TContext],
+        calls: list[ToolRunLocalShellCall],
+        context_wrapper: RunContextWrapper[TContext],
+        hooks: RunHooks[TContext],
+        config: RunConfig,
+    ) -> list[RunItem]:
+        results: list[RunItem] = []
+        # Need to run these serially, because each call can affect the local shell state
+        for call in calls:
+            results.append(
+                await LocalShellAction.execute(
+                    agent=agent,
+                    call=call,
+                    hooks=hooks,
+                    context_wrapper=context_wrapper,
+                    config=config,
+                )
+            )
+        return results
+
     @classmethod
     async def execute_computer_actions(
         cls,
@@ -643,6 +773,40 @@ class RunImpl:
             next_step=NextStepHandoff(new_agent),
         )
 
+    @classmethod
+    async def execute_mcp_approval_requests(
+        cls,
+        *,
+        agent: Agent[TContext],
+        approval_requests: list[ToolRunMCPApprovalRequest],
+        context_wrapper: RunContextWrapper[TContext],
+    ) -> list[RunItem]:
+        async def run_single_approval(approval_request: ToolRunMCPApprovalRequest) -> RunItem:
+            callback = approval_request.mcp_tool.on_approval_request
+            assert callback is not None, "Callback is required for MCP approval requests"
+            maybe_awaitable_result = callback(
+                MCPToolApprovalRequest(context_wrapper, approval_request.request_item)
+            )
+            if inspect.isawaitable(maybe_awaitable_result):
+                result = await maybe_awaitable_result
+            else:
+                result = maybe_awaitable_result
+            reason = result.get("reason", None)
+            raw_item: McpApprovalResponse = {
+                "approval_request_id": approval_request.request_item.id,
+                "approve": result["approve"],
+                "type": "mcp_approval_response",
+            }
+            if not result["approve"] and reason:
+                raw_item["reason"] = reason
+            return MCPApprovalResponseItem(
+                raw_item=raw_item,
+                agent=agent,
+            )
+
+        tasks = [run_single_approval(approval_request) for approval_request in approval_requests]
+        return await asyncio.gather(*tasks)
+
     @classmethod
     async def execute_final_output(
         cls,
@@ -727,6 +891,11 @@ class RunImpl:
                 event = RunItemStreamEvent(item=item, name="tool_output")
             elif isinstance(item, ReasoningItem):
                 event = RunItemStreamEvent(item=item, name="reasoning_item_created")
+            elif isinstance(item, MCPApprovalRequestItem):
+                event = RunItemStreamEvent(item=item, name="mcp_approval_requested")
+            elif isinstance(item, MCPListToolsItem):
+                event = RunItemStreamEvent(item=item, name="mcp_list_tools")
+
             else:
                 logger.warning(f"Unexpected item type: {type(item)}")
                 event = None
@@ -919,3 +1088,54 @@ class ComputerAction:
             await computer.wait()
 
         return await computer.screenshot()
+
+
+class LocalShellAction:
+    @classmethod
+    async def execute(
+        cls,
+        *,
+        agent: Agent[TContext],
+        call: ToolRunLocalShellCall,
+        hooks: RunHooks[TContext],
+        context_wrapper: RunContextWrapper[TContext],
+        config: RunConfig,
+    ) -> RunItem:
+        await asyncio.gather(
+            hooks.on_tool_start(context_wrapper, agent, call.local_shell_tool),
+            (
+                agent.hooks.on_tool_start(context_wrapper, agent, call.local_shell_tool)
+                if agent.hooks
+                else _coro.noop_coroutine()
+            ),
+        )
+
+        request = LocalShellCommandRequest(
+            ctx_wrapper=context_wrapper,
+            data=call.tool_call,
+        )
+        output = call.local_shell_tool.executor(request)
+        if inspect.isawaitable(output):
+            result = await output
+        else:
+            result = output
+
+        await asyncio.gather(
+            hooks.on_tool_end(context_wrapper, agent, call.local_shell_tool, result),
+            (
+                agent.hooks.on_tool_end(context_wrapper, agent, call.local_shell_tool, result)
+                if agent.hooks
+                else _coro.noop_coroutine()
+            ),
+        )
+
+        return ToolCallOutputItem(
+            agent=agent,
+            output=output,
+            raw_item={
+                "type": "local_shell_call_output",
+                "id": call.tool_call.call_id,
+                "output": result,
+                # "id": "out" + call.tool_call.id,  # TODO remove this, it should be optional
+            },
+        )

agents/extensions/models/litellm_model.py

@@ -6,6 +6,7 @@ from collections.abc import AsyncIterator
 from typing import Any, Literal, cast, overload
 
 import litellm.types
+from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from agents.exceptions import ModelBehaviorError
 
@@ -107,6 +108,16 @@ class LitellmModel(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
+                            )
+                        ),
+                        output_tokens_details=OutputTokensDetails(
+                            reasoning_tokens=getattr(
+                                response_usage.completion_tokens_details, "reasoning_tokens", 0
+                            )
+                        ),
                     )
                     if response.usage
                     else Usage()

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
 
@@ -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}")

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
@@ -83,6 +84,18 @@ 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()
@@ -252,7 +265,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/run.py

@@ -689,6 +689,8 @@ class Runner:
                         input_tokens=event.response.usage.input_tokens,
                         output_tokens=event.response.usage.output_tokens,
                         total_tokens=event.response.usage.total_tokens,
+                        input_tokens_details=event.response.usage.input_tokens_details,
+                        output_tokens_details=event.response.usage.output_tokens_details,
                     )
                     if event.response.usage
                     else Usage()

agents/stream_events.py

@@ -35,6 +35,8 @@ class RunItemStreamEvent:
         "tool_called",
         "tool_output",
         "reasoning_item_created",
+        "mcp_approval_requested",
+        "mcp_list_tools",
     ]
     """The name of the event."""
 

agents/tool.py

@@ -7,9 +7,11 @@ from dataclasses import dataclass
 from typing import Any, Callable, Literal, Union, overload
 
 from openai.types.responses.file_search_tool_param import Filters, RankingOptions
+from openai.types.responses.response_output_item import LocalShellCall, McpApprovalRequest
+from openai.types.responses.tool_param import CodeInterpreter, ImageGeneration, Mcp
 from openai.types.responses.web_search_tool_param import UserLocation
 from pydantic import ValidationError
-from typing_extensions import Concatenate, ParamSpec
+from typing_extensions import Concatenate, NotRequired, ParamSpec, TypedDict
 
 from . import _debug
 from .computer import AsyncComputer, Computer
@@ -130,7 +132,115 @@ class ComputerTool:
         return "computer_use_preview"
 
 
-Tool = Union[FunctionTool, FileSearchTool, WebSearchTool, ComputerTool]
+@dataclass
+class MCPToolApprovalRequest:
+    """A request to approve a tool call."""
+
+    ctx_wrapper: RunContextWrapper[Any]
+    """The run context."""
+
+    data: McpApprovalRequest
+    """The data from the MCP tool approval request."""
+
+
+class MCPToolApprovalFunctionResult(TypedDict):
+    """The result of an MCP tool approval function."""
+
+    approve: bool
+    """Whether to approve the tool call."""
+
+    reason: NotRequired[str]
+    """An optional reason, if rejected."""
+
+
+MCPToolApprovalFunction = Callable[
+    [MCPToolApprovalRequest], MaybeAwaitable[MCPToolApprovalFunctionResult]
+]
+"""A function that approves or rejects a tool call."""
+
+
+@dataclass
+class HostedMCPTool:
+    """A tool that allows the LLM to use a remote MCP server. The LLM will automatically list and
+    call tools, without requiring a a round trip back to your code.
+    If you want to run MCP servers locally via stdio, in a VPC or other non-publicly-accessible
+    environment, or you just prefer to run tool calls locally, then you can instead use the servers
+    in `agents.mcp` and pass `Agent(mcp_servers=[...])` to the agent."""
+
+    tool_config: Mcp
+    """The MCP tool config, which includes the server URL and other settings."""
+
+    on_approval_request: MCPToolApprovalFunction | None = None
+    """An optional function that will be called if approval is requested for an MCP tool. If not
+    provided, you will need to manually add approvals/rejections to the input and call
+    `Runner.run(...)` again."""
+
+    @property
+    def name(self):
+        return "hosted_mcp"
+
+
+@dataclass
+class CodeInterpreterTool:
+    """A tool that allows the LLM to execute code in a sandboxed environment."""
+
+    tool_config: CodeInterpreter
+    """The tool config, which includes the container and other settings."""
+
+    @property
+    def name(self):
+        return "code_interpreter"
+
+
+@dataclass
+class ImageGenerationTool:
+    """A tool that allows the LLM to generate images."""
+
+    tool_config: ImageGeneration
+    """The tool config, which image generation settings."""
+
+    @property
+    def name(self):
+        return "image_generation"
+
+
+@dataclass
+class LocalShellCommandRequest:
+    """A request to execute a command on a shell."""
+
+    ctx_wrapper: RunContextWrapper[Any]
+    """The run context."""
+
+    data: LocalShellCall
+    """The data from the local shell tool call."""
+
+
+LocalShellExecutor = Callable[[LocalShellCommandRequest], MaybeAwaitable[str]]
+"""A function that executes a command on a shell."""
+
+
+@dataclass
+class LocalShellTool:
+    """A tool that allows the LLM to execute commands on a shell."""
+
+    executor: LocalShellExecutor
+    """A function that executes a command on a shell."""
+
+    @property
+    def name(self):
+        return "local_shell"
+
+
+Tool = Union[
+    FunctionTool,
+    FileSearchTool,
+    WebSearchTool,
+    ComputerTool,
+    HostedMCPTool,
+    LocalShellTool,
+    ImageGenerationTool,
+    CodeInterpreterTool,
+]
 """A tool that can be used in an agent."""
 
 

agents/usage.py

@@ -1,4 +1,6 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+
+from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 
 @dataclass
@@ -9,9 +11,18 @@ class Usage:
     input_tokens: int = 0
     """Total input tokens sent, across all requests."""
 
+    input_tokens_details: InputTokensDetails = field(
+        default_factory=lambda: InputTokensDetails(cached_tokens=0)
+    )
+    """Details about the input tokens, matching responses API usage details."""
     output_tokens: int = 0
     """Total output tokens received, across all requests."""
 
+    output_tokens_details: OutputTokensDetails = field(
+        default_factory=lambda: OutputTokensDetails(reasoning_tokens=0)
+    )
+    """Details about the output tokens, matching responses API usage details."""
+
     total_tokens: int = 0
     """Total tokens sent and received, across all requests."""
 
@@ -20,3 +31,12 @@ class Usage:
         self.input_tokens += other.input_tokens if other.input_tokens else 0
         self.output_tokens += other.output_tokens if other.output_tokens else 0
         self.total_tokens += other.total_tokens if other.total_tokens else 0
+        self.input_tokens_details = InputTokensDetails(
+            cached_tokens=self.input_tokens_details.cached_tokens
+            + other.input_tokens_details.cached_tokens
+        )
+
+        self.output_tokens_details = OutputTokensDetails(
+            reasoning_tokens=self.output_tokens_details.reasoning_tokens
+            + other.output_tokens_details.reasoning_tokens
+        )

{openai_agents-0.0.15.dist-info → openai_agents-0.0.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.0.15
+Version: 0.0.16
 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,7 +20,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
 Requires-Dist: mcp<2,>=1.8.0; python_version >= '3.10'
-Requires-Dist: openai>=1.76.0
+Requires-Dist: openai>=1.81.0
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0

{openai_agents-0.0.15.dist-info → openai_agents-0.0.16.dist-info}/RECORD

@@ -1,7 +1,7 @@
-agents/__init__.py,sha256=T0Irpxfnd2SDSQ0aD5YvhwtAGTnzybnFb7qcvSsO5qY,6906
+agents/__init__.py,sha256=VXDkkC21o3n0JbKx8YIDwHBzTqwsTJ2JsDmL2p7THuU,7394
 agents/_config.py,sha256=ANrM7GP2VSQehDkMc9qocxkUlPwqU-i5sieMJyEwxpM,796
 agents/_debug.py,sha256=7OKys2lDjeCtGggTkM53m_8vw0WIr3yt-_JPBDAnsw0,608
-agents/_run_impl.py,sha256=7gKaBEDwQs7DqlcC3hSbU1I04wisvClXE0c3pZ9sGEM,34167
+agents/_run_impl.py,sha256=1aowNDgxwqPeFsxEQ6P2a7hrlniM_U3lRuKujUoyhuo,42569
 agents/agent.py,sha256=aTC49v9sQJm0gv5a3hW8xCgtMhk2TfjycBP8JyeOJ84,10571
 agents/agent_output.py,sha256=fEK1Yn0XfMrLXZRsBcSig-YDZZ0kZpCgATdwZ-eHYqQ,7127
 agents/computer.py,sha256=XD44UgiUWSfniv-xKwwDP6wFKVwBiZkpaL1hO-0-7ZA,2516
@@ -9,40 +9,40 @@ agents/exceptions.py,sha256=F3AltRt27PGdhbFqKBhRJL9eHqoN4SQx7oxBn0GWmhs,1856
 agents/function_schema.py,sha256=k4GTdxf5bvcisVr9b4xSdTGzkB5oP3XZnJMdouABCsw,12909
 agents/guardrail.py,sha256=vWWcApo9s_6aHapQ5AMko08MqC8Jrlk-J5iqIRctCDQ,9291
 agents/handoffs.py,sha256=wRg-HBGKBZev88mOg_mfv6CR8T2kewZM8eX3tb71l1g,9043
-agents/items.py,sha256=6Xnf6a2tIgM8Pz3T2Xr6J8wgok8fI-KhyKW1XdfHBJU,8306
+agents/items.py,sha256=lXFc_gKLEqwXIcyMKk4Q-6Rjry0MWD93xlvk4Y1W970,9695
 agents/lifecycle.py,sha256=wYFG6PLSKQ7bICKVbB8oGtdoJNINGq9obh2RSKlAkDE,2938
 agents/logger.py,sha256=p_ef7vWKpBev5FFybPJjhrCCQizK08Yy1A2EDO1SNNg,60
 agents/model_settings.py,sha256=7s9YjfHBVz1f1a-V3dd-8eMe-IAgfDXhQgChI27Kz00,3326
 agents/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 agents/result.py,sha256=dhtOaLIoOp5PYC4qcsgoU5qg2yvdI_VKdCy6i2qth7k,9305
-agents/run.py,sha256=kPxqU6KjFzkuVdH-UbKPUhJrvl70ChMnQbfI4UDD3fw,40276
+agents/run.py,sha256=5E3hx0mc3Gs3QcCCuNIddlRt4TJ9e_3629X5MSeOGX0,40454
 agents/run_context.py,sha256=vuSUQM8O4CLensQY27-22fOqECnw7yvwL9U3WO8b_bk,851
-agents/stream_events.py,sha256=ULgBEcL_H4vklZoxhpY2yomeoxVF0UiXvswsFsjFv4s,1547
+agents/stream_events.py,sha256=2zDCbJvUKnDfaogGltL6Yh9WvHxtTJf_z_IS0nvKjf0,1607
 agents/strict_schema.py,sha256=_KuEJkglmq-Fj3HSeYP4WqTvqrxbSKu6gezfz5Brhh0,5775
-agents/tool.py,sha256=XKeR1khfbaPbyO8DiGsn8WMO_Hkbrmm9NQzGeRsKcPs,11641
-agents/usage.py,sha256=-MZOmSDVdWxA2V_yVVnmUcwVcLdvYFccv0HXZ7Ow3_A,733
+agents/tool.py,sha256=CnGYyvDDYjIqGDSpDqUtbQtzeQrXdWJONMsFFmCpWHk,14711
+agents/usage.py,sha256=GB83eElU-DVkdutGObGDSX5vJNy8ssu3Xbpp5LlHfwU,1643
 agents/version.py,sha256=_1knUwzSK-HUeZTpRUkk6Z-CIcurqXuEplbV5TLJ08E,230
 agents/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agents/extensions/handoff_filters.py,sha256=2cXxu1JROez96CpTiGuT9PIuaIrIE8ksP01fX83krKM,1977
 agents/extensions/handoff_prompt.py,sha256=oGWN0uNh3Z1L7E-Ev2up8W084fFrDNOsLDy7P6bcmic,1006
 agents/extensions/visualization.py,sha256=AQFC7kQlZqTI6QVkyDHrF_DodCytrrhcLg35nfRd_JA,4256
 agents/extensions/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-agents/extensions/models/litellm_model.py,sha256=JV9DfS6gj9QR0NMFyX4o3Dq5QqJNQ3BksBh7ijrgWoA,13776
+agents/extensions/models/litellm_model.py,sha256=lLWLXmq5pUXAElyPSUKSmRbHPAiKjbG9aWvUSgTcS9s,14402
 agents/extensions/models/litellm_provider.py,sha256=wTm00Anq8YoNb9AnyT0JOunDG-HCDm_98ORNy7aNJdw,928
 agents/mcp/__init__.py,sha256=_aDpMTvYCe1IezOEasZ0vmombBM8r7BD8lpXiKi-UlM,499
-agents/mcp/server.py,sha256=f4F5DSH3TfMJ1SvruRqJT_wYbWhKQbRzVhdYdAjnOnk,15748
+agents/mcp/server.py,sha256=kIpQktrsNQUF0pNkERyfEcu-oYDvseBbsye_PzRmHnM,15910
 agents/mcp/util.py,sha256=dIEdYDMc7Sjp-DFQnvoc4VWU-B7Heyx0I41bcW7RlEg,5232
 agents/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agents/models/_openai_shared.py,sha256=4Ngwo2Fv2RXY61Pqck1cYPkSln2tDnb8Ai-ao4QG-iE,836
 agents/models/chatcmpl_converter.py,sha256=Sae-ITlhQz8_SiFiSat7Z-lavqIuczduOXR_PF_f6cs,18126
 agents/models/chatcmpl_helpers.py,sha256=eIWySobaH7I0AQijAz5i-_rtsXrSvmEHD567s_8Zw1o,1318
-agents/models/chatcmpl_stream_handler.py,sha256=VjskdeGnepn0iJbxsqNZrexcuAYAV1zd5hwt0lU8E7I,12452
+agents/models/chatcmpl_stream_handler.py,sha256=sDl8O7AKxpWxAq7-bgCUClD5JySUnbQ8RTPc0HeDElM,13713
 agents/models/fake_id.py,sha256=lbXjUUSMeAQ8eFx4V5QLUnBClHE6adJlYYav55RlG5w,268
 agents/models/interface.py,sha256=eEpiIBn9MxsmXUK1HPpn3c7TYPduBYC7tsWnDHSYJHo,3553
 agents/models/multi_provider.py,sha256=aiDbls5G4YomPfN6qH1pGlj41WS5jlDp2T82zm6qcnM,5578
-agents/models/openai_chatcompletions.py,sha256=QiUOdd4gQ7f-uslm4SqRlv9bt3T1oFL87EnqVYlWw4A,10390
+agents/models/openai_chatcompletions.py,sha256=obO209PFcf-qXDXmpoIagRmiLMVqsCoG1Amtvu9JfX0,11034
 agents/models/openai_provider.py,sha256=NMxTNaoTa329GrA7jj51LC02pb_e2eFh-PCvWADJrkY,3478
-agents/models/openai_responses.py,sha256=-hwXW7gXYOs4EbVrFhsil-tWb63gtLj_vaGQ9HXf6nE,14331
+agents/models/openai_responses.py,sha256=JFajISS-sYYxKhb66tZ5cYPEqIYOj6ap762Z-87c7fE,15368
 agents/tracing/__init__.py,sha256=-hJeEiNvgyQdEXpFTrr_qu_XYREvIrF5KyePDtovSak,2804
 agents/tracing/create.py,sha256=kkMf2pp5Te20YkiSvf3Xj3J9qMibQCjEAxZs1Lr_kTE,18124
 agents/tracing/logger.py,sha256=J4KUDRSGa7x5UVfUwWe-gbKwoaq8AeETRqkPt3QvtGg,68
@@ -76,7 +76,7 @@ agents/voice/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 agents/voice/models/openai_model_provider.py,sha256=Khn0uT-VhsEbe7_OhBMGFQzXNwL80gcWZyTHl3CaBII,3587
 agents/voice/models/openai_stt.py,sha256=rRsldkvkPhH4T0waX1dhccEqIwmPYh-teK_LRvBgiNI,16882
 agents/voice/models/openai_tts.py,sha256=4KoLQuFDHKu5a1VTJlu9Nj3MHwMlrn9wfT_liJDJ2dw,1477
-openai_agents-0.0.15.dist-info/METADATA,sha256=aWuj1znysjWdTLEA_Qtou1aOsPBNRRVFXiPcIoJ4o9c,8163
-openai_agents-0.0.15.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-openai_agents-0.0.15.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
-openai_agents-0.0.15.dist-info/RECORD,,
+openai_agents-0.0.16.dist-info/METADATA,sha256=EVGuugo_KTS-mZ0Luqa-wXEsgu8loIFS2lXwfzdJyR8,8163
+openai_agents-0.0.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openai_agents-0.0.16.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
+openai_agents-0.0.16.dist-info/RECORD,,