These patterns represent proven approaches for implementing Microsoft AI solutions. Each pattern includes clear guidance on when to use it and when to avoid it.

Use this page when you’ve identified a likely platform choice and want an execution-ready shape for delivery. Patterns are designed to be composable: it’s common to start with one pattern for speed (e.g., Copilot Studio) and adopt another as requirements mature (e.g., Azure-hosted orchestration).

Table of contents

Pattern 1: Start in Studio, Scale with Azure

Approach:

  1. Launch in Copilot Studio to capture instructions, knowledge sources, and connectors with low-code orchestration.1
  2. Publish to the Microsoft 365 channel (Teams, Outlook, Copilot Chat) to validate adoption and governance early.2
  3. Add approvals, analytics, and DLP controls through Power Platform admin policies while you refine prompts and topic structure.1
  4. Break down responsibilities into child and connected agents so specialized copilots can collaborate while you stay in the maker canvas.3
  5. When orchestration or private hosting requirements emerge, keep Copilot Studio as the front door while introducing Microsoft Foundry Agent Service plus Agent Framework workflows, and expose the orchestrator back through Copilot Studio or the Microsoft 365 Agents SDK.456

Strengths:

  • Fastest time-to-value for low/medium complexity use cases; aligns with makers in the Evaluation Criteria skills matrix.
  • Reuses Power Platform connectors and managed capacity instead of standing up Azure infrastructure.
  • Built-in analytics, transcript review, and admin approvals support early compliance conversations.
  • Connected and child agents let you validate multi-agent responsibilities before handing orchestration to pro-code teams.3

Trade-offs:

  • Advanced orchestration, custom routing, or strict VNet isolation still require an Azure landing zone.4
  • Connected agents are Preview and require agents to live in the same environment; plan ALM accordingly.3
  • Service-account execution must be reviewed to avoid over-privileged actions (align with the Action Safety Guardrail Playbook).
  • Consumption is metered per message, so sustained high-volume scenarios should model capacity vs. Azure consumption costs before scaling.

Signals this fits (Evaluation Criteria crosswalk):

  • Time-to-production measured in days → weeks.
  • Teams have makers or mixed maker/dev skill sets.
  • Budget tolerance focused on managed SaaS (Copilot Studio capacity) rather than Azure infrastructure.

When to pivot: Move to Pattern 2 or 4 when pro-code teams need sustained control across channels, or Pattern 5 if Agent Framework orchestration becomes the primary investment.

Sources:

Status: Recommended pattern for proofs of concept and iterative delivery Confidence Level: High (official Microsoft guidance)

Pattern 2: Pro-Code First, Surface in Copilot

Approach:

  1. Design and build in Microsoft Foundry or Microsoft Foundry Agent Service to control model selection, prompt flow evaluations, and custom toolchains.4
  2. Implement RAG with Azure AI Search, Cosmos DB, or SQL Server 2025 (native vector support) depending on data gravity.7
  3. Host the agent in Azure services you already operate (Container Apps, App Service, AKS) so networking, logging, and secrets align with your landing zone standards.8
  4. Expose the experience inside Microsoft 365 through API plugins or custom engine agents created with the Microsoft 365 Agents SDK.910

Strengths:

  • Full control over orchestration, latency budgets, and data residency; ideal for high/very high complexity use cases in the Evaluation Criteria.
  • Reuses existing Azure engineering investments (policy, monitoring, private endpoints).
  • Flexible channel reach - web, mobile, Microsoft 365, or bespoke user interfaces - using the Agents SDK as a distribution path.10

Trade-offs:

  • Requires dedicated engineering capacity (pro developers, DevOps) and longer lead time (weeks → months).
  • Azure consumption costs accumulate across hosting, vector stores, and observability; financial modeling is required up front.
  • Teams must implement Responsible AI controls (content safety, approvals) themselves or integrate Azure services such as AI Content Safety.

Signals this fits:

  • You already operate an Azure landing zone with security/compliance guardrails.
  • Teams have the pro developer profile in Evaluation Criteria, including infrastructure ownership.
  • Use case demands deterministic orchestration, custom metrics, or hybrid channel support.

When to pivot: If the pilot stalls due to skill or budget constraints, return to Pattern 1 to validate scope, or move to Pattern 4 when multi-channel distribution is required but you can partner with product teams for shared orchestration.

Sources:

Status: Recommended when enterprise teams lead with Azure-first architecture Confidence Level: High (official Microsoft guidance + internal comparison tables)

Pattern 3: Microsoft 365 Knowledge Grounding

Approach:

  1. Add SharePoint, OneDrive, and Teams knowledge sources directly in Copilot Studio so the agent grounds answers in tenant-secured content with security trimming.11
  2. Configure a declarative agent (Copilot Studio or Microsoft 365 Agents Toolkit) that references those knowledge sources and provides conversation starters aligned to business vernacular.12
  3. Extend coverage with Microsoft 365 Copilot connectors when you need external line-of-business or third-party content indexed into Microsoft 365 Search and Copilot experiences.13
  4. Optionally attach API plugins for light actions (create tickets, file requests) while keeping the agent primarily read-oriented.9
  5. Publish to Microsoft 365 Copilot or Teams to meet users where they already work; analytics and governance stay inside Microsoft 365.2

Strengths:

  • Safest path for read-only experiences; inherits Microsoft 365 identity, compliance, and data loss prevention controls without extra infrastructure.11
  • Minimal build effort. Aligns with low complexity / low budget profiles in Evaluation Criteria while improving search and retrieval outcomes.
  • Scales rapidly because indexing, security trimming, and citations are handled by Microsoft 365 knowledge services.

Trade-offs:

  • Limited to knowledge sources supported by Copilot Studio and Microsoft 365 Copilot connectors; large unstructured repositories may require Azure AI Search (Pattern 2).
  • Declarative agents rely on prompt engineering rather than custom orchestration; cannot enforce complex workflows without escalating to Patterns 1 or 4.
  • Agent Builder knowledge sources have strict limits (public URL depth, URL count, file limits) and can’t fully block general AI knowledge; use Copilot Studio when you need strict grounding controls.14
  • Actions via API plugins introduce consent prompts and require ongoing API management.

Signals this fits:

  • Goal is improved knowledge discovery, policy lookup, or FAQ automation.
  • Users will consume the agent inside Microsoft 365 applications.
  • Governance stakeholders need confidence that the agent cannot mutate records without explicit approvals.
  • Business owners want to keep delivery within the Microsoft 365 licensing boundary before investing in Azure infrastructure.

When to pivot: Add Pattern 1 when you need richer Power Platform actions, or Pattern 2 when integrating large non-Microsoft 365 datasets or when RAG precision/latency must be tuned outside Microsoft Search.

Sources:

Status: Recommended for M365-centric knowledge scenarios Confidence Level: High (official Microsoft guidance)

Pattern 4: Multi-Channel Custom Engine Agent with M365 Agents SDK

Approach:

  1. Scaffold a custom engine agent with the Microsoft 365 Agents Toolkit in Visual Studio/VS Code so you get channel adapters, debugging playground, and deployment templates out of the box.15
  2. Implement orchestration inside the agent container. Prefer Microsoft Agent Framework for multi-agent workflows, or plug in your existing orchestrator through the SDK’s activity pipeline.510
  3. Connect enterprise knowledge and actions by wiring Azure AI Search, Azure OpenAI, Microsoft Graph connectors, or first-party APIs behind secured tool handlers.16
  4. Configure channel reach and authentication using the Agents SDK adapters (Copilot, Teams, custom web, Direct Line) and align identity with Entra ID scopes.10
  5. Deploy the agent to your Azure landing zone (Container Apps, App Service, AKS) and publish through the Agents Toolkit so Microsoft 365 users can discover it in Copilot while other apps call the same endpoint.1517

Strengths:

  • Full control over orchestration, tooling, telemetry, and hosting. Fits high/very high complexity profiles in Evaluation Criteria.16
  • Single codebase can service Microsoft 365 Copilot, Teams, custom web or mobile clients using built-in channel adapters.15
  • Integrates cleanly with existing Azure DevSecOps practices (CI/CD, logging, private networking) and reusable agent components.15

Trade-offs:

  • Requires pro-code engineering, multi-environment CI/CD, and sustained ownership. Time-to-production is typically weeks → months.16
  • Agent Framework capabilities are GA; monitor release notes for incremental API updates.5
  • Because you bring your own orchestrator and tooling, you own Responsible AI guardrails (content safety, approvals, auditing) inside the agent container.10

Signals this fits:

  • You already run orchestrators or LLM infrastructure in Azure and need to surface them inside Microsoft 365.16
  • Product teams need channel-specific behaviors (Teams meetings, custom apps) beyond what Copilot Studio supports.10
  • Security/compliance teams require fine-grained control over networking, secrets, and approvals.15

When to pivot: Use Pattern 2 if the experience will remain outside Microsoft 365, or Pattern 1/3 when low-code teams can deliver the scenario faster without custom hosting.

Sources:

Status: Recommended for enterprise-grade, pro-code agents spanning multiple channels Confidence Level: High (Agents SDK GA, Agent Framework GA)

Pattern 5: Multi-Agent Workflows with Microsoft Agent Framework

Approach:

  1. Model the orchestration in Agent Framework Workflows to get type-safe executors, edges, and validation before anything runs.18
  2. Stand up specialized agents (Microsoft Foundry Agent Service, Microsoft Foundry, or custom ChatClient agents) and register them as workflow executors.1920
  3. Choose the right orchestration pattern (Sequential, Concurrent, Handoff, Group Chat, or Magentic) and configure routing rules that match each agent’s responsibilities.21
  4. Add reliability primitives like checkpointing, event streaming, and human-in-the-loop gates before hosting the workflow runtime.22
  5. Expose the orchestrator through your preferred surface (M365 Agents SDK, web API, Logic Apps trigger) so downstream channels can invoke the multi-agent workflow. Use the AG-UI protocol (Preview) when you need streaming, shared state, or human-approval experiences in custom web or mobile clients.1023

Strengths:

  • Purpose-built for complex, multi-step collaboration with first-class orchestration patterns.21
  • Strong typing, validation, and checkpointing reduce runtime surprises in long-running or regulated processes.1822
  • Works with Microsoft Foundry Agent Service or persistent Foundry agents, letting you reuse enterprise-grade agents inside coordinated workflows.1920
  • Surfaces advanced UI experiences through the AG-UI protocol with Server-Sent Events streaming, backend tool rendering, and human-in-the-loop approvals.23

Trade-offs:

  • Microsoft Agent Framework is GA; monitor release notes for incremental updates.24
  • Advanced orchestration features (for example, Magentic) remain experimental and require tolerance for pre-release quality.21
  • Engineering teams must own hosting, monitoring, and Responsible AI guardrails across all agents in the workflow.25

Signals this fits:

  • A single agent can’t reliably complete the workflow; each task needs a specialized agent or tool chain.25
  • You need deterministic control over multi-agent routing, sequencing, or human approvals.18
  • Teams already build in .NET or Python and can maintain preview SDKs.24

When to pivot: Stay with Patterns 1–4 when a single agent or low-code orchestration meets the requirement; Agent Framework adds value only once coordination overhead is justified.25

Sources:

Status: Microsoft Agent Framework (GA); Microsoft Foundry Agent Service (GA) Confidence Level: High (GA framework + GA runtime)

Pattern 6: Progressive Enhancement (Low-Code to Pro-Code Bridge)

Approach:

  1. Start: Build the core agent in Copilot Studio to handle standard intents, FAQs, and simple flows.
  2. Enhance (Reasoning): Swap the default model for a BYO Model from Microsoft Foundry (Azure) (e.g., a fine-tuned GPT-4o or specialized SLM) to improve domain-specific reasoning without changing the UI.26
  3. Extend (Orchestration): Identify complex, multi-step tasks that require advanced planning. Build these as Microsoft Foundry Agent Service agents.
  4. Connect: Use the Copilot Studio external agent connection (Preview) to let the Copilot Studio agent delegate these specific tasks to a Microsoft Foundry agent, then receive the result back to present to the user.27
  5. Share: Point both the Copilot Studio agent and the Microsoft Foundry agent to the same Azure AI Search index so they share a “brain” (knowledge base).28

Strengths:

  • Best of Both Worlds: Makers keep the low-code management canvas; developers get full control over the “hard parts” (reasoning/orchestration).
  • No Migration Cliff: You don’t have to throw away the Copilot Studio agent and rewrite it in Python just to add one complex feature.
  • Unified Governance: The “Front Door” (Copilot Studio) handles auth, channel publishing, and basic logging, while Azure handles the heavy compute.

Trade-offs:

  • Latency: Handoffs introduce a network hop between Copilot Studio and Azure.
  • Complexity: Requires managing two environments (Power Platform + Azure).
  • Preview Features: BYO Model and Agent Handoff are currently in Preview.

Signals this fits:

  • You have a working Copilot Studio agent but it struggles with one specific complex task.
  • You need a specialized model (e.g., medical/legal fine-tune) but want to keep the easy Teams integration of Copilot Studio.
  • You have a mixed team (Makers + Pro Devs) collaborating on the same bot.

When to pivot: If most of the agent’s logic is moving to Azure, switch to Pattern 2 (Pro-Code First) to reduce the overhead of the dual-stack approach.

Sources:

Status: Recommended for hybrid teams and scaling existing low-code agents Confidence Level: Medium (Relies on Preview features)

Pattern 7: Translytical Agent (Fabric + Power BI)

Approach:

  1. Ingest data into OneLake via Fabric shortcuts or pipelines to create a unified data estate.29
  2. Enable Fabric Data Agents (Preview) on your semantic models to allow conversational Q&A over structured data.30
  3. Use Translytical Task Flows (Preview) to embed “Action” buttons directly in Power BI reports, allowing users to trigger business processes (via Power Automate or Logic Apps) based on insights.31
  4. For custom scenarios, mirror Azure Cosmos DB for NoSQL into OneLake using Fabric mirroring (continuous backup required; analytics copy is read-only) to enable near real-time analytics without ETL.32

Strengths:

  • Zero-ETL: Analyzes data where it lives (OneLake/Cosmos DB) without moving it.
  • Actionable Insights: Closes the loop between “seeing a problem” (Analytics) and “fixing it” (Transaction) via Task Flows.
  • Business User Friendly: Users interact via chat (Fabric Copilot) or familiar Power BI interfaces.

Trade-offs:

  • Fabric Data Agents are for analytics retrieval, not general-purpose orchestration. They don’t “do” things outside of data analysis unless paired with Task Flows.
  • Translytical task flows are Preview and require preview features; PBIR/PBIP formats and Power BI Embedded are not supported.31
  • Requires Fabric capacity and appropriate licensing.

Signals this fits:

  • The primary goal is “Chat with Data” or “Insight-to-Action”.
  • Data gravity is in OneLake or SQL/Cosmos DB.
  • Users are analysts or business decision-makers using Power BI.

When to pivot: If you need complex multi-step orchestration beyond simple actions, use Pattern 5 (Agent Framework) and have it call Fabric APIs for data.

Sources:

Status: Recommended for Data-First / Analytics-First scenarios Confidence Level: Medium (Fabric Data Agents are Preview)

Pattern 8: Agentic DevOps Lifecycle

Approach:

  1. Plan: Developer assigns a task (refactor, test, feature) to GitHub Copilot Coding Agent via a GitHub Issue.
  2. Code: Coding Agent autonomously creates a branch, writes code, runs tests, and opens a Pull Request.
  3. Review: Developer reviews the PR in VS Code (Agent Mode) or GitHub.com.
  4. Deploy: CI/CD pipeline deploys the change.
  5. Monitor: Azure SRE Agent monitors the application in production.
  6. Fix: If an alert fires, SRE Agent performs RCA and creates a new GitHub Issue for the Coding Agent to fix.

Strengths:

  • Asynchronous Productivity: Developers offload routine tasks and focus on architecture/review.
  • Self-Healing: The loop between SRE Agent (Monitor) and Coding Agent (Fix) reduces MTTR.
  • Integrated Context: Agents share context via the GitHub platform (Issues, PRs, Code).

Trade-offs:

  • Trust & Verification: Requires rigorous testing and review gates; “autonomy” does not mean “unsupervised”.
  • Cost: Agent usage (Coding Agent, SRE Agent) is metered; monitor token consumption.
  • Complexity: Requires setting up multiple agents and ensuring they have correct permissions (Repo write, Azure Monitor read).

Signals this fits:

  • Team spends significant time on maintenance, boilerplate, or firefighting.
  • Mature DevOps practices (CI/CD, automated testing) are already in place.
  • “Inner loop” velocity is a bottleneck.

When to pivot: If the codebase is too legacy or lacks tests, start with Scenario 8 (App Modernization) to clean it up first.

Sources:

Status: Emerging Pattern (Preview) Confidence Level: Medium (Rapidly evolving)

Pattern 9: Foundry Agent → M365 Copilot Publish Path

Approach:

  1. Build and test the agent in Microsoft Foundry using the Agent Builder. Select a model, add instructions, configure tools (MCP, function calling, code interpreter), and validate in the Chat Playground.[^foundry-publish]
  2. Publish the agent as an Agent Application to create a managed Azure resource with its own stable endpoint, Entra agent identity, and RBAC scope. This step separates the agent from the development project.[^foundry-publish-share]
  3. Reassign permissions: publishing switches the agent from the project’s shared identity to a dedicated identity. RBAC roles for any Azure resources the agent accesses (Storage, Search, Cosmos DB) must be re-granted to the new identity.[^foundry-publish-share]
  4. Distribute to M365 Copilot using the one-click publish flow from the Foundry portal or the Microsoft 365 Agents Toolkit for advanced customization (SSO, multi-environment CI/CD).[^foundry-to-copilot]
  5. For organization-wide deployment, submit the agent through the Microsoft Admin Center for admin approval. Once approved, the agent appears under “Built by your org” in the Copilot Agent Store.[^foundry-to-copilot]

Strengths:

  • Bridges the gap between Azure-built agents and Microsoft 365 distribution. One agent serves both custom apps (via Responses API) and M365 Copilot (via Teams/Outlook/Word).[^foundry-to-copilot]
  • Full code-first control over model selection, orchestration, and tooling while inheriting M365 Copilot’s discovery and governance surface.[^foundry-publish-share]
  • The published Agent Application is an Azure resource governed by Azure Policy, enabling consistent security posture across the agent fleet.[^foundry-publish-share]

What you gain by surfacing inside M365 Copilot:

Publishing into M365 Copilot means your agent inherits a production-grade AI interface without building one. Copilot is the UI for AI. Your agent automatically appears across Teams, Outlook, Word, Excel, and PowerPoint with unified discovery through the Agent Store, tenant-wide governance via the Copilot Control System and Agent Registry, adaptive card rendering for rich interactive responses, built-in compliance and audit controls, usage analytics, mobile parity on iOS/Android, and Entra ID-scoped security trimming. No front-end engineering, no design system, no cross-platform testing. Just the agent logic and the experience it delivers.

Trade-offs:

  • Identity handoff is manual: publishing switches to a dedicated Entra agent identity, and RBAC roles for any Azure resources the agent accesses must be re-granted to the new identity. Skipping this step causes authorization failures post-publish.[^foundry-publish-share]
  • Requires Azure Bot Service resource provisioning and Entra ID app registration, adding infrastructure management overhead.[^foundry-to-copilot]
  • If the agent requires a fully custom visual experience (e.g., generative UI, streaming canvas, or drag-and-drop interactions), consider the AG-UI protocol (Pattern 5) alongside or instead of the M365 Copilot channel. Not every experience fits a conversational surface, and that’s fine.[^foundry-to-copilot]

Signals this fits:

  • You already build agents in Foundry and want to reach users inside Microsoft 365 without rewriting the agent.
  • The agent needs to serve both a custom app endpoint (Responses API) and M365 Copilot simultaneously.
  • Governance teams require Azure Policy-governed agent resources with centralized identity management.

When to pivot: If the agent is primarily M365-facing with no custom app requirement, start with Pattern 1 (Copilot Studio) for faster time-to-value. If the agent needs bespoke UI with streaming and human approvals, stay in Foundry with the AG-UI protocol (Pattern 5) instead of publishing to Copilot.

Sources:

Status: GA (Foundry Agent Service + M365 publish path) Confidence Level: High (official Microsoft documentation)

Pattern 10: Foundry IQ Grounded Agent

Approach:

  1. Create a knowledge base in Azure AI Search using the agentic retrieval API. Define knowledge sources (Azure Blob, SharePoint, OneLake, web via Bing), configure retrieval instructions, and set reasoning effort.[^foundry-iq-connect]
  2. Connect the knowledge base to a Foundry Agent Service agent via MCP. Create a project connection pointing to the knowledge base’s MCP endpoint and configure the agent with the knowledge_base_retrieve tool.[^foundry-iq-connect]
  3. Write agent instructions that explicitly require using the knowledge base for grounding and returning “I don’t know” when retrieval doesn’t contain the answer. This prevents hallucination and enforces citation discipline.[^foundry-iq-connect]
  4. Enable permission-aware retrieval by synchronizing ACLs from source systems and configuring the agent to run queries under the caller’s Entra identity.[^foundry-iq-overview]
  5. Test in the Chat Playground, then publish as an Agent Application or connect to a custom app via the Responses API.[^foundry-publish-share]

Strengths:

  • Permission-aware by design: ACL sync and Purview label enforcement mean agents never expose content the user isn’t authorized to see.[^foundry-iq-overview]
  • Citation-backed responses with extractive data give downstream agents raw content for reasoning, not pre-digested summaries.[^foundry-iq-overview]
  • Multiple agents can share a single knowledge base, eliminating redundant indexing and ensuring consistent grounding across agent workloads.[^foundry-iq-overview]

Trade-offs:

  • Foundry IQ is in Preview. Not recommended for production workloads without accepting preview SLA terms.[^foundry-iq-overview]
  • LLM-based query planning adds cost and latency; use minimal reasoning effort for cost-sensitive scenarios that don’t need multi-hop retrieval.[^foundry-iq-connect]
  • Knowledge source support is limited to the documented set. Custom databases or APIs require building your own indexer pipeline into AI Search first.[^foundry-iq-faq]

Signals this fits:

  • The agent needs governed access to enterprise documents across multiple repositories with user-level permission enforcement.
  • Compliance teams require citation-backed responses with traceable source attribution.
  • You want a shared knowledge layer that multiple agents can query without duplicating indexing infrastructure.

When to pivot: Use Pattern 3 (M365 Knowledge Grounding) when data lives exclusively in M365 and users consume the agent inside Copilot. Use Pattern 2 (Pro-Code First) with direct Azure AI Search calls when you need full control over the retrieval pipeline.

Sources:

Status: Preview (Foundry IQ) + GA (Foundry Agent Service) Confidence Level: Medium (preview knowledge layer + GA runtime)

Pattern 11: Responses API Migration (Assistants → Agents)

The Assistants API sunsets on August 26, 2026. This is not a deprecation warning buried in release notes. It is a hard cutoff. If you have production workloads on the Assistants API, migration is not a backlog item. It is the work.

The good news: you don’t have to do this alone, and you don’t have to do it by hand.

Approach: Three Migration Paths

Choose the path that matches your team’s velocity and codebase complexity. All three lead to the same destination: the Foundry Agents Service and Responses API.

  1. Automated migration tool: Microsoft provides a dedicated migration tool that inventories your existing Assistants API usage (threads, runs, assistant definitions) and automates structural conversion. Start here. It handles the mechanical translation: Threads become Conversations, Runs become Responses, Assistants become Agents (new), so your team can focus on testing business logic rather than rewriting boilerplate.[^agents-migrate]

  2. GitHub Copilot-assisted migration: For the parts the migration tool doesn’t cover (custom orchestration logic, error handling, business rules wired into tool call loops), use GitHub Copilot to accelerate the rewrite. The coding agent can refactor Assistants API patterns to Responses API patterns across your codebase. It understands both API surfaces and can handle the mapping at scale. Assign the migration as a GitHub Issue, let the coding agent open a PR with the refactored code, and review the diff. For large codebases, this turns weeks of manual rewriting into days of review.[^agents-migrate]

  3. Manual migration with the mapping guide: For teams that prefer full control or have highly customized orchestration, use the official migration guide as your reference. The key API primitive changes are straightforward:[^agents-migrate]

    Before (Assistants API) After (Responses API) What Changed
    Threads Conversations Supports streams of items, not just messages
    Runs Responses Input/output items with explicit tool call loop management
    Assistants Agents (new) Prompt-based, workflow-based, and hosted agent types with stateful context

  4. Update SDK packages: Install azure-ai-projects 2.x (replaces 1.x) and initialize the AIProjectClient pointing to your Foundry project endpoint. Ensure the SDK version matches the portal experience. Mixing 1.x SDK with new portal (or vice versa) causes errors.[^agents-migrate]

  5. Test and validate. The new agents support all existing tools (file search, code interpreter, function calling) plus capabilities the Assistants API never had: MCP tool calling, image generation, browser automation (Preview), background mode for long-running operations, and durable streams for disconnect/reconnect resilience. Run integration tests against the new endpoint before cutting over.[^agents-migrate][^responses-api]

What you gain by migrating:

  • Future-proof. New features and model support are only added to the new agents. The Assistants API is a frozen feature set counting down to removal.[^agents-migrate]
  • Single-tenant storage. Bring your own Cosmos DB for conversation state, keeping data in your security boundary instead of Microsoft-managed storage.[^agents-migrate]
  • Agent Applications. Published agents get their own Entra identity, stable endpoint, and Azure Policy integration. You can publish to M365 Copilot (Pattern 9), invoke via the Responses API, or both. The Assistants API never offered any of this.[^foundry-publish-share]
  • Background responses. Long-running tools return continuation tokens for polling or stream resumption, eliminating the timeout cliff that plagued complex Assistants API runs.[^responses-api]

Trade-offs:

  • This is a breaking API change, not a configuration update. The migration tool and GitHub Copilot reduce the effort, but they don’t eliminate testing.
  • Tool call loop management is now explicit rather than runtime-managed. This gives you more control but requires updating orchestration logic that previously relied on the Assistants API runtime to drive loops automatically.
  • The migration tool automates structure but not custom business logic. Plan for manual validation of complex workflows even when using automated paths.

Signals this fits:

  • You have production workloads on the Assistants API. The August 26, 2026 sunset means this pattern applies to you.
  • You need single-tenant storage, MCP integration, or Agent Application publishing that the Assistants API cannot provide.
  • You want to invest migration effort once and land on the platform where all future agent capabilities will ship.

When to pivot: If you’re starting a new agent project, skip migration entirely and build directly on the new agents experience from day one. Don’t learn the old API just to migrate off it.

Sources:

Status: GA (Foundry Agents Service and Responses API). Migration deadline: August 26, 2026 Confidence Level: High (official migration guidance with tooling)

Pattern Selection Guide

Pattern Time to Market Complexity Control Level Best User Experience
Pattern 1 (Studio → Azure) Fast (days to weeks) Start Simple → Scale Complex Low → High M365 Copilot, Teams
Pattern 2 (Pro-Code First) Moderate (weeks to months) High Full M365 Copilot, Custom Apps
Pattern 3 (M365 Knowledge) Fast (days) Low Medium M365 Copilot (native)
Pattern 4 (Multi-Channel SDK) Moderate (weeks) High Full 10+ channels
Pattern 5 (Agent Framework) Moderate (weeks to months) Very High Full Multi-agent workflows
Pattern 6 (Progressive) Moderate (weeks) Medium High M365 Copilot, Teams
Pattern 7 (Translytical) Fast (days) Medium Medium Power BI, Fabric
Pattern 8 (Agentic DevOps) Moderate (weeks) Medium High GitHub, Azure DevOps
Pattern 9 (Foundry → M365) Moderate (weeks) Medium High M365 Copilot, Custom Apps
Pattern 10 (Foundry IQ) Moderate (weeks) High Full Custom agents with governed data
Pattern 11 (API Migration) Moderate (weeks) Medium N/A Existing Assistants API workloads

Pattern Decision Tree

Ground yourself first

  1. Run the BXT gate. Confirm viability, desirability, and feasibility in Decision Framework Phase 1. Any red score means pause here. Capture the scenario in the Scenarios backlog) instead of forcing a pattern.

  2. Anchor the user experience.
    • M365-first surface (Teams, Outlook, Word) → stay inside the Microsoft 365 trust boundary with Pattern 3 for knowledge-only needs33 or Pattern 1 when you need orchestrated actions and governance controls inside Copilot Studio34.
    • Multi-channel or custom apps (web, mobile, SMS, API) → continue to step 3 with Patterns 2 or 4 in play.
  3. Clarify delivery ownership (avoid the low-code vs pro-code trap). Use the skills, time, and funding matrices in Evaluation Criteria. Decide who will build and run the backlog, not which UI they click.
    • Maker-led or mixed squads who will operate inside Copilot Studio, yet can still call custom APIs or child agents, start with Pattern 1 and expand to Azure as needed.
    • Engineer-led product teams with CI/CD, observability, and landing-zone governance treat Pattern 2 (Azure-first) or Pattern 4 (Agents SDK distribution) as the default.
    • Hybrid hand-offs (makers capturing intent, engineers owning orchestration) combine Pattern 1 for the front door with Pattern 2/Pattern 4 services behind it.35
  4. Decide the governance boundary. Align with the governance table in Evaluation Criteria.
    • Stay inside Microsoft 365 tenant controls → Pattern 1 or Pattern 3.
    • Require VNet isolation, private endpoints, or custom compliance → Pattern 2 or Pattern 4.
    • Hybrid front door (Copilot Studio + Azure runtime) → combine Pattern 1 and Pattern 2 as described in Pattern 1’s “Scale with Azure” step.
  5. Assess orchestration complexity. Mirror the “Multi-Agent Orchestration” diagram in Visual Framework.
    • Managed connected/child agents or Logic Apps AI Agent workflows suffice → stay with Patterns 1 or 2 and lean on those tooling features.
    • Need programmable routing, checkpointing, or specialized agent collaboration → invest in Pattern 5 (Agent Framework workflows) and surface them through Pattern 2 or Pattern 4 channels.1810

Before you decide: Validate your choice against the scenario playbooks in Scenarios and the capability groupings in Capability Model to ensure the pattern supports the right part of Microsoft’s AI portfolio. Use the comparison matrices in Quick Reference to double-check complexity, skills, budget, and governance trade-offs.

Related Resources

Next: Technologies - Deep dive into technical specifications

  1. Microsoft Copilot Studio overview, Microsoft Learn. Retrieved: 2026-02-09. https://learn.microsoft.com/en-us/microsoft-copilot-studio/fundamentals-what-is-copilot-studio ↩ ↩2 ↩3

  2. Add custom Copilot Studio agents to Microsoft 365, Microsoft Learn. Retrieved: 2026-01-13. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/publish ↩ ↩2 ↩3 ↩4

  3. Add other agents (Preview), Microsoft Copilot Studio documentation. Retrieved: 2025-12-03. https://learn.microsoft.com/en-us/microsoft-copilot-studio/authoring-add-other-agents ↩ ↩2 ↩3

  4. Foundry Agent Service overview, Microsoft Learn. Retrieved: 2026-01-21. https://learn.microsoft.com/en-us/azure/ai-foundry/agents/overview?view=foundry ↩ ↩2 ↩3 ↩4 ↩5

  5. Microsoft Agent Framework overview, Microsoft Learn. Retrieved: 2026-02-20. https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview ↩ ↩2 ↩3 ↩4

  6. Integrate with Copilot Studio using the Microsoft 365 Agents SDK, Microsoft Learn. Retrieved: 2025-11-26. https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs ↩

  7. See docs/feature-comparison.md for the detailed comparison matrices referenced in this pattern. ↩ ↩2

  8. See Governance & Compliance in docs/evaluation-criteria.md#governance--compliance for scoring guidance. ↩ ↩2

  9. Plugins for Microsoft 365 Copilot, Microsoft Learn. Retrieved: 2026-03-23. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-plugins ↩ ↩2 ↩3 ↩4

  10. Microsoft 365 Agents SDK overview, Microsoft Learn. https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/agents-sdk-overview ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10

  11. Add SharePoint as a knowledge source in Copilot Studio, Microsoft Learn. Retrieved: 2026-01-12. https://learn.microsoft.com/en-us/microsoft-copilot-studio/knowledge-add-sharepoint ↩ ↩2 ↩3

  12. Declarative agents for Microsoft 365 Copilot overview, Microsoft Learn. Retrieved: 2025-12-01. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-declarative-agent ↩ ↩2

  13. Microsoft 365 Copilot connectors overview (external data indexing into Microsoft 365), Microsoft Learn. Retrieved: 2026-02-25. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-copilot-connector ↩ ↩2

  14. Add knowledge sources to declarative agents in Microsoft 365 Copilot, Microsoft Learn. Retrieved: 2025-12-18. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/agent-builder-add-knowledge ↩ ↩2

  15. Microsoft 365 Agents Toolkit overview, Microsoft Learn. Retrieved: 2026-01-29. https://learn.microsoft.com/en-us/microsoft-365/developer/overview-m365-agents-toolkit ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  16. Build custom engine agents with Microsoft 365 Agents SDK, Microsoft Learn. Retrieved: 2025-07-21. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/m365-agents-sdk ↩ ↩2 ↩3 ↩4 ↩5

  17. Bring your agents into Microsoft 365 Copilot, Microsoft Learn. Retrieved: 2025-05-19. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/bring-agents-to-copilot ↩ ↩2

  18. Microsoft Agent Framework Workflows overview, Microsoft Learn. https://learn.microsoft.com/en-us/agent-framework/user-guide/workflows/overview ↩ ↩2 ↩3 ↩4 ↩5

  19. Agents in Workflows tutorial, Microsoft Learn. Retrieved: 2026-03-11. https://learn.microsoft.com/en-us/agent-framework/tutorials/workflows/agents-in-workflows ↩ ↩2 ↩3

  20. Microsoft Foundry Agents integration, Microsoft Learn. Retrieved: 2026-03-20. https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-types/azure-ai-foundry-agent ↩ ↩2 ↩3

  21. Agent Framework orchestration overview, Microsoft Learn. Retrieved: 2026-02-13. https://learn.microsoft.com/en-us/agent-framework/user-guide/workflows/orchestrations/overview ↩ ↩2 ↩3 ↩4

  22. Checkpointing and resuming workflows, Microsoft Learn. Retrieved: 2026-03-11. https://learn.microsoft.com/en-us/agent-framework/tutorials/workflows/checkpointing-and-resuming ↩ ↩2 ↩3

  23. AG-UI integration with Agent Framework, Microsoft Learn. Preview, Updated: 2025-11-07. https://learn.microsoft.com/en-us/agent-framework/integrations/ag-ui/ ↩ ↩2

  24. Microsoft Agent Framework overview, Microsoft Learn. Retrieved: 2026-02-20. https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview ↩ ↩2 ↩3

  25. Foundry Agent Service transparency note, Microsoft Learn. Retrieved: 2026-02-27. https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note?view=foundry#capabilities ↩ ↩2 ↩3 ↩4

  26. Bring Your Own Model to Copilot Studio, Microsoft Learn. Retrieved: 2025-11-25. https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-generative-actions ↩ ↩2

  27. Connect to a Microsoft Foundry agent (Preview), Microsoft Learn. Retrieved: 2025-12-03. https://learn.microsoft.com/en-us/microsoft-copilot-studio/add-agent-foundry-agent ↩ ↩2

  28. Azure AI Search Overview, Microsoft Learn. Retrieved: 2025-12-12. https://learn.microsoft.com/en-us/azure/search/ ↩ ↩2

  29. OneLake shortcuts, Microsoft Learn. Retrieved: 2026-01-08. https://learn.microsoft.com/en-us/fabric/onelake/onelake-shortcuts ↩ ↩2

  30. Microsoft Fabric Copilot overview, Microsoft Learn. Retrieved: 2026-01-25. https://learn.microsoft.com/en-us/fabric/fundamentals/copilot-fabric-overview ↩ ↩2

  31. Translytical task flows (Preview), Microsoft Learn. Retrieved: 2026-03-24. https://learn.microsoft.com/en-us/power-bi/create-reports/translytical-task-flow-overview ↩ ↩2 ↩3

  32. Azure Cosmos DB mirroring in Fabric, Microsoft Learn. Retrieved: 2025-12-03. https://learn.microsoft.com/en-us/fabric/mirroring/azure-cosmos-db ↩ ↩2

  33. Add SharePoint as a knowledge source in Copilot Studio, Microsoft Learn. Updated: 2026-01-12. https://learn.microsoft.com/en-us/microsoft-copilot-studio/knowledge-add-sharepoint ↩

  34. Microsoft 365 Copilot release notes, August 19, 2025, Microsoft Learn. https://learn.microsoft.com/en-us/copilot/microsoft-365/release-notes#august-19,-2025 ↩

  35. Evaluation Criteria: Skills & Resources, Microsoft AI Decision Framework. See docs/evaluation-criteria.md. ↩

Back to top

Copyright © 2025. This documentation is based on official Microsoft sources and best practices.

This site uses Just the Docs, a documentation theme for Jekyll.