/int-reference

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