OpenAI 创建自动化任务

2026-11-18 17:52 更新

post /agents/automations

将自动化任务保存为活动状态,留待后续调用。

请求体参数

内容类型为 application/json。

  • create_automation_params: AutomationScheduleParam

创建自动化任务,留待后续调用。

  • Periodic object { expression, name, target, 3 more }

  • expression: string

定义计划触发时间的标准五字段 cron 表达式。

minLength: 1, maxLength: 256

  • name: string

自动化任务的可读名称。

minLength: 1, maxLength: 256

  • target: AutomationTargetParam

自动化调用的目标会话。

  • NewSession object { environment, input, type, 4 more }

每次调用均创建一个会话。

  • environment: EnvironmentParam

每个新会话的执行环境。

  • None object { type }

在不配置执行环境的情况下运行智能体。

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { type, capability_directories, container_size, 10 more }

现有的 OpenAI 托管环境,或通过内联配置或模板新建的托管环境。

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • capability_directories: optional array of string or null

包含可向智能体提供的能力的目录。默认为空列表。

minItems: 0, maxItems: 16384

  • container_size: optional "small" or "medium" or "large"

托管容器的规格。省略时选择中等规格。

  • "small"

  • "medium"

  • "large"

  • desktop: optional object { enabled } or null

桌面配置。省略或传入 null 时继承模板设置,无模板设置时默认禁用。

  • enabled: boolean

是否配置桌面及其浏览器代理。

  • env: optional map[string] or null

向智能体提供的环境变量。

  • environment_id: optional string

现有的预热环境。不能与模板或内联配置同时指定。

minLength: 9, maxLength: 256

  • environment_template_id: optional string

可复用的托管环境模板,在内联会话配置之前应用。省略的字段继承模板,网络覆盖配置只能保持或收紧模板的网络策略。

minLength: 0, maxLength: 64

  • files: optional array of HostedEnvironmentFileParam or null

智能体启动前可用的文件。默认为空列表。

minItems: 0, maxItems: 50

  • FileID object { file_id, path, type }

此前通过 OpenAI Files API 上传的文件。

  • file_id: string

已上传文件的 ID。

minLength: 1, maxLength: 256

  • path: string

/workspace 内的目标绝对路径。

minLength: 1, maxLength: 4096

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { data, path, type }

直接以标准 Base64 数据提供的文件。

  • data: string

采用标准 Base64 编码的文件内容。

minLength: 0, maxLength: 6990508

  • path: string

/workspace 内的目标绝对路径。

minLength: 1, maxLength: 4096

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: optional object { access, allowed_domains, blocked_domains } or null

环境的网络访问策略。省略时,由 API 版本决定是否启用网络访问。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: optional array of string or null

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 16384

  • blocked_domains: optional array of string or null

网络访问受限时,执行器和浏览器均禁止访问的域名。列表非空时须设置 access: restricted,且 allowed_domains 必须为空。不支持通配符域名。

minItems: 0, maxItems: 100

  • packages: optional object { npm, python, system } or null

要安装到环境中的软件包。软件包列表默认为空。

  • npm: optional array of string or null

要全局安装的 npm 软件包。默认为空列表。

minItems: 0, maxItems: 16384

  • python: optional array of string or null

要安装的 Python 软件包。默认为空列表。

minItems: 0, maxItems: 16384

  • system: optional array of string or null

要安装的系统软件包。默认为空列表。

minItems: 0, maxItems: 16384

  • plugins: optional array of HostedPluginParam or null

以内联 ZIP 归档提供的插件。默认为空列表。

minItems: 0, maxItems: 32

  • description: string

.codex-plugin/plugin.json 中声明的插件描述。

minLength: 0, maxLength: 1048576

  • name: string

.codex-plugin/plugin.json 中声明的插件名称。

minLength: 1, maxLength: 64

  • source: InlineCapabilitySourceParam

提供以标准 Base64 编码的 ZIP 数据。

  • data: string

采用标准 Base64 编码的 ZIP 归档数据。

minLength: 1, maxLength: 70254592

  • media_type: "application/zip" (default: "application/zip")

归档文件的媒体类型,固定为 application/zip。

  • "application/zip"

  • type: "base64" (default: "base64")

对象类型,固定为 base64。

  • "base64"

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • setup_commands: optional array of SetupCommandParam or null

按顺序执行的机密初始化命令。响应始终省略命令正文。

minItems: 0, maxItems: 16

  • command: string

要执行的 Shell 命令。

minLength: 0, maxLength: 65536

  • cwd: optional string or null

工作目录的绝对路径,默认为 /workspace。

minLength: 0, maxLength: 4096

  • skills: optional array of HostedSkillParam or null

通过 ID 引用或以内联 ZIP 归档提供的技能。默认为空列表。

minItems: 0, maxItems: 200

  • SkillReference object { skill_id, type, version }

引用通过 Skills API 上传的技能。

  • skill_id: string

通过 /v1/skills 创建的技能 ID。

minLength: 1, maxLength: 64

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: optional string or null

技能版本,可以是正整数或 latest。省略时选择默认版本。

minLength: 0, maxLength: 1048576

  • Inline object { description, name, source, type }

直接在会话请求中提供技能 ZIP。

  • description: string

SKILL.md 中声明的技能描述。

minLength: 0, maxLength: 1048576

  • name: string

SKILL.md 中声明的技能名称。

minLength: 1, maxLength: 64

  • source: InlineCapabilitySourceParam

提供以标准 Base64 编码的 ZIP 数据。

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • SelfHosted object { type, workspace_directory, capability_directories }

以内联方式配置的应用托管环境。

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

自托管环境中的项目绝对路径。

minLength: 0, maxLength: 1048576

  • capability_directories: optional array of string or null

包含可向智能体提供的能力的目录。默认为空列表。

minItems: 0, maxItems: 16384

  • input: array of AgentSessionInputMessageParam

提交给每个新会话的初始用户消息。

minItems: 0, maxItems: 16384

  • content: array of InputContentParam

消息内容。

minItems: 0, maxItems: 16384

  • InputText object { text, type }

提供给模型的文本输入。

  • text: string

发送给模型的文本。

minLength: 0, maxLength: 1048576

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

对象类型,固定为 input_text。

  • "input_text"

  • InputImage object { image_url, type }

提供给模型的图像输入。

  • image_url: string

发送给模型的图像 URL。

minLength: 0, maxLength: 1048576

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

对象类型,固定为 input_image。

  • "input_image"

  • role: "user" (default: "user")

消息作者的角色,固定为 user。

  • "user"

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

输入条目类型,固定为 message。

  • "message"

  • type: "new_session" (default: "new_session")

对象类型,固定为 new_session。

  • "new_session"

  • agent: optional object { compaction, experimental, instructions, 6 more }

内联智能体配置。agent 和 agent_id 必须且只能提供一个。

  • 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

  • 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

  • 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 AgentToolParam or null

智能体可用的工具。省略时继承,传入 null 时清除。最终工具列表采用紧凑 UTF-8 JSON 编码时,大小不得超过 3 MiB(3,145,728 字节)。

minItems: 0, maxItems: 16384

  • 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: McpTransportParam

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

  • HTTP object { server_url, type, authorization, headers }

通过 HTTP 连接到 MCP 服务器。

  • server_url: string

MCP 服务器的 URL。

minLength: 0, maxLength: 1048576

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

对象类型,恒为 http。

  • "http"

  • authorization: optional string or null

发送给 MCP 服务器的授权值(如有)。

minLength: 0, maxLength: 1048576

  • headers: optional map[string] or null

发送给 MCP 服务器的附加 HTTP 请求头。

  • Stdio object { command, cwd, type, 3 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: optional map[string] or null

为 MCP 服务器进程设置的环境变量。

  • 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 时使用会话选定的环境。

  • "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_id: optional string

已保存的智能体 ID。agent 和 agent_id 必须且只能提供一个。

minLength: 0, maxLength: 64

  • metadata: optional map[string] or null

附加到每个新会话的元数据。

  • vault_ids: optional array of string or null

每个新会话可访问的凭证库 ID。

minItems: 0, maxItems: 16384

  • ExistingSession object { instructions, session_id, type }

向现有会话投递指令。

  • instructions: string

以自动化通知形式投递的指令。

minLength: 0, maxLength: 1048576

  • session_id: string

接收每次调用的会话。

minLength: 0, maxLength: 1048576

  • type: "existing_session" (default: "existing_session")

对象类型,固定为 existing_session。

  • "existing_session"

  • timezone: string

用于解释 cron 表达式的 IANA 时区。

minLength: 1, maxLength: 128

  • type: "periodic" (default: "periodic")

对象类型,固定为 periodic。

  • "periodic"

  • metadata: optional map[string]

  • Once object { name, run_at, target, 2 more }

  • name: string

自动化任务的可读名称。

minLength: 1, maxLength: 256

  • run_at: integer

将来时间的 Unix 时间戳,单位为秒。

format: int64

  • target: AutomationTargetParam

自动化调用的目标会话。

  • type: "once" (default: "once")

对象类型,固定为 once。

  • "once"

  • metadata: optional map[string]

返回值

  • Automation = PeriodicAutomation or OneTimeAutomation

已保存的自动化任务及其计划。

  • PeriodicAutomation object { id, created_at, created_by, 9 more }

周期性和一次性自动化任务共有的字段。

  • id: string

自动化任务 ID。

minLength: 0

  • created_at: integer

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

format: int64

  • created_by: AutomationCreatedBy

服务记录的来源信息,调用方不能设置此字段。

  • Developer object { type }

  • type: "developer" (default: "developer")

对象类型,固定为 developer。

  • "developer"

  • Agent object { session_id, tool_call_id, type }

  • session_id: string

创建该自动化任务的会话,也是任务的目标会话。

minLength: 0

  • tool_call_id: string

创建自动化任务的工具调用。

minLength: 0

  • type: "agent" (default: "agent")

对象类型,固定为 agent。

  • "agent"

  • expression: string

确定计划触发时间的 cron 表达式。

minLength: 0

  • metadata: map[string]

附加到自动化任务的自定义字符串键值对。

  • name: string

自动化任务的显示名称。

minLength: 0

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

固定为 agent.automation。

  • "agent.automation"

  • status: "active" or "paused"

计划投递处于活动还是暂停状态。

  • "active"

  • "paused"

  • target: AutomationTarget

接收调用投递的会话配置或现有会话。

  • NewSession object { agent, agent_id, environment, 4 more }

  • agent: AutomationAgentConfig or null

内联智能体配置。配置了 agent_id 时为 null。

  • instructions: string or null

自定义指令。未设置时为 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

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

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

  • agent_id: string or null

已保存智能体的引用。使用内联智能体配置时为 null。

minLength: 0

  • environment: AutomationEnvironment

用于选择执行环境的配置或引用。

  • None object { type }

  • type: "none" (default: "none")

对象类型,固定为 none。

  • "none"

  • OpenAIHosted object { capability_directories, container_size, desktop, 8 more }

托管环境的选择配置。返回内容省略机密的初始化命令和变量。

  • capability_directories: array of string or null

目录配置的覆盖项。传入 null 时继承模板或创建时的默认值。

minItems: 0, maxItems: 2000

  • container_size: "small" or "medium" or "large" or null

配置的容器规格。传入 null 时使用创建时的默认规格。

  • "small"

  • "medium"

  • "large"

  • desktop: object { enabled } or null

桌面配置的覆盖项。传入 null 时继承模板或创建时的默认值。

  • enabled: boolean

环境是否配置桌面及浏览器代理。

  • environment_id: string or null

现有环境的引用。配置新环境时为 null。

minLength: 0

  • environment_template_id: string or null

模板引用。未选用模板时为 null。

minLength: 0

  • files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type } or null

文件配置的覆盖项,返回内容省略文件正文。传入 null 时继承上级配置。

minItems: 0, maxItems: 2000

  • FileID object { file_id, path, type }

项目范围内的 Files API 引用,每个会话独立解析。

  • file_id: string

已上传文件的 ID。

minLength: 0

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • type: "file_id" (default: "file_id")

对象类型,固定为 file_id。

  • "file_id"

  • Inline object { path, size_bytes, type }

机密内联文件内容的元数据。

  • path: string

文件在环境内的绝对路径。

minLength: 0

  • size_bytes: integer

内联文件解码后的大小,单位为字节。

format: int64, minimum: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • network: object { access, allowed_domains } or null

网络配置的覆盖项。传入 null 时继承模板或创建时的默认值。

  • access: "enabled" or "disabled" or "restricted"

环境的网络访问模式。

  • "enabled"

允许不受限制的网络访问。

  • "disabled"

关闭网络访问。

  • "restricted"

应用配置的域名访问限制。

  • allowed_domains: array of string

网络访问受限时,环境可以访问的域名。

minItems: 0, maxItems: 2000

  • packages: object { npm, python, system } or null

软件包配置的覆盖项。传入 null 时继承模板或创建时的默认值。

  • 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 or null

插件配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。

minItems: 0, maxItems: 2000

  • description: string

已安装插件的描述。

minLength: 0

  • name: string

已安装插件的名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type } or null

技能配置的覆盖项,返回内容省略归档内容。传入 null 时继承上级配置。

minItems: 0, maxItems: 2000

  • SkillReference object { skill_id, type, version }

每次启动会话时都通过 Skills API 重新解析的技能。

  • skill_id: string

引用的技能 ID。

minLength: 0

  • type: "skill_reference" (default: "skill_reference")

对象类型,固定为 skill_reference。

  • "skill_reference"

  • version: string or null

请求的版本选择值,包含 latest 选项。

minLength: 0

  • Inline object { description, name, type }

可以安全返回的内联技能归档元数据。

  • description: string

SKILL.md 中声明的技能描述。

minLength: 0

  • name: string

SKILL.md 中声明的技能名称。

minLength: 0

  • type: "inline" (default: "inline")

对象类型,固定为 inline。

  • "inline"

  • type: "openai_hosted" (default: "openai_hosted")

对象类型,固定为 openai_hosted。

  • "openai_hosted"

  • SelfHosted object { capability_directories, environment_id, type, workspace_directory }

  • capability_directories: array of string

用于向智能体提供能力的目录。

minItems: 0, maxItems: 2000

  • environment_id: string or null

现有的环境注册记录。传入 null 时创建会话专属环境。

minLength: 0

  • type: "self_hosted" (default: "self_hosted")

对象类型,固定为 self_hosted。

  • "self_hosted"

  • workspace_directory: string

环境中的项目绝对路径。

minLength: 0

  • input: array of object { content, role, type }

向每个新会话投递的初始输入。

minItems: 0, maxItems: 2000

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

  • role: "user" (default: "user")

消息作者的角色,固定为 user。

  • "user"

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

输入条目类型,固定为 message。

  • "message"

  • metadata: map[string]

附加到每个新会话的元数据。

  • type: "new_session" (default: "new_session")

对象类型,固定为 new_session。

  • "new_session"

  • vault_ids: array of string

每个新会话可使用的凭证库。

minItems: 0, maxItems: 2000

  • ExistingSession object { instructions, session_id, type }

  • instructions: string

保存的指令,以自动化通知形式投递。

minLength: 0

  • session_id: string

接收每次调用的会话。

minLength: 0

  • type: "existing_session" (default: "existing_session")

对象类型,固定为 existing_session。

  • "existing_session"

  • timezone: string

用于解释此表达式的时区。

minLength: 0

  • type: "periodic" (default: "periodic")

对象类型,固定为 periodic。

  • "periodic"

  • pause_reason: optional "target_session_failed" or null (default: "target_session_failed")

服务暂停当前计划的原因。其他计划为 null。

  • "target_session_failed"

  • OneTimeAutomation object { id, created_at, created_by, 8 more }

周期性和一次性自动化任务共有的字段。

  • id: string

自动化任务 ID。

minLength: 0

  • created_at: integer

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

format: int64

  • created_by: AutomationCreatedBy

服务记录的来源信息,调用方不能设置此字段。

  • metadata: map[string]

附加到自动化任务的自定义字符串键值对。

  • name: string

自动化任务的显示名称。

minLength: 0

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

固定为 agent.automation。

  • "agent.automation"

  • run_at: integer

计划触发时间的 Unix 时间戳,单位为秒。

format: int64

  • status: "active" or "paused" or "completed"

完成状态表示计划已结束。智能体任务的完成状态需单独确认。

  • "active"

  • "paused"

  • "completed"

  • target: AutomationTarget

接收调用投递的会话配置或现有会话。

  • type: "once" (default: "once")

对象类型,固定为 once。

  • "once"

  • pause_reason: optional "target_session_failed" or null (default: "target_session_failed")

服务暂停当前计划的原因。其他计划为 null。

  • "target_session_failed"

示例

## 从环境变量读取 API 密钥。
## 原文使用占位值。将 expression 换成五字段 cron 表达式、timezone 换成 IANA 时区。
## 将 name 换成任务名称,将 input 中的 text 换成实际指令。
curl https://api.openai.com/v1/agents/automations \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "expression": "x",
          "name": "x",
          "target": {
            "environment": {
              "type": "none"
            },
            "input": [
              {
                "content": [
                  {
                    "text": "text",
                    "type": "input_text"
                  }
                ],
                "role": "user"
              }
            ],
            "type": "new_session"
          },
          "timezone": "x",
          "type": "periodic"
        }'

201 响应示例

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

{
  "id": "id",
  "created_at": 0,
  "created_by": {
    "type": "developer"
  },
  "expression": "expression",
  "metadata": {
    "foo": "string"
  },
  "name": "name",
  "object": "agent.automation",
  "status": "active",
  "target": {
    "agent": {
      "instructions": "instructions",
      "model": "model",
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 1
      },
      "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
      }
    },
    "agent_id": "agent_id",
    "environment": {
      "type": "none"
    },
    "input": [
      {
        "content": [
          {
            "text": "text",
            "type": "input_text"
          }
        ],
        "role": "user",
        "type": "message"
      }
    ],
    "metadata": {
      "foo": "string"
    },
    "type": "new_session",
    "vault_ids": [
      "string"
    ]
  },
  "timezone": "timezone",
  "type": "periodic",
  "pause_reason": "target_session_failed"
}

创建后可手动触发自动化任务。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号