将客户端 API 与Copilot Studio代理配合使用

$pages.agent 对象

使用 Power Pages 客户端 API $pages.agent 对象及其 SendActivity 方法发送消息或调用当前用户可用的Microsoft Copilot Studio代理中的事件。 响应和错误回调可帮助站点处理代理的结果。

SendActivity 方法

该方法SendActivity在指定的Copilot Studio代理中发送消息或调用事件，并使用回调函数处理响应和错误。

SendActivity 方法语法

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

SendActivity 方法参数

参数名称 类型 Description
agentSchemaName String 将活动发送到的机器人的架构名称。
inputActivity 对象 包含要发送到机器人的文本或事件的对象。
responseSubscriber 函数 代理发送响应时运行的回调函数。
errorSubscriber 函数 处理错误的回调函数。

该方法 SendActivity 返回 void。 若要从代理接收响应，请传递回调 responseSubscriber 函数。 当代理发送响应时，该方法将调用此回调。 传递回调 errorSubscriber 函数来处理错误。

SendActivity 响应属性

来自代理的响应对象采用以下格式接收：

名字 类型 Description
type String 活动类型，例如消息。
text String 可选，来自代理的消息。
textFormat String 可选，消息文本的格式，如 markdown、纯或 XML。
Id String 唯一标识活动的 ID。
From 对象 指定活动的发送方（包括 ID、名称（可选）和角色信息）。
Conversation 对象 包含活动所属的对话的 ID。
InputHint String 可选，指示机器人是接受、期望还是忽略用户输入。
replyToId String 答复消息的 ID。

Examples

以下示例演示如何定义响应和错误回调，以及用于 SendActivity 发送消息或调用事件。

示例 Description
定义响应和错误回调 responseSubscriber定义处理代理响应和错误的回调errorSubscriber函数。
将消息发送到代理 Hello!将文本活动发送到指定的代理，并使用回调函数来处理响应或错误。
调用客户端事件 AgentEvent调用客户端事件并将键值有效负载传递给代理。

定义响应和错误回调

responseSubscriber定义和errorSubscriber回调函数以处理代理响应和错误。

const responseSubscriber = (response) => {
    // Replace with your response handling.
    console.log('Agent response:', response);
};

const errorSubscriber = (error) => {
    // Replace with your error handling.
    console.error('Error:', error);
};

// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';

将消息发送到代理

此示例将文本活动发送到 Hello! 指定的代理，并使用回调函数来处理响应或错误。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        text: 'Hello!' // Message to the agent.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

调用客户端事件

此示例调用 AgentEvent 客户端事件并将键值有效负载传递给代理。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        name: 'AgentEvent', // The name of the event to be invoked.
        value: { key1: 'value1', key2: 'value2' } // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

错误消息

下面是用户可能会遇到的错误消息及其潜在原因。

错误类型 原因 用户的错误消息
代理架构验证 提供的机器人架构名称无效或用户无权访问代理 Invalid bot schema name or access denied. Check the bot schema name and try again.
提取令牌错误 提取直接线路令牌时出错 Something went wrong while fetching the token. Please try again.
发布活动错误（重试） 发布活动并需要重试时出错。 Something went wrong while posting the activity: retry.
发布活动错误（超时） 等待传出消息或 postActivity 时超时 Timed out while posting activity: Please retry.
发布活动错误（活动无效） 输入活动没有用于调用事件的文本或名称。 Invalid activity: At least one of text, name, or attachments must be provided.
发布活动错误（找不到用户 ID 或找不到令牌） 在会话存储中找不到令牌，或者在令牌中找不到用户 ID Error retrieving user ID: {error message}
发布活动错误（常规） 发布活动时发生未指定的错误 Something went wrong while posting the activity: Please try again.
Direct Line 连接错误 与机器人建立直接线路连接时出错。 Something went wrong while creating direct line connection: Please try again.
常规错误 不属于上述类别的意外错误 An unexpected error occurred while sending activity: Please try again.
  • 上次更新时间为