Share via

@microsoft/agents-copilotstudio-client package

Classes

ConnectionSettings

Represents the settings required to establish a connection to Copilot Studio.
CopilotStudioClient

Client for interacting with Microsoft Copilot Studio services. Provides functionality to start conversations and send messages to Copilot Studio bots.
CopilotStudioWebChat

A utility class that provides WebChat integration capabilities for Copilot Studio services.

Example

Basic WebChat Integration

import { CopilotStudioClient } from '@microsoft/agents-copilotstudio-client';
import { CopilotStudioWebChat } from '@microsoft/agents-copilotstudio-client';

// Initialize the Copilot Studio client
const client = new CopilotStudioClient({
  botId: 'your-bot-id',
  tenantId: 'your-tenant-id'
});

// Create a WebChat-compatible connection
const directLine = CopilotStudioWebChat.createConnection(client, {
  showTyping: true
});

// Integrate with WebChat
window.WebChat.renderWebChat({
  directLine: directLine,
  // ... other WebChat options
}, document.getElementById('webchat'));

Example

Advanced Usage with Connection Monitoring

const connection = CopilotStudioWebChat.createConnection(client);

// Monitor connection status
connection.connectionStatus$.subscribe(status => {
  switch (status) {
    case 0: console.log('Disconnected'); break;
    case 1: console.log('Connecting...'); break;
    case 2: console.log('Connected and ready'); break;
  }
});

// Listen for incoming activities
connection.activity$.subscribe(activity => {
  console.log('Received activity:', activity);
});
ExecuteTurnRequest

Represents a request to execute a turn in a conversation. This class encapsulates the activity to be executed during the turn.

Interfaces

CopilotStudioConnectionSettings

Represents the settings required to establish a direct connection to the engine.
CopilotStudioWebChatConnection

Represents a connection interface for integrating Copilot Studio with WebChat.
CopilotStudioWebChatSettings

Configuration settings for the Copilot Studio WebChat connection. These settings control the behavior and appearance of the WebChat interface when connected to the Copilot Studio service.

Enums

AgentType

Enum representing the type of agent.
PowerPlatformCloud

Enum representing different Power Platform cloud environments.

Functions

getCopilotStudioConnectionUrl(ConnectionSettings, string)

Generates the connection URL for Copilot Studio.
getTokenAudience(ConnectionSettings, PowerPlatformCloud, string, string)

Returns the Power Platform API Audience.
loadCopilotStudioConnectionSettingsFromEnv()

Loads the connection settings for Copilot Studio from environment variables.

Function Details

getCopilotStudioConnectionUrl(ConnectionSettings, string)

Generates the connection URL for Copilot Studio.

function getCopilotStudioConnectionUrl(settings: ConnectionSettings, conversationId?: string): string

Parameters

settings
ConnectionSettings

The connection settings.

conversationId

string

Optional conversation ID.

Returns

string

The connection URL.

getTokenAudience(ConnectionSettings, PowerPlatformCloud, string, string)

Returns the Power Platform API Audience.

function getTokenAudience(settings?: ConnectionSettings, cloud?: PowerPlatformCloud, cloudBaseAddress?: string, directConnectUrl?: string): string

Parameters

settings
ConnectionSettings

Configuration Settings to use.

cloud
PowerPlatformCloud

Optional Power Platform Cloud Hosting Agent.

cloudBaseAddress

string

Optional Power Platform API endpoint to use if Cloud is configured as "other".

directConnectUrl

string

Optional DirectConnection URL to a given Copilot Studio agent, if provided all other settings are ignored.

Returns

string

The Power Platform Audience.

loadCopilotStudioConnectionSettingsFromEnv()

Loads the connection settings for Copilot Studio from environment variables.

function loadCopilotStudioConnectionSettingsFromEnv(): ConnectionSettings

Returns

ConnectionSettings

The connection settings.