OpenAI 更新智能体

2026-11-18 17:52 更新

post /agents/{agent_id}

更新可复用智能体。参见智能体配置。

路径参数

  • agent_id: string

可复用智能体的 ID。

minLength: 0, maxLength: 1048576

请求体参数

内容类型为 application/json。

  • compaction: optional object { async } or null

上下文压缩配置。省略时保留现有设置,传入对象时替换现有设置,传 null 或空对象时采用阻塞式压缩。

  • async: optional boolean or null

是否在后台压缩上下文。省略或传 null 时默认为 false。设为 true 可启用后台压缩。后台压缩可能增加词元用量。

  • experimental: optional object { time_awareness } (default: {})

按键合并的实验性设置。省略的设置保留现有值。

  • time_awareness: optional boolean

模型是否会定期收到当前时间提醒。省略时保留现有设置。

  • instructions: optional string or null

附加到智能体默认基础指令之后的自定义指令。省略时保留原值。

minLength: 0, maxLength: 1048576

  • metadata: optional map[string] or null

替换全部元数据。省略时保留原值,传 null 或 {} 可清除。最多 16 个字符串键值对,键最长 64 个字符,值最长 512 个字符。

  • model: optional string

智能体使用的模型。系统保留请求中的模型名称。

minLength: 0, maxLength: 1048576

  • multi_agent: optional MultiAgentConfigParam or null

创建和协调子智能体的配置。

  • enabled: boolean

是否启用子智能体工具。

  • max_concurrent_subagents: optional integer

可同时运行的子智能体数上限,默认为 6。

format: int64, minimum: 1, maximum: 4294967295

  • name: optional string or null

新的名称。省略时保留原值,传 null 可清除名称。

minLength: 0, maxLength: 128

  • reasoning: optional AgentReasoningParam or null

模型推理配置。省略时保留现有设置,传 null 时恢复模型的默认推理强度。

  • effort: optional "none" or "minimal" or "low" or 4 more or null

模型使用的推理强度。省略时由模型选择。

  • "none"

  • "minimal"

  • "low"

  • "medium"

  • "high"

  • "xhigh"

  • "max"

  • summary: optional "concise" or "detailed" or "auto" or null

控制响应是否包含推理摘要。

  • "concise"

模型支持时,返回简明推理摘要。

  • "detailed"

模型支持时,返回详细推理摘要。

  • "auto"

自动选择模型支持的最详细摘要。

  • service_tier: optional "auto" or "default" or "flex" or 3 more or null

用于模型请求的服务层级。

  • "auto"

自动选择服务层级。

  • "default"

使用默认服务层级。

  • "flex"

使用 Flex 服务层级。

  • "priority"

使用 Priority 服务层级。

  • "fast"

使用 Fast 服务层级。

  • "ultrafast"

使用 Ultrafast 服务层级。

  • text: optional AgentTextParam or null

智能体生成文本的配置。

  • format: optional TextFormatParam or null

输出格式。省略时使用普通文本({"type": "text"})。

  • 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: optional "low" or "medium" or "high" or null

模型应生成的文本量。与 Responses 一致,默认为 medium。

  • "low"

生成较少文本。

  • "medium"

使用默认文本量。

  • "high"

生成较多文本。

  • tools: optional array of PersistedAgentToolParam or null

替换工具列表。省略时保留原值,传 null 可清除。替换后的列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。

minItems: 0, maxItems: 2000

  • Function object { description, name, parameters, 3 more }

应用定义的函数。

  • description: string

说明函数的用途。

minLength: 0, maxLength: 1048576

  • name: string

函数名称。

minLength: 0, maxLength: 1048576

  • parameters: map[unknown]

描述函数参数的 JSON Schema 对象。

  • type: "function" (default: "function")

对象类型,恒为 function。

  • "function"

  • async: optional boolean (default: false)

智能体是否无需等待函数结果即可继续。默认为 false。

  • defer_loading: optional boolean (default: false)

是否延迟加载函数并通过工具搜索发现。

  • ToolSearch object { type }

发现延迟加载的函数工具,并将其加载到模型上下文。

  • type: "tool_search" (default: "tool_search")

对象类型,恒为 tool_search。

  • "tool_search"

  • ProgrammaticToolCalling object { type, enabled }

允许模型生成的代码调用工具。

  • type: "programmatic_tool_calling" (default: "programmatic_tool_calling")

对象类型,恒为 programmatic_tool_calling。

  • "programmatic_tool_calling"

  • enabled: optional boolean (default: true)

是否允许从模型生成的代码调用工具。默认为 true。

  • Mcp object { server_label, transport, type, 5 more }

未配置已存储凭证的远程 MCP 服务器提供的工具。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0, maxLength: 1048576

  • transport: PersistedMcpTransportParam

用于连接 MCP 服务器的无凭证传输方式。

  • HTTP object { server_url, type, headers }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0, maxLength: 1048576

  • type: "http" (default: "http")

对象类型,恒为 http。

  • "http"

  • headers: optional map[string] or null

发送给 MCP 服务器的非机密 HTTP 请求头。

  • Stdio object { command, cwd, type, 2 more }

以本地进程方式启动 MCP 服务器。

  • command: string

用于启动 MCP 服务器的命令。

minLength: 0, maxLength: 1048576

  • cwd: string

用于启动 MCP 服务器的工作目录。

minLength: 0, maxLength: 1048576

  • type: "stdio" (default: "stdio")

对象类型,恒为 stdio。

  • "stdio"

  • args: optional array of string or null

传递给 MCP 服务器启动命令的参数。

minItems: 0, maxItems: 16384

  • env_vars: optional array of string or null

要从选定执行环境继承的环境变量名称。

minItems: 0, maxItems: 16384

  • type: "mcp" (default: "mcp")

对象类型,恒为 mcp。

  • "mcp"

  • allowed_tools: optional array of string or null

智能体可以调用的 MCP 工具。省略时允许服务器上的全部工具。

minItems: 0, maxItems: 16384

  • connection_origin: optional "service" or "environment" or null

选择出站 MCP HTTP 连接的来源。

  • "service"

使用 Managed Agents 服务网络。

  • "environment"

使用会话的执行环境。

  • credential_id: optional string or null

为此 MCP 服务器选择的凭证库凭证。如果只有一条已附加凭证与服务器 URL 匹配,则可省略。

minLength: 0, maxLength: 1048576

  • request_metadata: optional map[unknown] or null

随请求发送给此 MCP 服务器的元数据。

  • required: optional boolean (default: false)

是否必须在第一轮前初始化此 MCP 服务器。默认为 false。

  • WebSearch object { type, allowed_domains, context_size, 2 more }

网页搜索。

  • type: "web_search" (default: "web_search")

对象类型,恒为 web_search。

  • "web_search"

  • allowed_domains: optional array of string or null

可纳入搜索范围的域名。

minItems: 0, maxItems: 16384

  • context_size: optional "low" or "medium" or "high" or null

向模型提供的搜索上下文量。默认为 medium。

  • "low"

  • "medium"

  • "high"

  • location: optional object { city, country, region, timezone } or null

用于按地理位置调整搜索结果的近似位置。

  • city: optional string or null

城市名称。

minLength: 0, maxLength: 1048576

  • country: optional string or null

两个字母的 ISO 国家或地区代码,例如 US。

minLength: 0, maxLength: 1048576

  • region: optional string or null

地区或州的名称。

minLength: 0, maxLength: 1048576

  • timezone: optional string or null

IANA 时区,例如 America/Los_Angeles。

minLength: 0, maxLength: 1048576

  • mode: optional "disabled" or "cached" or "live" or null

网页搜索结果的来源,默认为 live。

  • "disabled"

关闭网页搜索。

  • "cached"

使用缓存的搜索结果。

  • "live"

搜索实时网页。

  • ComputerUse object { type, include_screenshots }

在 OpenAI 托管会话中使用浏览器。

  • type: "computer_use" (default: "computer_use")

对象类型,恒为 computer_use。

  • "computer_use"

  • include_screenshots: optional boolean (default: false)

计算机工具的输出是否包含屏幕截图。默认为 false。

  • Automations object { type }

允许智能体安排自身的定时唤醒。

  • type: "automations" (default: "automations")

对象类型,恒为 automations。

  • "automations"

返回值

  • Agent object { id, created_at, instructions, 12 more }

属于调用方项目的可复用智能体。

  • id: string

可复用智能体的 ID。

minLength: 0

  • created_at: integer

创建智能体时的 Unix 时间戳,单位为秒。

format: int64

  • instructions: string or null

附加到智能体默认基础指令之后的自定义指令。

minLength: 0

  • metadata: map[string]

附加到智能体的自定义字符串键值对。

  • 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

  • object: "agent" (default: "agent")

对象类型,恒为 agent。

  • "agent"

  • 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"

  • "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 PersistedAgentTool

智能体可用的工具。

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

智能体是否无需等待函数结果即可继续。

  • ToolSearch object { type }

发现延迟加载的函数工具,并将其加载到模型上下文。

  • type: "tool_search" (default: "tool_search")

对象类型,恒为 tool_search。

  • "tool_search"

  • 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 工具。允许服务器上的全部工具时为 null。

minItems: 0, maxItems: 2000

  • connection_origin: "service" or "environment"

出站 MCP HTTP 连接的来源。

  • "service"

  • "environment"

  • credential_id: string or null

为此 MCP 服务器选择的凭证库凭证(如有)。

minLength: 0

  • request_metadata: map[unknown]

随请求发送给此 MCP 服务器的元数据。

  • required: boolean

是否必须在第一轮前初始化此 MCP 服务器。

  • server_label: string

用于在工具调用中标识 MCP 服务器的标签。

minLength: 0

  • transport: PersistedMcpTransport

用于连接 MCP 服务器的无凭证传输方式。

  • HTTP object { headers, server_url, type }

通过 HTTP 连接到 MCP 服务器。

  • headers: map[string]

发送给 MCP 服务器的非机密 HTTP 请求头。

  • 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"

  • updated_at: integer

上次更新智能体时的 Unix 时间戳,单位为秒。

format: int64

  • compaction: optional object { async }

当前生效的上下文压缩配置。

  • async: boolean

是否在后台压缩上下文。默认为 false。

  • experimental: optional object { time_awareness }

当前生效的实验性设置。

  • time_awareness: boolean

模型是否会定期收到当前时间提醒。

示例

## 从环境变量读取 API 密钥。
## 将 AGENT_ID 设置为要操作的智能体 ID。
curl https://api.openai.com/v1/agents/$AGENT_ID \
    -X POST \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

200 响应示例

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

{
  "id": "id",
  "created_at": 0,
  "instructions": "instructions",
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 1
  },
  "name": "name",
  "object": "agent",
  "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
    }
  ],
  "updated_at": 0,
  "compaction": {
    "async": true
  },
  "experimental": {
    "time_awareness": true
  }
}

示例

## 从环境变量读取 API 密钥。
## 将 AGENT_ID 设置为要操作的智能体 ID。
## Renamed 是示例名称,可改为所需名称。
## 1. 省略 reasoning,重命名时保留当前推理设置。
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: agents=v1" \
  -d '{"name": "Renamed"}'

## 2. 传入 null,恢复模型的默认推理设置。
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: agents=v1" \
  -d '{"reasoning": null}'

## 3. 传入对象,整体替换推理配置。
## 智能体使用的模型必须支持 low 推理强度。
curl "https://api.openai.com/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: agents=v1" \
  -d '{"reasoning": {"effort": "low"}}'
以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号