int-reference

by microsoft

Reference tables for Copilot Studio YAML authoring: triggers, actions, variables, entities, Power Fx functions, templates. Preloaded by author and troubleshoot… npx skills add https://github.com/microsoft/skills-for-copilot-studio --skill int-reference Download ZIPGitHub345

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