Items

TResponse module-attribute

TResponse = Response

OpenAI SDK 中 Response 类型的类型别名。

TResponseInputItem module-attribute

TResponseInputItem = ResponseInputItemParam

OpenAI SDK 中 ResponseInputItemParam 类型的类型别名。

TResponseOutputItem module-attribute

TResponseOutputItem = ResponseOutputItem

OpenAI SDK 中 ResponseOutputItem 类型的类型别名。

TResponseStreamEvent module-attribute

TResponseStreamEvent = ResponseStreamEvent

OpenAI SDK 中 ResponseStreamEvent 类型的类型别名。

ToolCallItemTypes module-attribute

ToolCallItemTypes: TypeAlias = Union[
    ResponseFunctionToolCall,
    ResponseComputerToolCall,
    ResponseFileSearchToolCall,
    ResponseFunctionWebSearch,
    McpCall,
    ResponseCodeInterpreterToolCall,
    ImageGenerationCall,
    LocalShellCall,
]

表示工具调用条目的类型。

RunItem module-attribute

RunItem: TypeAlias = Union[
    MessageOutputItem,
    HandoffCallItem,
    HandoffOutputItem,
    ToolCallItem,
    ToolCallOutputItem,
    ReasoningItem,
    MCPListToolsItem,
    MCPApprovalRequestItem,
    MCPApprovalResponseItem,
]

由 agent 生成的条目。

RunItemBase dataclass

Bases: Generic[T], ABC

Source code in src/agents/items.py

@dataclass
class RunItemBase(Generic[T], abc.ABC):
    agent: Agent[Any]
    """生成该条目的 agent。"""

    raw_item: T
    """本次运行中原始的 Responses 条目。始终为输出项（即 openai.types.responses.ResponseOutputItem）
    或输入项（即 openai.types.responses.ResponseInputItemParam）。
    """

    def to_input_item(self) -> TResponseInputItem:
        """将该条目转换为适合传递给模型的输入项。"""
        if isinstance(self.raw_item, dict):
            # 我们知道输入项是 dict，可以忽略类型错误
            return self.raw_item  # type: ignore
        elif isinstance(self.raw_item, BaseModel):
            # 所有输出项都是可转换为输入项的 Pydantic 模型
            return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
        else:
            raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

raw_item instance-attribute

raw_item: T

本次运行中原始的 Responses 条目。始终为输出项（即 openai.types.responses.ResponseOutputItem） 或输入项（即 openai.types.responses.ResponseInputItemParam）。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

MessageOutputItem dataclass

Bases: RunItemBase[ResponseOutputMessage]

表示来自 LLM 的消息。

Source code in src/agents/items.py

@dataclass
class MessageOutputItem(RunItemBase[ResponseOutputMessage]):
    """表示来自 LLM 的消息。"""

    raw_item: ResponseOutputMessage
    """原始响应输出消息。"""

    type: Literal["message_output_item"] = "message_output_item"

raw_item instance-attribute

raw_item: ResponseOutputMessage

原始响应输出消息。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

HandoffCallItem dataclass

Bases: RunItemBase[ResponseFunctionToolCall]

表示从一个 agent 到另一个 agent 的交接工具调用。

Source code in src/agents/items.py

@dataclass
class HandoffCallItem(RunItemBase[ResponseFunctionToolCall]):
    """表示从一个 agent 到另一个 agent 的交接工具调用。"""

    raw_item: ResponseFunctionToolCall
    """表示交接的原始响应函数工具调用。"""

    type: Literal["handoff_call_item"] = "handoff_call_item"

raw_item instance-attribute

raw_item: ResponseFunctionToolCall

表示交接的原始响应函数工具调用。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

HandoffOutputItem dataclass

Bases: RunItemBase[TResponseInputItem]

表示交接的输出。

Source code in src/agents/items.py

@dataclass
class HandoffOutputItem(RunItemBase[TResponseInputItem]):
    """表示交接的输出。"""

    raw_item: TResponseInputItem
    """表示交接发生的原始输入项。"""

    source_agent: Agent[Any]
    """发起交接的 agent。"""

    target_agent: Agent[Any]
    """被交接到的 agent。"""

    type: Literal["handoff_output_item"] = "handoff_output_item"

raw_item instance-attribute

raw_item: TResponseInputItem

表示交接发生的原始输入项。

source_agent instance-attribute

source_agent: Agent[Any]

发起交接的 agent。

target_agent instance-attribute

target_agent: Agent[Any]

被交接到的 agent。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

ToolCallItem dataclass

Bases: RunItemBase[ToolCallItemTypes]

表示工具调用，例如函数调用或计算机动作调用。

Source code in src/agents/items.py

@dataclass
class ToolCallItem(RunItemBase[ToolCallItemTypes]):
    """表示工具调用，例如函数调用或计算机动作调用。"""

    raw_item: ToolCallItemTypes
    """原始工具调用条目。"""

    type: Literal["tool_call_item"] = "tool_call_item"

raw_item instance-attribute

raw_item: ToolCallItemTypes

原始工具调用条目。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

ToolCallOutputItem dataclass

Bases: RunItemBase[Union[FunctionCallOutput, ComputerCallOutput, LocalShellCallOutput]]

表示工具调用的输出。

Source code in src/agents/items.py

@dataclass
class ToolCallOutputItem(
    RunItemBase[Union[FunctionCallOutput, ComputerCallOutput, LocalShellCallOutput]]
):
    """表示工具调用的输出。"""

    raw_item: FunctionCallOutput | ComputerCallOutput | LocalShellCallOutput
    """来自模型的原始条目。"""

    output: Any
    """工具调用的输出。即工具调用返回的内容；`raw_item` 包含输出的字符串表示。"""

    type: Literal["tool_call_output_item"] = "tool_call_output_item"

raw_item instance-attribute

raw_item: (
    FunctionCallOutput
    | ComputerCallOutput
    | LocalShellCallOutput
)

来自模型的原始条目。

output instance-attribute

output: Any

工具调用的输出。即工具调用返回的内容；raw_item 包含输出的字符串表示。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

ReasoningItem dataclass

Bases: RunItemBase[ResponseReasoningItem]

表示推理条目。

Source code in src/agents/items.py

@dataclass
class ReasoningItem(RunItemBase[ResponseReasoningItem]):
    """表示推理条目。"""

    raw_item: ResponseReasoningItem
    """原始推理条目。"""

    type: Literal["reasoning_item"] = "reasoning_item"

raw_item instance-attribute

raw_item: ResponseReasoningItem

原始推理条目。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

MCPListToolsItem dataclass

Bases: RunItemBase[McpListTools]

表示对 MCP 服务器的列出工具调用。

Source code in src/agents/items.py

@dataclass
class MCPListToolsItem(RunItemBase[McpListTools]):
    """表示对 MCP 服务器的列出工具调用。"""

    raw_item: McpListTools
    """原始 MCP 列出工具调用。"""

    type: Literal["mcp_list_tools_item"] = "mcp_list_tools_item"

raw_item instance-attribute

raw_item: McpListTools

原始 MCP 列出工具调用。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

MCPApprovalRequestItem dataclass

Bases: RunItemBase[McpApprovalRequest]

表示 MCP 审批请求。

Source code in src/agents/items.py

@dataclass
class MCPApprovalRequestItem(RunItemBase[McpApprovalRequest]):
    """表示 MCP 审批请求。"""

    raw_item: McpApprovalRequest
    """原始 MCP 审批请求。"""

    type: Literal["mcp_approval_request_item"] = "mcp_approval_request_item"

raw_item instance-attribute

raw_item: McpApprovalRequest

原始 MCP 审批请求。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

MCPApprovalResponseItem dataclass

Bases: RunItemBase[McpApprovalResponse]

表示对 MCP 审批请求的响应。

Source code in src/agents/items.py

@dataclass
class MCPApprovalResponseItem(RunItemBase[McpApprovalResponse]):
    """表示对 MCP 审批请求的响应。"""

    raw_item: McpApprovalResponse
    """原始 MCP 审批响应。"""

    type: Literal["mcp_approval_response_item"] = "mcp_approval_response_item"

raw_item instance-attribute

raw_item: McpApprovalResponse

原始 MCP 审批响应。

agent instance-attribute

agent: Agent[Any]

生成该条目的 agent。

to_input_item

to_input_item() -> TResponseInputItem

将该条目转换为适合传递给模型的输入项。

Source code in src/agents/items.py

def to_input_item(self) -> TResponseInputItem:
    """将该条目转换为适合传递给模型的输入项。"""
    if isinstance(self.raw_item, dict):
        # 我们知道输入项是 dict，可以忽略类型错误
        return self.raw_item  # type: ignore
    elif isinstance(self.raw_item, BaseModel):
        # 所有输出项都是可转换为输入项的 Pydantic 模型
        return self.raw_item.model_dump(exclude_unset=True)  # type: ignore
    else:
        raise AgentsException(f"Unexpected raw item type: {type(self.raw_item)}")

ModelResponse dataclass

Source code in src/agents/items.py

@dataclass
class ModelResponse:
    output: list[TResponseOutputItem]
    """模型生成的输出（消息、工具调用等）的列表"""

    usage: Usage
    """响应的用量信息。"""

    response_id: str | None
    """响应的 ID，可用于在后续调用中引用该响应。并非所有模型提供商都支持。
    如果使用 OpenAI 的 Responses API，则为 `response_id` 参数，可传递给 `Runner.run`。
    """

    def to_input_items(self) -> list[TResponseInputItem]:
        """将输出转换为适合传递给模型的输入项列表。"""
        # 我们知道 Pydantic 输出项的结构与等价的 TypedDict 输入项一致，因此可以直接转换。
        # 这也通过单元测试验证。
        return [it.model_dump(exclude_unset=True) for it in self.output]  # type: ignore

output instance-attribute

output: list[TResponseOutputItem]

模型生成的输出（消息、工具调用等）的列表

usage instance-attribute

usage: Usage

响应的用量信息。

response_id instance-attribute

response_id: str | None

响应的 ID，可用于在后续调用中引用该响应。并非所有模型提供商都支持。 如果使用 OpenAI 的 Responses API，则为 response_id 参数，可传递给 Runner.run。

to_input_items

to_input_items() -> list[TResponseInputItem]

将输出转换为适合传递给模型的输入项列表。

Source code in src/agents/items.py

def to_input_items(self) -> list[TResponseInputItem]:
    """将输出转换为适合传递给模型的输入项列表。"""
    # 我们知道 Pydantic 输出项的结构与等价的 TypedDict 输入项一致，因此可以直接转换。
    # 这也通过单元测试验证。
    return [it.model_dump(exclude_unset=True) for it in self.output]  # type: ignore

ItemHelpers

Source code in src/agents/items.py

class ItemHelpers:
    @classmethod
    def extract_last_content(cls, message: TResponseOutputItem) -> str:
        """从消息中提取最后一条文本内容或拒绝内容。"""
        if not isinstance(message, ResponseOutputMessage):
            return ""

        last_content = message.content[-1]
        if isinstance(last_content, ResponseOutputText):
            return last_content.text
        elif isinstance(last_content, ResponseOutputRefusal):
            return last_content.refusal
        else:
            raise ModelBehaviorError(f"Unexpected content type: {type(last_content)}")

    @classmethod
    def extract_last_text(cls, message: TResponseOutputItem) -> str | None:
        """从消息中提取最后一条文本内容（如果有）。忽略拒绝内容。"""
        if isinstance(message, ResponseOutputMessage):
            last_content = message.content[-1]
            if isinstance(last_content, ResponseOutputText):
                return last_content.text

        return None

    @classmethod
    def input_to_new_input_list(
        cls, input: str | list[TResponseInputItem]
    ) -> list[TResponseInputItem]:
        """将字符串或输入项列表转换为输入项列表。"""
        if isinstance(input, str):
            return [
                {
                    "content": input,
                    "role": "user",
                }
            ]
        return copy.deepcopy(input)

    @classmethod
    def text_message_outputs(cls, items: list[RunItem]) -> str:
        """将消息输出项列表中的所有文本内容拼接起来。"""
        text = ""
        for item in items:
            if isinstance(item, MessageOutputItem):
                text += cls.text_message_output(item)
        return text

    @classmethod
    def text_message_output(cls, message: MessageOutputItem) -> str:
        """提取单个消息输出项中的所有文本内容。"""
        text = ""
        for item in message.raw_item.content:
            if isinstance(item, ResponseOutputText):
                text += item.text
        return text

    @classmethod
    def tool_call_output_item(
        cls, tool_call: ResponseFunctionToolCall, output: str
    ) -> FunctionCallOutput:
        """根据工具调用及其输出创建工具调用输出项。"""
        return {
            "call_id": tool_call.call_id,
            "output": output,
            "type": "function_call_output",
        }

extract_last_content classmethod

extract_last_content(message: TResponseOutputItem) -> str

从消息中提取最后一条文本内容或拒绝内容。

Source code in src/agents/items.py

@classmethod
def extract_last_content(cls, message: TResponseOutputItem) -> str:
    """从消息中提取最后一条文本内容或拒绝内容。"""
    if not isinstance(message, ResponseOutputMessage):
        return ""

    last_content = message.content[-1]
    if isinstance(last_content, ResponseOutputText):
        return last_content.text
    elif isinstance(last_content, ResponseOutputRefusal):
        return last_content.refusal
    else:
        raise ModelBehaviorError(f"Unexpected content type: {type(last_content)}")

extract_last_text classmethod

extract_last_text(
    message: TResponseOutputItem,
) -> str | None

从消息中提取最后一条文本内容（如果有）。忽略拒绝内容。

Source code in src/agents/items.py

@classmethod
def extract_last_text(cls, message: TResponseOutputItem) -> str | None:
    """从消息中提取最后一条文本内容（如果有）。忽略拒绝内容。"""
    if isinstance(message, ResponseOutputMessage):
        last_content = message.content[-1]
        if isinstance(last_content, ResponseOutputText):
            return last_content.text

    return None

input_to_new_input_list classmethod

input_to_new_input_list(
    input: str | list[TResponseInputItem],
) -> list[TResponseInputItem]

将字符串或输入项列表转换为输入项列表。

Source code in src/agents/items.py

@classmethod
def input_to_new_input_list(
    cls, input: str | list[TResponseInputItem]
) -> list[TResponseInputItem]:
    """将字符串或输入项列表转换为输入项列表。"""
    if isinstance(input, str):
        return [
            {
                "content": input,
                "role": "user",
            }
        ]
    return copy.deepcopy(input)

text_message_outputs classmethod

text_message_outputs(items: list[RunItem]) -> str

将消息输出项列表中的所有文本内容拼接起来。

Source code in src/agents/items.py

@classmethod
def text_message_outputs(cls, items: list[RunItem]) -> str:
    """将消息输出项列表中的所有文本内容拼接起来。"""
    text = ""
    for item in items:
        if isinstance(item, MessageOutputItem):
            text += cls.text_message_output(item)
    return text

text_message_output classmethod

text_message_output(message: MessageOutputItem) -> str

提取单个消息输出项中的所有文本内容。

Source code in src/agents/items.py

@classmethod
def text_message_output(cls, message: MessageOutputItem) -> str:
    """提取单个消息输出项中的所有文本内容。"""
    text = ""
    for item in message.raw_item.content:
        if isinstance(item, ResponseOutputText):
            text += item.text
    return text

tool_call_output_item classmethod

tool_call_output_item(
    tool_call: ResponseFunctionToolCall, output: str
) -> FunctionCallOutput

根据工具调用及其输出创建工具调用输出项。

Source code in src/agents/items.py

@classmethod
def tool_call_output_item(
    cls, tool_call: ResponseFunctionToolCall, output: str
) -> FunctionCallOutput:
    """根据工具调用及其输出创建工具调用输出项。"""
    return {
        "call_id": tool_call.call_id,
        "output": output,
        "type": "function_call_output",
    }