Implementation:Openai Openai python Response Input Item

Knowledge Sources	Openai_Openai_python
Domains	API_Types, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete Pydantic model definitions for response input items provided by the openai-python SDK.

Description

The response_input_item.py module defines the Pydantic BaseModel classes that represent all possible input item types for the OpenAI Responses API. These are the response/deserialization models (as opposed to the TypedDict request parameter variants in response_input_item_param.py).

The central type is ResponseInputItem, a discriminated Union (using the type field as discriminator) of 25 model classes covering messages, tool call outputs, shell commands, MCP interactions, and more.

Key model classes defined in this module:

Message -- A message input with a role ("user", "system", "developer"), content, and optional status.
ComputerCallOutput -- Output of a computer tool call, containing a screenshot and optional safety check acknowledgements.
FunctionCallOutput -- Output from a function tool call with a call_id and text/structured output.
ImageGenerationCall -- An image generation request with status and optional base64 result.
LocalShellCall / LocalShellCallOutput -- Local shell command execution and its output.
ShellCall / ShellCallOutput -- Remote shell command execution with environment configuration and captured stdout/stderr.
ApplyPatchCall / ApplyPatchCallOutput -- File creation, deletion, or update operations via unified diffs.
McpListTools -- Lists tools available on an MCP server.
McpApprovalRequest / McpApprovalResponse -- Human-in-the-loop approval flow for MCP tool invocations.
McpCall -- An invocation of a tool on an MCP server.
ItemReference -- An internal identifier for referencing existing items by ID.

This file is auto-generated from the OpenAI API spec by the Stainless code generation toolchain.

Usage

Use these types when working with response data returned by the API. They are the Pydantic models used for deserialization and validation of input items within response objects. For constructing request parameters, use the corresponding TypedDict variants from response_input_item_param.py.

Code Reference

Source Location

Repository: openai-python
File: src/openai/types/responses/response_input_item.py
Lines: 1-548

Signature

class Message(BaseModel):
    content: ResponseInputMessageContentList
    role: Literal["user", "system", "developer"]
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None
    type: Optional[Literal["message"]] = None

class ComputerCallOutput(BaseModel):
    call_id: str
    output: ResponseComputerToolCallOutputScreenshot
    type: Literal["computer_call_output"]
    id: Optional[str] = None
    acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]] = None
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None

class FunctionCallOutput(BaseModel):
    call_id: str
    output: Union[str, ResponseFunctionCallOutputItemList]
    type: Literal["function_call_output"]
    id: Optional[str] = None
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None

class ShellCall(BaseModel):
    action: ShellCallAction
    call_id: str
    type: Literal["shell_call"]
    id: Optional[str] = None
    environment: Optional[ShellCallEnvironment] = None
    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None

class McpCall(BaseModel):
    id: str
    arguments: str
    name: str
    server_label: str
    type: Literal["mcp_call"]
    approval_request_id: Optional[str] = None
    error: Optional[str] = None
    output: Optional[str] = None
    status: Optional[Literal["in_progress", "completed", "incomplete", "calling", "failed"]] = None

class ItemReference(BaseModel):
    id: str
    type: Optional[Literal["item_reference"]] = None

ResponseInputItem: TypeAlias = Annotated[
    Union[
        EasyInputMessage, Message, ResponseOutputMessage,
        ResponseFileSearchToolCall, ResponseComputerToolCall,
        ComputerCallOutput, ResponseFunctionWebSearch,
        ResponseFunctionToolCall, FunctionCallOutput,
        ResponseReasoningItem, ResponseCompactionItemParam,
        ImageGenerationCall, ResponseCodeInterpreterToolCall,
        LocalShellCall, LocalShellCallOutput,
        ShellCall, ShellCallOutput,
        ApplyPatchCall, ApplyPatchCallOutput,
        McpListTools, McpApprovalRequest, McpApprovalResponse,
        McpCall, ResponseCustomToolCallOutput,
        ResponseCustomToolCall, ItemReference,
    ],
    PropertyInfo(discriminator="type"),
]

Import

from openai.types.responses.response_input_item import (
    ResponseInputItem,
    Message,
    ComputerCallOutput,
    FunctionCallOutput,
    ImageGenerationCall,
    ShellCall,
    ShellCallOutput,
    McpCall,
    McpApprovalRequest,
    McpApprovalResponse,
    ItemReference,
)
# Or via the top-level re-export:
from openai.types.responses import ResponseInputItem

I/O Contract

Inputs

Name	Type	Required	Description
content	ResponseInputMessageContentList	Yes (Message)	List of content items for message input
role	Literal["user", "system", "developer"]	Yes (Message)	Role of the message sender
call_id	str	Yes (ComputerCallOutput, FunctionCallOutput, ShellCall, etc.)	ID of the tool call this output corresponds to
output	varies	Yes (FunctionCallOutput, ShellCallOutput, etc.)	The output content from a tool call
type	Literal[...]	Yes (most types)	Discriminator field identifying the input item type
id	str	Yes/Optional (varies)	Unique identifier for the input item
status	Literal["in_progress", "completed", "incomplete"]	No	Processing status of the item
arguments	str	Yes (McpCall, McpApprovalRequest)	JSON string of tool arguments
name	str	Yes (McpCall, McpApprovalRequest)	Name of the MCP tool
server_label	str	Yes (McpCall, McpListTools, McpApprovalRequest)	Label identifying the MCP server
approve	bool	Yes (McpApprovalResponse)	Whether the MCP tool call is approved

Outputs

Name	Type	Description
ResponseInputItem	TypeAlias (Annotated Union)	Discriminated union of all 25+ input item Pydantic models, discriminated on the `type` field
Message	BaseModel	A user/system/developer message with content and role
ComputerCallOutput	BaseModel	Screenshot output from computer tool calls
FunctionCallOutput	BaseModel	Text or structured output from function tool calls
ImageGenerationCall	BaseModel	Image generation request with base64 result
ShellCall	BaseModel	Shell command execution request with action and environment
ShellCallOutput	BaseModel	Captured stdout/stderr from shell execution
ApplyPatchCall	BaseModel	File patch operation (create, delete, update)
McpCall	BaseModel	MCP server tool invocation with arguments and output
ItemReference	BaseModel	Internal reference to an existing item by ID

Usage Examples

Working With Response Input Items

from openai.types.responses.response_input_item import (
    ResponseInputItem,
    Message,
    FunctionCallOutput,
)

# Type-narrow a ResponseInputItem
def describe_item(item: ResponseInputItem) -> str:
    if isinstance(item, Message):
        return f"Message from {item.role}: {item.content}"
    elif isinstance(item, FunctionCallOutput):
        return f"Function output for call {item.call_id}: {item.output}"
    return f"Unknown item type: {type(item).__name__}"

Handling MCP Items

from openai.types.responses.response_input_item import (
    McpCall,
    McpApprovalRequest,
    McpApprovalResponse,
)

def process_mcp_item(item):
    if isinstance(item, McpApprovalRequest):
        print(f"Approval needed for tool '{item.name}' on server '{item.server_label}'")
        # Return approval response
    elif isinstance(item, McpCall):
        print(f"MCP call to '{item.name}': status={item.status}")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment