目次
OpenAIのAgents には、エージェントの仕事を指定時刻やcronで起動するScheduled automationsがあります。毎朝の調査、週次レポート、期限後の再確認などを、外部のジョブ基盤から毎回を組み立て直さずに実行できます。ただし、予定時刻に呼び出せたことと、エージェントの仕事が正しく完了したことは別です。
この記事は2026年11月5日時点のOpenAI公式資料に基づく実践解説です。対象は、Agents APIで定期処理を組み込みたいWeb開発者と運用担当者です。新しいセッションを毎回作るか既存セッションを継続するか、で何を監視するか、失敗後にどこから再開するかを具体化します。実際のAPI呼び出しや動作を本サイトで実測した記事ではありません。
スポンサーリンク
自動化は時刻・対象・完了判定の三つに分ける
Scheduled automationsは、保存したスケジュールからAgents APIのセッションへ仕事を送る仕組みです。周期実行は5フィールドのcron式とIANAタイムゾーンを使い、1回だけの実行は将来のUnix時刻をrun_atへ指定します。作成直後の状態はactiveですが、その場では実行されず、次の該当時刻を待ちます。
| 設計項目 | 選択肢 | 確認すること |
|---|---|---|
| 時刻 | periodic / once | タイムゾーン、祝日、締切、遅延の許容 |
| 対象 | 新規セッション / 既存セッション | 前回の文脈や作業環境を引き継ぐ必要 |
| 完了 | イベント、出力、外部状態 | ターン成功と業務結果をどう判定するか |
| 再開 | 再試行 / 続きのターン / 人が確認 | 既に変わったファイルや外部処理の扱い |
cronは「作成から24時間後」ではなく、指定タイムゾーンの時計に沿って解釈されます。例えば0 9 * * MON-FRIは平日9時です。公式資料は、負荷分散のため周期実行に小さなランダム遅延が加わり、対象セッションが処理中ならさらに待つ場合があると説明しています。秒単位の開始時刻を前提にせず、結果の締切から逆算して余裕を持たせます。
毎回新しく始めるか、会話を続けるかを先に決める
新規セッションを対象にすると、呼び出すたびに新しいセッションが作られます。定型レポートや独立した集計のように、前回の会話を参照しなくても成立する仕事に向きます。入力、利用するエージェント、実行環境を自動化側へ保存し、各回のセッションIDを別々に追跡できます。前回の誤った前提や長い履歴を持ち込みにくい点も管理しやすさにつながります。
既存セッションを継続する方式は、同じ調査へ追加情報を渡す、前回の未完了作業を確認する、利用者との文脈を保つ用途に向きます。一方で、そのセッションが実行中なら予定した入力は待つことがあります。過去の出力やツール結果も判断へ影響するため、定期処理の基準日、確認範囲、前回からの差分を毎回の指示へ明示します。
判断に迷う場合は、同じ入力だけで完結する仕事を新規セッションにし、利用者の返答や前回の調査結果が必要な仕事だけを継続対象にします。「前回の続き」という曖昧な指示ではなく、未完了項目、基準日時、更新対象を具体的に渡す方が、長期運用で結果を比較しやすくなります。
スポンサーリンク
cronとタイムゾーンを設定例で確認する
次は、平日9時に新しいセッションを始める構成の概念例です。実際には、先に対象エージェントを作成し、必要なツールと実行環境を設定します。の型やベータヘッダーは利用中の最新版で確認してください。
const automation = await client.beta.agents.automations.create({
type: "periodic",
name: "平日の運用レポート",
expression: "0 9 * * MON-FRI",
timezone: "Asia/Tokyo",
target: {
type: "new_session",
agent_id: "agt_123",
environment: { type: "openai_hosted" },
input: [{
role: "user",
content: [{
type: "input_text",
text: "前営業日分を集計し、根拠と未取得項目を分けて報告する"
}]
}]
}
});例の入力は短く見せていますが、本番ではデータの対象期間、成功条件、出力形式、取得できない場合の扱いを保存します。エージェントが外部サービスを読むなら、予定時刻に資格情報と接続先が利用できるかも確認します。自動化の作成完了は初回タスクの完了ではないため、作成後に一覧から次回時刻と保存された対象を読み戻します。
Invocationを実行記録として扱う
各スケジュール実行ではinvocationが作られます。これは予定された仕事をセッションへ送ろうとした記録で、状態と対象セッションIDを追跡する入口です。ただし、invocationの完了はスケジュール処理が終わったことを表し、エージェントの仕事が期待どおり終わったことまでは保証しません。
運用画面には、自動化ID、予定時刻、実際の送信時刻、invocation状態、セッションID、ターンの結果、最終成果物の確認結果を分けて保存します。これにより「予定は動いたがセッションが失敗した」「ターンは完了したが外部APIの更新に失敗した」といった違いを調べられます。
スポンサーリンク
Webhookのidleだけで成功と判定しない
Agents APIのSession webhooksには、agent.session.created、action_required、in_progress、idle、failedなどがあります。Webhookを受けたら署名を検証し、イベントに含まれるセッションIDで最新状態を取得します。action_requiredの通知には関数結果、環境接続、コンピューター操作の確認などがあり、通知本文だけでは必要な詳細が足りないため、セッションのrequired_actionsを読みます。
idleは次の入力を受け取れる状態を意味し、直前のターン成功を意味しません。公式資料は、agent.session.turn.completed、turn.failed、turn.cancelledを確認し、完了ターンでも失敗したがないか調べるよう案内しています。レポート生成ならファイルが存在するか、外部更新なら対象レコードが期待値になったかまで確認します。
自動レビューは無人化の範囲を決めて使う
セッション作成時にreview: "auto_review"を指定すると、対応する承認要求をOpenAI管理のレビューモデルが自動で承認または拒否します。設定はルートターンとサブエージェントに適用され、レビューに使うトークンはエージェント本体とは別に課金されます。省略時の既定はnoneです。
自動レビューは、環境のネットワーク制限を広げません。ブラウザーのアクセスやサインイン、入力が必要なフォームも従来のフローが残ります。OpenAIホスト環境では、新規環境またはテンプレートから作るセッションが前提で、既存のホスト環境IDを再利用する方式ではサポートされません。利用中のプロジェクトで機能が有効でなければ、review指定は拒否されます。
長期の定期処理では、すべての要求を自動化するより、読み取りと限定的なファイル生成から始めます。外部への公開、送信、削除など業務影響の大きい処理は、エージェントの完了メッセージだけで進めず、別の業務ルールと確認工程を設けます。これはAgents APIの必須設定ではなく、本サイトが提案する導入順です。
失敗時は実行済みの処理を確認してから再開する
、過負荷、タイムアウト、一時的なサービス障害では再試行が必要になることがあります。公式のErrors and recoveryは、最初にセッション、ターン、保存済みitemを取得し、処理が継続中か完了済みかを確かめる手順を示しています。失敗したターンでも、ファイル変更や外部ツール呼び出しが一部完了している可能性があります。
- invocationから対象セッションとターンを特定する。
- 保存item、ツール結果、外部システムの状態を確認する。
- 入力不備、認証、請求上限は修正してから再送する。
- 一時障害は
Retry-Afterを守り、回数または期限を制限する。 - 失敗ターン後はidleを待ち、未完了部分だけを続ける新しい入力を送る。
同じ指示を無条件に再送すると、作成済みのファイルや通知を重複させることがあります。外部APIには業務単位の冪等キーを用意し、成果物には対象日や実行IDを付けます。再試行回数を使い切ったら、人が確認できる状態と未完了項目を残して停止します。
変更・停止・削除の意味を運用手順に入れる
自動化は後からスケジュールや対象を更新できます。対象を更新するときはオブジェクト全体を送り、必須フィールドとtypeを維持します。変更は次回以降に反映され、既にキューへ入ったinvocationは作成時点の対象と入力を保持します。締切直前の変更を、実行中の仕事へ反映できるとは考えないでください。
pauseは予定された配信を止めますが手動実行は可能で、進行中のセッションは止まりません。deleteも将来の実行を防ぐ操作で、作成済みセッションや既に始まった処理を削除・停止するものではありません。現在の仕事を止める必要がある場合は、対象ターンを別途キャンセルします。1回限りの予定時刻がpause中に過ぎた場合は、将来のrun_atへ更新してから再開します。
スポンサーリンク
小さな定期処理で評価してから広げる
最初の候補には、結果を読み戻せて、失敗しても外部状態を壊さない仕事を選びます。例えば、公開情報の差分を下書きへまとめる、テスト結果を保存する、期限が近い項目を一覧化するといった処理です。予定どおり起動した割合だけでなく、ターン完了、ツール成功、成果物の合格、再試行、待ち時間、モデルとレビューの費用を記録します。
新規セッション方式と継続方式は、同じ成功条件で比較します。継続方式が文脈を再利用しても、過去の誤りや不要な履歴で手戻りが増えるなら、新規方式の方が運用しやすい場合があります。反対に、前回の調査結果を毎回読み直す費用が大きいなら、継続方式と定期的な要約・整理を組み合わせます。
Scheduled automationsの導入で重要なのは、cronを登録することより、invocation、セッション、ターン、外部成果を別々に確認できることです。予定時刻の起動、仕事の完了、業務上の成功を一つの「成功」にまとめず、失敗後に重複なく続けられる設計を先に作ると、エージェントの定期処理を本番へ移しやすくなります。
関連記事
スポンサーリンク
