80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143

@dataclassclassRunItemBase(Generic[T],abc.ABC):agent:Agent[Any]"""The agent whose run caused this item to be generated."""raw_item:T"""The raw Responses item from the run. This will always be either an output item (i.e.    `openai.types.responses.ResponseOutputItem` or an input item    (i.e. `openai.types.responses.ResponseInputItemParam`).    """_agent_ref:weakref.ReferenceType[Agent[Any]]|None=field(init=False,repr=False,default=None,)def__post_init__(self)->None:# Store a weak reference so we can release the strong reference later if desired.self._agent_ref=weakref.ref(self.agent)def__getattribute__(self,name:str)->Any:ifname=="agent":returnself._get_agent_via_weakref("agent","_agent_ref")returnsuper().__getattribute__(name)defrelease_agent(self)->None:"""Release the strong reference to the agent while keeping a weak reference."""if"agent"notinself.__dict__:returnagent=self.__dict__["agent"]ifagentisNone:returnself._agent_ref=weakref.ref(agent)ifagentisnotNoneelseNone# Set to None instead of deleting so dataclass repr/asdict keep working.self.__dict__["agent"]=Nonedef_get_agent_via_weakref(self,attr_name:str,ref_name:str)->Any:# Preserve the dataclass field so repr/asdict still read it, but lazily resolve the weakref# when the stored value is None (meaning release_agent already dropped the strong ref).# If the attribute was never overridden we fall back to the default descriptor chain.data=object.__getattribute__(self,"__dict__")value=data.get(attr_name,_MISSING_ATTR_SENTINEL)ifvalueis_MISSING_ATTR_SENTINEL:returnobject.__getattribute__(self,attr_name)ifvalueisnotNone:returnvalueref=object.__getattribute__(self,ref_name)ifrefisnotNone:agent=ref()ifagentisnotNone:returnagentreturnNonedefto_input_item(self)->TResponseInputItem:"""Converts this item into an input item suitable for passing to the model."""ifisinstance(self.raw_item,dict):# We know that input items are dicts, so we can ignore the type errorreturnself.raw_item# type: ignoreelifisinstance(self.raw_item,BaseModel):# All output items are Pydantic models that can be converted to input items.returnself.raw_item.model_dump(exclude_unset=True)# type: ignoreelse:raiseAgentsException(f"Unexpected raw item type:{type(self.raw_item)}")

146147148149150151152153

@dataclassclassMessageOutputItem(RunItemBase[ResponseOutputMessage]):"""Represents a message from the LLM."""raw_item:ResponseOutputMessage"""The raw response output message."""type:Literal["message_output_item"]="message_output_item"

156157158159160161162163

@dataclassclassHandoffCallItem(RunItemBase[ResponseFunctionToolCall]):"""Represents a tool call for a handoff from one agent to another."""raw_item:ResponseFunctionToolCall"""The raw response function tool call that represents the handoff."""type:Literal["handoff_call_item"]="handoff_call_item"

166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221

@dataclassclassHandoffOutputItem(RunItemBase[TResponseInputItem]):"""Represents the output of a handoff."""raw_item:TResponseInputItem"""The raw input item that represents the handoff taking place."""source_agent:Agent[Any]"""The agent that made the handoff."""target_agent:Agent[Any]"""The agent that is being handed off to."""type:Literal["handoff_output_item"]="handoff_output_item"_source_agent_ref:weakref.ReferenceType[Agent[Any]]|None=field(init=False,repr=False,default=None,)_target_agent_ref:weakref.ReferenceType[Agent[Any]]|None=field(init=False,repr=False,default=None,)def__post_init__(self)->None:super().__post_init__()# Maintain weak references so downstream code can release the strong references when safe.self._source_agent_ref=weakref.ref(self.source_agent)self._target_agent_ref=weakref.ref(self.target_agent)def__getattribute__(self,name:str)->Any:ifname=="source_agent":# Provide lazy weakref access like the base `agent` field so HandoffOutputItem# callers keep seeing the original agent until GC occurs.returnself._get_agent_via_weakref("source_agent","_source_agent_ref")ifname=="target_agent":# Same as above but for the target of the handoff.returnself._get_agent_via_weakref("target_agent","_target_agent_ref")returnsuper().__getattribute__(name)defrelease_agent(self)->None:super().release_agent()if"source_agent"inself.__dict__:source_agent=self.__dict__["source_agent"]ifsource_agentisnotNone:self._source_agent_ref=weakref.ref(source_agent)# Preserve dataclass fields for repr/asdict while dropping strong refs.self.__dict__["source_agent"]=Noneif"target_agent"inself.__dict__:target_agent=self.__dict__["target_agent"]iftarget_agentisnotNone:self._target_agent_ref=weakref.ref(target_agent)# Preserve dataclass fields for repr/asdict while dropping strong refs.self.__dict__["target_agent"]=None

238239240241242243244245

@dataclassclassToolCallItem(RunItemBase[Any]):"""Represents a tool call e.g. a function call or computer action call."""raw_item:ToolCallItemTypes"""The raw tool call item."""type:Literal["tool_call_item"]="tool_call_item"

256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287

@dataclassclassToolCallOutputItem(RunItemBase[Any]):"""Represents the output of a tool call."""raw_item:ToolCallOutputTypes"""The raw item from the model."""output:Any"""The output of the tool call. This is whatever the tool call returned; the `raw_item`    contains a string representation of the output.    """type:Literal["tool_call_output_item"]="tool_call_output_item"defto_input_item(self)->TResponseInputItem:"""Converts the tool output into an input item for the next model turn.        Hosted tool outputs (e.g. shell/apply_patch) carry a `status` field for the SDK's        book-keeping, but the Responses API does not yet accept that parameter. Strip it from the        payload we send back to the model while keeping the original raw item intact.        """ifisinstance(self.raw_item,dict):payload=dict(self.raw_item)payload_type=payload.get("type")ifpayload_type=="shell_call_output":payload.pop("status",None)payload.pop("shell_output",None)payload.pop("provider_data",None)returncast(TResponseInputItem,payload)returnsuper().to_input_item()

290291292293294295296297

@dataclassclassReasoningItem(RunItemBase[ResponseReasoningItem]):"""Represents a reasoning item."""raw_item:ResponseReasoningItem"""The raw reasoning item."""type:Literal["reasoning_item"]="reasoning_item"

300301302303304305306307

@dataclassclassMCPListToolsItem(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"

310311312313314315316317

@dataclassclassMCPApprovalRequestItem(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"

320321322323324325326327

@dataclassclassMCPApprovalResponseItem(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"

344345346347348349350351352353354355356357358359360361362363364

@pydantic.dataclasses.dataclassclassModelResponse:output:list[TResponseOutputItem]"""A list of outputs (messages, tool calls, etc) generated by the model"""usage:Usage"""The usage information for the response."""response_id:str|None"""An ID for the response which can be used to refer to the response in subsequent calls to the    model. Not supported by all model providers.    If using OpenAI models via the Responses API, this is the `response_id` parameter, and it can    be passed to `Runner.run`.    """defto_input_items(self)->list[TResponseInputItem]:"""Convert the output into a list of input items suitable for passing to the model."""# We happen to know that the shape of the Pydantic output items are the same as the# equivalent TypedDict input items, so we can just convert each one.# This is also tested via unit tests.return[it.model_dump(exclude_unset=True)foritinself.output]# type: ignore

367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522

classItemHelpers:@classmethoddefextract_last_content(cls,message:TResponseOutputItem)->str:"""Extracts the last text content or refusal from a message."""ifnotisinstance(message,ResponseOutputMessage):return""ifnotmessage.content:return""last_content=message.content[-1]ifisinstance(last_content,ResponseOutputText):returnlast_content.textelifisinstance(last_content,ResponseOutputRefusal):returnlast_content.refusalelse:raiseModelBehaviorError(f"Unexpected content type:{type(last_content)}")@classmethoddefextract_last_text(cls,message:TResponseOutputItem)->str|None:"""Extracts the last text content from a message, if any. Ignores refusals."""ifisinstance(message,ResponseOutputMessage):ifnotmessage.content:returnNonelast_content=message.content[-1]ifisinstance(last_content,ResponseOutputText):returnlast_content.textreturnNone@classmethoddefinput_to_new_input_list(cls,input:str|list[TResponseInputItem])->list[TResponseInputItem]:"""Converts a string or list of input items into a list of input items."""ifisinstance(input,str):return[{"content":input,"role":"user",}]returninput.copy()@classmethoddeftext_message_outputs(cls,items:list[RunItem])->str:"""Concatenates all the text content from a list of message output items."""text=""foriteminitems:ifisinstance(item,MessageOutputItem):text+=cls.text_message_output(item)returntext@classmethoddeftext_message_output(cls,message:MessageOutputItem)->str:"""Extracts all the text content from a single message output item."""text=""foriteminmessage.raw_item.content:ifisinstance(item,ResponseOutputText):text+=item.textreturntext@classmethoddeftool_call_output_item(cls,tool_call:ResponseFunctionToolCall,output:Any)->FunctionCallOutput:"""Creates a tool call output item from a tool call and its output.        Accepts either plain values (stringified) or structured outputs using        input_text/input_image/input_file shapes. Structured outputs may be        provided as Pydantic models or dicts, or an iterable of such items.        """converted_output=cls._convert_tool_output(output)return{"call_id":tool_call.call_id,"output":converted_output,"type":"function_call_output",}@classmethoddef_convert_tool_output(cls,output:Any)->str|ResponseFunctionCallOutputItemListParam:"""Converts a tool return value into an output acceptable by the Responses API."""# If the output is either a single or list of the known structured output types, convert to# ResponseFunctionCallOutputItemListParam. Else, just stringify.ifisinstance(output,(list,tuple)):maybe_converted_output_list=[cls._maybe_get_output_as_structured_function_output(item)foriteminoutput]ifall(maybe_converted_output_list):return[cls._convert_single_tool_output_pydantic_model(item)foriteminmaybe_converted_output_listifitemisnotNone]else:returnstr(output)else:maybe_converted_output=cls._maybe_get_output_as_structured_function_output(output)ifmaybe_converted_output:return[cls._convert_single_tool_output_pydantic_model(maybe_converted_output)]else:returnstr(output)@classmethoddef_maybe_get_output_as_structured_function_output(cls,output:Any)->ValidToolOutputPydanticModels|None:ifisinstance(output,(ToolOutputText,ToolOutputImage,ToolOutputFileContent)):returnoutputelifisinstance(output,dict):# Require explicit 'type' field in dict to be considered a structured outputif"type"notinoutput:returnNonetry:returnValidToolOutputPydanticModelsTypeAdapter.validate_python(output)exceptpydantic.ValidationError:logger.debug("dict was not a valid tool output pydantic model")returnNonereturnNone@classmethoddef_convert_single_tool_output_pydantic_model(cls,output:ValidToolOutputPydanticModels)->ResponseFunctionCallOutputItemParam:ifisinstance(output,ToolOutputText):return{"type":"input_text","text":output.text}elifisinstance(output,ToolOutputImage):# Forward all provided optional fields so the Responses API receives# the correct identifiers and settings for the image resource.result:ResponseInputImageContentParam={"type":"input_image"}ifoutput.image_urlisnotNone:result["image_url"]=output.image_urlifoutput.file_idisnotNone:result["file_id"]=output.file_idifoutput.detailisnotNone:result["detail"]=output.detailreturnresultelifisinstance(output,ToolOutputFileContent):# Forward all provided optional fields so the Responses API receives# the correct identifiers and metadata for the file resource.result_file:ResponseInputFileContentParam={"type":"input_file"}ifoutput.file_dataisnotNone:result_file["file_data"]=output.file_dataifoutput.file_urlisnotNone:result_file["file_url"]=output.file_urlifoutput.file_idisnotNone:result_file["file_id"]=output.file_idifoutput.filenameisnotNone:result_file["filename"]=output.filenamereturnresult_fileelse:assert_never(output)raiseValueError(f"Unexpected tool output type:{output}")