Implementation:Openai Openai python Response Item Type

Knowledge Sources	Openai_Openai_python OpenAI API Reference
Domains	API_Types, Responses_API
Last Updated	2026-02-15 00:00 GMT

Overview

Discriminated union type alias and supporting models for representing all possible response items provided by the openai-python SDK.

Description

ResponseItem is a TypeAlias representing a discriminated union of all possible item types that can appear in a Responses API response. It is discriminated on the type field using PropertyInfo(discriminator="type"). The union includes input messages, output messages, various tool calls (function, computer, file search, web search, code interpreter, shell, apply patch), tool call outputs, image generation calls, local shell calls, MCP-related items (list tools, approval requests, approval responses, MCP calls), and more.

The module also defines several supporting Pydantic models:

• ImageGenerationCall - An image generation request with id, result, status, and type fields.
• LocalShellCallAction - Describes a shell command to execute, including command, env, timeout, user, and working directory.
• LocalShellCall - A tool call to run a command on the local shell.
• LocalShellCallOutput - The output of a local shell tool call.
• McpListToolsTool - A tool available on an MCP server with input_schema, name, annotations, and description.
• McpListTools - A list of tools available on an MCP server.
• McpApprovalRequest - A request for human approval of a tool invocation.
• McpApprovalResponse - A response to an MCP approval request.
• McpCall - An invocation of a tool on an MCP server.

Usage

Import ResponseItem when you need a type annotation covering all possible items returned in a response, or import individual supporting classes when working with specific item types such as MCP calls or image generation.

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/types/responses/response_item.py

Signature

ResponseItem: TypeAlias = Annotated[
    Union[
        ResponseInputMessageItem,
        ResponseOutputMessage,
        ResponseFileSearchToolCall,
        ResponseComputerToolCall,
        ResponseComputerToolCallOutputItem,
        ResponseFunctionWebSearch,
        ResponseFunctionToolCallItem,
        ResponseFunctionToolCallOutputItem,
        ImageGenerationCall,
        ResponseCodeInterpreterToolCall,
        LocalShellCall,
        LocalShellCallOutput,
        ResponseFunctionShellToolCall,
        ResponseFunctionShellToolCallOutput,
        ResponseApplyPatchToolCall,
        ResponseApplyPatchToolCallOutput,
        McpListTools,
        McpApprovalRequest,
        McpApprovalResponse,
        McpCall,
    ],
    PropertyInfo(discriminator="type"),
]

Import

from openai.types.responses import ResponseItem

I/O Contract

Union Members

Type	Discriminator Value	Description
ResponseInputMessageItem	"message"	An input message item.
ResponseOutputMessage	"message"	An output message from the model.
ResponseFileSearchToolCall	"file_search_call"	A file search tool call.
ResponseComputerToolCall	"computer_call"	A computer use tool call.
ResponseComputerToolCallOutputItem	"computer_call_output"	Output from a computer use tool call.
ResponseFunctionWebSearch	"web_search_call"	A web search tool call.
ResponseFunctionToolCallItem	"function_call"	A function tool call.
ResponseFunctionToolCallOutputItem	"function_call_output"	Output from a function tool call.
ImageGenerationCall	"image_generation_call"	An image generation request.
ResponseCodeInterpreterToolCall	"code_interpreter_call"	A code interpreter tool call.
LocalShellCall	"local_shell_call"	A local shell command call.
LocalShellCallOutput	"local_shell_call_output"	Output from a local shell call.
ResponseFunctionShellToolCall	"function_shell_call"	A function shell tool call.
ResponseFunctionShellToolCallOutput	"function_shell_call_output"	Output from a function shell tool call.
ResponseApplyPatchToolCall	"apply_patch_call"	An apply patch tool call.
ResponseApplyPatchToolCallOutput	"apply_patch_call_output"	Output from an apply patch tool call.
McpListTools	"mcp_list_tools"	A list of tools from an MCP server.
McpApprovalRequest	"mcp_approval_request"	An MCP approval request.
McpApprovalResponse	"mcp_approval_response"	An MCP approval response.
McpCall	"mcp_call"	An MCP tool call invocation.

Usage Examples

import openai

client = openai.OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="Search the web for the latest Python release.",
    tools=[{"type": "web_search_preview"}],
)

for item in response.output:
    # item is typed as ResponseItem (discriminated union)
    if item.type == "web_search_call":
        print(f"Web search: {item.id}")
    elif item.type == "message":
        for content in item.content:
            if content.type == "output_text":
                print(content.text)
    elif item.type == "mcp_call":
        print(f"MCP call to {item.name} on {item.server_label}")

Related Pages

• Environment:Openai_Openai_python_Python_3_9_Plus