OpenAI 创建自动化任务
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"
}
创建后可手动触发自动化任务。

TRAE-AI编程


更多建议: