OpenAI 列出智能体会话
get /agents/sessions
按指定排序方式列出托管智能体会话,使用基于 ID 的分页。参见管理会话。
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
agent_id: optional string
仅返回根智能体 ID 为此值的会话。省略时返回所有智能体的会话。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
metadata: optional map[string]
使用 metadata[key]=value 提供完全匹配的字符串条件。所有键值对都必须匹配。最多 16 对,键长为 1 至 64 个字符,值最长为 512 个字符。新会话及元数据更新可能过一段时间才会反映到筛选结果中。
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of AgentSession
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
会话 ID。
minLength: 0
agent: object { id, instructions, model, 8 more }
在会话内运行的智能体。
id: string
智能体的 ID。
minLength: 0
instructions: string or null
附加到智能体默认基础指令之后的自定义指令。
minLength: 0
model: string
智能体使用的模型。
minLength: 0
multi_agent: MultiAgentConfig
创建和协调子智能体的配置。
enabled: boolean
是否启用子智能体工具。默认关闭。
max_concurrent_subagents: integer or null
可同时运行的子智能体数上限。禁用时为 null,启用时默认为 6。
format: int64, minimum: 1, maximum: 4294967295
name: string or null
创建会话时可复用智能体的名称。没有保存名称时为 null。之后修改智能体名称不会改变此值。
minLength: 0
reasoning: AgentReasoning
智能体的推理配置。
effort: "none" or "minimal" or "low" or 4 more or null
请求的推理强度。由模型选择推理强度时为 null。
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
summary: "concise" or "detailed" or "auto" or null
请求的推理摘要格式。禁用摘要时为 null。
"concise"
模型支持时,返回简明推理摘要。
"detailed"
模型支持时,返回详细推理摘要。
"auto"
自动选择模型支持的最详细摘要。
service_tier: "auto" or "default" or "flex" or 3 more
模型请求实际采用的服务层级策略。默认为 auto。
"auto"
"default"
"flex"
"priority"
"fast"
"ultrafast"
text: AgentText
智能体生成文本的配置。
format: TextFormat
当前生效的输出格式,默认为普通文本。
Text object { type }
生成普通文本,无结构化输出限制。
type: "text" (default: "text")
对象类型,恒为 text。
"text"
JSONSchema object { schema, type }
将生成的文本限制为符合指定 JSON Schema。
schema: map[unknown]
生成的文本必须符合的 JSON Schema。
type: "json_schema" (default: "json_schema")
对象类型,恒为 json_schema。
"json_schema"
verbosity: "low" or "medium" or "high"
智能体生成文本的量。默认为 medium。
"low"
"medium"
"high"
tools: array of AgentTool
智能体可用的工具。
minItems: 0, maxItems: 2000
Function object { defer_loading, description, name, 3 more }
应用定义的函数。
defer_loading: boolean
函数是否延迟加载并通过工具搜索发现。
description: string
说明函数的用途。
minLength: 0
name: string
函数名称。
minLength: 0
parameters: map[unknown]
描述函数参数的 JSON Schema 对象。
type: "function" (default: "function")
对象类型,恒为 function。
"function"
async: optional boolean
智能体是否无需等待函数结果即可继续。
ProgrammaticToolCalling object { enabled, type }
允许模型生成的代码调用工具。
enabled: boolean
是否允许从模型生成的代码调用工具。
type: "programmatic_tool_calling" (default: "programmatic_tool_calling")
对象类型,恒为 programmatic_tool_calling。
"programmatic_tool_calling"
Mcp object { allowed_tools, connection_origin, credential_id, 5 more }
远程 MCP 服务器提供的工具。
allowed_tools: array of string or null
智能体可调用的 MCP 工具。
minItems: 0, maxItems: 2000
connection_origin: "service" or "environment"
出站 MCP HTTP 连接的来源。
"service"
"environment"
credential_id: string or null
为此 MCP 服务器选用的已附加凭证库凭证(如有)。只有一条已附加凭证与服务器 URL 匹配时,可以省略。
minLength: 0
request_metadata: map[unknown]
随请求发送给此 MCP 服务器的元数据。
required: boolean
是否必须在第一轮前初始化此 MCP 服务器。
server_label: string
用于在工具调用中标识 MCP 服务器的标签。
minLength: 0
transport: McpTransport
用于连接 MCP 服务器的传输方式。
HTTP object { server_url, type }
通过 HTTP 连接到 MCP 服务器。
server_url: string
MCP 服务器的 URL。
minLength: 0
type: "http" (default: "http")
对象类型,恒为 http。
"http"
Stdio object { args, command, cwd, 2 more }
以本地进程方式启动 MCP 服务器。
args: array of string
传递给 MCP 服务器启动命令的参数。
minItems: 0, maxItems: 2000
command: string
用于启动 MCP 服务器的命令。
minLength: 0
cwd: string
用于启动 MCP 服务器的工作目录。
minLength: 0
env_vars: array of string
从执行环境继承的环境变量名称。
minItems: 0, maxItems: 2000
type: "stdio" (default: "stdio")
对象类型,恒为 stdio。
"stdio"
type: "mcp" (default: "mcp")
对象类型,恒为 mcp。
"mcp"
WebSearch object { allowed_domains, context_size, location, 2 more }
网页搜索。
allowed_domains: array of string or null
允许搜索的域名。搜索范围不受限制时为 null。
minItems: 0, maxItems: 2000
context_size: "low" or "medium" or "high"
向模型提供的搜索上下文量。默认为 medium。
"low"
"medium"
"high"
location: object { city, country, region, timezone } or null
用于按地理位置调整搜索结果的近似位置(如果提供)。
city: string or null
城市名称。
minLength: 0
country: string or null
两个字母的 ISO 国家或地区代码,例如 US。
minLength: 0
region: string or null
地区或州的名称。
minLength: 0
timezone: string or null
IANA 时区,例如 America/Los_Angeles。
minLength: 0
mode: "disabled" or "cached" or "live"
网页搜索结果的来源。
"disabled"
"cached"
"live"
type: "web_search" (default: "web_search")
对象类型,恒为 web_search。
"web_search"
ComputerUse object { include_screenshots, type }
在 OpenAI 托管会话中使用浏览器。
include_screenshots: boolean
计算机工具的输出是否包含屏幕截图。
type: "computer_use" (default: "computer_use")
对象类型,恒为 computer_use。
"computer_use"
Automations object { type }
允许智能体安排自身的定时唤醒。
type: "automations" (default: "automations")
对象类型,恒为 automations。
"automations"
compaction: optional object { async }
当前生效的上下文压缩配置。
async: boolean
是否在后台压缩上下文。默认为 false。
experimental: optional object { time_awareness }
当前生效的实验性设置。
time_awareness: boolean
模型是否会定期收到当前时间提醒。
created_at: integer
会话创建时的 Unix 时间戳,单位为秒。
format: int64
environment: Environment
会话的执行环境。
None object { type }
会话与 CCA 通信,无需选择或配置执行环境。
type: "none" (default: "none")
对象类型,固定为 none。
"none"
OpenAIHosted object { id, capability_directories, desktop, 7 more }
OpenAI 托管的环境。
id: string
环境的公开 ID。
minLength: 0
capability_directories: array of string
包含可向智能体提供的能力的目录。
minItems: 0, maxItems: 2000
desktop: object { enabled }
当前生效的桌面配置。
enabled: boolean
环境是否配置桌面及浏览器代理。
files: array of HostedEnvironmentFile
环境中的可用文件。响应省略文件内容。
minItems: 0, maxItems: 50
HostedEnvironmentFileID object { id, file_id, path, 2 more }
从 OpenAI Files API 复制的文件。
id: string
执行环境中会话范围内的文件 ID。
minLength: 0
file_id: string
已上传文件的 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "file_id" (default: "file_id")
对象类型,固定为 file_id。
"file_id"
Inline object { id, path, size_bytes, type }
创建会话时以内联方式提供的文件。
id: string
执行环境中会话范围内的文件 ID。
minLength: 0
path: string
文件在环境内的绝对路径。
minLength: 0
size_bytes: integer
文件解码后的大小,单位为字节。
format: int64, minimum: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
network: object { access, allowed_domains }
当前生效的环境网络访问策略。
access: "enabled" or "disabled" or "restricted"
环境的网络访问模式。
"enabled"
允许不受限制的网络访问。
"disabled"
关闭网络访问。
"restricted"
应用配置的域名访问限制。
allowed_domains: array of string
网络访问受限时,环境可以访问的域名。
minItems: 0, maxItems: 2000
packages: object { npm, python, system }
在环境中安装的软件包。
npm: array of string
在环境中全局安装的 npm 软件包。
minItems: 0, maxItems: 16384
python: array of string
已安装到环境中的 Python 软件包。
minItems: 0, maxItems: 16384
system: array of string
已安装到环境中的系统软件包。
minItems: 0, maxItems: 16384
plugins: array of HostedPlugin
在环境中安装的插件。响应省略其归档内容。
minItems: 0, maxItems: 2000
description: string
已安装插件的描述。
minLength: 0
name: string
已安装插件的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
skills: array of HostedSkill
在环境中安装的技能。响应省略其归档内容。
minItems: 0, maxItems: 2000
HostedSkillReference object { description, name, skill_id, 2 more }
从 Skills API 安装的技能。
description: string
已安装技能的描述。
minLength: 0
name: string
已安装技能的名称。
minLength: 0
skill_id: string
引用的技能 ID。
minLength: 0
type: "skill_reference" (default: "skill_reference")
对象类型,固定为 skill_reference。
"skill_reference"
version: string
此会话实际安装的技能版本。
minLength: 0
Inline object { description, name, type }
从内联 ZIP 归档安装的技能。
description: string
已安装技能的描述。
minLength: 0
name: string
已安装技能的名称。
minLength: 0
type: "inline" (default: "inline")
对象类型,固定为 inline。
"inline"
type: "openai_hosted" (default: "openai_hosted")
对象类型,固定为 openai_hosted。
"openai_hosted"
container_size: optional "small" or "medium" or "large" or null
实际使用的 CPU 和内存规格。规格未知或超出公开规格范围时为 null。
"small"
"medium"
"large"
SelfHosted object { id, capability_directories, remote_url, 2 more }
应用托管的环境。
id: string
环境的公开 ID。
minLength: 0
capability_directories: array of string
包含可向智能体提供的能力的目录。
minItems: 0, maxItems: 2000
remote_url: string
连接此环境时,将此 URL 原样传给 codex exec-server --remote。
minLength: 0
type: "self_hosted" (default: "self_hosted")
对象类型,固定为 self_hosted。
"self_hosted"
workspace_directory: string
环境内项目目录的绝对路径,默认为 /workspace。
minLength: 0
error: string or null
导致会话失败的错误(如有)。
minLength: 0
last_active_at: integer
会话最后一次活跃时的 Unix 时间戳,单位为秒。
format: int64
metadata: map[string]
附加到会话的自定义字符串键值对。
object: "agent.session" (default: "agent.session")
对象类型,固定为 agent.session。
"agent.session"
required_actions: array of McpApprovalRequest { request, request_id, turn_id, type } or ComputerUseApprovalRequest { request, request_id, turn_id, type } or FunctionCall { arguments, call_id, name, 2 more } or EnvironmentConnection { environment_id, type }
会话继续之前必须完成的操作。
minItems: 0, maxItems: 2000
McpApprovalRequest object { request, request_id, turn_id, type }
响应 MCP 工具调用的审批请求。
request: object { arguments, message, name, 2 more }
呈现 MCP 审批所需的信息。
arguments: unknown
JSON 格式的工具参数。CCA 未提供时为 null。
message: string
minLength: 0
name: string or null
工具的名称。CCA 未提供时为 null。
minLength: 0
server_label: string
minLength: 0
type: "mcp_tool_call" (default: "mcp_tool_call")
对象类型,固定为 mcp_tool_call。
"mcp_tool_call"
request_id: string
响应时需要原样返回的不透明审批 ID。
minLength: 0
turn_id: string
请求审批的轮次。
minLength: 0
type: "mcp_approval_request" (default: "mcp_approval_request")
对象类型,固定为 mcp_approval_request。
"mcp_approval_request"
ComputerUseApprovalRequest object { request, request_id, turn_id, type }
响应计算机使用请求。
request: BrowserAuthentication { credential_origin, fields, options, 2 more } or BrowserOriginAccess { origin, reason, type }
呈现该请求所需的信息。
BrowserAuthentication 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"
BrowserOriginAccess object { origin, reason, type }
等待应用审批决定的浏览器源站。
origin: string
浏览器要访问且需要授权的源站。
minLength: 0
reason: string or null
浏览器对本请求的说明。无法取得时为 null。
minLength: 0
type: "browser_origin_access" (default: "browser_origin_access")
对象类型,固定为 browser_origin_access。
"browser_origin_access"
request_id: string
响应时需要原样返回的已注册请求 ID。
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"
FunctionCall object { arguments, call_id, name, 2 more }
运行函数工具并提交其结果。
arguments: unknown
模型提供的参数。
call_id: string
提交函数结果时应包含的 ID。
minLength: 0
name: string
函数的名称。
minLength: 0
turn_id: string
请求函数调用的轮次 ID。
minLength: 0
type: "function_call" (default: "function_call")
对象类型,固定为 function_call。
"function_call"
EnvironmentConnection object { environment_id, type }
重新连接会话环境。
environment_id: string
要重新连接的环境 ID。
minLength: 0
type: "environment_connection" (default: "environment_connection")
对象类型,固定为 environment_connection。
"environment_connection"
status: "idle" or "in_progress" or "requires_action" or "failed"
会话当前的状态。
"idle"
会话没有正在进行的轮次,可以接收输入。托管环境可能仍在配置中。
"in_progress"
会话正在处理一轮交互。
"requires_action"
会话正在等待一个或多个必需操作。
"failed"
会话已失败。
usage: TokenUsage or null
会话中能统计到的词元用量。用量未知时为 null,已经记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
vault_ids: array of string
本会话可访问的凭证库 ID。
minItems: 0, maxItems: 2000
prompt_cache_options: optional object { ttl } or null
此会话各轮次采用的默认提示词缓存时长(如已配置)。
ttl: "30m" or "12h"
"30m"
"12h"
review: optional "none" or "auto_review"
应用于本会话中适用操作的审查方式。审查模式为 none 且自动审查未启用时,响应省略此字段。字段省略表示 none。
"none"
"auto_review"
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 密钥。
curl https://api.openai.com/v1/agents/sessions \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"agent": {
"id": "id",
"instructions": "instructions",
"model": "model",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 1
},
"name": "name",
"reasoning": {
"effort": "none",
"summary": "concise"
},
"service_tier": "auto",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"tools": [
{
"defer_loading": true,
"description": "description",
"name": "name",
"parameters": {
"foo": "bar"
},
"type": "function",
"async": true
}
],
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
},
"created_at": 0,
"environment": {
"type": "none"
},
"error": "error",
"last_active_at": 0,
"metadata": {
"foo": "string"
},
"object": "agent.session",
"required_actions": [
{
"request": {
"arguments": {},
"message": "message",
"name": "name",
"server_label": "server_label",
"type": "mcp_tool_call"
},
"request_id": "request_id",
"turn_id": "turn_id",
"type": "mcp_approval_request"
}
],
"status": "idle",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"vault_ids": [
"string"
],
"prompt_cache_options": {
"ttl": "30m"
},
"review": "none"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
TRAE-AI编程


更多建议: