You have a Copilot Studio agent.
You want a web app.

What are you actually trying to solve?

Most "migrate to Foundry" requests are really one of seven underlying asks. Four of them don't require migration at all. Find your row before scoping the work.

Three integration paths

Sources: Integrate with web or native apps · Integrate with Copilot Studio

When Foundry genuinely is the answer

Know which docs you're reading

Microsoft restructured this product. Tutorials that tell you to create a thread and then a run are describing Foundry Agent Service (classic) — deprecated, with a retirement date of 31 March 2027.

Read the full decision framework →

How the agent is integrated into a frontend

The Copilot Studio Client hands you an object that drops straight into the standard botframework-webchat React component. You get a production chat UI without building one, but you own the page, the styling, and the auth.

 Browser (your React app)
 ┌──────────────────────────────────────────────────────┐
 │  ┌───────────────┐   1. loginPopup / silent          │
 │  │ MSAL Browser  │ ─────────────────────────────┐    │
 │  │ public client │ ◀──── access token ──────────┤    │
 │  └───────┬───────┘                              │    │
 │          │ 2. token                             │    │
 │          ▼                                      │    │
 │  ┌──────────────────────┐                       │    │
 │  │ CopilotStudioClient  │                       │    │
 │  └───────┬──────────────┘                       │    │
 │          │ 3. createConnection()                │    │
 │          ▼                                      │    │
 │  ┌──────────────────────┐                       │    │
 │  │ botframework-webchat │                       │    │
 │  └──────────────────────┘                       │    │
 └─────────────────────────────────┬───────────────┴────┘
                                   ▼
              Microsoft Entra ID ──▶ Power Platform API
        scope: CopilotStudio.Copilots.Invoke   (agent runtime)
    

Note what's not there: no Direct Line secret, and no custom token-minting backend. MSAL runs as a public client and the token is a delegated user token, so the browser never holds a long-lived shared secret.

Acquire the token

import { PublicClientApplication, InteractionRequiredAuthError } from '@azure/msal-browser'
import { CopilotStudioClient } from '@microsoft/agents-copilotstudio-client'

export async function acquireToken (settings) {
  const msalInstance = new PublicClientApplication({
    auth: {
      clientId: settings.appClientId,
      authority: `${settings.authority}/${settings.tenantId}`,
    },
  })
  await msalInstance.initialize()

  const loginRequest = {
    // the SDK resolves the correct Power Platform scope for your cloud
    scopes: [CopilotStudioClient.scopeFromSettings(settings)],
    redirectUri: window.location.origin,
  }

  try {
    const accounts = await msalInstance.getAllAccounts()
    if (accounts.length > 0) {
      const r = await msalInstance.acquireTokenSilent({ ...loginRequest, account: accounts[0] })
      return r.accessToken          // silent path — no prompt
    }
  } catch (e) {
    if (!(e instanceof InteractionRequiredAuthError)) throw e
  }

  const r = await msalInstance.loginPopup(loginRequest)
  return r.accessToken
}

Wire it into Web Chat

const token = await acquireToken(settings)
const client = new CopilotStudioClient(settings, token)
const connection = CopilotStudioWebChat.createConnection(client, { showTyping: true })

// `directLine` is just the prop name — this is NOT the Direct Line channel
<FluentThemeProvider>
  <Composer directLine={connection}>
    <BasicWebChat />
  </Composer>
</FluentThemeProvider>

The Entra app registration step people get wrong

1. API permissions → Add a permission → APIs my organization uses

   Search for Power Platform API.

2. Delegated permissions → Copilot Studio → CopilotStudio.Copilots.Invoke

   Add it, then grant admin consent if your tenant requires it.

3. Authentication → add a Single-page application redirect URI

   Must match window.location.origin for every environment.

An AADSTS65001 error or an empty token is almost always step 1 or 2.

Verified packages

Start with Microsoft's copilotstudio-webchat-react sample — validate your config with the console sample first, then bring up the UI.

Read the full frontend guide →

How user sessions are managed

There are three independent "sessions" in play, and they expire on different clocks. Most production bugs here come from assuming they're the same thing.

┌────────────────────────────────────────────────────────────────┐
│ 1. BROWSER SESSION          owned by: your app                 │
│    MSAL cache, your app cookie                                 │
│    Ends: tab close, cache clear, explicit sign-out             │
├────────────────────────────────────────────────────────────────┤
│ 2. IDENTITY SESSION         owned by: Microsoft Entra ID       │
│    Access token for the Power Platform / Direct Line scope     │
│    Ends: token expiry — renew silently via MSAL                │
├────────────────────────────────────────────────────────────────┤
│ 3. CONVERSATION SESSION     owned by: Copilot Studio           │
│    conversationId + agent-side variable state                  │
│    Ends: ~30 min inactivity, or you start a new one            │
└────────────────────────────────────────────────────────────────┘
    

A signed-in user with a valid token can still be talking to a brand-new conversation with none of their earlier context. If you want continuity, persist and reuse the conversationId yourself.

Pick your authentication mode first

The decisive question: does the agent need to call a downstream API as the user? If yes, only Authenticate manually gives you User.AccessToken.

Source: Configure user authentication

If you use Direct Line: never ship the secret

Refresh proactively at ~75% of expires_in. You can refresh an unlimited number of times — but you cannot refresh an expired token. Let it lapse and the user's conversation dies.

SSO needs two app registrations

An authentication app (exposes the custom scope, authorises the canvas app) and a canvas app (SPA platform, redirect URI, access + ID tokens). Confirm accessTokenAcceptedVersion is 2. The canvas intercepts the sign-in prompt, requests an on-behalf-of token, and the agent exchanges it to populate User.AccessToken.

* Teams requires extra config — skipping it makes users always fail authentication. Source: Configure SSO

Read the full sessions guide →

How chat history is stored and maintained

Copilot Studio stores transcripts in two places, with two different retentions — and there is one exclusion that invalidates most compliance reporting built on them.

Other things that will bite you

• Records are written after ~30 minutes of inactivity — not in real time. Don't build a live dashboard on this table.
• Content caps at 1 MB. Longer conversations split across records sharing Name + ConversationStartTime with different Metadata.BatchId. Group and sort by BatchId, or your analytics silently truncate.
• from.role is an integer: 0 = agent, 1 = user. Getting it backwards inverts every report.
• The Bot Transcript Viewer role is required. Environment Maker does not grant it.
• Nothing is written in Dataverse-for-Teams environments, for Microsoft 365 Copilot agents, or in developer environments — so dev testing won't surface the gap.
• Disabling transcript saving isn't instant or retroactive — up to 24 hours to stop, and re-enabling never backfills.

Source: Conversation transcript controls

Audit vs DSPM — the distinction that matters

Own your own history

Given the redaction behaviour, the 28/30-day windows, and the 30-minute write lag, most enterprise web apps should mirror the transcript into their own store.

   Browser (Web Chat)
        │  activities in / out
        ▼
  ┌───────────────────────┐        ┌──────────────────────────┐
  │  Your BFF / API       │───────▶│  Azure Cosmos DB         │
  │  • mints tokens       │        │  • partition: userId     │
  │  • mirrors activities │        │  • doc: conversationId   │
  │  • enforces retention │        │  • items: activities[]   │
  └───────────┬───────────┘        └──────────────────────────┘
              ▼
     Copilot Studio agent
    

Mirror server-side, not in the browser — a client-side mirror can be tampered with and is lost on tab close. Microsoft's baseline chat architecture names three triggers for self-managing history: zero-data-retention obligations, custom context-window control, and multiple UX channels with independent session semantics.

Two working references with real server-side history you can port: sample-app-aoai-chatGPT and azure-search-openai-demo. Both are OpenAI-centric, but the history layer is agent-agnostic.

Read the full chat history guide →

Embedding across multiple SharePoint sites

Four options. Microsoft's own sample repo tells you to prefer the built-in channel over custom code — and tenant-wide SPFx deployment is a blunt instrument with a 20-minute fuse.

The built-in channel

1. Publish the agent

   Nothing works until you do.

2. Channels → SharePoint tile

   Select the site, or type its name.

3. Deploy → Confirm

   You need WRITE access to the target site.

4. Mark the agent Approved

   It then appears in the dedicated Approved section of the agent picker, visible to all users of that site.

Source: Publish an agent to SharePoint

Tenant-wide SPFx deployment

Set "skipFeatureDeployment": true, upload the .sppkg to the tenant app catalog, and check "Enable this app and add it to all sites". That writes a row to the Tenant Wide Extensions list. Scope with WebTemplateId:

<ClientSideComponentInstance
    Title="AgentLauncher"
    Location="ClientSideExtension.ApplicationCustomizer"
    ComponentId="917a86f2-15c1-403e-bbe1-59c6bd50d1e1"
    WebTemplateId="SITEPAGEPUBLISHING#0"   <!-- communication sites only -->
    Sequence="10"
    HostProperties="{&quot;preAllocatedApplicationCustomizerBottomHeight&quot;:&quot;50&quot;}">
</ClientSideComponentInstance>

Gotchas, all directly sourced

• 20-minute delay before the first entry takes effect.
• Duplicate entries can be created when updating an existing package — leaving you with two chat widgets.
• Invisible at site level — tenant-deployed solutions don't appear in "add an app".
• No feature-framework upgrade path for centrally deployed solutions.
• Feature definitions are ignored when this option is used.
• SharePoint Server 2019 throws an exception on ClientSideInstance.xml.

Source: Tenant-wide deployment of SPFx extensions

Performance — the part that gets teams in trouble

• Ship only a small launcher button in onInit(); lazy-load the chat bundle on first click. Highest-impact change by far.
• Enable the Office 365 CDN — Microsoft calls it "required for optimal static resource download".
• Reuse SPFx-provided React and Fluent imports instead of bundling your own.
• Reserve space with preAllocatedApplicationCustomizer*Height to avoid layout jank.
• Measure with Page Diagnostics before and after rollout — not just on a dev tenant.

Source: Modern custom extensions performance

Rollout best practices

1. Pilot with the built-in channel on one site

   Prove value before investing in custom SPFx code.

2. Decide contextual vs ambient

   A few key sites → built-in channel. Help on every page → Application Customizer. Don't deploy both to the same site or users see two entry points.

3. Scope by WebTemplateId from day one

   Going tenant-wide then narrowing means an awkward removal across sites.

4. Use a site collection app catalog to pilot

   It's your blast-radius control — tenant-wide has a 20-minute delay in both directions.

5. Check the Tenant Wide Extensions list after every update

   To catch duplicate rows before users do.

6. Test as a guest user

   Guests can't get AI-generated answers from SharePoint or Graph Connector sources in SSO-enabled apps.

7. Plan transcript capture before rollout

   SharePoint-grounded answers are REDACTED in Dataverse. Solve it before an audit asks.

8. Model the capacity cost

   Wide deployment multiplies message volume, and SharePoint usage consumes Copilot Studio capacity.

Read the full SharePoint guide →