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; they 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. For teams that prefer configuration over code, use YAML-defined agents and workflows and load the topology with a single API call—keeping orchestration definitions version-controlled alongside your infrastructure-as-code.18
  2. Stand up specialized agents (Microsoft Foundry Agent Service, Microsoft Foundry, or custom ChatClient agents) and register them as workflow executors. Agents can discover and invoke external tools on any MCP-compliant server (GA), so your workflow isn’t limited to first-party integrations.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

The Trade-off: Autonomy vs. Oversight

The promise is seductive: detect an incident, generate a fix, and ship it before anyone finishes the postmortem. Safe delivery requires verified handoffs between operations and coding agents. Build an assisted-remediation loop around artifacts your organization already governs.

The Analogy: “The Two-Key Repair Shop.” Azure SRE Agent is the diagnostician that gathers evidence, and the governed incident or GitHub Issue is the work order a human authorizes. GitHub Copilot cloud agent is the mechanic working on the repair in a separate branch. CI, Copilot code review, and ASSERT provide inspection evidence; OpenTelemetry keeps the service record. For code-owned agents that integrate Agent Governance Toolkit and ACS, runtime policy defines the tools and actions the mechanic may use. Branch protection and human approval hold the two keys required to merge and deploy.

Approach:

  1. Configure: Enable GitHub Copilot cloud agent for approved repositories and define its repository instructions, access, workflow-approval policy, branch protection, and required reviews. The GitHub Copilot app can provide a shared desktop control surface for issues, sessions, pull requests, and CI.
  2. Plan: Start work from a GitHub Issue, a Copilot prompt, an @copilot pull-request comment, or a reviewed schedule/event automation. Use issues for planned work, PR comments for review fixes, and automations for bounded recurring tasks.
  3. Code: The cloud agent researches the repository, creates a plan when requested, works in its GitHub Actions-powered environment, writes code on a branch, and runs the repository’s build and test commands.
  4. Review: Open or review the pull request. Require CI, tests, dependency and security scans, code-owner review, and branch protection. Copilot code review adds another source of evidence.
  5. Merge: A permitted human or existing policy-controlled automation merges only after the required checks and approvals pass.
  6. Deploy: The existing CI/CD pipeline deploys the change and preserves rollback authority.
  7. Monitor: Configure Azure SRE Agent (GA) against the production resources and telemetry it needs, then use it to investigate incidents and verify recovery.
  8. Fix: Capture SRE Agent’s evidence in a reviewed incident record or GitHub Issue. A human narrows scope, defines acceptance criteria, and authorizes another pass through the loop.

Governance layer (non-negotiable for production use):

  • Agent Governance Toolkit v4.1.0 (Public Preview, MIT OSS): Optional application-layer middleware for runtime checks. It has zero GA features, ACS is beta, main v5 is unreleased, APIs can change, and it is not a managed service or support boundary.
  • ASSERT (open-source research project): Executable behavior evaluations. It complements runtime policy; it is not AGT coverage or a managed penetration-testing product.
  • OpenTelemetry observability: Agent actions emit structured traces. When the agent creates a file, runs a test, or calls an API, you can see it in your existing observability stack (Grafana, Datadog, Azure Monitor). This is how you build trust incrementally: start by watching everything, then relax oversight as patterns prove reliable.

Strengths:

  • Asynchronous Productivity: Developers offload routine tasks (test coverage, dependency updates, boilerplate) and focus on architecture and review.
  • Governed Handoff: Issues, pull requests, checks, and incident records create an auditable seam between diagnosis and code change.
  • Assisted Remediation: Production evidence reaches a coding workflow quickly without pretending the loop is self-healing.
  • Auditable Seams: policy checks, evaluations, traces, issues, and pull requests can produce evidence for security review when each layer is configured and operated correctly.

Trade-offs:

  • Trust is Earned, Not Configured: weak tests and permissive branch rules turn fast PR creation into fast regression creation.
  • No verified direct handoff: integration happens through governed artifacts unless current official documentation establishes another path.
  • Tooling maturity varies: verify each GitHub cloud-agent feature. AGT is Public Preview; ASSERT is a separate OSS research project.

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.
  • Security and compliance teams need an auditable governance story for AI-generated code.

When to pivot: If the codebase lacks reliable builds, tests, and branch protection, establish those controls before delegating remediation. An agent without a test suite is a merge request without a safety net.

Sources:

Component Status:

Component Status
GitHub Copilot cloud agent Available on paid Copilot plans; entry-point and automation availability varies
GitHub Copilot app Available on all Copilot plans; cloud sandboxes remain Public Preview
Copilot code review Available on paid Copilot plans; Azure DevOps integration remains Public Preview
Copilot automations Available for eligible plans and private or internal repositories
Agent Merge Available through the GitHub Copilot app; merge remains subject to repository rules and required checks
Agent Governance Toolkit / ACS Public Preview OSS / beta policy layer; zero GA features
ASSERT Open-source research project
Azure SRE Agent GA

Status: Recommended as assisted remediation with mandatory human and branch-policy gates Confidence Level: High for the artifact-based pattern; no direct SRE-to-cloud-agent handoff is claimed

Pattern 9: Foundry Agent → M365 Copilot Publish Path

The Trade-off: Distribution Speed vs. Surface Certainty

Publishing is a border crossing where the agent’s identity, tools, and channel behavior each require validation before entry. The core agent logic may remain intact across that journey.

Approach:

  1. Build and test a current Prompt Agent (GA) or Hosted Agent (mixed maturity) in Microsoft Foundry. If selecting Hosted Agents, apply the compute, session, storage, identity, networking, region, and package constraints in Technologies.33
  2. Use the current agent endpoint and agent identity. Do not build a new path around legacy Agent Applications, which are deprecated.34
  3. Assign least-privilege RBAC to the current agent identity for every downstream resource and test both user-delegated and background execution paths where applicable.
  4. Translate the business requirements and acceptance criteria into a representative evaluation dataset, evaluators, thresholds, and failure-handling rules. Run the evaluation against the Foundry endpoint to establish a release baseline for task completion, answer quality, groundedness, tool use, safety, latency, and any scenario-specific outcomes.35
  5. Distribute to Microsoft 365 Copilot or Teams only through the documented Early Access Preview path.36
  6. Test every tool, identity, and channel combination independently, then rerun the same business-requirement evaluations through each target surface. A successful Responses API call does not prove equivalent behavior in Teams, Word, Outlook, or mobile.

Strengths:

  • Reuses a current Foundry agent endpoint while validating Microsoft 365 as an additional distribution surface.
  • Keeps distribution optional: the custom endpoint remains the controlled baseline while the Preview channel is evaluated.

What you gain by surfacing inside M365 Copilot:

Microsoft 365 can become the front door, but Preview distribution does not erase channel differences. Treat each documented surface as a separate acceptance test. The useful mental model is one brain, inspected doors—shared agent logic behind channels that each need identity, tool, rendering, audit, and lifecycle validation.

Trade-offs:

  • Microsoft 365 distribution is Early Access Preview, not GA.
  • Legacy and current agent models differ in endpoint, identity, tool, and RBAC behavior; migration requires explicit retesting.34
  • Tool availability and authentication can differ by channel. Do not promise universal Microsoft 365, custom-app, or mobile parity.
  • 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.36

Signals this fits:

  • You already build agents in Foundry and want to reach users inside Microsoft 365 without rewriting the agent.
  • The team wants to test both a custom endpoint and Microsoft 365 distribution without coupling their release gates.
  • Governance teams require explicit identity, RBAC, audit, and channel approval evidence.

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 parent Agent Service + Early Access Preview Microsoft 365 distribution; Hosted Agent tooling has mixed maturity Confidence Level: High for lifecycle posture; channel fit requires workload-specific validation

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.37
  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.37
  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.37
  4. Enable permission-aware retrieval by synchronizing ACLs from source systems and configuring the agent to run queries under the caller’s Entra identity.38
  5. Test in the Chat Playground, then invoke the current agent endpoint from the custom app. If adding Microsoft 365 distribution, apply Pattern 9’s Early Access Preview gates.34

Strengths:

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

Trade-offs:

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

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

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

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

    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 Current agents Prompt Agent or Hosted Agent definitions with current endpoints and identity

  4. Update SDK packages: Install azure-ai-projects 2.x (replaces 1.x) and initialize the AIProjectClient pointing to your Foundry project endpoint. The standalone azure-ai-agents package is deprecated - remove it and use AIProjectClient in azure-ai-projects as the single entry point. Ensure the SDK version matches the portal experience. Mixing 1.x SDK with new portal (or vice versa) causes errors.40

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

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.40
  • Single-tenant storage. Bring your own Cosmos DB for conversation state, keeping data in your security boundary instead of Microsoft-managed storage.40
  • Current endpoints and identity. Current agents expose endpoint and identity through the current model. Microsoft 365 distribution remains Early Access Preview and requires the Pattern 9 channel-by-channel checks.34
  • Background responses. Long-running tools return continuation tokens for polling or stream resumption, eliminating the timeout cliff that plagued complex Assistants API runs.41

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 current agent endpoints, single-tenant storage, or MCP integration 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 needs42 or Pattern 1 when you need orchestrated actions and governance controls inside Copilot Studio43.
    • 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.44
  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. Create and deploy a custom engine agent with Microsoft 365 Agents SDK, Microsoft Learn. Updated: 2025-12-02. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/create-deploy-agents-sdk ↩ ↩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. Custom engine agents for Microsoft 365 overview, Microsoft Learn. Updated: 2026-07-02. https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-custom-engine-agent ↩ ↩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. Foundry Agent Service overview, Microsoft Learn. Updated: 2026-07-09. https://learn.microsoft.com/en-us/azure/foundry/agents/overview ↩ ↩2

  34. Migrate legacy Agent Applications, Microsoft Learn. Updated: 2026-05-27. https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/migrate-agent-applications ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  35. Evaluate your AI agents, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/observability/how-to/evaluate-agent ↩

  36. Publish an agent to Microsoft 365 Copilot and Teams (Early Access Preview), Microsoft Learn. Updated: 2026-07-10. https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/publish-copilot ↩ ↩2 ↩3

  37. Connect Foundry IQ to Foundry Agent Service, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/foundry-iq-connect ↩ ↩2 ↩3 ↩4 ↩5

  38. Foundry IQ overview, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/what-is-foundry-iq ↩ ↩2 ↩3 ↩4 ↩5 ↩6

  39. Foundry IQ FAQ, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/foundry-iq-faq ↩ ↩2

  40. Migrate to the current Foundry agents experience, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/migrate ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  41. Use the Responses API, Microsoft Learn. https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/responses ↩ ↩2 ↩3

  42. 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 ↩

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

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