如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

定时自动化

定时运行智能体任务,或让智能体自行安排后续任务。

使用定时自动化,按 cron 计划启动智能体会话。您也可以为智能体启用 automations 工具,让它们在执行任务时安排后续工作。

  • 按 cron 计划自动运行会话

    指定 cron 表达式和时区,即可定时启动新会话或继续现有会话。

  • 允许智能体创建自动化

    添加 automations 工具,让智能体在当前会话中安排后续任务。

  • 监控自动化调用

    每条调用记录都对应一次向会话投递任务的尝试。您可以查看调用状态和会话 ID。

按 cron 计划自动运行会话
import OpenAI from "openai";

const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
  type: "periodic",
  name: "Daily session",
  expression: "0 10 * * *",
  timezone: "America/New_York",
  target: {
    type: "new_session",
    agent_id: "agt_123",
    environment: { type: "openai_hosted" },
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Summarize the current status and next steps.",
          },
        ],
      },
    ],
  },
});
console.log(automation);

API 资源

  • 智能体

    /v1/agents

    定义执行任务所需的指令和工具。

  • 自动化

    /v1/agents/automations

    保存运行时间和目标会话配置。

  • 调用记录

    /v1/agents/automations/{automation_id}/invocations

    查看任务何时投递,以及哪个会话接收了任务。

  • 会话

    /v1/agents/sessions

    结合对话历史和工具执行任务。

  • 会话事件

    /v1/agents/sessions/{session_id}/events

    跟踪进度并获取结果。

使用场景

工作原理

自动化是为智能体任务保存的运行计划。Agents API 存储计划,并将每项任务投递到目标会话:

  1. 定义任务。 指定运行时间,并决定每次运行是启动新会话还是继续现有会话。
  2. 投递任务。 每次运行都会创建一条调用记录,记录这次向目标会话投递任务的尝试。如果会话正忙,任务将等待投递。
  3. 跟踪结果。 智能体利用会话的工具和上下文执行任务。跟踪会话事件即可查看进度并获取结果。会话收到任务并不代表智能体已完成工作。

您的应用可以通过 API 创建、更新、暂停或删除计划。启用 automations 工具后,智能体也可以在当前会话中自行安排下一次检查。

选择会话和运行计划

根据任务是否需要参考之前的对话选择目标:

目标 适用场景 必需配置
new_session 独立执行的任务,例如每月支出分析。 指定智能体和环境,并在 target.input 中提供初始消息。
existing_session 需要参考会话已有结果的后续任务。 提供会话 ID,并在 target.instructions 中填写提醒文本。

运行时间可独立于目标设置:

类型 时间字段 示例
periodic expression 和 timezone 每天上午 10 点(America/New_York 时区)。
once run_at 在未来的某个时间检查一次,用以秒为单位的 Unix 时间戳指定该时间。

两种计划类型均可与任一目标搭配使用。创建自动化时,系统会以 active 状态保存自动化,不会立即运行任务。周期性自动化的首次运行安排在下一个符合计划条件的时间点。

定时生成每日建议

创建自动化前,请先创建智能体,为其配置执行任务所需的指令和工具,确保它可以访问用户的日历、任务和消息。请参阅跨会话复用智能体。

SDK 已包含 OpenAI-Beta: agents=v1 请求头。使用 cURL 调用 API 时,请添加此请求头。

以下示例创建一个自动化,在纽约时间每天上午 10 点启动新会话:

定时生成每日建议
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Daily suggestions",
    expression="0 10 * * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my calendar, tasks, and recent messages for today. "
                            "Suggest the most useful actions I could take today, "
                            "with a short reason for each."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

请保存返回的自动化 id,以便日后查看或管理计划。每次调用都会启动新的对话。上述环境配置会为该会话创建一个 OpenAI 托管的沙盒。

您可以在 target.agent 中直接提供智能体配置,也可以用 target.agent_id 指定已保存的智能体。这两个字段必须且只能提供一个。请将初始消息放在 target.input 中,不要放在请求的顶层。至少提供一条包含非空文本或图片 URL 的消息。

每月分析支出

您可以用同样的方法安排每月支出分析。允许已保存的智能体访问用户的财务记录,然后安排在每月 1 日上午 9 点启动新会话:

安排每月支出分析
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Monthly spending review",
    expression="0 9 1 * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my spending for the previous month. Flag unused "
                            "subscriptions, price increases, and other potential "
                            "savings for me to review."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

设置周期性运行时间

使用包含五个字段的 cron 表达式,并指定时区名称:

表达式 运行时间
0 10 * * * 每天上午 10 点
0 */2 * * * 每两小时一次
0 9 1 * * 每月 1 日上午 9 点
0 9 * * MON-FRI 周一至周五上午 9 点

时区决定了如何解释表达式。按 UTC 时间运行时,使用 UTC;按当地时间运行时,使用 America/New_York 等 IANA 时区。不要在周期性自动化中包含 run_at。

cron 计划按所选时区的当地时间运行。例如,0 */3 * * * 会安排在零点、凌晨 3 点、早上 6 点及之后每隔三小时运行一次,而不是从创建时刻起每隔三小时运行一次。

计划指定的是预定运行时间。为分散负载,Agents API 会为周期性运行添加短暂的随机延迟。如果目标会话正忙,任务可能需要等待更久。

继续现有会话

如果智能体需要参考之前的结果、消息或已保存的工作成果,请使用现有会话。例如,用来安排晚餐的会话可以保留餐厅偏好和之前查询可订餐位的结果。

以下示例在该会话中每两小时查询一次可订餐位:

查询餐厅可订餐位
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Check restaurant reservations",
    expression="0 */2 * * *",
    timezone="America/New_York",
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check restaurant availability for our dinner plans. "
            "Compare with earlier checks and report newly available tables."
        ),
    },
)
print(automation.to_json())

每次调用都会将已保存的指令作为自动化通知投递到同一个会话。该会话使用当前的智能体配置和已保存的状态执行任务。自动化通知与新的用户消息彼此独立。

如果会话正在执行任务,系统会等到会话可用时再投递。定时运行不会中断当前轮次,也不会补上缺少的工具结果或审批。您的应用仍须处理所需操作。

安排一次检查

要安排一次后续检查,请将 type: "once" 与 run_at 搭配使用。后者的值必须是以秒为单位的整数 Unix 时间戳,且必须指向未来的时间。不要包含 expression 或 timezone。

安排在 2027 年 1 月 1 日上午 9 点(UTC) 执行一次检查:

安排智能体运行一次
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Check restaurant reply",
    run_at=1798794000,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check whether the restaurant replied about our booking. "
            "Summarize any changes to the dinner plans."
        ),
    },
)
print(automation.to_json())

一次性计划完成后,不会再定时运行。您仍可手动调用它,也可以创建另一个自动化来安排下一次跟进。

让智能体安排后续任务

将 automations 添加到智能体的工具中,使其能够安排用户要求的任务。此示例还启用了子智能体,以便主智能体将每项定时任务委派给子智能体,并保留简要结果:

让智能体安排任务
from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "Use automations to schedule tasks requested by the user. "
            "Delegate each scheduled task to a subagent and ask for a concise result. "
            "Keep the goal, schedule, and useful summaries in the main session. "
            "Adjust or stop schedules when the user asks."
        ),
        "multi_agent": {"enabled": True},
        "tools": [{"type": "automations"}],
    },
    environment={"type": "openai_hosted"},
    input=(
        "Every day at 10 AM in America/New_York, review the goals we discuss here "
        "and suggest the next actions I could take."
    ),
)
print(session.id)

这样,智能体就可以创建、列出、获取、更新、暂停、恢复和删除自己的自动化。Agents API 会将当前会话设为目标。智能体可以安排一次性或周期性运行,但不能使用这些工具启动新会话或管理其他会话的自动化。

这些工具只能访问智能体在当前会话中创建的自动化。您的应用可以通过 API 管理这些自动化,也可以管理应用自身创建的自动化。Agents API 会在 created_by 中记录创建者,请勿在创建请求中发送该字段。

默认情况下,智能体没有此工具。您的应用无需启用此工具也能安排任务。从智能体配置中移除工具不会删除已保存的计划。如有需要,请通过 API 暂停或删除这些计划。

避免重复任务占用主会话上下文

对于需要持续跟进的目标,请启用多智能体编排,配置为 agent.multi_agent.enabled: true。让主智能体保留目标和计划,将每项任务委派给子智能体,并保留简要结果。这样,反复检查产生的详细工具输出就不会占用主会话的上下文窗口。

例如,您可以在主智能体的指令中加入以下内容:

将每项定时任务委派给子智能体。向它说明目标和之前获得的相关结果,并要求它简要报告本次结果。查看结果,保留有用信息的摘要,并决定是继续、调整还是停止计划。

automations 工具用于管理计划。请保留智能体执行定时任务所需的其他工具和数据访问权限。

在应用中安排新用户引导的后续跟进

您的应用也可以根据自身事件创建计划。例如,当用户注册时,启动新用户引导会话,并将首次跟进安排在 48 小时后:

安排新用户引导的后续跟进
import time

from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Onboarding follow-up",
    run_at=int(time.time()) + 48 * 60 * 60,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Review onboarding progress and send the next onboarding message "
            "if the user has not completed onboarding."
        ),
    },
)
print(automation.to_json())

每次跟进完成后,应用都可以将下一次跟进安排在 48 小时后。如果用户已完成引导流程或选择退出,请停止跟进,并删除所有待执行的跟进任务。请使用一次性计划来安排这一间隔,因为 cron 表达式中指定每月几号的字段无法保证跨月时仍按 48 小时的间隔运行。

负责引导的智能体需要能够查看用户的引导进度,并使用应用的消息发送工具。创建自动化只会安排任务,不会立即发送消息。

试运行并检查投递情况

要立即测试已保存的自动化,请发送 POST /v1/agents/automations/auto_123/invocations,不要附带请求体。手动调用不会更改已保存的计划,也不会用掉一次性计划的定时运行机会。计划暂停期间也可以手动调用。

请保存返回的调用 ID。使用 GET /v1/agents/automations/auto_123/invocations/ainv_123 获取该调用记录,或使用 GET /v1/agents/automations/auto_123/invocations 列出投递历史。

要了解以往的运行情况,可以列出该自动化的调用记录:

监控自动化调用
import OpenAI from "openai";

const client = new OpenAI();
for await (const invocation of client.beta.agents.automations.invocations.list(
  "auto_123"
)) {
  console.log(invocation.id, invocation.status, invocation.session_id);
}

历史记录包含已经创建的调用,但不会列出今后的每一次定时运行。请查看以下字段:

字段 查看内容
status 初始值为 queued,投递成功后变为 completed。
session_id 标识投递后应跟踪的会话。在会话可用之前,值可能为 null。
source.type manual 表示手动调用,automation 表示定时运行。
scheduled_at 预定运行时间。对于手动调用,值为 null。

投递完成并不代表智能体已完成任务。 对于新会话,投递完成表示会话已接收初始输入。对于现有会话,则表示会话已接收通知和开始执行任务的请求。

使用调用记录中的 session_id 跟踪会话事件,查看该轮次的执行结果。

自动化负责安排任务。您的应用负责显示会话输出,并向用户发送相应通知。

更改或停止计划

使用 GET /v1/agents/automations/auto_123 获取自动化。使用 GET /v1/agents/automations 列出项目中的自动化。添加 session_id=sess_123 即可查找以指定的现有会话为目标的自动化。

更新 cron 表达式,将周期性检查的时间改为上午 11 点:

更改计划
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.update(
    automation_id="auto_123",
    expression="0 11 * * *",
)
print(automation.to_json())

省略的字段保持不变。如果提供 target,它会替换整个目标配置,因此请包含所有必需字段,并保留原有的目标类型。要更新提醒文本,请修改 target.instructions;要更新初始消息,请修改 target.input。对于智能体创建的自动化,目标必须始终是创建该自动化的会话。

请在下一次预定运行时间之前完成更改。更新适用于后续调用。已经进入队列的调用仍使用创建时保存的目标和输入。

执行以下操作时,请勿附带请求体:

目标 操作 效果
暂停定时任务。 POST /v1/agents/automations/auto_123/pause 暂缓尚未投递的定时任务,仍可手动调用。
恢复定时任务。 POST /v1/agents/automations/auto_123/resume 重新启用已保存的计划。
移除计划。 DELETE /v1/agents/automations/auto_123 阻止今后的定时调用和手动调用。

暂停或删除自动化不会停止会话已接收的任务,也不会删除会话。已经开始投递的任务仍可能送达目标会话。要停止当前任务,请取消正在执行的轮次。

如果一次性自动化的预定运行时间在暂停期间已过,请先将 run_at 设为新的未来时间,再恢复运行。已完成的一次性自动化无法暂停或恢复。如需再安排一次跟进,请创建另一个自动化。