int-reference

Copilot Studio YAML 参考

核心文件类型

文件	用途
agent.mcs.yml	Agent 主元数据（kind: GptComponentMetadata）
settings.mcs.yml	Agent 设置和配置
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	子 Agent（kind: AgentDialog）

触发器类型

带有 OnRecognizedIntent 的主题有两种路由机制，具体取决于编排模式：

• modelDescription — 用于生成式编排（GenerativeActionsEnabled: true）。AI 编排器会读取此内容来决定路由。这是生成式 Agent 的主要机制。
• 触发短语（triggerQueries）— 用于经典编排。通过模式匹配用户的话语。启用生成式编排时，它们是次要提示。

系统触发器（OnConversationStart、OnUnknownIntent、OnError 等）会自动触发，不使用上述任一机制。

Kind	用途
OnRecognizedIntent	匹配触发短语
OnConversationStart	对话开始
OnUnknownIntent	未匹配到主题（回退）
OnEscalate	用户请求人工 Agent
OnError	错误处理
OnSystemRedirect	仅由重定向触发
OnSelectIntent	匹配到多个主题（消歧）
OnSignIn	需要身份验证
OnToolSelected	调用子 Agent
OnKnowledgeRequested	触发自定义知识源搜索（仅 YAML，不在 UI 中显示）
OnGeneratedResponse	发送前拦截 AI 生成的回复
OnOutgoingMessage	不生效（2026-03-15） — 存在于架构中，但运行时不会触发。请勿使用。

仅限 YAML 的功能

这些功能在运行时有效，但不会显示在 Copilot Studio UI 中。请提醒用户，UI 编辑可能会悄无声息地移除这些功能。

功能	说明
知识源上的 triggerCondition	UI 仅将其显示为开关（=false 可将其从 UniversalSearchTool 中排除）。任意 Power Fx 表达式（例如 =Global.UserDepartment = "HR"）在运行时有效，但只能通过 YAML 设置。请谨慎使用。（2026-03-16）

操作类型

Kind	用途
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 搜索查询

Connector 操作（TaskDialog）

Connector 操作（kind: TaskDialog）会调用外部 Connector 操作。它们存储在 actions/ 中，并且需要在 connectionreferences.mcs.yml 中引用连接。

使用 /add-action 根据可用的 Connector 创建新操作。 架构描述了 TaskDialog 和 InvokeConnectorTaskAction 的结构属性，但每个 Connector 操作的具体输入和输出因 Connector 而异 — 使用 Connector 查找脚本（connector-lookup.bundle.js）获取完整的操作详情。

操作结构

字段	用途
kind: TaskDialog	标识这是一个 Connector 操作
inputs	输入：AutomaticTaskInput（由 AI 提供）或 ManualTaskInput（固定值）
modelDisplayName	用于 AI 编排器路由的显示名称
modelDescription	用于 AI 编排器路由的描述
outputs	Connector 返回的输出属性名称
action.kind	Connector 操作始终为 InvokeConnectorTaskAction
action.connectionReference	连接的逻辑名称（在 connectionreferences.mcs.yml 中注册）
action.connectionProperties.mode	Maker（创建者的凭据）或 Invoker（最终用户的凭据）
action.operationId	Connector 的特定操作标识符
outputMode	通常为 All — 导出所有操作输出

输入类型

输入类型	使用场景	说明
AutomaticTaskInput	AI 编排器应根据上下文提供值	包含 description，帮助 AI 了解应提供什么
ManualTaskInput	固定/硬编码的值（例如，时区、文件夹路径）	只能硬编码字符串。非字符串值（ID、枚举）应在推送后由用户检查

$ 前缀属性名称（SharePoint、OData）

某些 Connector（尤其是 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'"

切勿混用这两种格式。

系统变量

变量	说明
System.Bot.Name	Agent 的名称
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>	系统变量	内置，只读

全局变量以 YAML 文件形式定义，路径为 variables/<Name>.mcs.yml（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 流程
Agent	templates/agents/agent.mcs.yml	GptComponentMetadata
连接器操作（通用）	templates/actions/connector-action.mcs.yml	使用连接器的 TaskDialog（结构参考）
知识（公共网站）	templates/knowledge/public-website.knowledge.mcs.yml	PublicSiteSearchSource
知识（SharePoint）	templates/knowledge/sharepoint.knowledge.mcs.yml	SharePointSearchSource
全局变量	templates/variables/global-variable.variable.mcs.yml	GlobalVariableComponent