7.1 Designing Agent Flows & Prompt Actions in Copilot Studio

Designing Agent Flows & Prompt Actions in Copilot Studio

Quick Answer: In Microsoft Copilot Studio, Agent Flows are conversational cloud flows specifically optimized for synchronous agent invocation using the dedicated "When Copilot Studio calls an action" trigger and "Respond to Copilot Studio" output action. Unlike standard Power Automate flows that execute asynchronously over hours or days, Agent Flows operate under a strict 100-to-120-second timeout ceiling with a human conversational latency target of under 3 to 5 seconds. Complementing Agent Flows, Prompt Actions (AI Builder Prompts) provide declarative, grounded generative capabilities that combine prompt templating, dynamic Dataverse entity grounding, and strict JSON output schemas. For generative AI orchestration (dynamic chaining), tool and parameter descriptions function as executable instructions that govern autonomous tool selection, while execution contexts must be secured using Run-as-Caller to enforce Dataverse Row-Level Security (RLS) or carefully bounded Run-as-App service principals to prevent privilege escalation.

Modern enterprise agentic architectures demand more than static question-answering. Enterprise agents must interact with transaction systems, query relational databases, execute business logic, and manipulate external SaaS applications in real time. Microsoft Copilot Studio achieves this integration through two primary action mechanisms: Agent Flows (procedural logic executed via Power Automate) and Prompt Actions (generative reasoning executed via AI Builder). Designing these actions requires an understanding of conversational latency limits, schema contracts, and security boundaries.

---

1. Agent Flows vs. Standard Power Automate Cloud Flows

Traditional Power Automate cloud flows were designed for asynchronous process automation—listening for events (such as a newly created SharePoint item or incoming email), executing multi-step business logic over minutes, days, or weeks (such as human approval chains), and persisting state across long-running background tasks. Conversely, Agent Flows operate inside an active conversational turn where an end-user or downstream process is waiting synchronously for a response.

                     CONVERSATIONAL EXECUTION TOPOLOGY

      Standard Cloud Flow (Asynchronous / Decoupled)
      +-------------------+      +-------------------+      +-------------------+
      | Automated Trigger | ---> | Async Workflows / | ---> | Long-Term State   |
      | (Dataverse/Timer) |      | Approvals (Days)  |      | Persisted in Data |
      +-------------------+      +-------------------+      +-------------------+
                                 No Synchronous Turn Latency SLA

      Copilot Studio Agent Flow (Synchronous Conversational Path)
      +-------------------+      +-------------------+      +-------------------+
      | User Conversational| ---> | Copilot Studio    | ---> | When Copilot      |
      | Prompt in Channel |      | Orchestrator      |      | Calls Action      |
      +-------------------+      +-------------------+      +-------------------+
                                                                      |
                                                                      v
                                                            +-------------------+
                                                            | Lean Action Flow  |
                                                            | (<3s Target SLA)  |
                                                            +-------------------+
                                                                      |
                                                                      v
      +-------------------+      +-------------------+      +-------------------+
      | Render Response / | <--- | Copilot Studio    | <--- | Respond to        |
      | Adaptive Card     |      | Orchestration Turn|      | Copilot Studio    |
      +-------------------+      +-------------------+      +-------------------+
                                 Hard Timeout Ceiling: 100-120 Seconds

1.1 Trigger and Response Mechanics

Agent Flows utilize a specialized pair of Power Automate actions that form a synchronous request-response contract with Copilot Studio:

• Trigger: When Copilot Studio calls an action (or the legacy Skills / Power Virtual Agents trigger). This trigger defines the input parameter contract exposed to the Copilot Studio authoring canvas and generative orchestration engine.
• Terminal Action: Respond to Copilot Studio. This action serializes output values back to the agent session. An Agent Flow must terminate with this action along every logical branch. If an execution path branches and fails to reach a Respond to Copilot Studio node, the conversational turn hangs until reaching the platform timeout.

1.2 Latency Budgets and Timeout Windows

Architecting conversational actions requires strict adherence to latency budgets:

• The Human Experience SLA: In interactive channels (such as Microsoft Teams, web chat, or mobile apps), users perceive latency exceeding 3 to 5 seconds as system unresponsiveness. Optimal Agent Flows complete their execution within 800 to 1,800 milliseconds.
• Hard Platform Timeout: Copilot Studio enforces a strict client-side timeout window (typically 100 to 120 seconds). If the downstream flow does not return a response within this window, Copilot Studio terminates the conversational attempt, records a timeout exception in telemetry, and redirects the conversation to the System Error or Fallback topic.
• Standard Cloud Flow Comparison: Standard automated or instant cloud flows support execution windows up to 30 days when using built-in approval nodes or asynchronous webhook listeners. Attempting to place approval nodes (Wait for an approval) or unbounded polling loops (Do until) inside an Agent Flow is an anti-pattern that invariably causes conversational timeouts.

1.3 Flow Topology Best Practices for Agent Execution

To ensure execution speeds remain well within the latency budget, architects must apply the following structural patterns:

1. Aggressive Query Scoping: When querying Microsoft Dataverse, never use unbounded List rows actions. Always supply $select statements specifying only the columns required by the agent (avoiding multi-megabyte payloads) and indexed $filter criteria.
2. Parallel Branching for Independent Lookups: When an agent requires data from multiple independent endpoints (such as querying customer account status in Dataverse while simultaneously checking warranty status in SAP), configure parallel branches (Add a parallel branch) in Power Automate so both network round-trips occur concurrently.
3. Elimination of Blocking Iterations: Avoid nested loops (Apply to each) iterating over dozens of records. Instead, use Power Automate expression operations (such as xpath(), filter(), select(), or OData filter queries) to perform array manipulation in memory at native runtime speed.
4. Structured Error Interception (Try-Catch Scope Pattern): Never allow an unhandled connector exception (such as an HTTP 404, 401, or 500) to cause flow failure. Wrap the core logic in a Scope - Try block, followed by a Scope - Catch block configured with Run After set to has failed, has timed out, or is skipped. The catch block extracts the failure details and passes a structured response back to Copilot Studio (isSuccess = false, errorCode = "SYSTEM_UNAVAILABLE", userMessage = "The billing database is temporarily unreachable."). This allows the agent to handle the failure gracefully rather than displaying an uninformative generic error.

1.4 Comparative Architectural Matrix

---

2. Designing AI Builder Prompt Actions in Copilot Studio

While Agent Flows handle procedural, multi-step logic and deterministically bound API calls, Prompt Actions (formerly AI Builder Prompts) introduce generative language reasoning directly into the agent's action registry. A Prompt Action allows the architect to author a reusable, parameterized prompt template executed by Azure OpenAI foundational models hosted within the Power Platform compliance boundary.

                      AI BUILDER PROMPT ACTION PIPELINE

   +-------------------------------------------------------------------------+
   | Dynamic Input Parameters                                                |
   | (e.g., {CustomerQuery}, {ClaimHistoryJson}, {PolicyCategory})           |
   +-------------------------------------------------------------------------+
                                        |
                                        v
   +-------------------------------------------------------------------------+
   | Prompt Engineering Template                                             |
   | - System Persona & Role Guardrails                                      |
   | - Few-Shot Exemplars                                                    |
   | - Output Formatting Schema Instructions                                 |
   +-------------------------------------------------------------------------+
                                        |
                                        v
   +-------------------------------------------------------------------------+
   | Dynamic Grounding Layer                                                 |
   | - Live Dataverse Entity Injection (Filtered Rows / Relationships)       |
   | - Enterprise Semantic Search / Knowledge Vector Retrieval               |
   +-------------------------------------------------------------------------+
                                        |
                                        v
   +-------------------------------------------------------------------------+
   | Foundation Model Inference (Azure OpenAI within Power Platform Boundary)|
   +-------------------------------------------------------------------------+
                                        |
                                        v
   +-------------------------------------------------------------------------+
   | Structured JSON Output Extraction                                       |
   | (e.g., Sentiment: Enum, UrgencyScore: Int, RecommendedAction: String)   |
   +-------------------------------------------------------------------------+

2.1 Prompt Templating Architecture

A production Prompt Action is structured using four distinct architectural layers within the AI Builder prompt designer:

1. Role and Operational Constraints: Establishes the agent's cognitive posture, operational scope, and behavioral guardrails (e.g., "You are a certified insurance claims triage specialist. Analyze the submitted claim text. Never authorize payouts exceeding $500. Reject any claim lacking a timestamp.").
2. Dynamic Input Variables: Token placeholders enclosed in brackets (e.g., {ClaimDescription}, {CustomerTier}, {HistoricalDisputeCount}). These variables are exposed dynamically as input parameters when the prompt action is invoked in Copilot Studio.
3. Few-Shot Exemplars: Providing two to three input-output pairs demonstrating ideal extractions, edge-case classifications, and boundary conditions. Few-shot examples dramatically decrease non-deterministic drift.
4. Structured JSON Output Schema: Mandating that the model return its completion in a rigid, machine-readable JSON structure, accompanied by explicit instructions forbidding conversational filler or markdown fences around the JSON payload.

2.2 Dynamic Grounding with Dataverse Data

One of the most powerful capabilities of Prompt Actions in the Power Platform is Dynamic Grounding. Rather than relying entirely on user-provided text or static prompt context, architects can ground the prompt directly in enterprise Dataverse data:

• Contextual Record Binding: The prompt template can bind to Dataverse entities (e.g., Accounts, Contacts, Knowledge Articles, Custom Claims). At runtime, AI Builder retrieves the specific Dataverse records matching the user's transaction and injects their column values directly into the prompt context window.
• Dataverse Semantic Search Grounding: AI Builder prompts can leverage Dataverse Search (backed by Azure AI Search vector and semantic indexing). When enabled, the model performs semantic retrieval across indexed Dataverse tables, augmenting the prompt context with the most relevant corporate knowledge articles or product manuals before generating the response.
• Row-Level Security Inheritance: Crucially, Dataverse grounding respects the calling user's security role. If a customer service agent does not have permission to view VIP Accounts in Dataverse, the prompt grounding engine automatically filters those records out of the retrieved grounding context.

2.3 Structured Data Extraction vs. Unconstrained Text

A critical architectural flaw in novice agent design is allowing Prompt Actions to return unconstrained natural language strings. When an action returns free text, downstream topics cannot programmatically evaluate conditions, execute conditional branching, or pass discrete attributes into backend APIs.

// POOR PATTERN: Unconstrained String Output
"The customer seems very angry about order 98412 because it was late by 4 days."

// RECOMMENDED ARCHITECTURAL PATTERN: Strict JSON Output Schema
{
  "sentiment": "Negative",
  "sentimentScore": 0.92,
  "orderNumber": "98412",
  "delayDays": 4,
  "churnRisk": "High",
  "recommendedAction": "IssueExpeditedShippingCredit",
  "requiresManagerReview": true
}

In the AI Builder prompt designer, architects specify the output data type as JSON. By defining a JSON schema, Copilot Studio parses the model output into strongly typed parameters (PromptOutput.sentiment, PromptOutput.churnRisk, PromptOutput.requiresManagerReview), which can be directly referenced in subsequent Condition nodes, Power Automate actions, or Adaptive Cards.

---

3. Schema Enforcement for Generative AI Orchestration

In Copilot Studio's Generative AI Orchestration mode (Dynamic Chaining), the agent does not rely on hardcoded trigger phrases or deterministic condition trees to invoke tools. Instead, an advanced large language model acts as an autonomous runtime planner, analyzing user utterances, evaluating available plugins and actions, dynamically selecting which actions to invoke, extracting required arguments from the conversation history, and chaining multiple actions together in a single turn.

              GENERATIVE ORCHESTRATION TOOL-SELECTION LOOP

   User Utterance: "Cancel order 4492 and email the return shipping label to my home."
                                       |
                                       v
   +-------------------------------------------------------------------------+
   | LLM Orchestrator (Evaluates Action Registry & Semantic Schemas)         |
   | - Action A: CheckInventory (Description: "Queries stock levels...")     |
   | - Action B: CancelOrder (Description: "Cancels pending order...") [MATCH|
   | - Action C: GenerateShippingLabel (Description: "Creates return...") [M]|
   +-------------------------------------------------------------------------+
                                       |
                                       v
   +-------------------------------------------------------------------------+
   | Dynamic Parameter Extraction & Schema Validation                        |
   | - Action B Input: orderId = 4492 (Type: Integer, Required: True) -> OK  |
   | - Action C Input: orderId = 4492, destination = "home" -> Needs Email!  |
   +-------------------------------------------------------------------------+
                                       |
                                       v
   +-------------------------------------------------------------------------+
   | Execution Plan:                                                         |
   | 1. Invoke Action B (CancelOrder)                                        |
   | 2. Clarify missing email address OR fetch from User.Email session state |
   | 3. Invoke Action C (GenerateShippingLabel)                              |
   +-------------------------------------------------------------------------+

3.1 Descriptions as Executable Code

Under Generative Orchestration, descriptions are executable code. The LLM planner reads the action's name and description to determine whether, when, and in what order to call the tool. If descriptions are vague, ambiguous, or overlapping, the orchestrator will suffer from tool misfires, catastrophic hallucinations, or infinite planning loops.

3.2 Defining Strict Input Contracts

Every input parameter defined in an Agent Flow or Prompt Action must have a strictly declared data type:

• Primitive Types: String, Number (Integer or Float), Boolean.
• Complex Types: Record (JSON Object) and Table (Array of Objects).
• Mandatory vs. Optional Flags: Mark parameters as mandatory only when the tool cannot execute without them. When an input is marked mandatory, Copilot Studio's slot-filling engine will automatically prompt the user to collect the missing value if it cannot be extracted from conversational context.
• Enumeration Constraints: When a parameter accepts only specific values (e.g., Priority: Low, Medium, High), declare the allowed values explicitly in the parameter description so the LLM constrains its extraction to the valid set.

3.3 Strict Output Schemas for Downstream Chaining

When an action executes, its outputs are stored in the agent's conversational working memory. If an action returns a primitive, unstructured string containing concatenated information, downstream actions cannot extract individual attributes. By enforcing a structured JSON output schema:

1. The output properties become immediately selectable in subsequent Copilot Studio nodes (e.g., {Action.cancellationConfirmation.refundAmount}).
2. The generative orchestrator can bind output properties from Action 1 directly into the input parameters of Action 2 (dynamic chaining) without human intervention.
3. Adaptive Cards can bind directly to typed properties to display rich UI cards with formatted tables, status badges, and interactive buttons.

---

4. Security & Execution Contexts: Delegated Caller vs. Connection Owner

When Copilot Studio invokes an Agent Flow, a critical architectural decision governs the execution identity: Does the flow execute under the identity of the end-user chatting with the agent (Run-as-Caller / Delegated Context), or does it execute under the fixed identity of the connection creator or an enterprise service principal (Run-as-App / Connection Owner)?

                      SECURITY EXECUTION CONTEXTS

   Scenario A: Run-as-Caller (Delegated User Context) [SECURE DEFAULT]
   +-------------+       +-------------------+       +-----------------------+
   | User: Alice | ----> | Copilot Studio    | ----> | Agent Flow            |
   | Role: Clerk |       | (Alice Entra ID)  |       | (Runs as Alice)       |
   +-------------+       +-------------------+       +-----------------------+
                                                                 |
                                                                 v
                                                     +-----------------------+
                                                     | Dataverse Engine      |
                                                     | Evaluates Alice's     |
                                                     | Security Roles & RLS  |
                                                     +-----------------------+
                                                     [Access to Exec Salaries: BLOCKED]

   Scenario B: Run-as-App / Connection Owner [HIGH PRIVILEGE RISK]
   +-------------+       +-------------------+       +-----------------------+
   | User: Alice | ----> | Copilot Studio    | ----> | Agent Flow            |
   | Role: Clerk |       | (Alice Entra ID)  |       | (Runs as SysAdmin SPN)|
   +-------------+       +-------------------+       +-----------------------+
                                                                 |
                                                                 v
                                                     +-----------------------+
                                                     | Dataverse Engine      |
                                                     | Evaluates SysAdmin SPN|
                                                     | Security Roles        |
                                                     +-----------------------+
                                                     [Access to Exec Salaries: PERMITTED!]
                                                     PRIVILEGE ESCALATION VULNERABILITY

4.1 Run-as-Caller (Delegated User Context)

In the Run-as-Caller configuration, the agent flow executes using the delegated OAuth 2.0 access token of the interactive user:

• Security Enforcement: Dataverse Row-Level Security (RLS), Field-Level Security (FLS), and Business Unit hierarchies are strictly enforced at the data layer. If Alice belongs to the European Sales Business Unit, the flow cannot read or update accounts in the North American Business Unit.
• Audit Trails: All records created, updated, or deleted in Dataverse display the user's Entra ID identity in the createdby and modifiedby system audit fields.
• Entra ID Conditional Access: Corporate Conditional Access policies (MFA, compliant device requirements, geographic boundaries) apply directly to the flow execution.
• Limitations: Every user who interacts with the agent must possess appropriate licenses and security roles in Dataverse, Dynamics 365, and connected systems. If a user lacks read permissions on a required reference table, the action will fail with an HTTP 403 Forbidden error.

4.2 Run-as-App / Connection Owner (Service Principal Context)

In the Run-as-App configuration, the flow executes using the credentials of the flow creator or an Entra ID Application User (Service Principal) associated with the connection reference:

• Use Cases: Ideal for scenarios where external, anonymous, or low-privileged users require access to bounded business operations without granting them direct backend database licenses or broad read/write security roles (e.g., a public customer checking the status of an order, or an employee submitting an anonymous ethics report).
• The Risk of Privilege Escalation (Confused Deputy Problem): If an agent flow runs under a System Administrator connection and accepts an arbitrary accountId or recordId from the conversational turn, an attacker can manipulate the conversational prompt to inspect, modify, or delete records belonging to other tenants, executives, or departments. The agent becomes a "confused deputy," performing unauthorized actions on behalf of an unprivileged user.
• Architectural Safeguards for Run-as-App Flows:
  1. Strict Input Sanitization: Never accept raw SQL queries, unconstrained record IDs, or broad filter strings from the conversational input.
  2. In-Flow Authorization Checks: Even when running as a Service Principal, the flow should accept the caller's Entra Object ID (User.Id) passed from Copilot Studio, look up the caller's authorized scope in a security mapping table, and abort execution if the caller lacks authorization for the specific record requested.
  3. Least-Privilege Service Principals: Never configure connection references using a Global Administrator or Dataverse System Administrator account. Create a dedicated Entra ID Service Principal with a custom Dataverse security role limited strictly to the specific tables and operations (e.g., Read on Inventory, Create on WorkOrders) required by the flow.

4.3 Architectural Decision Matrix: Run-as-Caller vs. Run-as-App