Agent Flows: 新 UI Workflow の API 構築
標準対象は、Copilot Studio Workflow の Dataverse レコード作成/更新トリガー + 既存 Agent ノードで
発行済み v2 エージェントを起動する経路。Code Apps を介さないバックグラウンド処理にも使う。
手動 Start + 外部ツールなし inline Agent の CLI は、new UI Workflow の作成・公開・実行契約を検証する
補助経路であり、既存 v2 の呼び出し成功を代用しない。一般クラウドフローは
power-automate、既存 bot の構築は copilot-studio-v2 を使う。
標準経路: Dataverse トリガー + 既存 v2 Agent ノード
- 対象 v2 を公開し、対象環境、bot schema、利用スキル/MCP、実行主体を確定する。
- Copilot Studio の Workflows で Dataverse の行追加・変更トリガーを選び、テーブル、scope、filter columns、filter expression を最小化する。
- Agent ノードで 既存の発行済み v2 を明示選択し、固定された業務指示とトリガー行の必要項目だけを入力へ割り当てる。
- 構造化出力を検証してから Dataverse へ書き戻す。元行の再更新で自己再帰しない終了状態と条件を設ける。
- Review 後に公開し、専用テスト行を 1 件作成または更新して、trigger / Agent / write-back の run と業務出力を照合する。
製品 UI の Agent ノードが標準の authoring 経路。観測した shared_agentnode API Hub 契約を使って
定義を推測生成しない。接続所有者の権限を要求者本人の権限と表現せず、ACP/DLP、クレジット、重複起動、
タイムアウト後の再照合を受入項目に含める。API 側の検証境界は
Agent ノードの診断 を参照する。
補助経路: 手動 Start + inline Agent の API ライフサイクル
既存の最小フローを信頼済みテンプレートとして読み、同一ソリューション内へ別名作成する。
モデルと接続参照はテンプレートから継承する。既存フローの更新・削除は行わない。
Step 1: 対象と実行ゲートを確認する
standard の共通認証と .env を使い、
admin で環境・クラシック DLP・グループ継承を含む ACP を確認する。
使用コネクタは shared_agentnode。ポリシー変更は別の明示承認で行う。
設定の読み戻しと実行基盤の判定は別ゲートとして記録する。
python .github/skills/admin/scripts/check_development_environment.py --environment-id $env:ENV_ID --connector shared_agentnode
作成名、テンプレート、ソリューション、モデル、固定応答、実行回数をユーザーに提示する。
テナント固有値は references/.env.example に従い .env へ置く。
既存テンプレートに Start / Agent / edge / nodeActionMapping / 接続参照が揃っていることを CLI で検証する。
Step 2: API で別名作成する
python .github/skills/agent-flows/scripts/agent_flow.py create --report-file .local/agent-flow/create-plan.json
python .github/skills/agent-flows/scripts/agent_flow.py create --apply --expected-hash <approved-hash> --report-file .local/agent-flow/create-result.json
create-plan.json の定義と影響を確認してから適用する。計画ハッシュは環境、ソリューション、
テンプレート定義、接続参照、作成名に結び付く。書き込み直前に再読み取りする。
created-verified の flowId を .env の AGENT_FLOW_ID に設定する。
新規名の重複を拒否し、category=5 / type=1 / modernflowtype=1 と Draft を読み戻し検証する。
Step 3: 新 UI と公開を検証する
ブラウザ起動前に使用する Edge プロファイルを質問して確定する。同一タスクで確認済みなら再質問しない。
VS Code 統合ブラウザで /environments/{ENV_ID}/flows/{AGENT_FLOW_ID} を開き、
Start と Agent のキャンバスおよび Review を確認する。独立ブラウザや Playwright MCP は導入しない。
ネットワーク証跡は必要な操作と同一呼び出し内で採取し、method / origin+path / status のみ記録する。
Authorization、Cookie、署名クエリは取得・保存・表示しない。
python .github/skills/agent-flows/scripts/agent_flow.py publish --report-file .local/agent-flow/publish-plan.json
python .github/skills/agent-flows/scripts/agent_flow.py publish --apply --expected-hash <approved-hash> --report-file .local/agent-flow/publish-result.json
Dataverse の Active と Flow API の Started を照合する。Flow APIのresource IDはDataverse workflowidと
一致するとは限らないため、properties.workflowEntityIdが一致する1件をplanへ束縛する。
Dataverse PATCHが明確なHTTP 400を返し、直後のworkflow read-backが完全に無変更の場合だけ、承認済みの
Flow API resourceへ/start fallbackを1回実行する。画面でもPublishedを確認する。
Step 4: 一度実行して出力を確認する
python .github/skills/agent-flows/scripts/agent_flow.py run --report-file .local/agent-flow/run-plan.json
python .github/skills/agent-flows/scripts/agent_flow.py run --apply --expected-hash <approved-hash> --report-file .local/agent-flow/run-result.json
python .github/skills/agent-flows/scripts/agent_flow.py inspect --report-file .local/agent-flow/history.json
python .github/skills/agent-flows/scripts/agent_flow.py inspect --run-id <run-id> --report-file .local/agent-flow/output.json
実行受付は run-accepted として記録し、成功扱いにしない。履歴の開始時刻と対象 ID を照合して run を指定する。
run / Agent の Succeeded と固定 JSON 一致で output-verified になる。
出力の body.message、または body.status=Completed の body.result を検証する。
実行成功と回答内容の検証は別に記録する。利用者から成功 run ID の報告を受けた場合は、再実行せずその履歴を照合する。
履歴の最新1件を無条件に今回の run とみなさず、同時実行時は明示的に識別する。
成功以外は 異常系 に従う。自動リトライ・待機ループ・許可範囲拡大は行わない。
Step 5: 業務連携へ進む
非同期連携の契約 に従い、Code Apps からの要求・結果と既存 v2 bot 呼び出しを別段階で実装する。
inline InvokeDefinition の成功を既存 v2 bot / MCP / スキルの実行成功と同一視しない。
既存エージェントを利用する場合は Agent ノードの診断 に従い、
.env に対象 bot と接続参照を指定して読み取り専用の確認を行う。
python .github/skills/agent-flows/scripts/inspect_agent_node.py --report-file .local/agent-flow/agent-discovery.json
target-verified は一覧上の対象照合のみで、エージェントは実行しない。
Workflow の既存 Agent ノードは公式に案内されているが、ここで観測した直接 API は実験的経路として扱う。
ACP 反映待ちでもユーザーの承認に基づき実装・モックテストを進められるが、実応答・本人認可・本番受入のゲートは保持する。
ListAgentsで対象を一意確認できた後の限定smokeは、既存Agent nodeの
plan/hash手順に従う。invoke_agent_node.pyはHITLを無効化し、ツール・knowledge・file生成を禁止する固定nonce
promptと出力schemaを承認対象にする。HTTP 202はaccepted-unverifiedであり、再実行や成功扱いにしない。
HTTP 201、structured output完全一致、files 0件の組み合わせだけをoutput-verifiedとする。
既存 bot を呼ぶ要求/結果ワーカーは 構築・更新・受入パターン を使う。
conversation_contract.py の定義・要求者・相関・結果検証を実装に組み込み、
テーブル/列/許可対象を .env で指定して既存要求を読み取り検証する。
python .github/skills/agent-flows/scripts/inspect_conversation.py --request-id <accepted-request-id>
このコマンドは GET のみ。reply-envelope-verified は相関/所有者/応答形式の成功であり、
設計の幾何検証や回答の正しさは別ゲート。単一ユーザー限定なら対象変更を明示承認し、
サーバーの CreatedBy を許可 ID と照合する。クライアント表示制限だけを認可にしない。
Step 6: 検証と結果報告
python -m unittest discover -s .github/skills/agent-flows/tests -v
python .github/skills/update-skills/scripts/validate_skill.py .github/skills/agent-flows
報告は「作成 / 新 UI / 公開 / 実行受付 / 実行完了 / 出力検証 / 業務連携」を分ける。
ローカルの計画・結果には環境固有情報があるため Git 公開対象から除外する。
仕様・実測・未検証の区分は API 契約 を参照する。