Share via

Integrate with web or native apps 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 will interact with it.

Note

If you want to use the Embed code for the web app in Copilot Studio, you must set your security authentication options to No authentication. Navigate 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 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 copilot. Configure your app registration for user interactive sign-in
Connect to Copilot Studio with Agents SDK Service Principal sign-in To be used where you want the agent to have its own identity and not use on behalf of for the user accessing the agent. Useful in scenarios where you don't require user context but you still need to access privileged APIs or information and requires authentication. Note: To perform this task, you must have authentication for this agent in Copilot Studio set to No Authentication. Configure your app registration for Service Principal
Use legacy DirectLine to connect to Copilot Studio You can connect to DirectLine using the DirectLine API and should be used where the Agents SDK doesn't support your scenario. Publish an agent to mobile or custom apps

Prerequisites

  • .NET Core / JS/ Python
  • Packages–Copilot Studio client
  • An agent

Methods to Integrate your Copilot Studio agent

  • Copilot Studio client (using the Agents SDK): This method is the preferred way to integrate with Copilot Studio.

  • DirectLine: DirectLine is the legacy way to integrate with Copilot Studio and should be used where there's no support for your use case with Copilot Studio client.

    • Doesn't support service principal token

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 using the Microsoft 365 Agents SDK

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

    We simplified integration with the Agents SDK for your web and native apps by providing a client library that allows developers to enter a few details about your agent and to 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 be able 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 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 or Service Principal authentication methods to access your agent.

Configure your app registration for user interactive sign-in

  1. Navigate 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 should now be able to run the sample and connect to the agent via your app registration settings using the sample console application.

Configure your app registration for Service Principal

Alternatively, you might choose to configure your app registration for service authentication rather than for user authentication.

  1. On your app registration, go to API permission, add permissions, select APIs my organization uses, and search for Power Platform API.
  2. Select Application permissions > Copilot Studio, and check the Copilot Studio.Copilots.Invoke permission.
  3. Select Add Permissions.

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

  1. Adding the Connection String into the Copilot Studio client settings in the appsettings.config file:

    • DirectConnectUrl
    • TenantID:
    • UseS2SConnection: true
    • ClientID:
    • ClientSecret:

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

    • EnvironmentID:
    • SchemaName:
    • TenantID:
    • UseS2SConnection: true
    • AppClientID:
    • AppClientSecret:

You should now be able to run the sample and connect to the agent with your app registration settings using 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. Referencing the library in your application.
  2. Implementing objects and methods from the client library in your project.
  3. Injecting with DI or managing the client based on the existing design of your application, ensuring you reference the app settings for the configuration details for the agent.

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

You can add the Copilot Studio agent to your website using an iFrame, embeddable in the HTML of the website/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

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

  • Last updated on