应用直接调用 client.beta.agents.automations.create 即可创建计划，不必给 Agent 开启 automations 工具。重复任务用 periodic + 五段 cron + IANA 时区；单次任务用 once + 未来的 run_at。独立工作选 new_session，需要历史上下文选 existing_session。创建计划不会立即运行；一次 invocation 显示 completed 也只表示 Session 已接受任务，应用仍要跟踪 Session 事件和 Turn outcome。
官方资料（2026-11-02 核对）：Scheduled automations · Sessions · Errors 与 Recovery · Observability 与 Usage
先选 schedule 与 target
| 问题 | 选择 | 必填字段 | 注意 |
|---|---|---|---|
| 重复执行 | periodic | expression、timezone | 五段 cron；不要传 run_at |
| 未来执行一次 | once | run_at | 未来 Unix 时间戳（秒） |
| 每次独立工作 | new_session | Agent、environment、target.input | 每次建立新 Session |
| 沿用历史上下文 | existing_session | session_id、target.instructions | 目标 Session 忙时投递会等待 |
两种 schedule 都可搭配两种 target。cron 是所选时区的墙上时间，不是从创建时刻开始的固定间隔；需要严格 48 小时间隔时，更适合按完成结果创建下一次 one-time 计划。
最小 JavaScript 周期任务
import OpenAI from "openai";
const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
type: "periodic",
name: "工作日状态复查",
expression: "0 9 * * MON-FRI",
timezone: "Asia/Shanghai",
target: {
type: "existing_session",
session_id: "sess_123",
instructions: "复查状态；只报告新变化和证据。"
}
});
console.log(automation.id);SDK 会处理 Beta 请求头；cURL 需显式发送 OpenAI-Beta: agents=v1。保存 automation ID，API Key 只放服务端，并限制项目与 Scope。
cron、时区和延迟怎么理解
| expression | 含义 |
|---|---|
0 10 * * * | 每天当地时间 10:00 |
0 */2 * * * | 每天 00:00、02:00、04:00…… |
0 9 1 * * | 每月 1 日 09:00 |
0 9 * * MON-FRI | 周一至周五 09:00 |
timezone 使用命名 IANA 时区，例如 UTC、Asia/Shanghai 或 America/New_York。周期任务可能被加入小幅随机延迟以分散负载，既有 Session 忙碌时还会等待，因此不适合作为精确到秒的硬实时调度器。
new_session 的最小结构
const automation = await client.beta.agents.automations.create({
type: "once",
name: "明日独立报告",
run_at: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
target: {
type: "new_session",
agent_id: "agt_123",
environment: { type: "openai_hosted" },
input: [{
role: "user",
content: [{ type: "input_text", text: "生成独立状态报告。" }]
}]
}
});环境中的文件、联网、密钥与工具权限仍应最小化；定时执行不会替你完成业务授权、用户确认或高影响操作审批。
Agent 自己创建计划时的边界
只有希望 Agent 为当前 Session 安排后续工作时，才把 { type: "automations" } 加到工具。它默认不存在，只能管理当前 Session 中由该 Agent 创建的计划；目标固定为当前 Session，不能启动新 Session，也不能管理其他 Session 的计划。移除工具不会删除已保存的计划。
重复工作可能让主 Session 累积大量工具输出。可让主 Agent 只保留目标、计划和简短结论，把每轮细节交给子 Agent；这不是启用 Scheduled Automations 的必需条件。
手动触发与完成状态
- 调用
POST /v1/agents/automations/{id}/invocations立即测试；请求体为空。 - 手动调用不修改原计划、不消耗 one-time 的定时运行，暂停状态也可用。
- invocation 先是 queued，送达后变成 completed；
session_id可能稍后才出现。 - completed 只代表 Session 接受任务。用
session_id跟踪事件，检查 Turn 的 completed、failed、cancelled 与 required actions。 - 应用负责展示输出、发送通知并记录业务结果；Automation 只负责安排工作。
更新、暂停、恢复和删除
| 操作 | 效果 |
|---|---|
| 更新 | 省略字段保持不变；提供 target 时整体替换，需保留类型并补齐必填字段 |
| 暂停 | 阻止后续定时投递；手动 invocation 仍可用 |
| 恢复 | 重新激活；one-time 若已错过时间，先更新未来 run_at |
| 删除 | 阻止未来定时与手动调用，但不删除 Session 或取消活动 Turn |
更新只影响未来 invocation；已经 queued 的 invocation 仍使用创建时保存的 target 与 input 快照。
生产可靠性与安全清单
- 幂等：保存 automation ID、invocation ID、session_id 和业务幂等键。
- 状态：区分 queued、delivered、Turn terminal 与业务成功。
- 审批：缺少工具结果、授权或 required action 时由应用处理。
- 权限：服务端保存 Key，限制工具、网络、文件和第三方数据范围。
- 监控：记录计划/实际投递时间、等待、Turn 结果、Token、工具错误与通知。
- 停用：必要时取消活动 Turn，并处理已产生的外部副作用。
- 评测：测试 Session 忙碌、重复投递、工具失败、时区/DST 和暂停恢复。
常见问题
Scheduled Automations 的 periodic 和 once 有什么区别？
periodic 使用五段 cron expression 加命名时区，适合按日、周或月重复；once 使用未来的 Unix 秒级时间戳 run_at，只执行一次。周期任务不要同时传 run_at。
new_session 和 existing_session 怎么选？
独立工作用 new_session，并提供 Agent、environment 与 target.input；需要之前消息、发现或保存工作时用 existing_session，并提供 session_id 与 target.instructions。两种 target 都能搭配 periodic 或 once。
Agents API 定时任务会在 cron 时间精确启动吗？
不保证精确到秒。cron 按所选 IANA 时区的墙上时间解释，周期运行会有小幅随机延迟；如果 existing_session 正忙，投递还会继续等待。
invocation 显示 completed 就代表 Agent 做完了吗？
不代表。completed 只说明新 Session 接受了初始输入，或既有 Session 接受了通知和启动请求。应用还要用 invocation 的 session_id 跟踪 Session 事件与 Turn outcome。
应用创建定时任务必须给 Agent 开启 automations 工具吗？
不需要。应用可直接调用 Automations API；automations 工具默认不存在，只在需要 Agent 为当前 Session 自主管理自己的计划时启用，而且它不能创建新 Session 或管理其他 Session 的计划。
怎样在不等待 cron 的情况下测试任务？
调用 POST /v1/agents/automations/{id}/invocations 手动触发。它不改变保存的计划、不消耗一次性计划，也可在暂停状态使用；测试后仍要跟踪 Session 事件和实际输出。
暂停或删除计划会停止已经运行的 Agent 吗？
不会。暂停会阻止后续定时投递，删除会阻止未来定时与手动调用，但已送达或正在送达的工作仍可能继续；要停止当前工作需另外取消活动 Turn。
本文核对日期为 2026-11-02。Agents API Scheduled Automations 当前是 Beta；SDK、Header、cron 语义、Session、工具、限制与计费都可能变化，上线前请重新读取 Scheduled automations、Sessions、Errors 与 Observability 官方文档。