# 実行とトリガー (/ja/docs/flows/running-and-triggers)

フローは、何かが開始したときに実行されます。あなたが<strong>実行</strong>ボタンで開始するほか、フローをツールとして提供したときはAIエージェント、スケジュール、Webhook、ターミナルやCIでの`echolot flow run`が開始します。何が開始しても、すべてのリクエストはリクエストページから送信する場合と同じ経路を通ります。

## 手動で実行する [#run-by-hand]

1. フローのページでフローを開きます。
2. ツールバーの<strong>実行</strong>をクリックするか、<kbd>⌘</kbd><kbd>R</kbd>を押します。
3. フローに[入力](/docs/flows#inputs-and-outputs)がある場合は、フローの名前が付いた<strong>実行</strong>シートで入力を求められます。各フィールドには入力の名前、型、必須かどうかが表示され、最初からデフォルト値が入っています。デフォルト値を使うフィールドは空のままにして、<strong>実行</strong>をクリックします。

フローが最初に保存されるので、実行にはキャンバス上の内容が使われます。ウインドウのアクティブな[環境](/docs/workspaces/environments)で実行されます。フローにエラーがある間は、<strong>実行</strong>は使えません。ツールチップには「先にフローの問題を修正してください」と表示されます。

[保護された環境](/docs/workspaces/protected-environments)がアクティブなときは、ボタンが<strong>Productionで実行…</strong>（その環境の名前が入ります）と表示され、Echolotは実行を開始する前に1回確認します。実行の中のリクエストでは、再度確認されません。

### 実行ビュー [#the-run-view]

フローの実行中は、ブロックの状態がキャンバスに表示され、その下に<strong>実行</strong>ログが開きます。

| キャンバス上の表示 | 意味 |
| --- | --- |
| アクセントカラーの枠線 | ブロックが実行中、またはあなたの操作を待っています。 |
| 緑の枠線 | ブロックが完了しました。 |
| 赤の枠線 | ブロックが失敗しました。 |

実行ログには、次の内容が順に一覧表示されます。

- 終了した各ブロックと、その時間
- ログブロックの行と、評価ブロック内の`console.log`
- アサートブロックと`pm.test`のテスト結果（ヘッダーに<strong>テスト</strong>の成功数/総数）
- エラー（赤）
- 実行の終わり方: `Finished in 1.2 s`、`Stopped in …`、理由付きの`Failed in …`に当たる表示（アプリでは日本語で表示されます）

行をクリックすると、そのブロックが選択されます。任意のブロックを選択すると、インスペクタにそのブロックの<strong>前回の実行</strong>が表示され、ポートごとの<strong>入力</strong>値と<strong>出力</strong>値を確認できます。<strong>消去</strong>はログとキャンバスの状態を空にします。閉じるボタンでログが隠れ、ツールバーの<strong>実行ログ</strong>でもう一度表示できます。

実行中は、<strong>実行</strong>の代わりに<strong>停止</strong>（<kbd>⌘</kbd><kbd>.</kbd>）が表示されます。これで実行を終了し、送信中のリクエストを閉じ、画面に出ている質問を取り除きます。

実行が失敗し、Macのオンデバイスモデルが利用できる場合は、ログのヘッダーにあるボタンで、ログをもとに失敗の理由を説明してもらえます。

### 以前の実行 [#earlier-runs]

ウインドウには、開いているフローの直近20回の実行が保持されます。スケジュールやWebhookが開始した実行も含まれます。サイドバーの<strong>（フロー名）の実行</strong>（終わり方、開始時刻、かかった時間が付きます）と、ツールバーの<strong>実行</strong>メニューに一覧表示されます。1つクリックすると、ブロックの状態と各ブロックの<strong>前回の実行</strong>がキャンバスに再び表示されます。<strong>実行</strong>メニューの<strong>キャンバスを消去</strong>で、キャンバスから消えます。

実行の記録はウインドウ内にだけ残ります。フローが送信したリクエストは、ほかの送信と同じように、ワークスペースの[履歴](/docs/workspaces/history)に残ります。

## トリガー [#triggers]

<strong>開始</strong>ブロックを選択すると、インスペクタにフローの<strong>トリガー</strong>が表示されます。<strong>「実行」ボタンと`echolot flow run`</strong>は常にオンです。ほかのトリガーは、チェックを入れて追加します。

- <strong>エージェント（MCPツール）</strong>
- <strong>スケジュール</strong>
- <strong>Webhook</strong>

開始ブロックには、オンになっているトリガーごとに小さなアイコンが表示され、サイドバーではフローの名前の下に表示されます。

<Shot id="flows-triggers-start" alt="Order status on webhookの開始ブロックのインスペクタ。トリガーのセクションでWebhookにチェックが入り、メソッドPOSTとパス/order-status、URLをコピーとトークンをコピーが付いたローカルアドレス、許可済みと許可を取り消すが表示されている" />

### トリガーを許可する [#allow-a-trigger]

エージェント、スケジュール、Webhookは、あなたがキャンバスの前にいないときにフローを開始します。そのため、それぞれについて、このフローに対するあなたの許可も必要です。チェックを入れた各トリガーの下で、<strong>許可</strong>をクリックします。トリガーに<strong>許可済み</strong>と<strong>許可を取り消す</strong>ボタンが表示されます。

許可の対象は、現在の状態のフローです。フロー自体、フローが送信するリクエストとその上位のフォルダ、ワークスペースの変数、認証、プロキシ、証明書、フローが実行するフローが含まれます。キャンバス上でも、Gitでも、エージェントによっても、これらのどれかを変更すると、再び許可するまでトリガーは止まります。このとき「許可した後にフローが変更されました。」と表示され、<strong>再び許可</strong>が提示されます。フローが自分自身を許可することはできません。許可は、ワークスペースではなく、あなたのMac上のEcholotに保存されます。エラーのあるフローは、トリガーから開始されることはありません。

環境の値の変更（たとえば新しいトークン）では、許可は取り消されません。

### エージェント: フローをMCPツールにする [#agents-a-flow-as-an-mcp-tool]

フローをAIエージェントに提供すると、EcholotのMCPサーバのツールの1つになります。エージェントは1つのツールを呼び出し、フローがリクエストを行い、シークレットはEcholotの中にとどまります。

1. 開始ブロックを選択し、<strong>エージェント（MCPツール）</strong>にチェックを入れます。
2. <strong>ツール名</strong>は、別の名前を入力しない限り、`flow_`にフローのファイル名をアンダースコアでつないだもの（`flow_place_test_order`）になります。英字、数字、`_`、`-`で64文字以内です。
3. モデルに向けて<strong>ツールの機能</strong>を書きます。最初はフローの説明が入っています。
4. <strong>許可</strong>をクリックします。
5. <strong>設定 › エージェント</strong>をオンにして、クライアントを接続します。[AIエージェント](/docs/ai/agents)を参照してください。

ツールの引数はフローの入力で、結果は出力ブロックが受け取った内容です。<strong>Place a test order</strong>は`place_test_order`として提供されます。フローは、<strong>フロー</strong>ツールセットがオンの間（デフォルトでオン）ツール一覧に表示されます。エージェントが開始できるのは、提供され、許可されたフローだけです。

エージェントがフローを開始するとき、Echolotは実行の前に1回、フローが行う内容をあなたに示して確認します。どのアドレスにどのリクエストを送信するか、どの変数とシークレットを保存するか、どのファイルを書き込むか、どのツールとフローを実行するか、どこで人に確認するか、です。実行の中では、承認した内容は再度確認されずに実行されます。ただし、保護された環境、新しいホスト、削除は引き続き確認され、エージェント自身のルールが拒否するものも同様です。

エージェントが開始したフローの人の操作のブロックは、エージェントのクライアントに届きます。クライアントがメッセージ、コード、リンクを表示するか、値を尋ねます。承認ブロックは常にあなたのものです。エージェントが承認ブロックに答えようとすると、Echolotはまずあなたに確認します。

[アシスタント](/docs/ai/assistant)も、同じ方法でフローを実行します。

### スケジュール [#schedule]

フローを、数分おき、またはカレンダーに従って、自動で実行します。

1. 開始ブロックを選択し、<strong>スケジュール</strong>にチェックを入れます。最初は60分ごとになっています。
2. <strong>間隔</strong>を選んで<strong>間隔</strong> … <strong>分</strong>に入力するか、<strong>時刻を指定（cron）</strong>を選んでcron式（分、時、日、月、曜日）を入力します。スケジュールはどちらか一方で、実行は最大でも1分に1回です。
3. <strong>許可</strong>をクリックします。

許可されると、インスペクタに<strong>次回の実行</strong>とその日時が表示されます。スケジュールされた実行は、ワークスペースのウインドウが開いている間に、実行時点のウインドウのアクティブな環境で行われ、入力のデフォルト値で開始されます。Macがスリープしていた間やウインドウを閉じていた間に実行されなかった分は、Echolotが次に確認したときに1回実行されます。実行中のフローが再び開始されることはありません。スケジュールされた実行が失敗すると、通知が表示されます。アプリなしでスケジュールを実行するには、[`echolot flow serve`](#run-from-the-command-line)を使います。

cron式は5つのフィールドで、Macのタイムゾーンで解釈されます。分（0–59）、時（0–23）、日（1–31）、月（1–12または`jan`–`dec`）、曜日（0–7または`sun`–`sat`。0と7は日曜日）です。各フィールドには、`*`、数値、範囲（`1-5`）、リスト（`1,15`）、ステップ（`*/15`、`8-18/2`）を指定できます。日と曜日の両方を指定した場合は、どちらか一方に一致すれば実行されます。

| cron式 | 実行されるタイミング |
| --- | --- |
| `0 6 * * *` | 毎日6:00（<strong>Morning stock check</strong>）。 |
| `0 7 * * 1-5` | 平日の7:00。 |
| `*/15 8-18 * * *` | 8:00から18:45まで15分ごと。 |
| `0 9 1 * *` | 毎月1日の9:00。 |

スケジュールされた実行では、人の操作のブロックは誰にも確認できないため、失敗します。

### Webhook [#webhook]

ローカルアドレスにリクエストが送られたときに、フローを開始します。

1. 開始ブロックを選択し、<strong>Webhook</strong>にチェックを入れます。
2. メソッド（`GET`、`POST`、`PUT`、`PATCH`、`DELETE`。デフォルトは`POST`）と、`/`で始まるパスを選びます。パスは最初、`/`にフローのファイル名を付けたものになっています。
3. <strong>許可</strong>をクリックします。

許可されると、インスペクタに`POST http://127.0.0.1:52817/order-status`のようなアドレスが、<strong>URLをコピー</strong>と<strong>トークンをコピー</strong>とともに表示されます。Echolotは、ウインドウが開いている間、このMac上（127.0.0.1）だけで待ち受けます。ポートはワークスペースごとに1回選ばれ、そのまま保持されます。

呼び出し元は、ワークスペースのトークンを送る必要があります。トークンはEcholotが初回に作成し、キーチェーンに保存します。次のどれでも使えます。

- ヘッダー`Authorization: Bearer <token>`
- ヘッダー`X-Echolot-Token: <token>`
- クエリパラメータ`?token=<token>`

```sh
curl -X POST http://127.0.0.1:52817/order-status \
  -H "Authorization: Bearer <token>"
```

<strong>Order status on webhook</strong>は、サインインして注文を取得し、その注文を返します。クエリ文字列とJSONボディのキーは、同じ名前のフローの入力を埋めます。それ以外のキーは使われません。`body`という名前の入力には、ボディ全体が入ります。そのため、入力`order`があるフローは、`?order=ord_7Hk2Lw`または`{"order": "ord_7Hk2Lw"}`を受け取れます。実行にはウインドウのアクティブな環境が使われます。

| 応答 | 条件 |
| --- | --- |
| 出力をJSONにした`200` | 実行が成功しました。ボディは出力ブロックが受け取った内容、またはなければ`null`です。 |
| `401` | トークンがないか、間違っています。 |
| `404` | そのメソッドとパスに応答する許可済みのフローがありません。エラーには応答できるものの一覧が入ります。 |
| `413` | ボディが8 MBを超えています。フローは実行されません。 |
| `500` | 実行が失敗しました。ボディに`error`と実行のIDが入ります。 |
| `503` | 実行が停止されました。 |

Webhookの実行は2分で停止します。人の操作のブロックはそこでは誰にも確認できないため、失敗します。

## バックグラウンドでの実行 [#background-runs]

アプリ内でスケジュールやWebhookが開始した実行は、フローを開いている間、フローの<strong>（フロー名）の実行</strong>に表示されます。失敗した実行では、フローの名前とエラーを示すmacOSの通知が表示されます。これらはあなたが開始した実行と同じ権限で実行されますが、対象は許可したフローだけです。

## コマンドラインから実行する [#run-from-the-command-line]

`echolot`コマンドは、アプリなしで同じフローを実行します。CIでは、これによってフローがリリースのゲートになります。

```sh
# フローと、その入力、問題を一覧表示する
echolot flow list -w Alpenglow.echolot

# 1つ実行する。実行またはテストのどれかが失敗するとエラーで終了する
echolot flow run morning-stock-check -w Alpenglow.echolot --env staging --no-input

# 入力をname=valueで渡す（Paginate and exportテンプレートから作ったフロー）
echolot flow run export-products -w Alpenglow.echolot --input pages=5

# スケジュールを実行し、Ctrl-Cまでwebhookに応答する
echolot flow serve -w Alpenglow.echolot --port 4100
```

- `flow run`は、終了した各ブロックを出力し、続けて出力を表示します。`--json`を付けると、代わりに実行の記録を出力します。人の操作のブロックはターミナルで確認します。`--no-input`を付けると実行が失敗します。CIではこれが必要です。通知ブロックはテキストを出力します。
- `flow serve`は、スケジュールされたフローを時刻になると実行し、ポート4100でWebhookに応答します（`--port 0`で空いているポートが選ばれます）。`--share`はすべてのネットワークインターフェースで待ち受けます。コンテナ向けです。トークンは`--token`から、なければ`ECHOLOT_WEBHOOK_TOKEN`から、それもなければ新しく作成されて出力されます。
- コマンドラインでは、実行を自分で開始しているため、フローに<strong>許可</strong>は不要です。`flow serve`は、スケジュールまたはWebhookがあり、エラーのないすべてのフローを実行します。

すべてのオプションは[echolot flow](/docs/cli/flow)にあります。

<Edition only="direct">
  コマンドラインツールは、ダイレクトダウンロード版に含まれています（<strong>Echolot › コマンドラインツールをインストール…</strong>）。
  App Store版では、リリースページのzipから別途インストールします。
</Edition>