utils Module

Functions

capture_input_message

Extract and store the first user message from input list for parent agent span.

capture_input_message(parent_span_id: str, input_list: Any, agent_inputs: dict[str, str]) -> None

Parameters

Name Description
parent_span_id
Required
str
input_list
Required
Any
agent_inputs
Required
dict[str, str]

Returns

Type Description
None

capture_output_message

Extract and store the last assistant message with actual content (no tool calls) for parent agent span.

capture_output_message(parent_span_id: str, output_list: Any, agent_outputs: dict[str, str]) -> None

Parameters

Name Description
parent_span_id
Required
str
output_list
Required
Any
agent_outputs
Required
dict[str, str]

Returns

Type Description
None

capture_tool_call_ids

Extract and store tool_call_ids from generation output for later use by FunctionSpan.

capture_tool_call_ids(output_list: Any, pending_tool_calls: dict[str, str], max_size: int = 1000) -> None

Parameters

Name Description
output_list
Required
Any

The generation output containing tool calls
pending_tool_calls
Required
dict[str, str]

OrderedDict to store pending tool calls
max_size
int

Maximum number of pending tool calls to keep in memory

Default value: 1000

Returns

Type Description
None

find_ancestor_agent_span_id

Walk up the parent chain to find the nearest ancestor AgentSpan.

find_ancestor_agent_span_id(span_id: str | None, agent_span_ids: set[str] | Mapping[str, object], span_parents: Mapping[str, str]) -> str | None

Parameters

Name Description
span_id
Required
str | None
agent_span_ids
Required
set[str] | Mapping[str, object]
span_parents
Required
Mapping[str, str]

Returns

Type Description
str | None

get_attributes_from_chat_completions_message_content 

get_attributes_from_chat_completions_message_content(obj: str | Iterable[Mapping[str, Any]], prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
str | Iterable[Mapping[str, Any]]
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_chat_completions_message_dicts 

get_attributes_from_chat_completions_message_dicts(obj: Iterable[Mapping[str, Any]], prefix: str = '', msg_idx: int = 0, tool_call_idx: int = 0) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
Iterable[Mapping[str, Any]]
prefix
str
Default value: ""
msg_idx
int
Default value: 0
tool_call_idx
int
Default value: 0

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_function_call_output 

get_attributes_from_function_call_output(obj: FunctionCallOutput, prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.response_input_item_param.FunctionCallOutput>
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_function_span_data 

get_attributes_from_function_span_data(obj: FunctionSpanData) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:agents.tracing.span_data.FunctionSpanData>

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_generation_span_data 

get_attributes_from_generation_span_data(obj: GenerationSpanData) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:agents.tracing.span_data.GenerationSpanData>

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_input 

get_attributes_from_input(obj: Iterable[EasyInputMessageParam | Message | ResponseOutputMessageParam | ResponseFileSearchToolCallParam | ResponseComputerToolCallParam | ComputerCallOutput | ResponseFunctionWebSearchParam | ResponseFunctionToolCallParam | FunctionCallOutput | ToolSearchCall | ResponseToolSearchOutputItemParamParam | ResponseReasoningItemParam | ResponseCompactionItemParamParam | ImageGenerationCall | ResponseCodeInterpreterToolCallParam | LocalShellCall | LocalShellCallOutput | ShellCall | ShellCallOutput | ApplyPatchCall | ApplyPatchCallOutput | McpListTools | McpApprovalRequest | McpApprovalResponse | McpCall | ResponseCustomToolCallOutputParam | ResponseCustomToolCallParam | ItemReference], msg_idx: int = 1) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
Iterable[<xref:openai.types.responses.easy_input_message_param.EasyInputMessageParam> | <xref:openai.types.responses.response_input_item_param.Message> | <xref:openai.types.responses.response_output_message_param.ResponseOutputMessageParam> | <xref:openai.types.responses.response_file_search_tool_call_param.ResponseFileSearchToolCallParam> | <xref:openai.types.responses.response_computer_tool_call_param.ResponseComputerToolCallParam> | <xref:openai.types.responses.response_input_item_param.ComputerCallOutput> | <xref:openai.types.responses.response_function_web_search_param.ResponseFunctionWebSearchParam> | <xref:openai.types.responses.response_function_tool_call_param.ResponseFunctionToolCallParam> | <xref:openai.types.responses.response_input_item_param.FunctionCallOutput> | <xref:openai.types.responses.response_input_item_param.ToolSearchCall> | <xref:openai.types.responses.response_tool_search_output_item_param_param.ResponseToolSearchOutputItemParamParam> | <xref:openai.types.responses.response_reasoning_item_param.ResponseReasoningItemParam> | <xref:openai.types.responses.response_compaction_item_param_param.ResponseCompactionItemParamParam> | <xref:openai.types.responses.response_input_item_param.ImageGenerationCall> | <xref:openai.types.responses.response_code_interpreter_tool_call_param.ResponseCodeInterpreterToolCallParam> | <xref:openai.types.responses.response_input_item_param.LocalShellCall> | <xref:openai.types.responses.response_input_item_param.LocalShellCallOutput> | <xref:openai.types.responses.response_input_item_param.ShellCall> | <xref:openai.types.responses.response_input_item_param.ShellCallOutput> | <xref:openai.types.responses.response_input_item_param.ApplyPatchCall> | <xref:openai.types.responses.response_input_item_param.ApplyPatchCallOutput> | <xref:openai.types.responses.response_input_item_param.McpListTools> | <xref:openai.types.responses.response_input_item_param.McpApprovalRequest> | <xref:openai.types.responses.response_input_item_param.McpApprovalResponse> | <xref:openai.types.responses.response_input_item_param.McpCall> | <xref:openai.types.responses.response_custom_tool_call_output_param.ResponseCustomToolCallOutputParam> | <xref:openai.types.responses.response_custom_tool_call_param.ResponseCustomToolCallParam> | <xref:openai.types.responses.response_input_item_param.ItemReference>]
msg_idx
int
Default value: 1

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_mcp_list_tool_span_data 

get_attributes_from_mcp_list_tool_span_data(obj: MCPListToolsSpanData) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:agents.tracing.span_data.MCPListToolsSpanData>

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_message_content_list 

get_attributes_from_message_content_list(obj: Iterable[ResponseInputTextParam | ResponseInputImageParam | ResponseInputFileParam | ResponseOutputTextParam | ResponseOutputRefusalParam], prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
Iterable[<xref:openai.types.responses.response_input_text_param.ResponseInputTextParam> | <xref:openai.types.responses.response_input_image_param.ResponseInputImageParam> | <xref:openai.types.responses.response_input_file_param.ResponseInputFileParam> | <xref:openai.types.responses.response_output_text_param.ResponseOutputTextParam> | <xref:openai.types.responses.response_output_refusal_param.ResponseOutputRefusalParam>]
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_message_param 

get_attributes_from_message_param(obj: EasyInputMessageParam | Message | ResponseOutputMessageParam, prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.easy_input_message_param.EasyInputMessageParam> | <xref:openai.types.responses.response_input_item_param.Message> | <xref:openai.types.responses.response_output_message_param.ResponseOutputMessageParam>
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_response 

get_attributes_from_response(obj: Response) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.response.Response>

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_response_custom_tool_call_output_param 

get_attributes_from_response_custom_tool_call_output_param(obj: ResponseCustomToolCallOutputParam, prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.response_custom_tool_call_output_param.ResponseCustomToolCallOutputParam>
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_response_custom_tool_call_param 

get_attributes_from_response_custom_tool_call_param(obj: ResponseCustomToolCallParam, prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.response_custom_tool_call_param.ResponseCustomToolCallParam>
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_response_function_tool_call_param 

get_attributes_from_response_function_tool_call_param(obj: ResponseFunctionToolCallParam, prefix: str = '') -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.response_function_tool_call_param.ResponseFunctionToolCallParam>
prefix
str
Default value: ""

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_response_output 

get_attributes_from_response_output(obj: Iterable[ResponseOutputMessage | ResponseFileSearchToolCall | ResponseFunctionToolCall | ResponseFunctionToolCallOutputItem | ResponseFunctionWebSearch | ResponseComputerToolCall | ResponseComputerToolCallOutputItem | ResponseReasoningItem | ResponseToolSearchCall | ResponseToolSearchOutputItem | ResponseCompactionItem | ImageGenerationCall | ResponseCodeInterpreterToolCall | LocalShellCall | LocalShellCallOutput | ResponseFunctionShellToolCall | ResponseFunctionShellToolCallOutput | ResponseApplyPatchToolCall | ResponseApplyPatchToolCallOutput | McpCall | McpListTools | McpApprovalRequest | McpApprovalResponse | ResponseCustomToolCall | ResponseCustomToolCallOutputItem], msg_idx: int = 0) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
Iterable[<xref:openai.types.responses.response_output_message.ResponseOutputMessage> | <xref:openai.types.responses.response_file_search_tool_call.ResponseFileSearchToolCall> | <xref:openai.types.responses.response_function_tool_call.ResponseFunctionToolCall> | <xref:openai.types.responses.response_function_tool_call_output_item.ResponseFunctionToolCallOutputItem> | <xref:openai.types.responses.response_function_web_search.ResponseFunctionWebSearch> | <xref:openai.types.responses.response_computer_tool_call.ResponseComputerToolCall> | <xref:openai.types.responses.response_computer_tool_call_output_item.ResponseComputerToolCallOutputItem> | <xref:openai.types.responses.response_reasoning_item.ResponseReasoningItem> | <xref:openai.types.responses.response_tool_search_call.ResponseToolSearchCall> | <xref:openai.types.responses.response_tool_search_output_item.ResponseToolSearchOutputItem> | <xref:openai.types.responses.response_compaction_item.ResponseCompactionItem> | <xref:openai.types.responses.response_output_item.ImageGenerationCall> | <xref:openai.types.responses.response_code_interpreter_tool_call.ResponseCodeInterpreterToolCall> | <xref:openai.types.responses.response_output_item.LocalShellCall> | <xref:openai.types.responses.response_output_item.LocalShellCallOutput> | <xref:openai.types.responses.response_function_shell_tool_call.ResponseFunctionShellToolCall> | <xref:openai.types.responses.response_function_shell_tool_call_output.ResponseFunctionShellToolCallOutput> | <xref:openai.types.responses.response_apply_patch_tool_call.ResponseApplyPatchToolCall> | <xref:openai.types.responses.response_apply_patch_tool_call_output.ResponseApplyPatchToolCallOutput> | <xref:openai.types.responses.response_output_item.McpCall> | <xref:openai.types.responses.response_output_item.McpListTools> | <xref:openai.types.responses.response_output_item.McpApprovalRequest> | <xref:openai.types.responses.response_output_item.McpApprovalResponse> | <xref:openai.types.responses.response_custom_tool_call.ResponseCustomToolCall> | <xref:openai.types.responses.response_custom_tool_call_output_item.ResponseCustomToolCallOutputItem>]
msg_idx
int
Default value: 0

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_tools 

get_attributes_from_tools(tools: Iterable[FunctionTool | FileSearchTool | ComputerTool | ComputerUsePreviewTool | WebSearchTool | Mcp | CodeInterpreter | ImageGeneration | LocalShell | FunctionShellTool | CustomTool | NamespaceTool | ToolSearchTool | WebSearchPreviewTool | ApplyPatchTool] | None) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
tools
Required
Iterable[<xref:openai.types.responses.function_tool.FunctionTool> | <xref:openai.types.responses.file_search_tool.FileSearchTool> | <xref:openai.types.responses.computer_tool.ComputerTool> | <xref:openai.types.responses.computer_use_preview_tool.ComputerUsePreviewTool> | <xref:openai.types.responses.web_search_tool.WebSearchTool> | <xref:openai.types.responses.tool.Mcp> | <xref:openai.types.responses.tool.CodeInterpreter> | <xref:openai.types.responses.tool.ImageGeneration> | <xref:openai.types.responses.tool.LocalShell> | <xref:openai.types.responses.function_shell_tool.FunctionShellTool> | <xref:openai.types.responses.custom_tool.CustomTool> | <xref:openai.types.responses.namespace_tool.NamespaceTool> | <xref:openai.types.responses.tool_search_tool.ToolSearchTool> | <xref:openai.types.responses.web_search_preview_tool.WebSearchPreviewTool> | <xref:openai.types.responses.apply_patch_tool.ApplyPatchTool>] | None

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_attributes_from_usage 

get_attributes_from_usage(obj: ResponseUsage | None) -> Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

Parameters

Name Description
obj
Required
<xref:openai.types.responses.response_usage.ResponseUsage> | None

Returns

Type Description
Iterator[tuple[str, Union[str, bool, int, float, Sequence[str], Sequence[bool], Sequence[int], Sequence[float]]]]

get_span_kind 

get_span_kind(obj: SpanData) -> str

Parameters

Name Description
obj
Required
<xref:agents.tracing.span_data.SpanData>

Returns

Type Description
str

get_span_name 

get_span_name(obj: Span[Any]) -> str

Parameters

Name Description
obj
Required
<xref:agents.tracing.spans.Span>[Any]

Returns

Type Description
str

get_span_status 

get_span_status(obj: Span[Any]) -> Status

Parameters

Name Description
obj
Required
<xref:agents.tracing.spans.Span>[Any]

Returns

Type Description
<xref:opentelemetry.trace.status.Status>

get_tool_call_id

Get and remove the tool_call_id for a function with specific arguments.

get_tool_call_id(function_name: str, function_args: str, pending_tool_calls: dict[str, str]) -> str | None

Parameters

Name Description
function_name
Required
str
function_args
Required
str
pending_tool_calls
Required
dict[str, str]

Returns

Type Description
str | None