Integrate with web or native apps by using Microsoft 365 Agents SDK

Important

This content is intended for experienced IT professionals, such as IT admins or developers, who are familiar with developer tools, utilities, and integrated development environments (IDEs). It requires software development expertise.

After you create and test your agent in Copilot Studio, deploy it to your preferred channel to test how your target users interact with it.

Note

To use the Embed code for the web app in Copilot Studio, set your security authentication options to No authentication. Go to Settings > Security > Authentication and select No authentication to make it publicly available.

This guide covers how to take your Copilot Studio agent and integrate it with your existing web application (typically a website) or native application by using the Copilot Studio client with the Microsoft 365 Agents SDK.

Note

For another option to connect a Copilot Studio or Microsoft 365 Agents SDK agent to a native mobile or Windows app, see Integrate with native apps using the Agents Client SDK.

Different parts of this guide are relevant depending on whether you have an existing UX/UI that you want to integrate the agent into, or if you plan to use a Microsoft-provided UX/UI. Use the following table to find the section that fits your scenario.

Deployment Method How, where, and why Quick Link
Use the Default Web Chat Embed Code With an agent that has No Authentication security setting enabled, it's available on the Web channel publishing pane in Copilot Studio. Note: This option only appears when you have No Authentication selected in Copilot Studio. Use the default Web Chat Embed code (without development/code)
Connect to Copilot Studio with Agents SDK User sign-in Use the Agents SDK connection string or configuration settings to directly integrate to your agent using user credentials using the agent. Configure your app registration for user interactive sign-in
Use Direct Line to connect to Copilot Studio You can connect to a Copilot Studio agent using the Direct Line API. Use it when the Agents SDK doesn't support your scenario. Publish an agent to mobile or custom apps

Prerequisites

  • .NET Core, JavaScript, or Python
  • Packages - Copilot Studio client
  • A Copilot Studio agent

Methods to integrate your Copilot Studio agent

  • Copilot Studio client (using the Agents SDK): Use this method to integrate with Copilot Studio.

  • Direct Line: Use Direct Line API to integrate with Copilot Studio. Use this method when Microsoft 365 Agents SDK doesn't support your scenario, for example:

    • The Microsoft 365 Agents SDK doesn't support service principal tokens.

Copilot Studio client samples

Use these .NET, JavaScript, or Python samples in the following section depending on the language you use:

Get started: Basic configuration and agent connection testing by using the Microsoft 365 Agents SDK

  1. Download the Copilot Studio client sample from the Microsoft 365 Agents SDK.

    To simplify integration with the Agents SDK for your web and native apps, Microsoft provides a client library. Developers can enter a few details about your agent and easily integrate it into your applications.

  2. Get the appropriate sample for .NET, JavaScript, or Python from the Copilot Studio Client Samples.

  3. Get the Embed code or connection string for your agent in Copilot Studio.

    You need access to your agent in Copilot Studio to get the connection string details (or details for the configuration setting) to connect to it.

    In Copilot Studio, open your agent, select Settings > Security > Authentication, and then review your agent's settings.

    • If either Authenticate with Microsoft or Authenticate manually is selected, you see only the connection string option to integrate with Agents SDK.

    • If No authentication is selected, you see both the Embed code that you can add to your website and the connection string. The Embed code option doesn't use the Agents SDK and uses the standard out-of-the-box Web Chat component.

    Screenshot of an agent's authentication settings, showing no authentication is selected.

  4. Get your connection string.

    To get the connection string for your agent in Copilot Studio, select either Web app or Native app on the Channels page. Select Copy next to the connection string under Microsoft 365 Agents SDK. Use this string to connect to this agent from your web or native app's code.

    Screenshot of Copilot Studio's Channels page.

    Screenshot of Web app channel panel in Copilot Studio.

  5. Get information for traditional configuration settings.

    If you don't want to use the connection string method, and instead use the traditional configuration settings, you need some other metadata from your Copilot Studio agent.

    Select Settings > Advanced. Under Metadata, you need the Environment ID, Tenant ID, and Schema name. Record these metadata values for later.

    Screenshot of advanced settings page for an agent in Copilot Studio.

  6. Configure your application registration for the correct permissions to access Copilot Studio.

    Your web or native app needs to have an app registration in Azure. If you don't have an app registration in Azure, you can follow the full guide on setting one up by using the Readme or in the Azure documentation. For more information, see Register an application in Microsoft Entra ID.

    Note

    Most likely you already have an existing app registration for your registration, and you need to use that instead. You can configure User authentication to access your agent.

Configure your app registration for user interactive sign-in

  1. Go to API permission > Add permissions, select APIs my organization uses, and search for Power Platform API.

  2. Select delegated permissions > Copilot Studio > Copilot Studio.Copilots.Invoke permission. Select Add Permissions.

For user sign-in, you can test the sample work with your application registration and your Copilot Studio agent, by:

  • Adding the connection string into the Copilot Studio client settings in the appsettings.config file:

    • DirectConnectUrl
    • TenantID:
    • ClientID:
    • ClientSecret:

  • Adding the Copilot Studio client settings in the appsettings.config file:

    • EnvironmentID:
    • SchemaName:
    • TenantID:
    • AppClientID:
    • AppClientSecret:

You can now run the sample and connect to the agent by using your app registration settings and the sample console application.

Integrate the Copilot Studio client into your existing UI/UX

Now you have tested your agent with the Copilot Studio client. Your testing confirms your agent is connected with the sample console app, you're ready to integrate the library into your existing website or app, and connect/surface it with your existing UI.

How you integrate your agent into the application is up to you and your existing code base. Typically, steps to integrate your agent might include:

  1. Reference the library in your application.
  2. Implement objects and methods from the client library in your project.
  3. Inject the client by using DI or manage the client based on the existing design of your application. Ensure you reference the app settings for the configuration details for the agent.

Use the default Web Chat Embed code (without development or code)

You can add the Copilot Studio agent to your website by using an iFrame, which you can embed in the HTML of the website or web app.

This code is visible only if the No authentication option is selected in the agent's settings in Copilot Studio under Security. If Authenticate with Microsoft or Authenticate manually is selected, the Embed Code isn't visible.

Screenshot of an agent's authentication settings.

Use DirectLine to connect to Copilot Studio

To use DirectLine to integrate with your Copilot Studio agent, see Publish an agent to mobile or custom apps.

  • Last updated on