microsoft/int-reference

Copilot Studio YAML Reference

Core File Types

| File | Purpose | |------|---------| | agent.mcs.yml | Main agent metadata (kind: GptComponentMetadata) | | settings.mcs.yml | Agent settings and configuration | | connectionreferences.mcs.yml | Connector references | | topics/*.mcs.yml | Conversation topics (kind: AdaptiveDialog) | | actions/*.mcs.yml | Connector-based actions (kind: TaskDialog) | | knowledge/*.mcs.yml | Knowledge sources (kind: KnowledgeSourceConfiguration) | | variables/*.mcs.yml | Global variables (kind: GlobalVariableComponent) | | agents/*.mcs.yml | Child agents (kind: AgentDialog) |

Trigger Types

Topics with OnRecognizedIntent have two routing mechanisms — which one matters depends on the orchestration mode:

• modelDescription — used by generative orchestration (GenerativeActionsEnabled: true). The AI orchestrator reads this to decide routing. Primary mechanism for generative agents.
• Trigger phrases (triggerQueries) — used by classic orchestration. Pattern-matched against the user's utterance. Secondary hints when generative orchestration is enabled.

System triggers (OnConversationStart, OnUnknownIntent, OnError, etc.) fire automatically and don't use either mechanism.

| Kind | Purpose | |------|---------| | OnRecognizedIntent | Trigger phrases matched | | OnConversationStart | Conversation begins | | OnUnknownIntent | No topic matched (fallback) | | OnEscalate | User requests human agent | | OnError | Error handling | | OnSystemRedirect | Triggered by redirect only | | OnSelectIntent | Multiple topics matched (disambiguation) | | OnSignIn | Authentication required | | OnToolSelected | Child agent invocation | | OnKnowledgeRequested | Custom knowledge source search triggered (YAML-only, no UI) | | OnGeneratedResponse | Intercept AI-generated response before sending | | OnOutgoingMessage | Non-functional (2026-03-15) — exists in schema but does not fire at runtime. Do not use. |

YAML-Only Features

These features work at runtime but are not visible in the Copilot Studio UI. Warn users that UI edits may silently remove them.

| Feature | Notes | |---------|-------| | triggerCondition on knowledge sources | The UI only exposes this as an on/off toggle (=false to exclude from UniversalSearchTool). Arbitrary Power Fx expressions (e.g., =Global.UserDepartment = "HR") work at runtime but can only be set via YAML. Use with caution. (2026-03-16) |

Action Types

| Kind | Purpose | |------|---------| | SendActivity | Send a message | | Question | Ask user for input | | SetVariable | Set/compute a variable (Power Fx expression, prefix =) | | SetTextVariable | Set a text variable using template interpolation ({}). Useful for converting non-text types (e.g., Number) to text: "You have {Topic.Count} items" | | ConditionGroup | Branching logic | | BeginDialog | Call another topic | | ReplaceDialog | Replace current topic | | EndDialog | End current topic | | CancelAllDialogs | Cancel all topics | | ClearAllVariables | Clear variables | | SearchAndSummarizeContent | Generative answers (grounded in knowledge) | | AnswerQuestionWithAI | AI answer (conversation history + general knowledge only) | | EditTable | Modify a collection | | CSATQuestion | Customer satisfaction | | LogCustomTelemetryEvent | Logging | | OAuthInput | Sign-in prompt | | SearchKnowledgeSources | Search knowledge sources (returns raw results, no AI summary) | | CreateSearchQuery | AI-generated search query from user input |

Connector Actions (TaskDialog)

Connector actions (kind: TaskDialog) invoke external connector operations. They are stored in actions/ and require a connection reference in connectionreferences.mcs.yml.

Use /add-action to create new actions from available connectors. The schema describes the structural properties of TaskDialog and InvokeConnectorTaskAction, but the specific inputs and outputs for each connector operation are connector-specific — use the connector lookup script (connector-lookup.bundle.js) to get the full operation details.

Action Structure

| Field | Purpose | |-------|---------| | kind: TaskDialog | Identifies this as a connector action | | inputs | Inputs: AutomaticTaskInput (AI-provided) or ManualTaskInput (fixed value) | | modelDisplayName | Display name for AI orchestrator routing | | modelDescription | Description for AI orchestrator routing | | outputs | Output property names returned by the connector | | action.kind | Always InvokeConnectorTaskAction for connector actions | | action.connectionReference | Logical name of the connection (registered in connectionreferences.mcs.yml) | | action.connectionProperties.mode | Maker (maker's credentials) or Invoker (end user's credentials) | | action.operationId | The connector's specific operation identifier | | outputMode | Usually All — exports all operation outputs |

Input Types

| Input Kind | Use When | Notes | |------------|----------|-------| | AutomaticTaskInput | The AI orchestrator should provide the value based on context | Includes description for the AI to understand what to provide | | ManualTaskInput | A fixed/hardcoded value (e.g., timezone, folder path) | Can only hardcode strings. Non-string values (IDs, enums) should be reviewed by the user after pushing |

$-Prefixed Property Names (SharePoint, OData)

Some connectors (notably SharePoint) use OData parameters like $filter, $orderby, $top. These require special quoting in TaskDialog YAML — both single and double quotes:

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

"'$filter'" means: the outer "" are YAML string delimiters; the inner '' are part of the literal value sent to the runtime. Using $filter, "$filter", or '$filter' alone will fail.

InvokeConnectorAction (inline in topics) uses a different format — the parameters/ prefix with no inner single quotes:

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

Never mix these two formats.

System Variables

| Variable | Description | |----------|-------------| | System.Bot.Name | Agent's name | | System.Activity.Text | User's current message | | System.Conversation.Id | Conversation identifier | | System.Conversation.InTestMode | True if in test chat | | System.FallbackCount | Number of consecutive fallbacks | | System.Error.Message | Error message | | System.Error.Code | Error code | | System.SignInReason | Why sign-in was triggered | | System.Recognizer.IntentOptions | Matched intents for disambiguation | | System.Recognizer.SelectedIntent | User's selected intent | | System.SearchQuery | AI-rewritten search query (available in OnKnowledgeRequested) | | System.KeywordSearchQuery | Keyword version of search query (available in OnKnowledgeRequested) | | System.SearchResults | Table to populate with custom search results — schema: Content, ContentLocation, Title (available in OnKnowledgeRequested) | | System.ContinueResponse | Set to false in OnGeneratedResponse to suppress auto-send | | System.Response.FormattedText | The AI-generated response text (available in OnGeneratedResponse) |

Variable Scopes

| Prefix | Scope | Lifetime | |--------|-------|----------| | Topic.<name> | Topic variable | Current topic only | | Global.<name> | Global variable | Entire conversation (defined in variables/ folder) | | System.<name> | System variable | Built-in, read-only |

Global variables are defined as YAML files in variables/<Name>.mcs.yml (kind: GlobalVariableComponent). aIVisibility accepts UseInAIContext (orchestrator can read and reason about the value) or Hidden (orchestrator unaware — use for flags and internal bookkeeping).

Prebuilt Entities

| Entity | Use Case | |--------|----------| | BooleanPrebuiltEntity | Yes/No questions | | NumberPrebuiltEntity | Numeric inputs | | StringPrebuiltEntity | Free text | | DateTimePrebuiltEntity | Date/time | | EMailPrebuiltEntity | Email addresses |

Power Fx Expression Reference

Only use functions from the supported list below. Copilot Studio supports a subset of Power Fx — using unsupported functions will cause errors.

# 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

Supported Power Fx Functions

These are all the Power Fx functions available in Copilot Studio. Do NOT use any function not on this list.

Math: 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

Text: 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/Time: Date, DateAdd, DateDiff, DateTime, DateTimeValue, DateValue, Day, EDate, EOMonth, Hour, IsToday, Minute, Month, Now, Second, Time, TimeValue, TimeZoneOffset, Today, Weekday, WeekNum, Year

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

Table: 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

Aggregate: Average, Max, Min, StdevP, VarP

Type conversion: AsType, Boolean, Dec2Hex, Decimal, Float, GUID, Hex2Dec, JSON, ParseJSON

Other: Blank, ColorFade, ColorValue, Error, Language, OptionSetInfo, RGBA, Trace, With

Available Templates

Templates are bundled with the plugin. Skills that use templates reference them via ${CLAUDE_SKILL_DIR}/../../templates/.

| Template | File | Pattern | |----------|------|---------| | Greeting | templates/topics/greeting.topic.mcs.yml | OnConversationStart welcome | | Fallback | templates/topics/fallback.topic.mcs.yml | OnUnknownIntent with escalation | | Arithmetic | templates/topics/arithmeticsum.topic.mcs.yml | Inputs/outputs with computation | | Question + Branching | templates/topics/question-topic.topic.mcs.yml | Question with ConditionGroup | | Knowledge Search | templates/topics/search-topic.topic.mcs.yml | SearchAndSummarizeContent fallback | | Custom Knowledge Source | templates/topics/custom-knowledge-source.topic.mcs.yml | OnKnowledgeRequested with custom API (YAML-only) | | Remove Citations | templates/topics/remove-citations.topic.mcs.yml | OnGeneratedResponse citation stripping | | Authentication | templates/topics/auth-topic.topic.mcs.yml | OnSignIn with OAuthInput | | Error Handler | templates/topics/error-handler.topic.mcs.yml | OnError with telemetry | | Disambiguation | templates/topics/disambiguation.topic.mcs.yml | OnSelectIntent flow | | Agent | templates/agents/agent.mcs.yml | GptComponentMetadata | | Connector Action (generic) | templates/actions/connector-action.mcs.yml | TaskDialog with connector (structural reference) | | Knowledge (Public Website) | templates/knowledge/public-website.knowledge.mcs.yml | PublicSiteSearchSource | | Knowledge (SharePoint) | templates/knowledge/sharepoint.knowledge.mcs.yml | SharePointSearchSource | | Global Variable | templates/variables/global-variable.variable.mcs.yml | GlobalVariableComponent |