Echolotブロック
フローに置けるすべての種類のブロックを、設定とポートとともに説明します。ブロック間で受け渡される値、テンプレート、条件の仕組みも扱います。
各ブロックは1つのことを行います。設定はブロックを選択したときにインスペクタに表示され、ポートはキャンバス上にあります（入力は左、出力は右）。このページでは、ブロックピッカーと同じグループ分けで、すべての種類を順に説明します。そのあとで、ブロック間を流れる値、{{body.id}}のようなテンプレート、条件を説明します。
実行の流れ
- ブロックは、接続が入っているすべての入力に値が届くと実行されます。実行後は、いくつかの出力から値を送り出し、それらの出力に接続されたブロックだけが次に実行されます。
- 最初に実行されるのは開始ブロックです。何も接続されていない値ブロックと変数を取得ブロックも、開始時に実行されます。
- ブロックは、可能なら並行して実行されます。表示して待機ブロックがあなたの操作を待っている間も、ポーリングブロックは動き続けられます。
- 失敗する可能性があるブロックがいくつかあります。リクエスト、ポーリング、ツール、フロー、評価、ファイルに書き込むには
fail出力があります。これが接続されていると、失敗はそこから出て、実行は続きます。接続されていないと、実行全体がそのブロックで失敗します。 - 実行中のものが何もなくなると、実行は終了します。
どのブロックのインスペクタにもタイトル（ブロックに表示されます。空のときは種類の名前）と一時停止中（値はそのまま通過します）があります。一時停止したブロックは薄く表示されてスキップされ、入ってきた値は最初の出力からそのまま出ていきます。
トリガー
開始
実行が始まる場所です。実行ボタン、エージェント（フローがツールのとき）、スケジュール、Webhook、echolot flow runのいずれかから始まります。インスペクタには、フローのトリガーがあります。実行とトリガーを参照してください。
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 出力 | フローのすべての入力を1つのオブジェクトにしたもの。 |
| 入力ごとに1つ | 出力 | その入力の値。 |
フローにある開始ブロックはちょうど1つです。ブロックピッカーには表示されません。
出力
実行が返す内容です。返す先は、フローを呼び出したエージェント、コマンドライン、Webhookの呼び出し元、または親フローです。1つのフローに最大1つです。
| ポート | 向き | 運ぶ値 |
|---|---|---|
value | 入力 | 結果。 |
アクション
リクエスト
ワークスペースの保存済みリクエスト（HTTP、GraphQL、MCPリクエスト）を、その認証、スクリプト、チェック、実行の環境とともに送信します。
| 設定 | 内容 |
|---|---|
| リクエスト | 保存済みリクエストを一覧から選びます（必須）。 |
| 変数 | 名前をカンマで区切って指定します。それぞれがリクエストの{{variable}}を埋める入力になります。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
send | 入力 | リクエストを送信します。オブジェクトが届くと、そのキーがそれぞれこの送信の変数になります。 |
| 変数の名前ごとに1つ | 入力 | その変数の値。 |
success | 出力 | リクエストが成功したときのレスポンス。 |
fail | 出力 | 2xx以外で応答した、またはチェックに失敗したときはレスポンス。何も返ってこなかったときはエラー。 |
リクエストは、2xxで応答し、チェック、スクリプトのテスト、スクリプトがすべて成功したときに成功します。これはランナーと同じです。フローが渡した変数は、その送信に限り、環境の変数より優先されます。
フローPlace a test orderでは、Sign inのsuccess出力がCreate orderのsendに接続されています。注文はサインインが成功した後でのみ行われ、Sign inがキャプチャしたトークンはすでに{{token}}に入っています。
ツール
モックの起動、フォルダの実行、仕様のリント、MCPサーバのツールの呼び出しなど、Echolot自身のツールを1つ実行します。ルールはエージェントの場合と同じです。
| 設定 | 内容 |
|---|---|
| ツール | ツールを一覧から選びます（必須）。 |
| 引数 | ツールの引数をJSONで指定します（{ "name": "{{value}}" }など）。テキストの値にはテンプレートを使えます。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | ツールを実行します。オブジェクトが届くと、そのキーが引数に追加されます。 |
result | 出力 | ツールが返した内容。 |
fail | 出力 | 失敗した理由。 |
ツールブロックから別のフローは実行できません。その場合はフローブロックを使います。
直接ダウンロード版のみ
ローカルのプログラム（stdio）として動くMCPサーバを呼び出すツールブロックは、ダイレクトダウンロード版で使えます。 App Store版ではEcholotがそのプログラムを起動できないため、ブロックに警告が表示され、実行すると失敗します。
エディションを比較フロー
ワークスペースの別のフローを実行し、その出力ブロックが受け取った内容を送ります。
| 設定 | 内容 |
|---|---|
| フロー | 実行する別のフロー（必須）。フローは自分自身を実行できず、フロー同士が循環して実行し合うこともできません。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
input | 入力 | 別のフローの入力を持つオブジェクト。 |
output | 出力 | 別のフローが返した内容。 |
fail | 出力 | 別のフローが失敗した理由。 |
フローが互いに呼び出せるのは、最大8階層までです。シークレットは値としてはフロー間で渡されません。代わりに変数として保存してください。
人の操作
人の操作のブロックは、実行を一時停止してあなたに確認します。アプリではシートが開きます。エージェントが開始した場合は、質問がエージェントのクライアントに届きます。コマンドラインでは、ターミナルで質問されます。スケジュールやWebhookが開始した実行には確認できる相手がいないため、人の操作のブロックはそこで失敗します。echolot flow run --no-inputでも同様です。
確認
小さなフォームで値を尋ねます。
| 設定 | 内容 |
|---|---|
| メッセージ | 尋ねる内容。テンプレートを使えます。 |
| フィールド | フォームのフィールド（必須）。それぞれに、name（ポートとキー）、横に表示されるlabel、type（text、number、bool、secret、choice）、選択肢の場合はカンマ区切りのchoices、defaultがあります。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | 尋ねます。オブジェクトはメッセージのテンプレートを埋めます。 |
answers | 出力 | すべての回答を1つのオブジェクトにしたもの。 |
| フィールドごとに1つ | 出力 | そのフィールドの回答。 |
cancelled | 出力 | ユーザーがキャンセルをクリックしたときはtrue。 |
シートにはキャンセルと続けるがあります。secretフィールドの回答は、実行ログでは隠されます。
表示して待機
メッセージ、コピー用のコード、開くリンクを表示し、続けるが押されるか、untilに値が届くまで待ちます。デバイスでのサインインに使います。ポーリングブロックが承認を待つ間、コードを表示します。
| 設定 | 内容 |
|---|---|
| タイトル | シートのタイトル。 |
| メッセージ | 表示する内容（必須）。 |
| コード | 大きく表示され、コードをコピーが付きます（デバイスコード）。 |
| リンク | ブラウザで開くが付いて表示されます。 |
| QRコード | リンクをQRコードでも表示します。 デフォルトではオフです。 |
5つすべてでテンプレートを使えます。
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | シートを表示します。オブジェクトはテンプレートを埋めます。 |
until | 入力 | ポーリングブロックのsuccessなど、値が届くと自動的に続行します。 |
done | 出力 | runに入ってきた内容。 |
untilが接続されていると、シートに完了すると自動的に続行します。と表示されます。待機を停止を押すとシートが閉じ、ブロックは失敗します。
承認
元に戻せないことを行う前など、フローを続ける前にあなたの承認を求めます。
| 設定 | 内容 |
|---|---|
| メッセージ | 質問（必須）。テンプレートを使えます。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | 尋ねます。オブジェクトはメッセージのテンプレートを埋めます。 |
approved | 出力 | 承認した後に、runに入ってきた内容。 |
declined | 出力 | 拒否した後に、runに入ってきた内容。 |
承認は、常に人が行うものです。エージェントがフローを実行して承認ブロックに答えようとする場合も、Echolotはまずあなたに質問します。Place a test orderでは、承認ブロックKeep the order?が、ショップが作成したばかりの注文についてKeep order {{body.id}} for CHF {{body.total.amount}}?と尋ねます。拒否すると、Cancel orderに進みます。
ロジック
条件分岐
入ってきた値を、条件によってtrueまたはfalseに送ります。
| 設定 | 内容 |
|---|---|
| 条件 | value.status == 200のようなJavaScriptの式（必須）。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
value | 入力 | 判定する値。 |
true、false | 出力 | 同じ値が、2つのうちどちらかから出ます。 |
Morning stock checkでは、ショップが返した商品に対して、条件分岐ブロックRunning low?がvalue.body.items.some(p => p.stock.bern < 5)を使っています。
場合分け
入ってきた値を、条件が成り立つ最初のケースに送ります。どれも成り立たなければdefaultに送ります。
| 設定 | 内容 |
|---|---|
| ケース | リスト（必須）。各ケースには、name（出力ポート）とconditionがあります。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
value | 入力 | 判定する値。 |
| ケースごとに1つ | 出力 | そのケースが最初に成り立ったときの値。 |
default | 出力 | どのケースも成り立たなかったときの値。 |
評価
入ってきた値に対してJavaScriptを実行します。最後の式が結果になります（({ id: value.body.id })やa + bなど）。独自にreturnを持つコードは関数の本体として実行され、returnが返す値が結果になります。Promiseは待機されます。pm.testとpm.expectはスクリプトと同じように使え、その結果は実行のテストとして数えられます。console.logの行は実行ログに出ます。
| 設定 | 内容 |
|---|---|
| コード | JavaScript（必須）。 |
| 入力 | 入力名をカンマで区切って指定します。それぞれがコード内の変数になります。空のときはvalueです。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
| 入力の名前ごとに1つ | 入力 | その変数の値。 |
result | 出力 | 結果。 |
fail | 出力 | コードが例外を投げたときのエラー。 |
// 入力: pages。収集ブロックが集めたリストを1つにつなげます。
return pages.flat();遅延
待機してから、値をそのまま渡します。
| 設定 | 内容 |
|---|---|
| ミリ秒 | 待機する時間（必須）。数値、または{{wait}}のようなテンプレート。 |
ポート: valueが入力、valueが出力。
ループ
繰り返す
回数の分だけ、0から数えたindexを送り、最後にdoneを送ります。
| 設定 | 内容 |
|---|---|
| 回数 | 繰り返す回数（必須）。0から100,000まで。数値、または{{pages}}のようなテンプレート。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | ループを開始します。 |
index | 出力 | 1回ごとに0、1、2…。 |
done | 出力 | 最後の回が終わった後に、runに入ってきた内容。 |
各項目を繰り返す
リストの各項目を順に送り、最後にdoneを送ります。設定はありません。
| ポート | 向き | 運ぶ値 |
|---|---|---|
list | 入力 | リスト。それ以外が届くと、ブロックは失敗します。 |
item | 出力 | 1回につき1項目。 |
index | 出力 | 項目の位置（0から数えます）。 |
done | 出力 | 最後の回が終わった後の、リスト全体。 |
収集
ループ中に届いた値を1つのリストにまとめ、ループが終わったときに送ります。設定はありません。
| ポート | 向き | 運ぶ値 |
|---|---|---|
item | 入力 | 1回につき1つの値。 |
list | 出力 | 集めたすべての値。属しているループが終わったときに出ます。 |
ループの各回は、前の回が終わってから始まり、その回で到達したブロックは毎回実行し直されます。開始ブロックの入力のようにループの外にある値は、どの回でも使えます。
ポーリング
条件が成り立つ（サインインが承認された、ジョブが完了したなど）か、期限が過ぎるまで、保存済みリクエストを繰り返し送信します。
| 設定 | 内容 |
|---|---|
| リクエスト | 保存済みリクエスト（必須）。 |
| 変数 | 名前をカンマで区切って指定します。それぞれが{{variable}}を埋める入力になります。 |
| 終了条件 | 直近のレスポンスであるresponseに対する条件。デフォルト: response.status >= 200 && response.status < 300。 |
| 間隔 | 送信の間隔（秒）。デフォルトは5。数値またはテンプレート。 |
| 期限 | あきらめるまでの秒数。デフォルトは300。数値またはテンプレート。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
send | 入力 | ポーリングを開始します。オブジェクトが届くと、そのキーが変数になります。 |
| 変数の名前ごとに1つ | 入力 | その変数の値。 |
success | 出力 | 条件を満たしたレスポンス。 |
timeout | 出力 | 期限が過ぎたときの、直近のレスポンス。timeoutが接続されていないと、代わりにブロックが失敗します。 |
fail | 出力 | 送信が失敗したときのエラー。 |
リクエストと違い、2xx以外のレスポンスでもポーリングは失敗しません。終了条件が成り立つまで、再び送信します。
データ
値
固定の値です。テキスト、数値、trueまたはfalse、リスト、オブジェクトが使えます。
| 設定 | 内容 |
|---|---|
| 値 | テキスト、数値、またはJSON（必須）。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | 何かが届くたびに、値を再び送ります。 |
value | 出力 | その値。runに何も接続されていないと、開始時に1回送られます。 |
テンプレート
届いたオブジェクトと実行の変数で{{name}}を埋めたテキストです。
| 設定 | 内容 |
|---|---|
| テキスト | テンプレートを含むテキスト（必須）。 |
ポート: valuesが入力（オブジェクト）、textが出力。
抽出
入ってきた値からパスで値を取り出し、1つずつ別の出力に送ります。
| 設定 | 内容 |
|---|---|
| フィールド | リスト（必須）。各フィールドには、name（出力ポート）と、$.body.user_codeのようなpathがあります。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
value | 入力 | 取り出す元の値。多くの場合はレスポンス。 |
| フィールドごとに1つ | 出力 | そのパスにある値。何もなければnull。 |
all | 出力 | すべてのフィールドを1つのオブジェクトにしたもの。 |
パスは、JSONPathの共通部分です。
| パス | 取り出すもの |
|---|---|
$.body.items[0].sku | キーを取り出し、続けてリストの最初の項目。 |
$.body.items[-1] | 最後の項目。 |
$.body.items[*].sku | すべての項目のskuをリストにしたもの。 |
$['content-type'] | ドットでは指定できない文字を含むキー。 |
body.id | $がなければ、パスは値の先頭から始まります。 |
変数を設定
値を変数として保存し、後のブロックやリクエストが{{name}}で読めるようにします。
| 設定 | 内容 |
|---|---|
| 変数 | リスト（必須）。それぞれに、name、入ってきた値の中のpath（空のときは全体）、scope、secretがあります。 |
| スコープ | 値の保存先 |
|---|---|
run | この実行と、それが送信するリクエストのみ。 |
environment | アクティブな環境（デフォルト）。環境が選ばれていないと、実行はここで失敗します。 |
workspace | ワークスペース自身の変数。 |
global | フローからは書き込めません。実行が失敗し、環境かワークスペースに保存するよう促されます。 |
secretをオンにすると、値はファイルではなくキーチェーンに保存され、その前のブロックから出た時点から、実行ログとエージェントに見える内容では隠されます。pathで何も見つからないときは、変数は古い値のままです。そのため、新しいリフレッシュトークンを含まないトークンのレスポンスが、すでに持っているリフレッシュトークンを消すことはありません。シークレットを参照してください。
ポート: valueが入力、valueが出力（入ってきた値をそのまま渡します）。
変数を取得
リクエストから見えるとおりに変数を読み取ります。実行自身の変数、次に環境、ワークスペース、グローバルの変数の順です。
| 設定 | 内容 |
|---|---|
| 名前 | 変数（必須）。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
run | 入力 | 何かが届くたびに、再び読み取ります。 |
value | 出力 | その値。なければnull。runに何も接続されていないと、開始時に1回読み取られます。 |
出力
表示
入ってきた値をそのまま渡し、確認できるようにします。実行後にこのブロックを選択して、インスペクタの前回の実行を読んでください。
| 設定 | 内容 |
|---|---|
| フォーマット | auto、text、json、table、image。デフォルトはauto。 |
ポート: valueが入力、valueが出力。
ログ
実行ログに1行書き込みます。
| 設定 | 内容 |
|---|---|
| メッセージ | 書き込む行。テンプレートを使えます。{{value}}は入ってきた値で、メッセージが空のときは値全体です。 |
ポート: valueが入力、valueが出力。Place a test orderでは、注文できなかったときにOrder failedがCreate order answered {{status}}をログに書きます。
アサート
入ってきた値をチェックします。各チェックは実行のテスト結果になり、失敗したチェックがあるとecholot flow runは失敗します。
| 設定 | 内容 |
|---|---|
| チェック | リスト（必須）。各チェックには、nameと、valueに対するconditionがあります。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
value | 入力 | チェックする値。 |
passed | 出力 | すべてのチェックが成り立ったときの値。 |
failed | 出力 | いずれかのチェックが失敗したときの値。 |
value.status === 200 // 200で応答する
value.time < 2000 // 2秒以内通知
Echolotからの通知をmacOSで表示します。初回はmacOSが許可を求めます。コマンドラインでは、通知の代わりに内容が出力されます。
| 設定 | 内容 |
|---|---|
| タイトル | 通知のタイトル（必須）。テンプレートを使えます。 |
| メッセージ | 通知の本文。テンプレートを使えます。 |
ポート: valueが入力、valueが出力。Morning stock checkは、タイトルがRestock Bernの通知ブロックRestockで終わります。
ファイルに書き込む
入ってきた値を、ワークスペースフォルダ内のファイルに書き込みます。
| 設定 | 内容 |
|---|---|
| パス | ワークスペースフォルダからの相対パス（exports/items.jsonなど、必須）。テンプレートを使えます。 |
| フォーマット | json（整形あり）、text、csv。デフォルトはjson。 |
| ポート | 向き | 運ぶ値 |
|---|---|---|
value | 入力 | 書き込む内容。 |
path | 出力 | ファイルのパス（ワークスペースからの相対パス）。 |
fail | 出力 | 書き込めなかった理由。 |
すでにあるファイルは置き換えられます。ワークスペース自身のファイルは書き込み禁止です。requests、flows、environments、mocks、mcp-servers、specsフォルダ、workspace.toml、隠しファイルが該当します。CSVでは、オブジェクトのリストはオブジェクト1つにつき1行、キー1つにつき1列になり、それ以外は1行に1つの値で書き込まれます。
ブロック間の値
値はJSONです。テキスト、数値、trueとfalse、リスト、オブジェクト、nullのいずれかです。
レスポンスオブジェクト
リクエストとポーリングは、レスポンスをオブジェクトとして送ります。
{
"status": 201,
"reason": "Created",
"headers": { "content-type": "application/json", "location": "/v1/orders/ord_9Px3Kd" },
"body": { "id": "ord_9Px3Kd", "total": { "amount": 449, "currency": "CHF" } },
"time": 182.4,
"url": "https://demo.echolot.dev/v1/orders"
}bodyは、レスポンスがJSONのときは解析済みのJSON、それ以外はテキスト、空のときはnullです。- ヘッダー名は小文字です。複数回送られたヘッダーは
,で連結されます。 timeは、やり取り全体にかかった時間（ミリ秒）です。- 8 MBを超えるボディは
nullになり、"truncated": trueが付きます。完全なレスポンスは履歴に残っています。
テンプレート
「テンプレートを使えます」と書かれた設定では、ブロックに入ってきた値から{{name}}が埋められます。
{{status}}、{{body.id}}、{{body.items[0].sku}}: 入ってきたオブジェクトのキー、またはそこへのパス。- ログ、通知、ファイルに書き込むでの
{{value}}: 入ってきた値全体。 - 変数を設定ブロックがスコープ
runで保存した変数。
どれにも一致しない名前はそのまま残るので、リクエストブロック自身の{{variables}}は、送信するときに環境から解決されます。オブジェクトとリストはJSONテキストとして書き込まれます。
条件
条件分岐、場合分け、ポーリング、アサートは、真偽が決まるJavaScriptの式を受け取ります。valueは入ってきた値です。ポーリングの終了条件では、これをresponseとして読みます。どこでも使えます。
value.status == 200
response.status === 200 && !!(response.body && response.body.access_token)
value.body.items.length > 0例外を投げる式は、ブロックを失敗させます（アサートでは、そのチェックが失敗します）。
上限
間違った接続で実行が止まらなくなることがないよう、実行は、ブロックの実行が10,000回に達するか、1時間たつと停止します。Webhookが開始した実行は、2分で停止します。