int-reference

Copilot Studio YAML リファレンス

コアファイルの種類

ファイル	用途
agent.mcs.yml	エージェントのメインメタデータ（kind: GptComponentMetadata）
settings.mcs.yml	エージェントの設定と構成
connectionreferences.mcs.yml	コネクタの参照
topics/*.mcs.yml	会話トピック（kind: AdaptiveDialog）
actions/*.mcs.yml	コネクタベースのアクション（kind: TaskDialog）
knowledge/*.mcs.yml	ナレッジソース（kind: KnowledgeSourceConfiguration）
variables/*.mcs.yml	グローバル変数（kind: GlobalVariableComponent）
agents/*.mcs.yml	子エージェント（kind: AgentDialog）

トリガーの種類

OnRecognizedIntent を持つトピックには、2 つのルーティング方式があります。どちらが重要かは、オーケストレーションモードによって異なります。

• modelDescription — 生成オーケストレーション（GenerativeActionsEnabled: true）で使用します。AI オーケストレーターはこれを読み取り、ルーティングを判断します。生成エージェントの主要な方式です。
• トリガーフレーズ（triggerQueries）— クラシックオーケストレーションで使用します。ユーザーの発話とパターンマッチングを行います。生成オーケストレーションが有効な場合は、補助的なヒントになります。

システムトリガー（OnConversationStart、OnUnknownIntent、OnError など）は自動的に起動し、どちらの方式も使用しません。

種類	用途
OnRecognizedIntent	トリガーフレーズが一致
OnConversationStart	会話の開始
OnUnknownIntent	一致するトピックがない場合（フォールバック）
OnEscalate	ユーザーが人間のエージェントを要求
OnError	エラー処理
OnSystemRedirect	リダイレクトによってのみ起動
OnSelectIntent	複数のトピックが一致（曖昧さの解消）
OnSignIn	認証が必要
OnToolSelected	子エージェントの呼び出し
OnKnowledgeRequested	カスタムナレッジソースの検索が起動（YAML のみ、UI なし）
OnGeneratedResponse	送信前に AI 生成の応答をインターセプト
OnOutgoingMessage	機能しません（2026-03-15） — スキーマには存在しますが、実行時には起動しません。使用しないでください。

YAML のみの機能

これらの機能は実行時に動作しますが、Copilot Studio の UI には表示されません。UI で編集すると、これらの機能が通知なく削除される可能性があることをユーザーに伝えてください。

機能	注記
ナレッジソースの triggerCondition	UI ではオン／オフの切り替え（UniversalSearchTool から除外する場合は =false）のみ設定できます。任意の Power Fx 式（例：=Global.UserDepartment = "HR"）は実行時に動作しますが、YAML からのみ設定できます。注意して使用してください。（2026-03-16）

アクションの種類

種類	用途
SendActivity	メッセージを送信
Question	ユーザーに入力を求める
SetVariable	変数を設定／計算（Power Fx 式、先頭に =）
SetTextVariable	テンプレート補間（{}）を使ってテキスト変数を設定します。テキスト以外の型（例：Number）をテキストに変換する場合に便利です："You have {Topic.Count} items"
ConditionGroup	分岐ロジック
BeginDialog	別のトピックを呼び出す
ReplaceDialog	現在のトピックを置き換える
EndDialog	現在のトピックを終了
CancelAllDialogs	すべてのトピックをキャンセル
ClearAllVariables	変数をクリア
SearchAndSummarizeContent	生成回答（ナレッジに基づく）
AnswerQuestionWithAI	AI による回答（会話履歴と一般知識のみ）
EditTable	コレクションを変更
CSATQuestion	顧客満足度
LogCustomTelemetryEvent	ログ記録
OAuthInput	サインインのプロンプト
SearchKnowledgeSources	ナレッジソースを検索（生の結果を返し、AI による要約は行わない）
CreateSearchQuery	ユーザー入力から AI が検索クエリを生成

コネクターアクション（TaskDialog）

コネクターアクション（kind: TaskDialog）は、外部コネクターの操作を呼び出します。actions/ に保存され、connectionreferences.mcs.yml 内の接続参照が必要です。

利用可能なコネクターから新しいアクションを作成するには、/add-action を使用してください。 スキーマには、TaskDialog と InvokeConnectorTaskAction の構造プロパティが記述されています。ただし、各コネクター操作固有の入力と出力を確認するには、コネクター検索スクリプト（connector-lookup.bundle.js）を使用して、操作の詳細をすべて取得してください。

アクションの構造

フィールド	用途
kind: TaskDialog	これがコネクターアクションであることを示します
inputs	入力：AutomaticTaskInput（AI が指定）または ManualTaskInput（固定値）
modelDisplayName	AI オーケストレーターによるルーティング用の表示名
modelDescription	AI オーケストレーターによるルーティング用の説明
outputs	コネクターから返される出力プロパティ名
action.kind	コネクターアクションでは常に InvokeConnectorTaskAction
action.connectionReference	接続の論理名（connectionreferences.mcs.yml に登録）
action.connectionProperties.mode	Maker（作成者の資格情報）または Invoker（エンドユーザーの資格情報）
action.operationId	コネクター固有の操作識別子
outputMode	通常は All。すべての操作出力をエクスポートします

入力の種類

入力の種類	使用する場合	備考
AutomaticTaskInput	AI オーケストレーターがコンテキストに基づいて値を指定する場合	AI が指定する内容を理解するための description を含みます
ManualTaskInput	固定値／ハードコードされた値（例：タイムゾーン、フォルダーパス）を指定する場合	ハードコードできるのは文字列のみです。文字列以外の値（ID、列挙値）は、プッシュ後にユーザーが確認する必要があります

$ で始まるプロパティ名（SharePoint、OData）

一部のコネクター（特に SharePoint）は、$filter、$orderby、$top などの OData パラメーターを使用します。これらを TaskDialog YAML で使うには、単一引用符と二重引用符の両方で囲む必要があります。

# TaskDialog (actions/*.mcs.yml) — CORRECT
- kind: ManualTaskInput
  propertyName: "'$filter'"
  value: "Status eq 'Active'"

"'$filter'" は、外側の "" が YAML の文字列区切り文字で、内側の '' がランタイムに送信されるリテラル値の一部であることを意味します。$filter、"$filter"、'$filter' のいずれかだけを使用すると失敗します。

InvokeConnectorAction（トピック内にインラインで記述する場合）では形式が異なり、parameters/ プレフィックスを使用し、内側の単一引用符は不要です。

# InvokeConnectorAction (inside topics) — CORRECT
- kind: InvokeConnectorAction
  operationId: GetItems
  input:
    parameters/$filter: "Status eq 'Active'"

これら 2 つの形式を混在させないでください。

システム変数

変数	説明
System.Bot.Name	エージェントの名前
System.Activity.Text	ユーザーの現在のメッセージ
System.Conversation.Id	会話の識別子
System.Conversation.InTestMode	テストチャット中の場合は True
System.FallbackCount	連続したフォールバックの回数
System.Error.Message	エラーメッセージ
System.Error.Code	エラーコード
System.SignInReason	サインインが開始された理由
System.Recognizer.IntentOptions	曖昧さを解消するために一致したインテント
System.Recognizer.SelectedIntent	ユーザーが選択したインテント
System.SearchQuery	AI が書き換えた検索クエリ（OnKnowledgeRequested で利用可能）
System.KeywordSearchQuery	検索クエリのキーワード版（OnKnowledgeRequested で利用可能）
System.SearchResults	カスタム検索結果を設定するテーブル。スキーマ：Content、ContentLocation、Title（OnKnowledgeRequested で利用可能）
System.ContinueResponse	自動送信を抑制するには、OnGeneratedResponse で false に設定します
System.Response.FormattedText	AI が生成した応答テキスト（OnGeneratedResponse で利用可能）

変数のスコープ

プレフィックス	スコープ	有効期間
Topic.<name>	トピック変数	現在のトピックのみ
Global.<name>	グローバル変数	会話全体（variables/ フォルダーで定義）
System.<name>	システム変数	組み込み、読み取り専用

グローバル変数は、variables/<Name>.mcs.yml に YAML ファイルとして定義します（kind: GlobalVariableComponent）。aIVisibility には、UseInAIContext（オーケストレーターが値を読み取り、推論できます）または Hidden（オーケストレーターには認識されません。フラグや内部管理に使用します）を指定できます。

事前構築済みエンティティ

エンティティ	用途
BooleanPrebuiltEntity	はい／いいえの質問
NumberPrebuiltEntity	数値入力
StringPrebuiltEntity	自由形式のテキスト
DateTimePrebuiltEntity	日付／時刻
EMailPrebuiltEntity	メールアドレス

Power Fx 式のリファレンス

以下のサポート対象リストにある関数のみを使用してください。 Copilot Studio がサポートするのは Power Fx のサブセットです。サポートされていない関数を使用すると、エラーが発生します。

# Arithmetic
value: =Text(Topic.number1 + Topic.number2)

# Date formatting
value: =Text(Now(), DateTimeFormat.UTC)

# Conditions
condition: =System.FallbackCount < 3
condition: =Topic.EndConversation = true
condition: =!IsBlank(Topic.Answer)
condition: =System.Conversation.InTestMode = true
condition: =System.SignInReason = SignInReason.SignInRequired
condition: =System.Recognizer.SelectedIntent.TopicId = "NoTopic"

# String interpolation in activity (uses {} without =)
activity: "Error: {System.Error.Message}"
activity: "Error code: {System.Error.Code}, Time (UTC): {Topic.CurrentTime}"

# Record creation
value: "={ DisplayName: Topic.NoneOfTheseDisplayName, TopicId: \"NoTopic\", TriggerId: \"NoTrigger\", Score: 1.0 }"

# Variable initialization (first assignment uses init: prefix)
variable: init:Topic.UserEmail
variable: init:Topic.CurrentTime
# Subsequent assignments omit init:
variable: Topic.UserEmail

サポートされている Power Fx 関数

以下は、Copilot Studio で使用できる すべての Power Fx 関数です。このリストにない関数は使用しないでください。

数学: Abs, Acos, Acot, Asin, Atan, Atan2, Cos, Cot, Degrees, Exp, Int, Ln, Log, Mod, Pi, Power, Radians, Rand, RandBetween, Round, RoundDown, RoundUp, Sin, Sqrt, Sum, Tan, Trunc

テキスト: Char, Concat, Concatenate, EncodeHTML, EncodeUrl, EndsWith, Find, Left, Len, Lower, Match, MatchAll, Mid, PlainText, Proper, Replace, Right, Search, Split, StartsWith, Substitute, Text, Trim, TrimEnds, UniChar, Upper, Value

日付／時刻: Date, DateAdd, DateDiff, DateTime, DateTimeValue, DateValue, Day, EDate, EOMonth, Hour, IsToday, Minute, Month, Now, Second, Time, TimeValue, TimeZoneOffset, Today, Weekday, WeekNum, Year

論理: And, Coalesce, If, IfError, IsBlank, IsBlankOrError, IsEmpty, IsError, IsMatch, IsNumeric, IsType, Not, Or, Switch

テーブル: AddColumns, Column, ColumnNames, Count, CountA, CountIf, CountRows, Distinct, DropColumns, Filter, First, FirstN, ForAll, Index, Last, LastN, LookUp, Patch, Refresh, RenameColumns, Sequence, ShowColumns, Shuffle, Sort, SortByColumns, Summarize, Table

集計: Average, Max, Min, StdevP, VarP

型変換: AsType, Boolean, Dec2Hex, Decimal, Float, GUID, Hex2Dec, JSON, ParseJSON

その他: Blank, ColorFade, ColorValue, Error, Language, OptionSetInfo, RGBA, Trace, With

利用可能なテンプレート

テンプレートはプラグインに同梱されています。テンプレートを使用するスキルは、${CLAUDE_SKILL_DIR}/../../templates/ を使ってテンプレートを参照します。

テンプレート	ファイル	パターン
挨拶	templates/topics/greeting.topic.mcs.yml	OnConversationStart のウェルカム
フォールバック	templates/topics/fallback.topic.mcs.yml	エスカレーションを伴う OnUnknownIntent
算術	templates/topics/arithmeticsum.topic.mcs.yml	計算を伴う入力／出力
質問＋分岐	templates/topics/question-topic.topic.mcs.yml	ConditionGroup を伴う質問
ナレッジ検索	templates/topics/search-topic.topic.mcs.yml	SearchAndSummarizeContent のフォールバック
カスタムナレッジソース	templates/topics/custom-knowledge-source.topic.mcs.yml	カスタム API を使用する OnKnowledgeRequested（YAML のみ）
引用の削除	templates/topics/remove-citations.topic.mcs.yml	引用を削除する OnGeneratedResponse
認証	templates/topics/auth-topic.topic.mcs.yml	OAuthInput を使用する OnSignIn
エラーハンドラー	templates/topics/error-handler.topic.mcs.yml	テレメトリを伴う OnError
曖昧さの解消	templates/topics/disambiguation.topic.mcs.yml	OnSelectIntent のフロー
エージェント	templates/agents/agent.mcs.yml	GptComponentMetadata
コネクターアクション（汎用）	templates/actions/connector-action.mcs.yml	コネクターを使用する TaskDialog（構造上の参照）
ナレッジ（公開 Web サイト）	templates/knowledge/public-website.knowledge.mcs.yml	PublicSiteSearchSource
ナレッジ（SharePoint）	templates/knowledge/sharepoint.knowledge.mcs.yml	SharePointSearchSource
グローバル変数	templates/variables/global-variable.variable.mcs.yml	GlobalVariableComponent