For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

おすすめ

Agents API

Agents SDK

ChatKit

API ダッシュボード
ChatGPT を試す

オートメーションのスケジュール実行

スケジュールに従ってエージェントのタスクを実行したり、エージェント自身に次のタスクをスケジュールさせたりできます。

オートメーションを使うと、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 タイムスタンプで指定した将来の時刻に、1 回だけ確認します。

どちらのスケジュールも、新しいセッションと既存のセッションの両方に使えます。オートメーションを作成すると、ステータスが 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 件必要です。

毎月の支出の見直し

同じ方法で毎月の支出を見直すこともできます。保存済みのエージェントがユーザーの取引記録を参照できるようにし、毎月 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())

繰り返し実行する時刻の設定

5 つのフィールドからなる cron 式とタイムゾーン名を指定します。

式 実行スケジュール
0 10 * * * 毎日午前 10 時
0 */2 * * * 2 時間ごと
0 9 1 * * 毎月 1 日の午前 9 時
0 9 * * MON-FRI 月曜日から金曜日までの午前 9 時

cron 式の時刻は、指定したタイムゾーンに基づいて解釈されます。UTC 基準のスケジュールには UTC を、現地時刻を使うスケジュールには America/New_York などの IANA タイムゾーンを指定します。定期オートメーションには run_at を指定しないでください。

cron スケジュールは、選択したタイムゾーンの時刻に従います。たとえば、0 */3 * * * の実行時刻は午前 0 時、午前 3 時、午前 6 時、以降 3 時間ごとです。作成時刻から 3 時間ごとに実行する指定ではありません。

スケジュールが示すのは実行予定時刻です。Agents API は負荷を分散するため、定期実行のたびにランダムな短い遅延を加えます。対象のセッションが処理中の場合、タスクの待機時間がさらに長くなることがあります。

既存のセッションの継続

エージェントが過去の調査結果、メッセージ、保存済みの作業内容を必要とする場合は、既存のセッションを使います。たとえば、夕食を計画するセッションには、レストランの希望条件と過去の空席確認の結果を保持できます。

次の例では、そのセッションで 2 時間ごとにレストランの空席を確認します。

レストランの空席確認
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())

呼び出しのたびに、保存済みの指示がオートメーションからの通知として同じセッションに届きます。その際、セッションの現在のエージェント設定と保存済みの状態が使われます。この通知は、新しいユーザーメッセージとは別に扱われます。

セッションが処理中の場合は、次のタスクを受け付けられるようになるまで配信が保留されます。スケジュール実行によって進行中のターンが中断されることはありません。また、まだ届いていないツールの結果や承認が補われることもありません。アプリケーション側で引き続き必要なアクションを処理する必要があります。

1 回限りの確認のスケジュール設定

フォローアップを 1 回だけ実行するには、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())

1 回限りのスケジュールが完了すると、以降の実行予定はありません。完了後も手動で呼び出せます。次のフォローアップをスケジュールするには、別のオートメーションを作成します。

エージェントによるフォローアップのスケジュール設定

エージェントのツールに 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 で有効にします。メインエージェントには、目標とスケジュールを保持し、個々のタスクをサブエージェントに委任して、結果の要約を残すよう指示します。こうすると、確認のたびに生成される詳細なツール出力が、メインセッションのコンテキストウィンドウに蓄積されません。

たとえば、メインエージェントの指示に次の内容を含めます。

スケジュール済みタスクを 1 件ずつサブエージェントに委任してください。目標と関連する過去の調査結果を伝え、結果を簡潔に報告するよう求めてください。報告を確認し、役に立つ内容を要約して残したうえで、スケジュールを継続するか、変更するか、停止するかを判断してください。

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 時間後に次のフォローアップをスケジュールできます。オンボーディングが完了するか、ユーザーが以降のフォローアップを辞退したら、フォローアップを停止し、保留中のものを削除します。この間隔で実行するには、1 回限りのスケジュールを使ってください。cron 式で月内の日付を指定しても、月をまたいで 48 時間ごとに繰り返す間隔は表せません。

オンボーディングを担当するエージェントには、オンボーディングの進捗情報とアプリケーションのメッセージ送信ツールへのアクセスが必要です。オートメーションを作成すると作業がスケジュールされます。メッセージがすぐに送信されるわけではありません。

テスト実行と配信状況の確認

保存済みのオートメーションをすぐにテストするには、リクエストボディを指定せずに POST /v1/agents/automations/auto_123/invocations を送信します。手動で呼び出しても、保存済みのスケジュールは変わらず、1 回限りの実行予定も消費されません。スケジュールの一時停止中も手動で呼び出せます。

レスポンスで返された呼び出し 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 配信後に追跡するセッションの 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 以降はスケジュール実行も手動での呼び出しもできなくなります。

オートメーションを一時停止または削除しても、セッションがすでに受け付けた作業は停止せず、セッションも削除されません。配信がすでに始まっているタスクは、そのままセッションに届くことがあります。進行中の作業を停止するには、実行中のターンをキャンセルしてください。

1 回限りのオートメーションの一時停止中に実行予定時刻を過ぎた場合は、再開する前に run_at に将来の時刻を指定し直してください。完了済みの単発オートメーションは一時停止も再開もできません。次のフォローアップをスケジュールするには、別のオートメーションを作成してください。