如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 America/New_York 時區每天上午 10 點。
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 設為新的未來時間,再恢復排程。已完成的單次自動化無法暫停或恢復;若要安排下一次追蹤,請另行建立自動化。