OpenAI 列出子智能体条目

2026-11-18 18:02 更新

get /agents/sessions/{session_id}/subagents/{subagent_id}/items

列出此子智能体在所有轮次中生成的自身条目。参见子智能体工作流。

路径参数

  • session_id: string

会话 ID。

minLength: 0, maxLength: 1048576

  • subagent_id: string

此会话中的子智能体 ID。

minLength: 0, maxLength: 1048576

查询参数

  • after: optional string

按选定顺序返回此资源 ID 之后的资源。

minLength: 0, maxLength: 1048576

  • limit: optional integer (default: 20)

返回资源的最大数量,范围为 1 至 100,默认为 20。

format: int64, minimum: 1, maximum: 100

  • order: optional "asc" or "desc" (default: "desc")

返回资源的排序方式,默认为 desc。

  • "asc"

按升序返回资源。

  • "desc"

按降序返回资源。

返回值

  • data: array of AgentSessionItem

本页返回的资源,按指定顺序排列。

minItems: 0, maxItems: 2000

  • AgentSessionMessage object { id, content, phase, 4 more }

记录在会话中的用户消息或助手消息。

  • id: string or null

此条目的 ID。未记录 ID 的旧版用户消息返回 null。

minLength: 0

  • content: array of AgentSessionMessageContent

消息内容。用户消息含输入文本或图像,助手消息含输出文本。

minItems: 0, maxItems: 2000

  • InputText object { text, type }

用户提供的文本。

  • text: string

用户提供的文本。

minLength: 0

  • type: "input_text" (default: "input_text")

对象类型,固定为 input_text。

  • "input_text"

  • InputImage object { image_url, type }

用户提供的图像。

  • image_url: string

用户提供的图像 URL,可以是以 Base64 编码的 data URL。

minLength: 0

  • type: "input_image" (default: "input_image")

对象类型,固定为 input_image。

  • "input_image"

  • OutputText object { text, type }

助手生成的文本。

  • text: string

助手生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

对象类型,固定为 output_text。

  • "output_text"

  • phase: "commentary" or "final_answer" or null

助手消息所处的阶段。用户消息的此字段为 null。

  • "commentary"

智能体工作时生成的过程说明。

  • "final_answer"

智能体的最终回答。

  • role: "user" or "assistant"

消息作者的角色。

  • "user"

  • "assistant"

  • status: AgentOutputItemStatus

消息的状态。用户消息始终为 completed。

  • "in_progress"

条目正在处理。

  • "completed"

条目处理已完成。

  • "incomplete"

条目在完成前已停止。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "message" (default: "message")

类型,固定为message。

  • "message"

  • AgentReasoningItem object { id, status, summary, 2 more }

智能体生成的推理条目。

  • id: string

推理条目的 ID。

minLength: 0

  • status: AgentOutputItemStatus or null

推理条目的状态。

  • summary: array of SummaryText

智能体生成的推理摘要。

minItems: 0, maxItems: 2000

  • text: string

推理摘要文本。

minLength: 0

  • type: "summary_text" (default: "summary_text")

内容类型,固定为 summary_text。

  • "summary_text"

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "reasoning" (default: "reasoning")

条目类型,固定为 reasoning。

  • "reasoning"

  • AgentFunctionCallItem object { id, arguments, call_id, 4 more }

智能体生成的函数调用。

  • id: string

函数调用条目的 ID。

minLength: 0

  • arguments: unknown

要传给函数的参数。

  • call_id: string

用于提交函数结果的 ID。

minLength: 0

  • name: string

要调用的函数名称。

minLength: 0

  • status: AgentFunctionCallStatus

函数调用的状态。

  • "in_progress"

调用正在进行。

  • "completed"

调用已成功完成。

  • "failed"

调用失败。

  • "incomplete"

调用在完成前已停止。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "function_call" (default: "function_call")

条目类型,固定为 function_call。

  • "function_call"

  • FunctionCallOutput object { id, call_id, error, 4 more }

为函数调用提供的结果。

  • id: string

函数调用输出条目的 ID。

minLength: 0

  • call_id: string

生成此输出的函数调用 ID。

minLength: 0

  • error: string or null

调用失败时的错误消息。

minLength: 0

  • output: AgentFunctionCallOutput or null

调用成功时的函数结果。

  • string

minLength: 0

  • array of InputContent

minItems: 0, maxItems: 2000

  • InputText object { text, type }

记录在会话条目中的文本输入。

  • text: string

提供给智能体的文本。

minLength: 0

  • type: "input_text" (default: "input_text")

对象类型,固定为 input_text。

  • "input_text"

  • InputImage object { image_url, type }

记录在会话条目中的图像输入。

  • image_url: string

提供给智能体的图像 URL,可以是以 Base64 编码的 data URL。

minLength: 0

  • type: "input_image" (default: "input_image")

对象类型,固定为 input_image。

  • "input_image"

  • status: AgentFunctionCallStatus

函数调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "function_call_output" (default: "function_call_output")

条目类型,固定为 function_call_output。

  • "function_call_output"

  • AgentMessage object { id, content, recipient_agent_id, 3 more }

智能体线程之间交换的消息。

  • id: string

消息 ID。

minLength: 0

  • content: array of AgentContent

智能体之间交换的内容。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • text: string

智能体生成的文本。

minLength: 0

  • type: "output_text" (default: "output_text")

内容类型,固定为 output_text。

  • "output_text"

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • encrypted_content: string

加密内容载荷。

minLength: 0

  • type: "encrypted_content" (default: "encrypted_content")

内容类型,固定为 encrypted_content。

  • "encrypted_content"

  • recipient_agent_id: string

接收方智能体的 ID 或名称。

minLength: 0

  • sender_agent_id: string

发送方智能体的 ID 或名称。

minLength: 0

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "agent_message" (default: "agent_message")

条目类型,固定为 agent_message。

  • "agent_message"

  • AgentMcpCallItem object { id, arguments, error, 6 more }

调用 MCP 服务器工具的记录。

  • id: string

MCP 调用条目的 ID。

minLength: 0

  • arguments: unknown

传给 MCP 工具的参数。

  • error: unknown

MCP 工具返回的错误(如果有)。

  • name: string

MCP 工具名称。

minLength: 0

  • output: unknown

MCP 工具返回的输出(如果有)。

  • server_label: string

MCP服务器标签。

minLength: 0

  • status: AgentFunctionCallStatus

MCP 工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "mcp_call" (default: "mcp_call")

条目类型,固定为 mcp_call。

  • "mcp_call"

  • ComputerUseCall object { id, output, status, 3 more }

平台提供的计算机使用功能的一次执行。

  • id: string

活动条目的 ID。

minLength: 0

  • output: object { image_url, type } or null

模型发出的最后一张屏幕截图。未启用返回截图,或调用未生成截图时为 null。

  • image_url: string

完整的 JPEG 图像,表示为 Base64 data URL。

minLength: 0

  • type: "computer_screenshot" (default: "computer_screenshot")

内容类型,固定为 computer_screenshot。

  • "computer_screenshot"

  • status: AgentFunctionCallStatus

活动的执行状态。

  • title: string or null

模型生成的活动说明(如果有)。

minLength: 0

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "computer_use_call" (default: "computer_use_call")

条目类型,固定为 computer_use_call。

  • "computer_use_call"

  • ComputerUseApprovalRequest object { id, request, request_id, 2 more }

已发出登录请求的历史记录,其中省略凭证。

  • id: string

稳定的历史条目 ID。

minLength: 0

  • request: object { credential_origin, fields, options, 2 more }

等待应用响应的已注册表单。

  • credential_origin: string or null

将在其上填写值的已注册表单或框架的源站。

minLength: 0

  • fields: array of object { id, label, required, type }

要呈现的表单控件。所有提交的值均为敏感数据。

minItems: 0, maxItems: 2000

  • id: string

提交 fields 条目时要用作 field_id 的字段 ID。

minLength: 0

  • label: string

显示在控件旁的标签。

minLength: 0

  • required: boolean

此控件是否需要非空值。

  • type: string

控件的呈现类型,例如电子邮件、密码或文本。

minLength: 0

  • options: array of object { id, field_ids, label }

登录方式。普通表单中为空。

minItems: 0, maxItems: 2000

  • id: string

作为 selected_option 提交的选项 ID。

minLength: 0

  • field_ids: array of string

此方法接受的已注册字段 ID。

minItems: 0, maxItems: 2000

  • label: string

要显示的方式标签。

minLength: 0

  • reason: string or null

智能体需要用户登录的原因。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

对象类型,固定为 browser_authentication。

  • "browser_authentication"

  • request_id: string

minLength: 0

  • turn_id: string

minLength: 0

  • type: "computer_use_approval_request" (default: "computer_use_approval_request")

条目类型,固定为 computer_use_approval_request。

  • "computer_use_approval_request"

  • ComputerUseApprovalRequestResult object { id, request_id, response, 2 more }

已受理响应的记录,其中省略凭证。实际是否完成需另外确认。

  • id: string

稳定的历史条目 ID。

minLength: 0

  • request_id: string

此条目响应的已注册请求。

minLength: 0

  • response: Submit { action, selected_option, type } or Cancel { action, type }

已受理的响应,其中省略提交的凭证值。

  • Submit object { action, selected_option, type }

  • action: "submit" (default: "submit")

  • "submit"

  • selected_option: string or null

选中的登录方式。未提供候选方式时为 null。

minLength: 0

  • type: "browser_authentication" (default: "browser_authentication")

  • "browser_authentication"

  • Cancel object { action, type }

  • action: "cancel" (default: "cancel")

  • "cancel"

  • type: "browser_authentication" (default: "browser_authentication")

  • "browser_authentication"

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "computer_use_approval_request_result" (default: "computer_use_approval_request_result")

  • "computer_use_approval_request_result"

  • AgentWebSearchCallItem object { id, action, status, 2 more }

智能体生成的网页搜索调用。

  • id: string

网页搜索调用 ID。

minLength: 0

  • action: WebSearchAction or null

网页搜索工具执行的操作。

  • Search object { queries, query, type }

一条或一组搜索查询。

  • queries: array of string or null

使用多条查询时的搜索查询列表。

minItems: 0, maxItems: 2000

  • query: string or null

使用单条查询时的搜索查询。

minLength: 0

  • type: "search" (default: "search")

对象类型,固定为 search。

  • "search"

  • OpenPage object { type, url }

打开网页。

  • type: "open_page" (default: "open_page")

对象类型,固定为 open_page。

  • "open_page"

  • url: string or null

打开的网页的 URL。

minLength: 0

  • FindInPage object { pattern, type, url }

在网页中查找文本。

  • pattern: string or null

要查找的文本模式。

minLength: 0

  • type: "find_in_page" (default: "find_in_page")

对象类型,固定为 find_in_page。

  • "find_in_page"

  • url: string or null

执行查找操作的网页 URL。

minLength: 0

  • Other object { type }

其他网页搜索操作。

  • type: "other" (default: "other")

对象类型,固定为 other。

  • "other"

  • status: AgentOutputItemStatus

网页搜索调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "web_search_call" (default: "web_search_call")

条目类型,固定为 web_search_call。

  • "web_search_call"

  • AgentCommandExecutionItem object { id, command, cwd, 6 more }

智能体生成的命令执行记录。

  • id: string

命令执行条目的 ID。

minLength: 0

  • command: string

执行过的命令。

minLength: 0

  • cwd: string or null

执行命令时使用的工作目录。

minLength: 0

  • duration_ms: integer or null

命令执行时长,单位为毫秒。

format: int64

  • exit_code: integer or null

命令执行结束后的进程退出码。

format: int64

  • output: string or null

命令输出(如果有)。

minLength: 0

  • status: AgentFunctionCallStatus

命令执行的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "command_execution" (default: "command_execution")

条目类型,固定为 command_execution。

  • "command_execution"

  • AgentCreateSubagentCallItem object { id, agent_id, content, 5 more }

创建子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • agent_id: string

请求创建子智能体的智能体 ID。

minLength: 0

  • content: array of AgentContent

交给新建智能体的任务。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • model: string or null

为新建的子智能体指定的模型。

minLength: 0

  • reasoning_effort: string or null

为新建的子智能体指定的推理强度。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "create_subagent_call" (default: "create_subagent_call")

条目类型,固定为 create_subagent_call。

  • "create_subagent_call"

  • AgentSendSubagentInputCallItem object { id, content, recipient_agent_id, 4 more }

向另一智能体发送输入的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • content: array of AgentContent

发给接收方智能体的输入。

minItems: 0, maxItems: 2000

  • OutputText object { text, type }

智能体生成的一段文本内容。

  • EncryptedContent object { encrypted_content, type }

智能体之间交换的加密内容。

  • recipient_agent_id: string

接收输入的智能体 ID。

minLength: 0

  • sender_agent_id: string

发送输入的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "send_subagent_input_call" (default: "send_subagent_input_call")

条目类型,固定为 send_subagent_input_call。

  • "send_subagent_input_call"

  • AgentResumeSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

恢复子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要恢复的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起恢复请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "resume_subagent_call" (default: "resume_subagent_call")

条目类型,固定为 resume_subagent_call。

  • "resume_subagent_call"

  • AgentWaitForSubagentsCallItem object { id, recipient_agent_ids, sender_agent_id, 3 more }

等待一个或多个子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_ids: array of string

要等待的智能体 ID 列表。

minItems: 0, maxItems: 2000

  • sender_agent_id: string

等待结果的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "wait_for_subagents_call" (default: "wait_for_subagents_call")

条目类型,固定为 wait_for_subagents_call。

  • "wait_for_subagents_call"

  • AgentInterruptSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

中断子智能体当前轮次的请求。该子智能体仍可使用。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要中断的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起中断请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "interrupt_subagent_call" (default: "interrupt_subagent_call")

条目类型,固定为 interrupt_subagent_call。

  • "interrupt_subagent_call"

  • AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

关闭子智能体的请求。

  • id: string

工具调用条目的 ID。

minLength: 0

  • recipient_agent_id: string

要关闭的智能体 ID。

minLength: 0

  • sender_agent_id: string

发起关闭请求的智能体 ID。

minLength: 0

  • status: AgentFunctionCallStatus

工具调用的状态。

  • turn_id: string

包含此条目的轮次 ID。

minLength: 0

  • type: "close_subagent_call" (default: "close_subagent_call")

条目类型,固定为 close_subagent_call。

  • "close_subagent_call"

  • first_id: string or null

data 中第一项的资源 ID。当前页为空时为 null。

minLength: 0

  • has_more: boolean

当前页之后是否还有可获取的资源。

  • last_id: string or null

data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。

minLength: 0

  • object: "list" (default: "list")

对象类型,恒为 list。

  • "list"

示例

## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
## 将 SUBAGENT_ID 设置为目标子智能体的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/subagents/$SUBAGENT_ID/items \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

字段名、类型值和示例标识均按接口定义保留。

{
  "data": [
    {
      "id": "id",
      "content": [
        {
          "text": "text",
          "type": "input_text"
        }
      ],
      "phase": "commentary",
      "role": "user",
      "status": "in_progress",
      "turn_id": "turn_id",
      "type": "message"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号