ワークフロー

ワークフローは、実行の定義に名前を付けて保存したものです。プロンプト、モデル、ファイル、接続、タイムアウト、シェルと Web の設定を保持します。コードからは名前を指定して開始し、実行ごとに変わる部分だけを送信します。

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

保存される内容と、実行ごとに送る内容

ワークフローは、ダッシュボードのワークフロー、PUT /v1/workflows/{name}、または ephemeral workflows save で保存できます。通信で使う形式は JSON で、CLI は YAML も読み込めます。名前は英字または数字で始め、英字、数字、_、.、- を使って 128 文字まで指定できます。

保存済みフィールドの上書き

実行リクエストで prompt、model、files、connections、timeout_seconds、shell、web のいずれかを指定すると、その実行に限って保存された値が置き換えられます。ファイルと接続は、コレクション全体が置き換わります。保存済みのものとマージされることはありません。

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

空のオブジェクトまたは配列を指定すると、その実行ではコレクションが空になります。接続やファイルを 1 つだけ変更したい場合は、実行に持たせたい一覧を完全な形で送信してください。

参照が解決されるタイミング

ワークフローは、ファイルと保存済みの接続を名前で参照します。Ephemeral はこれらの名前を実行の作成時に解決し、実行は解決した結果を保持します。ファイル名は、その名前の最新のアップロードに解決されます。そのため、playbook.md の新しいバージョンをアップロードすれば、ワークフローを編集しなくても、次の実行から読み取る内容が変わります。

参照しているファイルまたは接続が存在しなくなった場合、実行リクエストは 400 で失敗し、見つからない参照が示されます。キューには何も入らず、課金も発生しません。

入力と出力を記述する

任意の 3 つのフィールドで、ワークフローは自分自身を説明できます。人も、ほかのコードも、AI エージェントも、プロンプトを読まずに呼び出し方がわかります。description は、ワークフローが何をし、どんな入力を期待するかを 1、2 文で説明します (500 文字まで)。input_schema は、実行の input が満たすべき JSON Schema です。output_schema は、実行の出力が満たすべき JSON Schema です。3 つとも GET /v1/workflows?detail=true と MCP の list_workflows ツールで取得でき、インラインの実行でも使えます。

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

入力は、API、CLI、MCP ツール、スケジュールのどこから来る場合でも、実行の作成時に検証されます。一致しない場合、リクエストは 400 で失敗し、問題ごとにパスと理由が示されます (例: input.city: required)。キューには何も入らず、課金もされません。スケジュールの入力は、スケジュールの作成時と変更時に検証され、開始のたびに再度検証されます。一致しなくなった開始は、スケジュールの最後のエラーとして記録されます。

出力は output_schema に一致する JSON である必要があります。エージェントにはスキーマが伝えられ、JSON だけで返答するよう求められます。返答が一致しない場合は、正確なエラーが返され、最大 2 回まで修正を求められます。その後、Ephemeral が出力をもう一度検証します。一致すれば実行は succeeded のままで、出力はコードブロックで囲まれていない JSON テキストになります。一致しなければ実行は failed で終了し、error には output did not match output_schema: output.temperature_c: got string, want number のような内容が入ります。エージェントが書いた内容を確認できるよう、出力テキストは保持されます。ゼロデータ保持の実行では、エラーに詳細は残りません。

スキーマは JSON Schema draft 2020-12 を使います (draft 7 以前を指定する $schema も使えます)。1 つあたり 32 KiB までで、参照できるのは #/$defs/address のようにスキーマ内の定義のみです。無効なスキーマは、ワークフローの保存時または実行の作成時に 400 で拒否されます。

ワークフローを編集する

ワークフローを再度保存すると、置き換えられます。バージョン履歴はありません。変更前に作成された実行は、作成時の定義を保持します。実行が実際に使った内容を確認するには、その定義を読み取ってください。

ワークフローを読み取ると、接続の認証情報と URL 内のシークレットが除かれた状態で返されます。これらのフィールドを省いたまま保存し直した場合、認証の種類が同じであれば、保存済みの認証情報は保持されます。