setup

初回セットアップガイド

技術に詳しくないユーザーが、Power Automate プラグインを初めて使えるようサポートします。親しみやすく、わかりやすい言葉で説明し、ターミナルコマンドを知っていることを前提にしないでください。各手順を一つずつ案内してください。

Step 1: Node.js を確認する

サイレントに実行します：

node --version 2>&1

• 成功した場合（v18.x.x 以上のように表示される場合）：「Node.js はインストールされています」と伝えて次に進みます。
• 失敗した場合、またはバージョンが 18 未満の場合：Node.js 18 以降が必要だと伝えます。使用しているオペレーティングシステムを尋ね、最も簡単なインストール手順を案内します：
  • Windows：「https://nodejs.org にアクセスし、LTS バージョンをダウンロードして、インストーラーを実行してください。すべての画面で［次へ］をクリックしてください。」
  • Mac：「ターミナルを開いて、brew install node を実行してください」（または nodejs.org を案内します）
  • インストール後、node --version で再確認します。

Step 2: Azure CLI を確認する

サイレントに実行します：

az --version 2>&1

• 成功した場合：「Azure CLI はインストールされています」と伝えて次に進みます。
• 失敗した場合：Azure CLI が必要だと伝えます。使用している OS を尋ねます：
  • Windows：「管理者として PowerShell を開き、winget install Microsoft.AzureCLI を実行してください。」または https://aka.ms/installazurecliwindows を案内します。
  • Mac：「brew install azure-cli」
  • インストール後、az --version で再確認します。

ステップ 3：Azure へのログイン

すでにログインしているか確認します。

az account show --output json 2>&1

• 成功した場合（アカウント情報が表示される場合）：ログイン中のアカウント（user.name フィールド）を伝え、そのアカウントでよいか確認します。
• 失敗した場合：「Azure にログインしましょう」と伝えます。その後、次を実行します。

  az login
  

  ブラウザーが開きます。次のように伝えます。「ブラウザーウィンドウが開きます。Power Automate で使用している職場アカウントでサインインしてください。」 ログインが完了したら、もう一度 az account show を実行して成功したことを確認します。

トークンへのアクセスを確認 — 早い段階で権限の問題を検出できます。

まず、使用している Azure クラウドを確認します。Power Automate のリソース URL はクラウドによって異なり、商用環境の URL を前提にはできないためです（GCC High／DoD テナントではその URL へのアクセスに失敗します）。

az cloud show --query name -o tsv

az cloud show	Power Automate リソース
AzureCloud（商用）	https://service.flow.microsoft.com
AzureCloud + GCC テナント	https://gov.service.flow.microsoft.us
AzureUSGovernment（GCC High）	https://high.service.flow.microsoft.us
AzureUSGovernment（DoD）	オペレーターが確認した PA_FLOW_RESOURCE の値が必要です。組み込みの対象リソースはありません

az cloud show では、商用環境と GCC、または GCC High と DoD を区別できません。 これらの場合は、PA_CLOUD=gcc／PA_CLOUD=dod を明示的に設定してください。

DoD エンドポイントのホスト名には appsplatform.us が使用されますが、これによってトークンの対象（App ID URI）が特定されるわけではありません。PA_CLOUD=dod の場合、FlowAgent にはオペレーターが確認した PA_FLOW_RESOURCE の明示的な指定が必要であり、そうでなければ設定に失敗します。ホスト名から推測した対象をコピーしないでください。テナントに適した値を入手してください。

次に、一致するリソースのトークンを要求します。たとえば、商用環境の場合は次のとおりです。

az account get-access-token --resource https://service.flow.microsoft.com --output json 2>&1

FlowAgent も同じ方法でクラウドを自動検出します。PA_CLOUD=commercial|gcc|gcchigh|dod を指定して検出結果を上書きできます。

• 成功した場合：次に進みます。
• 「AADSTS65002」で失敗した場合（GCC High でよく発生します）：そのクラウドでは、Azure CLI アプリが Power Automate リソースに事前承認されていません。これはライセンスの問題ではありません。委任された Power Automate（Flow サービス）の権限を持つパブリッククライアントアプリを登録し、PA_CLIENT_ID=<app-id> を設定してください。以降、フローコマンドではそのアプリが使用されます。
• その他の「AADSTS」エラーで失敗した場合：ユーザーのアカウントには Power Automate へのアクセス権がない可能性があります。次のように伝えてください。「Azure アカウントでは Power Automate にアクセスできないようです。Power Automate のライセンスが付与されているか、IT 管理者に確認してください。」
• その他のエラーで失敗した場合：エラーを表示し、IT サポートへの問い合わせを勧めます。
• ソブリンクラウドを使用していて、接続管理コマンドが失敗した場合：元のエラーを保持し、そのコードを確認します。AADSTS650057 は、リソースが無効であるか、アプリの承認が不足している可能性を示します。AADSTS65001 の場合は、管理者の同意が必要なことがあります。アプリが見つからないエラーや同意に関するエラーには、適切な権限を持つパブリッククライアントの登録と PA_CLIENT_ID=<app-id> が必要な場合があります。ネットワーク、テナントの選択、セッションの有効期限切れには、それぞれ異なる対処が必要です。クラウド名だけから事前承認の不足を推測したり、その他すべてのコードを無関係なものと判断したりしないでください。

特定のアカウントでサインインする

接続管理は az とは別に認証されます。独自のディスク上のトークンキャッシュを使う独自の MSAL セッションを使用するため、az login／az account set を実行しても、接続管理で使用するアカウントは切り替わりません。

このためのツールは 3 つあります。

ツール	用途
list_accounts	キャッシュされたアカウントの一覧、effectiveConnectivityIdentity、nextSignIn の設定を確認します。非アクティブなテナントのキャッシュは、ID の不一致には該当しません。トークンは取得しません。
switch_account	優先する username を保存します。省略すると、設定をクリアします。preferencePersisted と nextSignIn を確認してください。環境変数によるオーバーライドは引き続き適用されます。
whoami／doctor	Connectivity の有効なユーザー名とテナントを Azure CLI と比較します。同じテナント内の異なるユーザーも比較対象です。

接続ツールが ServiceToServiceEnvironmentNotFound で失敗した場合は、環境が存在しないと判断する前に ID を確認してください。list_accounts は、有効なアカウントと過去にキャッシュされたアカウントを区別します。有効なアカウントのユーザー名またはテナントが異なる場合は不一致を示しますが、使用されていないテナントのキャッシュだけでは不一致とはなりません。switch_account はキャッシュされたサインインをクリアし、再認証に使用する優先ユーザー名を記録します。後続のサインインが成功したことや、環境に対する権限が正しいことを証明するものではありません。

switch_account は Azure CLI の ID を変更しません。az の設定は自分で行ってください。両者が異なる場合、ツールは一方を暗黙に切り替えるのではなく、その旨を通知します。reconnect は記録された優先設定を維持します。認証情報は削除されますが、優先設定は認証情報ではなく、意図を示すものです。 保留中のトークン取得とキャッシュのクリーンアップが完了するまで待機した後、Connectivity に加えて、すべての Azure CLI リソースのメモリ内トークンをクリアします。クリーンアップに失敗した場合は、切り替えが完了したのではなく、エラーとなります。キャッシュへのアクセスの問題を修正して再試行してください。リセットに失敗した場合は、認証情報が変更されたものとして処理を続けないでください。

対話型サインインでは、FlowAgent はデフォルトでアカウント選択画面を強制表示するため、ブラウザーで現在サインインしているアカウントが暗黙に使用されることはありません。オーバーライドは 2 つあります。

変数	効果
PA_LOGIN_HINT=<upn>	そのアカウントを事前に選択します。すでにアカウントが指定されているため、選択画面は表示されません。
PA_NO_ACCOUNT_PICKER=1	通常のブラウザー SSO に戻します。余分なクリックを避けたい、単一アカウントのユーザー向けです。

優先順位は、より具体的なものから順に、PA_LOGIN_HINT、switch_account の優先設定、PA_NO_ACCOUNT_PICKER、選択画面です。 たとえば、PA_LOGIN_HINT=A が設定されている場合、ユーザー名 B を指定して switch_account を実行しても、A が対象となります。ユーザー名を省略すると、保存された優先設定のみがクリアされます。PA_LOGIN_HINT または PA_NO_ACCOUNT_PICKER をオーバーライドすることはありません。このような場合、応答では選択画面が表示されると保証するのではなく、有効な設定が報告されます。

ステップ 4：FlowAgent ツールが接続されているか確認する

このプラグインは、プラグインの .mcp.json で flowagent として登録され、自動的に起動する FlowAgent MCP サーバー を通じて Power Automate と通信します。.mcp.json は、プラグインのインストールディレクトリ（PLUGIN_ROOT、それがなければ CLAUDE_PLUGIN_ROOT、それもなければ現在のディレクトリ）を解決する小さな Node ブートストラップを介して、同梱の server/mcp.mjs を読み込みます。バンドルが見つからない場合は、対処方法を示すエラーを出力します。

• ツール一覧に flowagent-* / mcp__flowagent__* ツールが表示されている場合：「Power Automate ツールに接続されています」と伝えて、次に進みます。

• 見つからない場合：MCP サーバーが登録されていません。自動的に修正します。

  1. インストール済みプラグインの MCP バンドルを特定します。 これは power-automate プラグインディレクトリ内のバンドルのみを検出するため、別のプラグインの MCP サーバーを誤って取得することはありません。

     node -e "const fs=require('fs'),p=require('path'),d=p.join(process.env.HOME||process.env.USERPROFILE,'.copilot','installed-plugins');const find=(dir)=>{let out=[];for(const e of fs.readdirSync(dir,{withFileTypes:true})){const f=p.join(dir,e.name);if(e.isDirectory()){try{out=out.concat(find(f))}catch{}}else if(e.name==='mcp.mjs'&&p.basename(p.dirname(dir))==='power-automate'){out.push(dir)}}return out};try{const hits=find(d);if(hits.length===1)console.log(JSON.stringify({found:true,serverDir:hits[0],mcpMjs:p.join(hits[0],'mcp.mjs')}));else if(hits.length>1)console.log(JSON.stringify({found:false,reason:'multiple power-automate bundles',candidates:hits}));else console.log(JSON.stringify({found:false}))}catch(e){console.log(JSON.stringify({found:false,error:e.message}))}"
     

     multiple power-automate bundles と表示された場合は、候補を提示し、どれを登録するかユーザーに確認します。推測で選んではいけません。

  2. 1 つだけ見つかった場合は、~/.copilot/mcp-config.json を読み込み、flowagent MCP エントリを追加して書き戻します。

     node -e "const fs=require('fs'),p=require('path');const home=process.env.HOME||process.env.USERPROFILE;const cfgPath=p.join(home,'.copilot','mcp-config.json');let cfg;try{cfg=JSON.parse(fs.readFileSync(cfgPath,'utf8'))}catch{cfg={mcpServers:{}}};if(!cfg.mcpServers)cfg.mcpServers={};if(cfg.mcpServers.flowagent){console.log('already registered');process.exit(0)}const d=p.join(home,'.copilot','installed-plugins');const find=(dir)=>{let out=[];for(const e of fs.readdirSync(dir,{withFileTypes:true})){const f=p.join(dir,e.name);if(e.isDirectory()){try{out=out.concat(find(f))}catch{}}else if(e.name==='mcp.mjs'&&p.basename(p.dirname(dir))==='power-automate'){out.push(dir)}}return out};const hits=find(d);if(hits.length!==1){console.log(hits.length?'ambiguous: '+JSON.stringify(hits):'mcp.mjs not found');process.exit(1)}const mcpPath=p.join(hits[0],'mcp.mjs');cfg.mcpServers.flowagent={command:'node',args:[mcpPath]};fs.writeFileSync(cfgPath,JSON.stringify(cfg,null,2)+'\n');console.log('registered flowagent MCP at '+mcpPath)"
     

  3. ユーザーにエージェントを再起動するよう伝えます（Copilot CLI の場合は /restart、Claude Code の場合はプロセスを再起動）。再起動後、flowagent-* ツールが表示されるはずです。

  4. 見つからない場合（プラグインがインストールされていない場合）は、まずプラグインをインストールするよう伝えます。

     /plugin marketplace add microsoft/power-platform-skills
     

     次に power-automate を選択して、もう一度 /setup を実行します。

ステップ 5：スモークテスト

ユーザーの環境を一覧表示して、最初から最後まで正しく動作することを確認します。

• 推奨：list_environments ツールを呼び出します。

• MCP ツールを利用できない場合：node <path-to-plugin>/server/mcp.mjs を実行して、同梱の MCP サーバーが問題なく起動することを確認してから、再試行する前にプラグインのインストールまたは .mcp.json の設定を修正します。

• 環境が返された場合：成功です！ユーザーに次のように伝えます。

  • 「すべて正常に動作しています！Power Automate の環境は次のとおりです。」
  • 環境をシンプルな表（名前、場所）で表示します。
  • 複数の環境がある場合は、主に使用する環境を尋ね、デフォルトに設定することを提案します（set_current_env ツールを使うか、「デフォルト環境を に設定して」と依頼します）。
  • 利用可能なスキルについて伝えます。
    • /browse-flows — フローを閲覧する
    • /create-flow — 新しいフローを作成する
    • /debug-flow — 壊れたフローを修正する

• 失敗した場合：エラーを確認します。よくある問題：

  • 認証エラー → ステップ 3 に戻ります
  • ツールが見つからない → ステップ 4 に戻ります
  • ネットワークエラー → 企業のプロキシまたは VPN を使用しているか尋ねます

会話のトーンに関するガイドライン

• 「Node.js がインストールされているか確認しましょう」のように、「私たち」を主語にします。
• 小さな成功も喜びましょう：「すばらしいです。Node.js を利用できます！」
• すべての手順を一度に提示せず、一度に 1 つずつ進め、次へ進む前に確認します。
• 何か問題が起きても慌てず、何が起きたのか、次に何をすればよいのかを平易な言葉で説明します。
• 生の JSON エラーを、意味を説明せずにユーザーに見せてはいけません。