int-reference
Reference tables for Copilot Studio YAML authoring: triggers, actions, variables, entities, Power Fx functions, templates. Preloaded by author and advisor agents.
microsoft · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add microsoft/skills-for-copilot-studio --skill int-referenceAbout this skill
name: int-reference description: "Reference tables for Copilot Studio YAML authoring: triggers, actions, variables, entities, Power Fx functions, templates. Preloaded by author and advisor agents." user-invocable: false
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
Read the complete source ↗