crontap-recurring-agent-endpoint

アプリが所有するエージェントエンドポイントのスケジュール設定

ワークフローを開始するデプロイ済みの HTTP サービスをユーザーが管理している場合にのみ、このアーキテクチャを使用してください。Crontap は HTTP リクエストをスケジュールし、チェックインを監視します。エージェント、IDE セッション、チャット、MCP クライアントを起動するものではありません。

Cursor、Claude、ChatGPT、Codex、その他のクライアント内で定期的にプロンプトを実行する場合は、そのクライアントのネイティブ自動化機能を使用してください。MCP クライアントはツール呼び出しを開始します。MCP サーバーからクライアントに接続を開始することはありません。

アーキテクチャ

Crontap clock -> protected app endpoint -> app-owned queue -> agent worker
                                                     |
                                                     +-> heartbeat on completion

前提条件

必須ツールを使用する前に、利用可能かどうかを確認してください。不足しているツールがある場合は、そこで中断し、ユーザーに次の2つの選択肢を正確に提示してください。

1. https://mcp.crontap.com/mcp で Crontap MCP に接続します。MCP はすべての Crontap プランで利用できます。
2. $CRONTAP_CLIENT_ID と $CRONTAP_API_KEY を設定して、Raw API を使用します。Raw API の利用には Ultra が必要です。

ユーザーが選択するまで、選択肢を暗黙的に選んだり、処理を続けたりしないでください。

• デプロイ済みのアプリケーションエンドポイントと、永続性のあるワーカーがすでに存在していること。
• エンドポイントが専用の cron シークレットを認証すること。
• キューへの登録と下流の処理が、論理的な実行期間ごとに冪等であること。
• ワーカーがハートビート URL を安全に読み取れること。

ワークフロー

1. 想定される完了時間に合わせて期間と猶予時間を設定し、ハートビートを作成します。
2. そのシークレット URL をワーカーのシークレットマネージャーに保存します。
3. 永続的な処理が正常に完了した後にのみ ping を送信し、明示的な最終失敗には /fail を使用するよう、ワーカーを更新します。
4. 保護されたキュー登録エンドポイントに対する Crontap スケジュールを作成します。
5. キュー登録の証拠、ワーカーの証拠、ハートビートの証拠を確認します。

MCP の例

完了監視を作成します。

{
  "tool": "create_heartbeat",
  "arguments": {
    "name": "Daily agent workflow completion",
    "periodMinutes": 1440,
    "graceMinutes": 60
  }
}

HTTP クロックを作成します。

{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://agent-app.example.com/api/jobs/daily-analysis",
    "text": "every day at 07:00",
    "timezone": "UTC",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <cron-secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "body": {
      "workflow": "daily-analysis"
    },
    "label": "Daily analysis enqueue"
  }
}

UTC の1日分のハートビート証拠を確認します。

{
  "tool": "get_heartbeat_pings",
  "arguments": {
    "heartbeatId": "<heartbeat-id>",
    "day": "2026-09-14"
  }
}

エンドポイントの契約

• リクエスト本文を読み取ったり、キューに登録したりする前に認証します。
• 安定した論理的実行キーを導出または受け取り、それが永続的に一意となるようにします。
• キューがジョブを受け付けた後にのみ、2xx を返します。
• 再度キューに登録しても安全な場合にのみ、再試行可能な 5xx を返します。
• モデルプロバイダーの認証情報は、ワーカー環境内に保持します。

REST の代替手段

REST の作成には Ultra API の利用が必要です。

curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://agent-app.example.com/api/jobs/daily-analysis",
    "interval": "0 7 * * *",
    "timezone": "UTC",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <cron-secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "data": {"workflow": "daily-analysis"},
    "label": "Daily analysis enqueue"
  }'

接続されている場合は MCP を使用してください。MCP の利用は Ultra 限定ではありません。

検証

• スケジュール呼び出し1回につき、論理的な実行期間に対する永続的なキューレコードが1件作成されます。
• ワーカーの再試行によって外部への副作用が重複することはありません。
• 成功時の ping は、キューへの登録後ではなく、永続的な処理の完了後に送信されます。
• 実行されなかったジョブや失敗したジョブは、シークレット URL を公開することなく、ハートビートの履歴に表示されます。

安全性とプランの制限

• モデルキー、cron シークレット、ハートビート URL をプロンプトやログに公開しないでください。
• アプリが所有するワーカー内で、コスト、実行時間、モデル呼び出し、外部への書き込みに上限を設けてください。
• デプロイ済みのエンドポイントがない場合は、クライアントのネイティブ自動化機能を使用してください。
• リソース制限によって作成できない場合は、返された4つの選択肢からなる段階的な案内をそのまま維持し、実行可能な最小の選択肢を示してください。

トラブルシューティング

• スケジュールが成功しているのにハートビートがない場合、キューへの登録は成功しましたが、ワーカーが完了していないか、ping を送信していません。
• スケジュールが失敗する場合は、ワーカーより先に HTTP 境界をデバッグしてください。
• キューレコードが繰り返し作成される場合、キュー登録エンドポイントにアトミックな冪等性がありません。
• 保留中のハートビートには、受け付けられた ping がまだ一度も届いていません。

参考資料

• Crontap エージェントスキルのカタログ
• スケジュールされた AI ジョブ
• Crontap ハートビート
• Cron ジョブの監視
• Crontap MCP