debug-flow

失敗したフロー実行をデバッグする

Power Automate の失敗したフロー実行のデバッグをユーザーに支援します。

ツール

このスキルでは、FlowAgent MCP ツールを使用します。クライアントによって、ツールには固有のプレフィックス（mcp__flowagent__<tool>（Claude Code）または flowagent-<tool>（Copilot CLI））が付与されるため、以下ではプレフィックスを省略した名前で参照します （例：get_run_actions）。CLI のみの操作、または MCP ツールがない場合は、CLI シェルコマンド（ローカルエンジンのビルドのみ）を使用してください。

ツール	目的
list_flows	名前でフローを検索します（検索には name パラメーターを使用）
get_run_history	フローの最近の実行履歴を取得します
diagnose_run	1 回の操作で、失敗したアクションを分類して修正方法を提示します
get_run_details	特定の実行の詳細を取得します
get_run_actions	アクションレベルの実行トレースを取得します
get_run_action_content	1 つのアクションについて、記録された入力または出力を範囲を指定して取得します
get_run_action_repetitions	ループの反復レベルの詳細を取得します（失敗した反復を特定するには、ループ内のアクションを指定します）
get_flow	コンテキストとしてフロー定義を取得します
get_operation_details	正しいアクションの種類とパラメーターを確認します
edit_flow	1 つのアクションまたはパラメーターに対して、必要最小限の修正を適用します
update_flow	定義全体を置き換えます（大規模な書き換え）
run_flow	修正後に再実行します（結果を確認するには wait: true を指定）
resubmit_run / cancel_run	修正した実行を再送信する／停止状態の実行をキャンセルする

手順

1. フローを特定して実行を確認する

   • $ARGUMENTS を解析して、フロー ID と任意の実行 ID を取得します。
   • フロー ID が指定されていない場合は、name パラメーターを指定して list_flows を呼び出し、検索します。候補が複数ある場合は、ユーザーに選んでもらいます。
   • 実行 ID が指定されていない場合は、get_run_history を呼び出し、直近で失敗した実行を探します。
   • 最近の実行を次の表にまとめて提示します：実行 ID | ステータス | 開始時刻 | エラー

2. diagnose_run で迅速にトリアージする

   • 対象の実行に対して diagnose_run を呼び出します。失敗またはタイムアウトしたアクションがすでに分類され、それぞれに修正案が提示されます。これを分析の出発点にします。
   • 詳細に分析する場合は、get_run_actions（完全なトレース）と get_flow（定義のコンテキスト）も並行して取得します。失敗したループについては、ループ内のアクションに対して get_run_action_repetitions を呼び出し、失敗した反復を特定します。
   • 反復結果は { action, count, truncated, repetitions } です。count は返された件数であり、合計件数ではありません。truncated が true の場合、返された一部の結果だけから該当する反復がないとは判断しないでください。
   • 記録されたペイロードが必要な場合は、includeSizes: true を指定して get_run_actions を使い、その後、アクション名と which: "inputs" または "outputs" を指定して get_run_action_content を呼び出します。デフォルトのダウンロード上限は 256000 バイトです。上限を超える結果は、内容をそのまま出力せずに報告されます。診断に必要な内容だけを取得し、レポートに機密性の高いペイロードを再掲しないでください。

3. 失敗を分析する

   • ステータスが Succeeded 以外のアクションを特定します。
   • runAfter の依存関係をたどり、根本原因と連鎖的な失敗を切り分けます。
     • 根本原因：すべての依存先が Succeeded だったにもかかわらず失敗したアクション
     • 連鎖的な失敗：依存先の失敗によりスキップされたアクション
   • 根本原因となるアクションについて、名前、種類、エラーコード、エラーメッセージを報告します。

4. 根本原因を分類する

   • 接続エラー（AuthorizationFailed、ConnectionNotFound、InvokerConnectionOverrideFailed）：再認証するか、接続元を Embedded に修正するよう提案します。
   • 式のエラー（ExpressionEvaluationFailed、InvalidTemplate）：式を示し、問題点を説明して、修正を提案します。
   • API／外部エラー（401／403／404／429／500 以上）：HTTP エラーを説明し、コネクタのステータスを確認します。
   • パラメーターエラー（WorkflowOperationParametersRuntimeMissingValue）：必須パラメーターがないか空です。null ガードを追加します：@if(empty(...), 'default', ...)
   • タイムアウト（ActionTimedOut）：再試行ポリシーを設定するか、処理を分割するよう提案します。
   • 型の不一致（InvalidOpenApiConnectionOperationType）：アクションの種類が間違っています。正しい種類を確認するために get_operation_details を呼び出します。

5. 修正を提案する

   • コードまたは式の変更を含む、具体的な修正方法を提示します。
   • 定義の変更が必要な場合は、edit_flow で対象を絞って（1 つのアクションまたはパラメーターだけ）変更することを提案します。大規模な書き換えの場合に限り、代わりに update_flow を使います。

6. 再テストする

   • 修正が機能することを確認するため、wait: true を指定して run_flow を呼び出すか、元の実行のトリガー入力で再試行するために resubmit_run を呼び出すことを提案します。
   • 結果をアクションの詳細とともに報告します：Succeeded／Failed。

出力形式

診断の概要

• フロー：[名前]（[ID]）
• 実行：[実行 ID] | [開始時刻] | ステータス：[ステータス]

失敗したアクション

#	アクション	ステータス	エラーコード	エラーメッセージ

根本原因

[分類]：[説明]

修正

[コードを含む段階的な修正手順]