ワークフロー · Ephemeral ドキュメント

実行の定義に名前を付けて保存し、POST /v1/runs で開始します。このページのエンドポイントは、すべてメンバーキーと管理者キーで使えます。保存済みのフィールドと上書きの組み合わせ方については、ワークフローをご覧ください。

ワークフローを保存

PUT/v1/workflows/{name}

ワークフローを作成します。同じ名前がすでにある場合は置き換えます。名前は英字または数字で始め、英字、数字、_、.、- を使って 128 文字まで指定できます。

ボディ

promptstring必須

タスク。最大 128 KiB。

modelstring

モデル ID。省略すると、各実行は、作成した時点のデフォルトのモデルを使います。

filesarray

ファイルのエントリ。実行リクエストと同じ形式です。名前は、各実行の作成時に解決されます。

connectionsobject

接続。キーはエージェントに見える名前です。{"ref": "<saved name>"} 形式のエントリを推奨します。

descriptionstring

ワークフローが何をし、どんな入力を期待するか。500 文字まで。

input_schemaobject

各実行の input が満たすべき JSON Schema。一致しない実行は 400 で拒否されます。入力と出力を記述するを参照してください。

output_schemaobject

各実行の出力が満たすべき JSON Schema。出力は JSON になり、出力が一致しない実行は失敗します。入力と出力を記述するを参照してください。

timeout_secondsinteger

1 から 3600。省略すると、実行では 300 が使われます。

shellboolean

省略すると、実行では true が使われます。

webboolean | object

ワークフローの実行に対する Web アクセス。true、または allow と search を持つオブジェクト。省略するとオフです。

ワークフローには、input、max_cost_micros、callback を含められません。これらは実行ごとに指定するものです。レスポンスは {"name": "investigate-payment"} です。

curl -X PUT $EPHEMERAL_URL/v1/workflows/investigate-payment \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find out why this payment failed. Follow the playbook.",
    "model": "anthropic/claude-haiku-5.5",
    "files": [{ "file": "playbook.md" }],
    "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
    "timeout_seconds": 120,
    "shell": false
  }'

ワークフローを開始

ワークフロー名を、その実行の入力と予算とともに POST /v1/runs に送信します。含めた定義フィールドは、その実行に限って保存済みの値を置き換えます。files と connections は、コレクション全体が置き換わります。

ターミナル

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow":"investigate-payment","input":{"payment_id":"pay_123"},"max_cost_micros":500000}'

ワークフローが存在しない場合、リクエストは 400 とメッセージ saved workflow not found で失敗します。

ワークフローを一覧

GET/v1/workflows

組織内のワークフローを、アルファベット順に、それぞれ name を持つオブジェクトとして返します。?detail=true を付けると、description、input_schema、output_schema を持つワークフローについてはそれらも含まれます。定義全体を確認するには、名前を指定してワークフローを取得します。

JSON

[{ "name": "investigate-payment" }, { "name": "weekly-report" }]

?detail=true を付けると、エージェントは各ワークフローが何を期待し、何を返すかを確認できます。

JSON

[
  {
    "name": "weather",
    "description": "Current weather for a city. Input is a city name.",
    "input_schema": { "type": "object", "required": ["city"], "properties": { "city": { "type": "string" } } },
    "output_schema": { "type": "object", "required": ["city", "temperature_c", "summary"] }
  },
  { "name": "weekly-report" }
]

ワークフローを取得

GET/v1/workflows/{name}

保存済みの定義を返します。インライン接続の認証情報は取り除かれ、URL 内のクエリの値はマスクされます。

ワークフローを編集するには、取得して変更し、PUT で保存し直します。空のままにした認証情報のフィールドは、接続の認証の種類が変わらない限り、保存済みの値が保持されます。

ワークフローを削除

DELETE/v1/workflows/{name}

ワークフローを削除し、204 No Content を返します。すでにそのワークフローを使った実行には影響しません。

ワークフローにはバージョンがありません。保存または削除すると、その名前を指定する次の実行から反映されます。