Forward Session で自然言語を使用して Schedule を作成、照会、変更、アーカイブします。
Forward Session で自然言語を使用して、Schedule を直接作成、照会、変更、アーカイブできます。
API の呼び出しに加えて、エンドユーザーは Web または IM Channel でタスクの内容と実行時刻を説明できます。Agent が Schedule を作成し、その後は元の Session をオンラインに保たなくても、予定どおりに自動実行されます。
Schedule の実行時は Template / Identity Config で有効なファイルを使用できます。作成元の会話の添付ファイルは Schedule に自動コピーされません。専用ファイルは HTTP 作成またはSchedule 更新の
Schedule を管理する前に、現在の Template または Identity の有効な設定で、対応する Schedule 管理機能を有効にしてください。
既存の Template を更新する例:
同じ Template 配下の Identity ごとに異なる Schedule 機能が必要な場合は、Identity Config でツール名ごとに個別スイッチを設定できます。
Identity Config に記載されていないツールは Template のベースラインを継承します。個別ツールを
有効なデフォルトの Forward MCP 設定を使用する場合、新しいリクエストで設定が更新されると、Schedule が無効でも対話 Session のモデルには 4 つのツールが表示されます。同名のカスタムツールが既にある場合は、そのツールを保持します。表示されることは実行権限を意味せず、呼び出し時に Template と Identity の有効なスイッチおよびリソースアクセス権限を検証します。
どちらもツール結果内の業務エラーで、
会話で次の情報を指定します。
監視タスクでは、実行頻度、対象日、年、開始時刻と終了時刻、トリガー条件を明示することをお勧めします。必要な情報が不足している場合、Agent が追加で確認します。
作成が完了すると、Agent が結果を返します。作成した Schedule を表示するよう Agent に依頼し、タスク名、トリガールール、タイムゾーンを確認することもできます。
以下では、連携側がエラーコードを読み取り、理由を表示して次の操作を判断できるように、
以下の表の MCP エラーコードは
自然言語による作成では
これらの状況は必ずしも MCP の業務結果として返されないため、
実行内容には空でない
失敗時に
MCP の実際の作成リクエストはそれぞれ独立して処理され、同じ Session、Turn、引数による自動重複排除はありません。結果が不明なときに作成を自動で再実行しないでください。従来ツールの同じ信頼済み呼び出し識別子に対する再実行ルールも、すべての経路に共通する冪等性の保証ではありません。
現在表示できる Schedule を照会し、名前、タスク内容、またはステータスで絞り込めます。例:
タスクの名前、説明、実行内容、実行時刻、頻度、監視期間を変更できます。例:
Schedule ID でタスクを正確に指定するか、名前・説明・実行内容のキーワードで検索できます。変更対象は現在の Session の Owner と Identity に属するタスクに限定されます。複数のタスクに一致した場合は何も変更せず、Agent が候補を返して Schedule ID の指定を求めます。一致するタスクがない場合も、新しいタスクは作成しません。
Agent は
cron または interval の変更時、省略した監視期間の境界は維持されます。once に切り替えると継承した監視期間はクリアされ、once に空でない start_at / stop_at は設定できません。interval ルールを変更すると、更新時点から後続のトリガー時刻を再計算します。ルールが変わらない場合は既存の次回トリガー時刻を維持します。
例えば、毎日実行する cron タスクの時刻だけを午前 10 時に変更し、元のタイムゾーンと監視期間を維持するツールパラメーターは次のとおりです。
他の設定を維持したまま終了時刻をクリア:
キーワードでタスクを一意に特定し、実行内容を置き換える(元のタスクの初期メッセージは 1 件のみ):
10 分後に 1 回実行するタスクに変更:
Schedule ID、名前、またはタスク内容を指定してアーカイブできます。自然言語では引き続き「削除」と表現できますが、データは物理削除されません。例:
複数の Schedule が一致した場合、Agent はアーカイブを実行せず、Schedule ID で選択できる候補を返します。「削除」は実際にはアーカイブであり、新しい Run は作成されません。Schedule は ID または
アプリケーションで作成・検索・変更・アーカイブツールの結果を受け取るには、Schedule 管理ツール結果 Webhookを購読します。これらは Schedule Run の実行成功・失敗通知とは独立しています。作成とアーカイブの成功には既存の
既存の個別購読には新しいイベントを明示的に追加する必要があります。
resources 配列で指定してください。現在の自然言語作成・変更ツールには resources パラメーターがなく、HTTP API のファイル設定・実行はこのページの管理ツールスイッチに依存しません。
前提条件
Schedule を管理する前に、現在の Template または Identity の有効な設定で、対応する Schedule 管理機能を有効にしてください。
- Schedule の作成:
create_forward_schedule - Schedule の照会:
list_forward_schedules - Schedule の変更:
update_forward_schedule - Schedule のアーカイブ:
delete_forward_schedule
schedule バンドルは 4 つの機能をまとめて設定し、ツール名ごとに個別設定することもできます。managed_tool_config は Template リクエストボディのトップレベルフィールドで、次の API から設定できます。
- Template の作成:
POST /api/v1/forward/templates - Template の更新:
POST /api/v1/forward/templates/{template_id}
enabled_tools は Forward 管理機能のベースライン全体を置き換えます。引き続き有効にする必要がある他の管理機能も含めてください。
enabled_tools を ["schedule"] にすると、作成・照会・変更・アーカイブをまとめて有効にできます。既存の設定で作成・照会・アーカイブの 3 ツールだけを明示している場合、変更機能は自動で有効になりません。update_forward_schedule を追加するか schedule バンドルに切り替えてください。
Identity ごとのオーバーライド
同じ Template 配下の Identity ごとに異なる Schedule 機能が必要な場合は、Identity Config でツール名ごとに個別スイッチを設定できます。
null にするとそのオーバーライドを削除し、managed_tool_config: null にするとすべてのオーバーライドを削除します。詳細なマージおよび競合ルールは、Identity Config の作成または更新を参照してください。
既存の Identity では、identity_config.tools.<name>.enabled=false を使用して継承した管理対象ツールを無効化する方法も引き続き利用できます。新規連携では identity_config.managed_tool_config を使用してください。
ツールの表示と有効化
有効なデフォルトの Forward MCP 設定を使用する場合、新しいリクエストで設定が更新されると、Schedule が無効でも対話 Session のモデルには 4 つのツールが表示されます。同名のカスタムツールが既にある場合は、そのツールを保持します。表示されることは実行権限を意味せず、呼び出し時に Template と Identity の有効なスイッチおよびリソースアクセス権限を検証します。
| ツール結果のエラーコード | 意味と対応 |
|---|---|
schedule_feature_disabled | 対応する機能が無効で、操作は実行されません。Agent はテンプレートページの「ツール」で Schedule を有効にして保存するよう案内します。有効済みの場合は管理者が Identity のオーバーライドを確認してください。設定権限のないユーザーはアシスタント管理者に連絡してください。 |
schedule_configuration_changed | 現在の Session に有効化後の設定が未適用です。ユーザーが新しいリクエストを送信し、必要に応じて Session に入り直して設定を更新してください。 |
retryable=false です。Agent は自動で呼び出しを繰り返してはいけません。有効化後も、ユーザーが新しいリクエストを送信して設定を更新してください。
これらは Schedule CRUD API の新しい HTTP エラーではありません。スイッチは Schedule API の直接呼び出しに影響せず、既存 Schedule も一時停止しません。Schedule 実行 Session には管理ツールを公開しません。従来の Custom Tool 経路は従来の動作を維持し、無効でも表示されるルールの対象外です。
Schedule を作成する
会話で次の情報を指定します。
- 実行時刻(毎日午前 9 時、毎週月曜日の午前 10 時、2 時間後など)
- タスクの内容
- 出力要件
- タイムゾーン。指定しない場合、デフォルトは
Asia/Shanghaiです。
定期タスク
1 回限りのタスク
固定間隔のタスク
作成失敗とエラーコード
以下では、連携側がエラーコードを読み取り、理由を表示して次の操作を判断できるように、create_forward_schedule の作成失敗を説明します。HTTP による Schedule の作成、検索・変更・アーカイブツールのエラー、および作成後の Run 実行やメッセージ配信の失敗とは分けて処理してください。
作成失敗のコールバックを受信するには、Schedule 管理ツール結果 Webhookを購読します。以下の表は、作成経路の既存の安定した業務エラーコードを対象とします。詳細コードがない場合や結果が不確かな場合は、後述します。
最初にエラーの発生経路を確認する
| 経路 | 失敗の判定 | エラーコードの場所 |
|---|---|---|
| Forward Builtin MCP ツールの業務結果 | is_error=true。HTTP 200 でも業務失敗を示す場合があります | structured_content.error_code |
| 従来の Custom Tool のツール結果イベント | user.tool_result または user.custom_tool_result の is_error=true | content 内の type=text 項目の text を JSON として解析し、error.code を読み取ります |
| MCP リクエストレベルのエラー | HTTP 非 2xx。HTTP エラーエンベロープを使用します | error.code。一部のエラーでは省略されるため、error.type、HTTP ステータス、および存在する場合は request_id も読み取ります |
| 作成失敗 Webhook(購読済みの場合) | イベントタイプが forward.schedule.create_failed | data.error.code。category、message、requires_input も含まれます |
error.message、structured_content.message、自然言語の応答文は安定性が保証されません。文言の一致で処理を分岐しないでください。1 回の呼び出しに複数の問題がある場合、最初に該当したエラーを返し、すべての検証エラーを一度には返しません。
時間ルールと業務エラーコード
以下の表の MCP エラーコードは structured_content.error_code、従来ツールのエラーコードは解析後の error.code にあります。Webhook 固有の違いは後述します。
| エラーコード | 対象経路 | 失敗する状況 | 対処方法 |
|---|---|---|---|
trigger_policy_time_too_soon | MCP、従来ツール | once の対象時刻がサーバーの現在時刻以前、または指定した stop_at が現在時刻以前 | 実際の現在時刻、完全な日付、タイムゾーンを確認し、ユーザーの意図を再確認してから未来の時刻を使用します。過去の日付をそのまま翌日に変更しないでください |
trigger_policy_too_frequent | MCP、従来ツール | interval が 1 分未満、または cron が 5 フィールドを超える場合(秒フィールドを含む形式も対象) | 繰り返しタスクは 1 分以上にし、cron は 5 フィールド式を使用します。1 回限りのリマインダーには once を使用します |
invalid_trigger_policy | MCP、従来ツール | 式の欠落や解析不能、必要なタイムゾーンの解析不能、不正な時間ウィンドウ、once 以外での delay 使用、expression との同時指定、不正な duration などのポリシー検証エラー | 以下のポリシールールに従って修正します。MCP でポリシーオブジェクトや type が欠落するなどの構造エラーは先に HTTP 400 を返す場合があります。「パラメーターと権限の失敗」を参照してください |
invalid_sinks | MCP、従来ツール | IM の送信元から導出した通知先設定の検証に失敗。必要な宛先情報の欠落や不正なルーティングなど | チャネルのバインドと通知先を確認してから新しいリクエストを送信します。モデルが独自に sinks を指定して送信元を上書きしてはいけません |
schedule_feature_disabled | MCP | 現在の Template または Identity で該当する Schedule 機能が有効になっていない | テンプレートのツール設定で有効にして保存するか、管理者に Identity のオーバーライド設定を確認してもらいます。修正後に新しいリクエストを送信し、自動再試行はしません |
schedule_configuration_changed | MCP | 現在の設定では有効だが、Session に対応するツール設定がまだ適用されていない | 新しいリクエストで Session の設定を更新します。それでも利用できない場合は Session を開き直します。自動再試行はしません |
schedule_owner_unsupported | MCP | 現在の所有者とその認証情報の機能が Schedule の作成をまだサポートしていない | 管理者にその所有者の Schedule サポート状況を確認してもらいます。同じリクエストを再試行しても解決しません |
ポリシールール
| タイプまたはフィールド | 有効なルールと境界 |
|---|---|
once.expression | 1 回限りの絶対時刻はサーバーの現在時刻より後である必要があります。once には 1 分の最小間隔制限がなく、10 秒後のリマインダーも作成できます |
once.delay | 相対的な 1 回限りのリマインダーは PT10S、PT2M などの ISO 8601 duration を使用します。ツール経由のみで対応し、サーバーが絶対時刻に変換します。expression との同時指定はできません |
interval.expression | PT1M、PT15M、P1D など、1 分以上の ISO 8601 duration を使用します。PT30S は頻度超過、30s は形式不正としてポリシー形式エラーを返します |
cron.expression | 0 9 * * * などの 5 フィールド cron を使用します。6 フィールド以上の式は頻度超過として拒否されます |
timezone | ツールで省略すると Asia/Shanghai が既定値です。オフセット付き絶対時刻はその絶対時刻として、オフセットなしの時刻は指定タイムゾーンで解釈します |
start_at / stop_at | 時刻は解析可能である必要があります。stop_at は現在時刻より後、両方を設定する場合は start_at より後である必要があります。once はこの 2 つのウィンドウフィールドをサポートしません |
cron、once、interval を使用します。MCP は manual を受け付けません。HTTP 直接作成で manual をサポートする規約は、このツールには適用されません。
パラメーターと権限の失敗
これらの状況は必ずしも MCP の業務結果として返されないため、structured_content.error_code だけを確認してはいけません。
| 状況 | 従来ツールの結果 | MCP の同期応答 | 対処方法 |
|---|---|---|---|
| ツール引数の型の誤り、不正なフィールド、実行内容の欠落、名前や説明の上限超過、非対応の制御文字 | 通常は invalid_request | HTTP 400、error.type=invalid_request_error。error.code がない場合があります | 引数を修正してから再送信します |
trigger_policy、type の欠落、または非対応のタイプ | invalid_trigger_policy | HTTP 400、invalid_request_error。詳細コードがない場合があります | ポリシーを補い、ツールが対応するタイプだけを指定します |
モデルが user_id、identity_id、template_id、environment_id、sinks、metadata などの所有者・送信元フィールドを指定 | invalid_request | HTTP 400、invalid_request_error。詳細コードがない場合があります | フィールドを削除します。所有者と送信元は現在の Session から決まります |
| 送信元の Identity や Session コンテキストが欠落・不一致、または現在の Identity・リソースへのアクセス検証が拒否された | invalid_identity。一部の所有者競合は引き続き invalid_request | HTTP 403、error.type=permission_error。一部のコンテキスト異常では別の HTTP エラーになる場合があります | Identity、リソースの認可、現在の Session を確認し、必要に応じて Session を開き直すか管理者に連絡します |
| Schedule の実行で作成された Session 内で Schedule 管理ツールを再度呼び出す | schedule_tool_forbidden_in_schedule_run | HTTP 403、permission_error。詳細コードがない場合があります | 通常のユーザー Session に戻って作成し、再帰的なタスク作成を避けます |
| ツールが存在しない、または Session で利用が許可されていない | そのツールの結果イベントがない場合があります | HTTP 404 not_found_error または HTTP 403 permission_error。詳細コードがない場合があります | ツール設定と Session を確認し、頻度や時刻の問題として扱わないでください |
initial_events、または互換フィールド instruction を使用します。イベントタイプは user.message、内容は空でない必要があります。MCP のフィールド構造の事前検証は従来ツールと異なるため、同じ不正入力でも経路によって異なる応答になる場合があります。
現在の応答の互換性の違い
| 状況 | 同期応答と Webhook の違い |
|---|---|
| 送信元の IM チャネルが無効 | 現在の MCP 同期呼び出しは HTTP 500 api_error となり、詳細コードがない場合があります。従来ツールの同期結果は invalid_request にフォールバックします。購読済みの作成失敗 Webhook では invalid_sinks に正規化されます |
| 現在の所有者が Schedule をサポートしていない | MCP の業務結果は schedule_owner_unsupported、従来ツールの同期結果は引き続き invalid_request です。対応する Webhook では MCP は schedule_owner_unsupported を維持し、従来ツールは invalid_request を維持して category=forbidden を付けます |
| 一部の所有者競合 | 従来ツールの同期結果は invalid_request の場合があります。購読済みの失敗 Webhook では invalid_identity、category=forbidden に正規化される場合があります。MCP 同期呼び出しも詳細コードのない HTTP エラーになる場合があります |
invalid_request を常にユーザー引数の誤りと解釈しないでください。従来経路でまだ細分化されていない拒否や例外の場合もあります。Webhook の正規化されたエラーコードから、同期応答にも必ず同じフィールドが含まれるとは判断できません。
失敗の例
MCP:繰り返しタスクの間隔が 30 秒
trigger_policy={"type":"interval","expression":"PT30S"} の場合の業務結果例は次のとおりです。HTTP ステータスは 200 ですが、呼び出し側は is_error=true に従って失敗を処理する必要があります。
従来ツール:1 回限りの対象時刻が過去
サーバーの現在時刻がすでに2026-07-29T11:00:00+08:00 より後であるとします。以下はツール結果イベントの content[].text を解析した JSON で、イベント自体には別途 is_error=true があります。
schedule_id が存在する保証はありません。必ず空文字列になると想定しないでください。従来ツールが再帰隔離で拒否された場合、結果に error しか含まれないことがあり、tool_name、success、トリガーポリシーのフィールドが補われる保証はありません。
MCP:詳細コードのない引数エラー
たとえば、ツールに必須のポリシーオブジェクトがリクエストにない場合、HTTP 400 の応答は次のようになります。作成失敗 Webhook
forward.schedule.create_failed を購読した後、同イベントの data に含まれる関連フィールドは次のとおりです。
requires_input=false は自動再試行が許可されることを意味しません。送信元を検証できない場合、失敗 Webhook が生成されないことがあります。通知の永続化・配信やツール結果の書き戻しに失敗しても、Schedule が作成されなかったとは判断できません。
システム異常、不確かな結果、再試行
| 状況 | 呼び出し側の処理 |
|---|---|
| 時刻、ポリシー、機能、引数に関する明確な拒否 | 原因を修正するかユーザーの意図を補ってから再送信します。同じ引数で繰り返しリクエストしても解決しません |
| HTTP 401 / 403 | 認証や権限の問題として処理します。モデルに Identity を推測させたり所有者フィールドを上書きさせたりしないでください |
| HTTP 5xx、タイムアウト、切断、結果を受信できない | 利用可能なリクエスト・Session 識別子を保存し、先に Schedule を照会して作成済みか確認してから再作成を判断します。作成がコミットされた後にこれらが発生する場合があります |
| ツールが呼ばれず、モデルが確認質問や自然言語だけを返す | 作成エラーコードがない場合があります。応答文だけでは作成成功・失敗を判断できません |
| タスクは作成されたが、その後の実行や配信に失敗 | Schedule Run または通知配信の結果に従って処理し、作成失敗には分類しません |
schedule_not_found、schedule_archived、schedule_match_ambiguous などは既存の Schedule の管理に関するもので、通常の作成検証エラーとして表示してはいけません。連携側が独自に定義したトップレベルの error_code、error_message、operation、rule_description などは、上記の各経路で共通して保証される応答構造ではありません。
Schedule を照会する
現在表示できる Schedule を照会し、名前、タスク内容、またはステータスで絞り込めます。例:
Schedule の変更
タスクの名前、説明、実行内容、実行時刻、頻度、監視期間を変更できます。例:
変更ツールのパラメーター
Agent は update_forward_schedule で変更を行います。以下はツールのパラメーターであり、HTTP Schedule 更新のリクエストボディではありません。呼び出し元が内部 MCP 呼び出しを構築する必要はありません。
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| schedule_id | string | query とどちらか一方 | タスクを正確に指定する空でない Schedule ID。 |
| query | string | schedule_id とどちらか一方 | 名前・説明・初期イベント内容に一致する空でないキーワード。一意に一致した場合のみ変更します。 |
| name | string | いいえ | 空でない名前。最大 256 文字。 |
| description | string | いいえ | 説明。最大 2048 文字。空文字列で説明をクリアします。 |
| instruction | string | いいえ | 空でない実行指示。元のタスクに user.message 初期イベントがちょうど 1 件ある場合のみ使用できます。initial_events と排他です。 |
| initial_events | array | いいえ | 初期イベント一覧を 1~50 件で完全に置き換えます。各イベントには type: user.message と空でない content のみを含めます。複数イベントは配列内の順序を維持します。instruction と排他です。 |
| trigger_policy | object | いいえ | サブフィールド単位でトリガーポリシーを部分更新します。少なくとも 1 フィールドが必要で、省略したフィールドは現在の設定を維持します。 |
name、description、instruction、initial_events、trigger_policy のうち少なくとも 1 つを指定してください。すべてのパラメーターで null と未知のフィールドを拒否します。ツールは identity_id、template_id、environment_id、resources、sinks、execution、metadata、状態フィールドを受け付けません。これらの設定は対応する管理 API で変更してください。
trigger_policy は次のサブフィールドをサポートします。
| フィールド | 型 | 説明 |
|---|---|---|
| type | string | cron、once、interval。manual は受け付けません。種類を切り替える場合、新しい expression、または once の delay も必要です。 |
| expression | string | 5 フィールドの cron、once の絶対時刻、interval の ISO 8601 duration。delay と排他です。 |
| delay | string | once 専用の正の相対遅延。例:PT10M。元の絶対トリガー時刻を置き換えます。 |
| timezone | string | IANA timezone。省略時は元のタイムゾーンを維持します。 |
| start_at | string | 開始時刻。timezone で解釈する秒単位のローカル時刻、または offset 付き RFC3339 を受け付けます。空文字列でこの境界をクリアします。 |
| stop_at | string | 終了時刻。形式は start_at と同じです。空文字列でこの境界をクリアします。 |
変更結果
| ツール結果 status | 意味 |
|---|---|
| updated | 変更済み。タスク ID、名前、schedule_status、initial_events_version、トリガーポリシー、利用可能な場合は next_trigger_at を返します。 |
| unchanged | 正規化したリクエストが現在の設定と一致します。バージョン、updated_at、次回トリガー時刻は更新しません。 |
| not_found | query に一致するタスクがありません。変更・作成は行いません。 |
| multiple_matches | query が複数タスクに一致しました。候補を返すので、schedule_id を 1 つ指定してから変更してください。 |
status は今回のツール操作の結果で、タスクの active / paused 状態は schedule_status が表します。一時停止中のタスクを変更しても自動再開しません。必要に応じてSchedule の再開を別途行ってください。指定した正確な ID が存在しないかアーカイブ済みの場合、ツールの業務エラーを返します。
実行内容が実際に変わった場合のみ initial_events_version が増加し、名前やトリガールールの変更では増加しません。既存 Run は入力バージョンとバインド規則に従い、変更によって履歴は書き換えられません。next_trigger_at はツール結果のフィールドであり、HTTP Schedule オブジェクトに追加されるフィールドではありません。
Schedule をアーカイブする
Schedule ID、名前、またはタスク内容を指定してアーカイブできます。自然言語では引き続き「削除」と表現できますが、データは物理削除されません。例:
include_archived=true で取得でき、履歴も保持されます。既存の pending または running Run はキャンセルされません。
実行結果を確認する
- Web で作成した Schedule の結果は元の Session に返されます。作成後にオフラインになっても、次にその Session を開いたときに保留中の結果を受け取れます。
- IM Channel で作成した Schedule の結果は、対応する Channel Session に送信されます。
- API で Schedule Run を一覧表示 または Schedule Run を取得 することもできます。
管理ツール結果通知の受信
アプリケーションで作成・検索・変更・アーカイブツールの結果を受け取るには、Schedule 管理ツール結果 Webhookを購読します。これらは Schedule Run の実行成功・失敗通知とは独立しています。作成とアーカイブの成功には既存の forward.schedule.created と forward.schedule.archived を使用します。
変更ツールが実際に変更を保存し、結果が updated の場合は forward.schedule.updated を送信します。設定が現在の値と同じで結果が unchanged の場合は通知せず、結果は現在の Session で確認できます。確定的な業務失敗、一致なし、複数一致は forward.schedule.update_failed で通知されます。インフラ障害やコミット結果が不確かな場合は、業務上の失敗通知を保証しません。コールバックが届かないことを変更失敗の根拠にしないでください。
例えば、実際の変更と確定的な変更失敗の通知を購読します。
* の購読では自動的に受信します。変更成功イベントは schedule_id、updated_at、schedule_version などの要約を提供し、タスクの指示や完全な初期イベントは含みません。この通知は管理ツールの呼び出しのみが対象です。HTTP の Schedule 更新を直接呼び出した場合、この成功イベントは生成しません。
制限事項
cronおよびintervalトリガーの最小粒度または間隔は 1 分です。onceトリガーで相対遅延を指定する場合、上記の最小頻度は適用されませんが、遅延は 0 より大きい必要があります。- Schedule の実行中は、別の Schedule を作成、照会、変更、アーカイブできません。これにより、タスクの自己複製や再帰的な Schedule 管理を防ぎます。