宣言型エージェント (Declarative Agents)

エージェントをコードではなく YAML で定義し、Web アプリから 有効なエージェントをランタイム切替 できます -- コード変更も再起動も不要です。ChatWalaʻau は Microsoft Agent Framework の宣言型フォーマット (agent-framework-declarative、AgentFactory.create_agent_from_yaml / create_agent_from_yaml_path) を使用します。

重要な原則: YAML は仕様であり、構築は ChatWalaʻau が所有します。 マッピングできないフィールドは警告とともに無視され、製品の設計方針と衝突するフィールド (例: temperature) は有効化しようとした時点で拒否されます。Microsoft スキーマとの 100% 互換は意図的に 目標としません。

同じフォルダには、トップレベルの kind フィールドで区別される 2 つの兄弟 kind も置けます: Declarative Workflow(kind: Workflow)と、会話ごとの run-target として実行される自律型ソフトウェアエンジニアリングエージェント Harness Agent(kind: Harness)です。

できること

組み込みの CORE エージェント。 既定の ChatWalaʻau エージェントが CORE エージェントとして登録され、最初から有効です -- 標準の挙動を完全に再現します。これまで通り使うために設定は一切不要です。
フォルダからのカスタムエージェント。 DECLARATIVE_AGENTS_DIR を YAML ファイルのフォルダ (ネストフォルダ可) に向けると、各ファイルが選択可能なエージェントになります。
有効なエージェントは 1 つ、Web アプリから切替。 管理モーダル (サイドバー下部の、File Explorer アイコン隣のロボットアイコン) が CORE エージェントとカスタムエージェントをフォルダツリーで一覧します。1 つを選んで有効化すると、ChatWalaʻau がエージェントを再構築し、切替完了まで「rebuilding」インジケータを表示します。
GUI でエージェントを組み立て -- YAML の手書き不要。 Declarative Agents モーダルの Create ボタン (各カスタムエージェントの Edit / Delete) が全画面エディタを開きます。名前・説明・ instructions のフォーム、モデルとツールを接続する視覚キャンバス、直接編集もできるライブ YAML プレビューを備えます。保存すると YAML を生成し、エージェントを即座に登録します。
エージェント単位のツール。 エージェントは自分専用のツール面を持てます -- 組み込みツール・MCP サーバ/ツール・Skills から必要なものだけを選ぶと、そのエージェントはそれらだけで動作します。省略すれば従来通り有効な全ツールを継承します。
誤りは可視化されます。 マッピングに失敗した YAML はエラー付きで一覧に表示され、有効化できません。

有効化する

# .env
DECLARATIVE_AGENTS_DIR=.agents

フォルダを作成し、YAML ファイルを配置します (ネストフォルダも可):

.agents/
  pirate.yaml
  support/
    triage.yaml

DECLARATIVE_AGENTS_DIR が未設定でも CORE エージェントは常に存在します。

ChatWalaʻau 互換のサンプル

このサンプルは サポートされる全フィールド を網羅しています。警告なくマップされるため、既定デプロイ (gpt-5.5 を固定) ではそのまま有効化できます。

kind: Prompt                       # 宣言型スキーマで必須
name: Support Triage Assistant     # Declarative Agents 管理画面に表示
displayName: Support Triage        # 任意。name が無い場合に使用
description: >-                     # 管理画面の詳細ペインに表示
  受信したサポート質問をトリアージし、構造化サマリを返します。

# 人格 -> Identity (システムプロンプトの最初のブロック)。"=Identity" を指定するか
# instructions を省略すると、グローバルの .agent/IDENTITY.md の人格を引き継ぎます。
instructions: >-
  あなたは簡潔なカスタマーサポートのトリアージ担当です。要求を分類し、要約し、
  次のアクションを提案してください。簡潔かつ実用的に。

model:
  # 優先既定モデル。構成済みモデル (AZURE_OPENAI_MODELS / ANTHROPIC_MODELS) のいずれかで
  # ある必要があります (そうでないと有効化はブロックされます)。他の構成済みモデルも選択可能
  # なままです。id を省略するとデプロイの既定モデルを使用します。
  id: gpt-5.5
  options:
    # サポートされるのは reasoning effort と (gpt-5.x の) text verbosity のみです。
    # effort:    low | medium | high | xhigh | max
    # verbosity: low | medium | high
    effort: high
    verbosity: medium

# 任意。このエージェントを利用可能ツールの「部分集合」に制限します。ブロックを省略すると
# 有効な全ツールを継承します。各エントリは既存のツールを参照します -- ここで新しいツールを
# 導入することはできません。認識できない名前は警告となり、有効化がブロックされます。
tools:
  - kind: function          # 組み込みツール (名前指定)
    name: rag_search
  - kind: mcp               # MCP サーバ全体...
    name: microsoft_learn
    allowedTools:           # ...または一部のツールのみ
      - microsoft_docs_search
  - kind: skill             # Agent Skill (名前指定)
    name: pptx

# 任意。すべての回答を既定でこの JSON 形に制約します (チャットでメッセージ単位に
# オフ/編集も可能)。通常の会話エージェントにする場合はこのブロックを削除してください。
# strict JSON では列挙した全プロパティが必須で、追加プロパティは許可されません。
outputSchema:
  properties:
    category:
      type: string
      required: true
      description: billing / technical / account / other のいずれか。
    summary:
      type: string
      required: true
      description: 要求の一文要約。
    next_action:
      type: string
      required: true
      description: サポートチームの推奨次アクション。

保存して Declarative Agents モーダル (サイドバー下部のロボットアイコン) を開き、エージェントを選んで Activate をクリックします。モデル選択、reasoning effort / verbosity コントロール、JSON スキーマエディタがすべてエージェントを反映して更新されます。

GUI でエージェントを組み立てる

YAML を書きたくない場合は、DECLARATIVE_AGENTS_DIR が 書き込み可能 なフォルダを指していれば、 Declarative Agents モーダルに Create ボタン (各カスタムエージェントには Edit / Delete) が表示されます。全画面エディタは 3 ペイン構成です。

左 -- 基本情報。 名前・説明・instructions (人格)。
中央 -- キャンバス。 エージェントのノードと、モデル (構成済みモデルからの reasoning effort / verbosity) を選ぶツールバー、そして組み込みツール・MCP サーバ/ツール・Skills の検索可能な一覧から ツールを追加 する操作。追加したツールは削除可能な接続ノードとして表示されます。
右 -- YAML。 保存される内容そのままのライブ正規プレビュー。Edit raw YAML に切り替えると直接編集でき、検証は常時実行され、警告はインライン表示されます。

モデル選択は構成済みモデルが駆動します -- プロバイダー・エンドポイント・資格情報をエディタが尋ねることはありません (ChatWalaʻau が解決します)。

保存は「終了」ではなく「チェックポイント」です。 ボタンは初回だけ Create（まだ何も存在しないため）、以降は Save になります。いずれの場合もエディタは開いたままで、キャンバス・選択中のノード・スクロール位置はそのまま維持され、書き込みが完了したことは短い通知で示されます。作成 → 保存 → 試す → 調整、を一続きのセッションで行えます。新しいエージェントはすぐ一覧に現れ、有効化できます。閉じるのは Close だけで、未保存の変更があるときは従来どおり確認します。

2 回目以降の保存は同じエージェントを更新します。作成後に編集を続けても、中途半端なコピーが 2 つできることはありません。

マップ / 無視 / 拒否される項目

YAML フィールド	ChatWalaʻau の挙動
`instructions`	エージェントの人格になります (システムプロンプトの最初のブロック)。`"=Identity"` を指定するか省略すると、グローバルの `.agent/IDENTITY.md` を引き継ぎます。
`model.id`	エージェントの優先既定モデルを設定します。他の構成済みモデルも選択可能なまま (選択 UI は消えません)。未構成のモデルは警告とともに無視されます。
`model.options.effort`	reasoning effort にマップされます。
`model.options.verbosity`	text verbosity (gpt-5.x) にマップされます。
`tools`	エージェントを利用可能ツールの部分集合に制限します (`kind: function` / `mcp` / `skill`)。省略すると有効な全ツールを継承します。認識できない名前は警告となり有効化をブロックします。既存しないツールを追加することはできません。
`outputSchema`	既定の構造化出力スキーマになります (メッセージ単位で上書き可能)。
`model.connection` / 資格情報 / `=Env.*`	無視されます (警告を表示)。資格情報とエンドポイントは ChatWalaʻau が解決し、YAML から取りません。
`temperature` / `top_p` / `top_k` / `seed` ...	有効化時に拒否されます。対応モデル (Azure gpt-5.5 / gpt-5.4、Anthropic Opus 4.7 / 4.8) は reasoning 専用で、従来のサンプリングパラメータを受け付けません。
不正な `effort` / `verbosity` 値	警告が表示され (有効化はブロック)、サイレントに無視せずタイポを修正させます。
その他	警告とともに無視されます。

警告がある場合は有効化できません

警告が 1 つでもあるエージェントは、YAML を修正するまで有効化できません。管理画面は当該エージェントを明示し、警告を一覧表示し、Activate ボタンを無効化します。これにより有効なエージェントは常にクリーンで完全対応の定義になります。警告が出るもの: 無視される model.connection / 資格情報、未知の model.options キー、不正な effort / verbosity 値、構成されていない model.id。不正な YAML や拒否されるサンプリングパラメータ (例: temperature) はハードエラーです。

補足

エージェントのオプションは既定として適用されます。 エージェントの reasoning effort・ verbosity・出力スキーマは切り替えると有効になり、チャットのモデル選択・オプションパネルもそれを反映して更新されます。各オプションはメッセージ単位で上書きでき、パネルを明示的に変更していない項目はエージェントの値が使われます。
実行中のエージェント名はチャットに表示され、クリックできます。 実行対象が組み込みエージェント以外のときは、メッセージ入力欄の上にモデル操作の代わりにその名前が表示されます。名前をクリック すると Declarative Agents & Workflows モーダルが開くので、サイドバーのアイコンを探す必要はありません。何も事前選択されないため、開いただけで意図しない切替が準備されることはありません。
切替は Web アプリのみ。 OpenAI 互換 API と Microsoft Teams は常に現在有効なエージェントを使用します -- 選択に追従し、自分では切り替えません。
選択は再起動を越えて保存されません。 再起動すると CORE エージェントが再び有効になります。切替を簡単に取り消せ、新しいプロセスで予期しない状態にならないようにするためです。
切替は全員に影響します。 有効化はプロセス全体に作用します (MCP / Skills の管理と同様)。
有効なエージェントはログ出力されます。 起動時と切替のたびに、有効なエージェント名を 1 行出力するので、どの YAML が効いているか確認できます。

できること​

有効化する​

ChatWalaʻau 互換のサンプル​

GUI でエージェントを組み立てる​

マップ / 無視 / 拒否される項目​

警告がある場合は有効化できません​

補足​