ドキュメント
API リファレンスダッシュボードログイン今すぐ始める
ドキュメント
ダッシュボードログイン今すぐ始める

コンセプト

実行

1 つのエージェントを 1 つの使い捨て microVM で動かす、キューから精算までの流れ。

実行とは、1 つのエージェントが専用の microVM の中で 1 つのタスクに取り組むことです。プロンプトと JSON 入力に加えて、使用できるファイルと接続を送信すると、Ephemeral が実行をキューに入れ、新しいマシンを起動し、 すべてのステップを記録して、実行が終わるとマシンを破棄します。

実行の構成要素

すべての実行にはプロンプトがあり、入力は省略できます。それ以外の定義で、使用するモデル、読み取れるもの、呼び出せるもの、かかってよい時間、使ってよい金額が決まります。定義全体をインラインで送ることも、保存済みのワークフローの名前を指定して入力だけを送ることもできます。

POST /v1/runs
{
  "prompt": "Find out why this payment failed. Follow the playbook.",
  "input": { "payment_id": "pay_123" },
  "model": "anthropic/claude-haiku-5.5",
  "files": [{ "file": "playbook.md" }],
  "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
  "timeout_seconds": 120,
  "shell": false,
  "max_cost_micros": 500000
}

microVM の中では、エージェントはマウントされたファイルをいつでも読み取れます。shell がオン (デフォルト) の場合は、シェルコマンドを実行し、作業ディレクトリにファイルを書き込むこともできます。許可した接続ごとに、呼び出せるツールが増えます。Web アクセスがオンの場合は、ページの閲覧、検索、公開 API の呼び出しもできます。マシン自体はインターネットに接続できません。作業ディレクトリはマシンとともに破棄されるため、次の実行には何も引き継がれません。

ライフサイクル

実行は次のステータスを順に移ります。最後の 5 つは最終状態で、実行がいずれかに到達すると、それ以降は変化しません。

ステータス意味
reservingホスト型のみ。実行の予算に相当するクレジットを確保しています。
queuedワーカーの空きを待っています。
startingキューから取り出されました。定義とファイルを読み込んでいます。
runningmicroVM を起動中、またはエージェントが作業中です。
succeededエージェントが完了し、出力を返しました。
failedワーカーが失敗したか、クレジットを確保できませんでした。どちらかは error フィールドで分かります。
cancelled誰かが実行をキャンセルしました。
timed_out完了する前にタイムアウトに達しました。
interrupted実行中にエンジンが再起動した、または受け付け処理が完了しませんでした。

実行は作成された順にキューから取り出されます。セルフホストのインストールでは、デフォルトで同時に 2 件ずつ実行され、残りは queued のまま待機します。タイムアウトは実行がキューを離れた時点から数えるため、待機中の時間は消費されません。

上限

項目値
timeout_seconds1 から 3,600。デフォルトは 300。
プロンプト128 KiB
入力JSON で 1 MiB
ファイル1 実行あたり 32 個、1 個あたり 1 MiB、合計 4 MiB
接続1 実行あたり 16 件
モデル呼び出し1 実行あたり 100 回
モデルの返信 1 回あたりの出力モデル自体の上限 (最大 32,000 トークン)。ただし予算の残りに収まるよう短縮されます。上限で途切れた返信は自動的に続行され、続行は最大 2 回までです。
Web リクエストと検索Web アクセスがオンの場合、1 実行あたり 50 回
出力最大 1 MiB。これより長い回答はそこで切り詰められ、切り詰めたことが実行に記録されます。
イベント記録として保持するのは、1 イベントあたり最大 256 KiB、1 実行あたり 10,000 件または 16 MiB までです。これより大きいツールの結果は、記録上では短縮されて印が付きますが、エージェントには全文が渡されます。記録がいっぱいになると、以降の詳細は保存されず、件数だけが数えられます。どちらの場合も実行が失敗することはありません。
max_cost_micros1 から 100,000,000 (最大 $100)

実行の進行を追跡する

実行の状況と終了を知る方法は 3 つあります。

  • ステータスが最終状態になるまで GET /v1/runs/{id} をポーリングします。
  • GET /v1/runs/{id}/events をストリーミングします。これは Server-Sent Events のストリームで、これまでに記録されたすべてを再生した後、実行が終わるまでリアルタイムに続きます。
  • 実行にコールバックを設定します。実行が最終ステータスに達すると、Ephemeral があなたのサーバーに署名付きのリクエストを送信します。

イベントストリームを閉じても、実行には影響しません。最後に受け取ったイベント ID を指定して再接続すれば、そこから続きを受け取れます。

イベントの種類

種類記録されるタイミング
status実行が running になったとき、または最終ステータスに達したとき。
microvm_startingEphemeral が microVM を要求したとき。
microvm_readymicroVM が起動したとき。
worker_startedエージェントのプロセスが開始したとき。シェルがオンかどうかを含みます。
connection_readyMCP 接続の準備ができたとき。実行が呼び出せるツールを含みます。
tool_startエージェントがツールを呼び出したとき。引数を含みます。
tool_endツール呼び出しが戻ったとき。結果とエラーかどうかを含みます。256 KiB を超える結果はここで短縮され、trimmed_from_bytes が付きます。
text_deltaモデルがテキストをストリーミングしたとき。1 秒に約 10 回、まとめて記録されます。
model_usageモデルの応答が終わったとき。ワーカーが報告したトークン使用量です。請求には使われません。
usageEphemeral がモデル呼び出しのコストを承認または照合したとき。
connectionエンジンが実行の代理として HTTP リクエストまたは MCP ツール呼び出しを行ったとき。
web_requestエンジンがエージェントのために Web リクエストを送信したとき。URL、ステータス、コスト、安全性チェックの結果を含みます。
web_searchエンジンがエージェントのために Web 検索を実行したとき。
web_refusedWeb リクエストまたは検索が、送信前に拒否されたとき。理由を含みます。
resultエージェントが最終出力を返したとき。実行の output フィールドにはすべてが入っており、このイベントは短縮されることがあります。
model_call_refusedモデル呼び出しが拒否されたとき。たとえば、最悪の場合のコストが予算の残りを超える場合です。理由を含みます。
output_limit返信がモデルの出力上限に達し、エージェントに続行が求められたとき。
output_truncated最終出力が 1 MiB を超え、そこで切り詰められたとき。
events_skipped実行の記録がいっぱいになり、以降のイベントが保存されなかったとき。保存されなかった件数を含みます。
worker_errorワーカーがエラーで停止したとき。
microvm_terminatedmicroVM が破棄されたことが確認されたとき。
microvm_cleanup_pending終了をまだ確認できず、再試行されるとき。
doneストリームの最後のメッセージ。最終的な実行オブジェクトを含みます。

Ephemeral は、接続トークンなど既知の認証情報の値を、イベントと出力から削除したうえで保存します。ストリームの正確な形式は、API リファレンスで確認できます。

実行をキャンセルする

POST /v1/runs/{id}/cancel は、reserving、queued、starting、running のいずれかの実行を停止します。ワーカーが停止し、microVM が終了します。すでに終了した実行をキャンセルしても、何も変わりません。

キャンセルしても外部での操作は取り消せません
エージェントがすでに、返金の実行など何かを変更する API を呼び出していた場合、実行をキャンセルしてもその操作は元に戻りません。失敗、タイムアウト、中断した実行でも同様です。Ephemeral が実行を自動的に再試行することはないため、副作用が繰り返されることもありません。

ゼロデータ保持

機密性の高いタスクでは、実行または保存済みワークフローで zero_data_retention を true に設定します。すると Ephemeral は実行の内容を一切記録せず、受け取れるのは出力のみになります。

保持するもの保持しないもの
実行 ID、組織、ステータス、タイムスタンプ、スケジュール、コストと使用量の数値、ワーカーのテキストを含まない一般的なエラー分類。イベント、配信後の出力、ワーカーのエラーテキスト、実行の定義（プロンプト、入力、ファイル一覧、接続の参照）。実行の定義は取得も再実行もできません。
  • 実行中は、どのエンジンでも GET /v1/runs/{id}/events でイベントを引き続きストリーミングできます。イベントは一時的な保管領域に置かれ、実行の終了から数分後に削除されます。
  • 出力は一度だけ返されます。実行の終了後、最初の GET /v1/runs/{id} が出力を返し、同時に削除します。コールバックがある場合は、コールバックが出力を配信するまで読み取っても削除されません。いずれの場合も、遅くとも 1 時間後に削除されます。出力がまだ保持されているかは output_available と output_expires_at で確認できます。
  • モデル呼び出しは、データを保持せず学習にも利用しないプロバイダーにのみ送られます。そのようなプロバイダーがないモデルは、何かを確保する前に 400 で拒否されます。
  • ホスト型サービスでは実行のコストが 10% 増えます。追加料金はコンピュート、モデル呼び出し、Web リクエストに適用され、予算に含まれ、コストの内訳に表示されます。セルフホストでは追加料金はかかりません。
  • 一時的なデータはすべてのバックアップから除外されるテーブルに置かれるため、復元したデータベースにも含まれません。

実行後

実行には、出力、エラーメッセージ、タイムスタンプ、イベント、コストが保持されます。ステータスが最終状態で、かつ billing_pending が false になれば、コストは確定です。詳しくは予算と請求をご覧ください。

終了した実行は、終了から 30 日後にイベントとともに削除されます。請求、コールバックの配信、microVM のクリーンアップのいずれかが未完了の間は、それより長く保持されます。セルフホストのインストールでは、保持期間を変更できます。

同じタスクをもう一度実行するには、GET /v1/runs/{id}/definition を取得します。認証情報を除いた、実行が実際に使った定義が返されるので、内容を確認し、新しい予算を設定して送信できます。

実行の定義には、送信したプロンプト、入力、インラインのファイル内容が保持されます。これらにシークレットを含めないでください。代わりに、保存済みの接続を使用してください。
© 2026 Ephemeral制作: erni.works
esc

「」に一致する項目はありません。