宣言型ワークフロー (Declarative Workflows)

マルチエージェントのオーケストレーションをコードではなく YAML で定義します。「宣言型 ワークフロー」は Microsoft Agent Framework の Declarative Workflow であり、その実行グラフ -- 順次ステップ・条件分岐・ループ・foreach・エージェント呼出 -- を手組みではなくファイルから コンパイルします。ワークフローは宣言型エージェントと同じ画面で 一緒に管理し、トップレベルの kind フィールドで区別します。kind: Prompt はエージェント、 kind: Workflow はワークフローです。

重要な原則は宣言型エージェントと同じです。YAML は仕様であり、構築は ChatWalaʻau が所有します。 ワークフローはエージェントを名前で参照するだけで、資格情報・プロバイダ・サンプリングパラメータを 一切持ちません。参照される各エージェントは単体のときと同じように ChatWalaʻau が構築するため、 モデル・オプション・エージェント単位のツールはそのエージェントの仕様に由来します。

できること

• YAML を実行グラフにコンパイル。 kind: Workflow の YAML を DECLARATIVE_AGENTS_DIR (エージェントと同じフォルダ) に置くと、ChatWalaʻau が Microsoft Agent Framework の WorkflowFactory でコンパイルします。専用ディレクトリや有効化フラグは不要 -- フォルダ未設定 ならワークフローは単に存在しません。
• 宣言型エージェントをオーケストレーション。 ワークフローの InvokeAzureAgent ステップが kind: Prompt エージェント (組込み CORE エージェントを含む) を呼び出します。ChatWalaʻau が 各エージェントを自前のエージェント/プロバイダ経路で解決・構築するため、資格情報とモデルルーティングは ChatWalaʻau の管理下に留まります。InvokeAzureAgent は宣言型 Prompt エージェントのみに 解決され、生の Foundry エージェントを構築することはありません。
• フルアクションサーフェス。 Microsoft Agent Framework の宣言型アクション 23 種すべてを オーサリングできます。カテゴリ別 (下記) に、変数・制御フロー・出力・エージェント・ツール・ HTTP・人間参加・ワークフロー制御を扱えます。
• エージェントと同じ画面で管理。 Prompt エージェントとワークフローは1つの管理モーダル (サイドバーフッターのロボットアイコン) で管理し、Prompt / Workflow タグで区別します。Prompt エージェントを有効化するか、ワークフローをチャットで実行として選択します (選択は記憶されます)。
• 2 つの実行方法。
  • チャットで -- 管理モーダルを開き、ワークフローのRun in chatを押します。次のメッセージが ワークフローを駆動し、進捗が小さなグラフでライブ表示され、アシスタントメッセージにワークフロー名が ラベル表示されます。ワークフロー実行対象の間は、メッセージ単位のモデル / Reasoning / Verbosity / 構造化出力の操作は非表示になります。各ステップのモデルは呼び出すエージェントに固定されるためです。
  • バックグラウンドジョブで -- 同じワークフローを Pipeline ジョブとして実行し、run 履歴と ログを取得します。長時間・無人実行向けです。
• 人間に一時停止して尋ねる。 Question と RequestExternalInput は run を中断してオペレータに 尋ねます -- チャットでは入力カード (インタラクティブ)、Pipeline ポータルでは「入力待ち」状態 (バックグラウンド)。回答すると、停止した位置から run が再開します。
• 図として作成。 Create -> New Workflow (と各ワークフローの編集 / 削除) でフルスクリーン エディタを開きます。ステップの視覚的な DAG キャンバス、各ステップのフォーム (「エージェント呼出」ステップは Prompt エージェントを選択)、直接編集もできるライブ YAML プレビュー。 制御フローのステップは入れ子のコンテナノード (下記) として描画され、分岐やループはキャンバス上でも 形を保ちます。
• 誤りは見える化。 未対応のアクション、Prompt エージェントでないエージェントへの参照、クラスが 有効化されていない境界越えアクションは警告としてフラグされ、ワークフローの実行をブロックします -- そのため検証を通過したワークフローは必ず実行できます。

kind フィールド

kind	何か	実行方法
Prompt	単一エージェント	唯一の有効エージェント (人格) として有効化。
Workflow	オーケストレーション	会話ごとに実行対象として選択、またはバックグラウンドジョブで実行。

ワークフローは人格ではありません。選択しても有効エージェントは変わらず、OpenAI 互換 API や Teams では使われません (これらは常に有効な Prompt エージェントを実行します)。ワークフローは Web アプリ専用です。

アクションサーフェス

Microsoft Agent Framework の宣言型アクション 23 種すべてをオーサリングでき、カテゴリ別に整理 されています。境界越えの 3 クラス (Tool と HTTP) は既定で無効で、環境変数でクラスごとに 有効化します -- 境界越えアクションを参照してください。

カテゴリ	アクション種別
Variable	SetVariable, SetMultipleVariables, SetTextVariable, ResetVariable, ClearAllVariables, ParseValue, EditTableV2
Control Flow	If, ConditionGroup, Foreach, BreakLoop, ContinueLoop, GotoAction
Output	SendActivity
Agent	InvokeAzureAgent (宣言型 Prompt エージェントを呼び出す)
Tool	InvokeFunctionTool, InvokeMcpTool -- 隔離・オプトイン
HTTP	HttpRequestAction -- 隔離・オプトイン
Human-in-the-Loop	Question, RequestExternalInput
Workflow Control	EndWorkflow, EndConversation, CreateConversation

全アクション共通の kind / id / displayName

エレメント	必須	内容
kind	○	アクションの種類。
id	○	アクションを一意に識別する ID。GotoAction の移動先にも使用します。エディタは常に付与します。
displayName	任意	表示名。実行中の進捗インジケータでそのステップの名前として表示されます。

変数と名前空間

変数パスは常に 名前空間.名前 の形です。名前空間なしの名前は保存時・読み込み時・コンパイル時 に自動で Local. が補われるため、counter と入力すれば Local.counter になります。

名前空間	内容
Local.*	ワークフロー内部の読み書き可能な変数。
Workflow.Inputs.*	起動時に渡された入力値。読み取り専用。
Workflow.Outputs.*	呼び出し元へ返す出力値。
System.*	会話 ID などランタイム提供値。

エディタの各変数入力欄は、これらの名前空間に加えて、ワークフロー内で既に使われている Local.* の 名前と inputs: / outputs: で宣言済みの名前を候補として表示します。書き込みフィールドでは 読み取り専用の Workflow.Inputs.* は候補に出ません。

ランタイムが受け付けないパス (Workflow.Inputs.*、Workflow 単体、未知の Workflow.<名前>、空の パス) への書き込みはブロッキング警告となり、実行中のエラーではなく実行前に報告されます。

ランタイムが認識しない名前空間 (例: topic.x) は正当なカスタム名前空間として扱われ、記述した ままに保持されます。エディタが候補として提案しないだけです。

ユーザーへの質問

Question は回答が来るまでワークフローを一時停止します。choices の各要素は value / label のペアで、allowFreeText は自由入力を許可するかを文書上で明示するため常に出力され ます。

- kind: Question
  id: ask_priority
  displayName: 優先度を質問
  question:
    text: 優先度を選択してください
  variable: Local.priority
  choices:
    - value: high
      label: 高
    - value: low
      label: 低
  allowFreeText: false
  default: medium

フィールド名はランタイムに従います

各アクションのフィールドは、インストール済みの Microsoft Agent Framework ランタイムが実際に読む 名前です。SetTextVariable は text、SetMultipleVariables は assignments リスト、ParseValue は value (および任意の valueType)、EditTableV2 は item (および任意の key / index) を 受け取ります。旧フィールド名で書かれたワークフローは、最初に検証または実行された時点で自動的に 移送されます。ファイル自体が書き換わるのは保存したときだけです。

制御フローは入れ子

制御フローは DAG エディタで入れ子のコンテナノードとしてオーサリングし、YAML のツリーと正確に 一致します -- フラットな分岐/合流エッジではありません。

• If -- then レーンと else レーンを持つコンテナ。
• Foreach -- 本体レーンを 1 つ持つコンテナ。ヘッダにはソース・item 名・index 名を表示。 BreakLoop / ContinueLoop はループコンテナの内側でのみオーサリング可能。
• ConditionGroup -- 条件ごとに 1 レーン (ラベル付き)、加えて elseActions レーン。
• GotoAction -- ターゲットアクションへのラベル付きエッジとして描画 (唯一の後方エッジ)。

YAML の入れ子がスコープを定義するため、コンテナノードとファイルはロスなく往復します。プレビュー ペインで raw YAML を直接編集することも常に可能です。

境界越えアクション (オプトイン)

3 つのアクションクラスは、ランタイムが通常は閉じている資格情報 / プロバイダ / ネットワークの境界を 越えます。これらは既定で無効で、環境変数によりクラス単位で有効化します。クラスが無効の場合、その アクションの使用はブロッキング警告となり、「フラグを有効化」できる旨のメッセージが表示されます -- そのためワークフローが黙って外部に到達することはありません。

• InvokeFunctionTool -- 呼び出すエージェントが持つのと同じ関数サーフェスのみを実行します (コーディングは引き続き CODING_ENABLED でゲート)。WORKFLOW_FUNCTION_ACTIONS_ENABLED で有効化。
• InvokeMcpTool -- 既に構成済みかつゲーティングストアで有効化された MCP サーバ/ツール のみに到達します。新しいサーバを導入することはできません。WORKFLOW_MCP_ACTIONS_ENABLED で 有効化。
• HttpRequestAction -- 送信 HTTP リクエストを行い、WORKFLOW_HTTP_ALLOWED_HOSTS (空 = すべて拒否) に制限されます。SSRF ガードは許可リストに関わらず loopback・private・ link-local・metadata アドレスをブロックします。WORKFLOW_HTTP_ACTIONS_ENABLED で有効化し、 WORKFLOW_HTTP_TIMEOUT_MS が各リクエストを上限化します。

設定

変数	既定	目的
DECLARATIVE_AGENTS_DIR	(未設定)	ワークフロー (とエージェント) を探索するフォルダ。未設定=ワークフローなし。オーサリングには書込可能が必要。
WORKFLOW_MAX_ITERATIONS	100	暴走ループ / コストガード。ワークフローのステップ数を上限化 (YAML の maxTurns はより小さいフォールバックとして適用)。
WORKFLOW_FUNCTION_ACTIONS_ENABLED	false	InvokeFunctionTool の隔離ハンドラを有効化 (エージェント相当の関数サーフェスのみ)。
WORKFLOW_MCP_ACTIONS_ENABLED	false	InvokeMcpTool の隔離ハンドラを有効化 (構成済み+ゲーティングストア有効の MCP サーバ/ツールのみ)。
WORKFLOW_HTTP_ACTIONS_ENABLED	false	HttpRequestAction の隔離ハンドラを有効化。
WORKFLOW_HTTP_ALLOWED_HOSTS	(空 = すべて拒否)	HttpRequestAction のカンマ区切りホスト許可リスト。SSRF ガードは loopback / private / link-local / metadata アドレスを引き続きブロック。
WORKFLOW_HTTP_TIMEOUT_MS	10000	HttpRequestAction のリクエストごとのタイムアウト。

例

ワークフローは任意の inputs / outputs、maxTurns の上限、トップレベルの actions リストを 宣言します。制御フローのアクションは子アクションをインライン (then / else、actions、 conditions) で保持します。

name: workflow-name
description: workflow description
maxTurns: 100
inputs:
  inputName:
    type: string
    description: input description
outputs:
  outputName:
    type: string
actions:
  - kind: SetVariable
    id: initialize
    displayName: 入力を読み取る      # 任意。実行中のステップ名として表示
    variable: Local.value
    value: =Workflow.Inputs.inputName
  - kind: If
    id: branch
    condition: =Not(IsBlank(Local.value))
    then:
      - kind: InvokeAzureAgent
        id: invoke_agent
        agent:
          name: MyAgent          # kind:Prompt の宣言型エージェントに解決される
        input:
          messages: =Local.value
        output:
          responseObject: Local.AgentResult
    else:
      - kind: SendActivity
        id: invalid_input
        activity:
          text: Input is empty.
  - kind: SetVariable
    id: set_output
    variable: Workflow.Outputs.outputName
    value: =Local.AgentResult.summary
  - kind: EndWorkflow
    id: finish

DECLARATIVE_AGENTS_DIR 配下に保存し、Declarative Agents & Workflows モーダル (サイドバー フッターのロボットアイコン) を開いてワークフローを選択し、Run in chat を押します。または バックグラウンドジョブとして実行します。