@microsoft/agents-copilotstudio-client

Overview

The @microsoft/agents-copilotstudio-client package allows you to interact with Copilot Studio Agents using the Direct Engine Protocol. This client library is designed to facilitate communication with agents, enabling seamless integration and interaction within your JavaScript or TypeScript applications.

This package provides exports for CommonJS and ES6 modules, and also a bundle to be used in the browser.

Installation

To install the package, use npm or yarn:

npm install @microsoft/agents-copilotstudio-client
Copy

Prerequisite

To use this library, you will need the following:

1. An Agent Created in Microsoft Copilot Studio.
2. Ability to Create or Edit an Application Identity in Azure
   1. (Option 1) for a Public Client/Native App Registration or access to an existing registration (Public Client/Native App) that has the CopilotStudio.Copilot.Invoke API Delegated Permission assigned.
   2. (Option 2) for a Confidential Client/Service Principal App Registration or access to an existing App Registration (Confidential Client/Service Principal) with the CopilotStudio.Copilot.Invoke API Application Permission assigned.

Create a Agent in Copilot Studio

1. Create or open an Agent in Copilot Studio
   1. Make sure that the Copilot is Published
   2. Goto Settings => Advanced => Metadata and copy the following values. You will need them later:
      1. Schema name - this is the 'unique name' of your agent inside this environment.
      2. Environment Id - this is the ID of the environment that contains the agent.

Create an Application Registration in Entra ID to support user authentication to Copilot Studio

Add the CopilotStudio.Copilots.Invoke permissions to your Application Registration in Entra ID to support User or Service Principal authentication to Copilot Studio

This step will require permissions to edit application identities in your Azure tenant.

1. In your azure application
   1. Goto Manage
   2. Goto API Permissions
   3. Click Add Permission
      1. In the side pannel that appears, Click the tab API's my organization uses
      2. Search for Power Platform API.
         1. If you do not see Power Platform API see the note at the bottom of this section.
      3. For User Interactive Permissions, choose Delegated Permissions
         1. In the permissions list choose CopilotStudio and Check CopilotStudio.Copilots.Invoke
         2. Click Add Permissions
      4. For Service Principal/Confidential Client, choose Application Permissions
         1. In the permissions list choose CopilotStudio and Check CopilotStudio.Copilots.Invoke
         2. Click Add Permissions
         3. An appropriate administrator must then Grant Admin consent for copilotsdk before the permissions will be available to the application.
   4. Close Azure Portal

How-to use

The Copilot Client is configured using the ConnectionSettings class and a jwt token to authenticate to the service. The ConnectionSettings class can be configured using either instantiating the class or loading the settings from a .env.

Using the default class

There are a few options for configuring the ConnectionSettings class. The following are the most common options:

Using Environment ID and Copilot Studio Agent Schema Name:

const settings: ConnectionSettings = {
  environmentId: "your-environment-id",
  agentIdentifier: "your-agent-schema-name",
};
Copy

Using the DirectConnectUrl:

const settings: ConnectionSettings = {
  directConnectUrl: "https://direct.connect.url",
};
Copy

Using the .env file

You can use the loadCopilotStudioConnectionSettingsFromEnv function to load the ConnectionSettings from a .env file.

The following are the most common options:

Using Environment ID and Copilot Studio Agent Schema Name:

environmentId=your-environment-id
agentIdentifier=your-agent-schema-name
Copy

Using the DirectConnectUrl:

directConnectUrl=https://direct.connect.url
Copy

Example of how to create a Copilot client

const createClient = async (): Promise<CopilotStudioClient> => {
  const settings = loadCopilotStudioConnectionSettingsFromEnv()
  const token = await acquireToken(settings)
  const copilotClient = new CopilotStudioClient(settings, token)
  return copilotClient
}
const copilotClient = await createClient()
const replies = await copilotClient.startConversationAsync(true)
replies.forEach(r => console.log(r.text))
Copy