mcpField
T
tilebox-workflow-jobs

tilebox-workflow-jobs

github.com/tileboxクラウド・DevOps083 回インストール今日更新
リポジトリ

tilebox-workflow-jobs について

`tilebox` CLIでTilebox Workflowsのジョブを操作するエージェント向けスキルです。ジョブの投入、状態確認、ログやトレースの調査、入力形式、再試行、キャンセルを扱います。

主な機能

  1. 01ジョブの投入と完了待ち
  2. 02状態の絞り込みと確認
  3. 03ログと実行スパンの調査
  4. 04失敗タスクの再試行やキャンセル
  5. 05タスク識別子と入力形式の確認

活用シーン

  1. 01クラスターへのワークフロータスク投入
  2. 02タスク失敗や実行時間のデバッグ
  3. 03再試行やキャンセル前の進捗確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/tilebox/skills --skill tilebox-workflow-jobs

インストール後、Claude Code で/tilebox-workflow-jobsを入力して読み込まれたか確認します。

詳細

Tilebox ジョブの管理

tilebox job と tilebox cluster を使った運用作業には、このスキルを使用します。エージェントでは、人間向けの出力を明示的に生成する場合を除き、すべてのジョブコマンドで --json を使用してください。

CLI メタデータの更新

記憶に頼る前に、インストール済みの正確なフラグとスキーマを確認してください。

tilebox agent-context job --output-schema
tilebox agent-context cluster --output-schema

関連するドキュメントの概念：

  • Tilebox Workflows は、クラスター全体でタスクを並列処理するエンジンです。
  • ジョブを送信するとトレースが開始され、タスクの実行ごとにスパンが作成されます。
  • タスクのログは、ジョブ、タスク、ランナー、サービス、トレース、スパンのメタデータと関連付けられます。
  • アクティブなスパン内で出力されたログは、トレースビューでスパンイベントとしても表示されます。

コマンドの選択

  • 作業を開始する：tilebox job submit --name ... --task ... --input ... --json。
  • ジョブを検索する：tilebox job list --last 7d --json を実行するか、--state、--task-state、--name で絞り込みます。
  • 1 つのジョブを調べる：tilebox job get <job-id> --json。
  • 完了、失敗、キャンセルを待つ：tilebox job wait <job-id> --json。
  • ジョブのログメッセージを調べる：tilebox job logs <job-id> --sort desc --limit 100 --json。
  • タイミングのデバッグでジョブのトレース／スパンを調べる：tilebox job spans <job-id> --sort asc --json。
  • 原因を修正した後、再試行可能な失敗タスクを再試行する：tilebox job retry <job-id> --json。
  • 保留中／実行中の作業を停止する：tilebox job cancel <job-id> --json。

コマンドの引数や出力形式が不明な場合は、tilebox agent-context job <subcommand> --output-schema を使用してください。agent-context は常に JSON を返すため、--json は追加しないでください。

ジョブの送信

基本形式：

tilebox job submit \
  --name <job-name> \
  --task <task-identifier-name> \
  --version v0.0 \
  --input '<json-or-plain-text>' \
  --json

重要なフラグ：

  • --name：必須のジョブ名です。1 回の実行を識別するもので、場所、期間、頻度など、実行固有の有用な情報を含めることができます。インスタンス固有のジョブ名をワークフロー名やスラッグとして再利用しないでください。
  • --task：必須のタスク識別子名です。
  • --version：デフォルトは v0.0 です。
  • --input：インラインの JSON またはプレーンテキストです。有効な JSON はそのまま渡され、JSON ではないテキストは JSON 文字列になります。
  • --input-file：ファイルから入力を読み取ります。標準入力には - を使用します。
  • --cluster：任意のクラスターのスラッグです。デフォルトのクラスターを使う場合は省略します。
  • --max-retries：ルートタスクの再試行回数です。デフォルトは 0 です。
  • --wait：送信後、新しいジョブ ID を指定した tilebox job wait <new-job-id> と同様に待機します。

互換性のあるランナーが利用可能で、タスクを実行する見込みがあるとわかっている場合にのみ --wait を使用してください。それ以外の場合は、--wait を付けずに送信し、job get、job logs、または job spans で調べてください。

例：

tilebox job submit --name process-scene --task ProcessScene --input S2A_001 --json
tilebox job submit --name process-count --task ProcessCount --input 5 --json
tilebox job submit --name process-count --task ProcessCount --input '"5"' --json
tilebox job submit --name structured --task tilebox.com/process_scene --version v1.0 --input '{"scene_id":"S2A_001","other_arg":3}' --json
tilebox job submit --name from-file --task ProcessScenes --input-file scenes.json --json
cat scenes.json | tilebox job submit --name from-stdin --task ProcessScenes --input-file - --json

Python の CronTask または StorageEventTask を送信する場合は、tilebox-workflow-automations スキルを使用してください。これらのタスクでは、自動化トリガーのラッパーを構築するために --automation が必要です。

Python タスク識別子と入力

Python の Task クラスは、明示的な identifier() メソッドを定義していない場合、デフォルトで識別子 <ClassName>@v0.0 を使用します。ランナーに登録された正確なタスク名とバージョンを指定してください。

入力は Python の serialize_task(task)／deserialize_task(TaskClass, bytes) に一致させる必要があります。

  • フィールドなし：入力を省略するか、{} を送信します。
  • フィールドが 1 つ：フィールドの値を直接送信します。
    • scene_id: str → --input S2A_001 は JSON 文字列 "S2A_001" を送信します。
    • count: int → --input 5 は JSON 数値 5 を送信します。文字列 "5" の場合は --input '"5"' を使用します。
    • scene_ids: list[str] → オブジェクトではなく、JSON 配列を送信します。
  • フィールドが複数：フィールド名をキーとする JSON オブジェクトを送信します。

不明な場合は、Python で正確なペイロードを生成してください。

/path/to/.venv/bin/python - <<'PY' > task-input.json
from test import ProcessScenes
from tilebox.workflows.task import serialize_task, deserialize_task

task = ProcessScenes(["S2A_001", "S2B_002"])
payload = serialize_task(task)
assert deserialize_task(ProcessScenes, payload).scene_ids == task.scene_ids
print(payload.decode())
PY

tilebox job submit --name process-scenes --task ProcessScenes --input-file task-input.json --json

一覧表示、調査、待機

tilebox job list --last 7d --limit 100 --json
tilebox job list --state failed --after 2026-05-01 --before 2026-06-01 --json
tilebox job list --name landsat --task-state failed,failed_optional --json
tilebox job get <job-id> --json
tilebox job wait <job-id> --stalled-timeout 5m --json

ページ分割された一覧出力の場合、フィルターとソート順を変えずに保ち、next_cursor が空になるまで --cursor に渡してください。

job get では、まず state、execution_stats、task_summaries、progress を確認してください。

ログ、スパン、再試行、キャンセル

tilebox job logs <job-id> --sort desc --limit 100 --json
tilebox job logs <job-id> --include-runner-attributes --json
tilebox job spans <job-id> --sort asc --limit 100 --json
tilebox job spans <job-id> --include-runner-attributes --json
tilebox job retry <job-id> --json
tilebox job cancel <job-id> --json

アプリケーションのメッセージやエラーにはログを使用してください。タイミング、順序、親子関係、属性にはスパンを使用してください。根本的な問題を修正した後にのみ再試行してください。作業を続行すべきでない場合はキャンセルしてください。キューに登録されたタスクは実行されず、すでに実行中のタスクは完了する場合があります。

デバッグの流れ

  1. tilebox job get <job-id> --json を実行して、状態とタスク数を確認します。
  2. 失敗した場合は、失敗したタスクの概要と直近のログを調べます。
  3. タイミング、順序、またはランナー／ランタイムの属性が重要な場合は、スパンを使用します。
  4. コード、データ、認証情報、またはインフラストラクチャを修正してから再試行します。
  5. 再試行せずにジョブを停止すべき場合は、キャンセルします。

コメント

Markdown 対応