Usar a API do cliente com agentes Copilot Studio

objeto $pages.agent

Use o objeto de API $pages.agent do cliente Power Pages e seu método SendActivity para enviar mensagens ou invocar eventos no agente Microsoft Copilot Studio disponível para o usuário atual. Os retornos de chamada de resposta e erro ajudam o site a lidar com os resultados do agente.

Método SendActivity

O SendActivity método envia uma mensagem ou invoca um evento no agente de Copilot Studio especificado e usa funções de retorno de chamada para lidar com respostas e erros.

Sintaxe do método SendActivity

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

Parâmetros do método SendActivity

Nome do parâmetro Tipo Descrição
agentSchemaName String Nome do esquema do bot para o qual a atividade é enviada.
inputActivity Objeto Objeto que contém o texto ou evento a ser enviado para o bot.
responseSubscriber função Função de retorno de chamada que é executada quando o agente envia uma resposta.
errorSubscriber função Função de retorno de chamada que manipula erros.

O SendActivity método retorna void. Para receber uma resposta do agente, passe uma responseSubscriber função de retorno de chamada. O método invoca esse retorno de chamada quando o agente envia uma resposta. Passe uma errorSubscriber função de retorno de chamada para lidar com erros.

Propriedades de resposta SendActivity

Objeto de resposta do agente recebido no seguinte formato:

Name Tipo Descrição
type String Tipo da atividade, como mensagem.
text String Opcional, mensagem do agente.
textFormat String Opcional, formato do texto da mensagem, como markdown, simples ou XML.
Id String ID que identifica exclusivamente a atividade.
From Objeto Especifica o remetente da atividade (inclui id, nome (opcional) e informações de função).
Conversation Objeto Contém a ID da conversa à qual a atividade pertence.
InputHint String Opcional, indica se o bot está aceitando, esperando ou ignorando a entrada do usuário.
replyToId String ID da mensagem de resposta.

Examples

Os exemplos a seguir mostram como definir retornos de chamada de resposta e erro e usar SendActivity para enviar uma mensagem ou invocar um evento.

Exemplo Descrição
Definir retornos de chamada de resposta e erro Define as responseSubscriber funções de retorno de chamada e errorSubscriber que lidam com respostas e erros do agente.
Enviar mensagem ao agente Envia uma Hello! atividade de texto para o agente especificado e usa funções de retorno de chamada para lidar com a resposta ou um erro.
Invocar evento do cliente Invoca o AgentEvent evento cliente e passa uma carga chave-valor para o agente.

Definir retornos de chamada de resposta e erro

Defina as responseSubscriber funções de retorno de chamada e errorSubscriber para lidar com respostas e erros do agente.

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';

Enviar mensagem ao agente

Este exemplo envia uma Hello! atividade de texto para o agente especificado e usa funções de retorno de chamada para lidar com a resposta ou um erro.

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

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

Invocar evento do cliente

Este exemplo invoca o AgentEvent evento cliente e passa uma carga chave-valor para o agente.

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);
});

Mensagens de erro

Aqui estão possíveis mensagens de erro que os usuários podem encontrar e suas possíveis causas.

Tipo de erro Causa Mensagem de erro para o usuário
Validação de esquema do agente Nome de esquema de bot inválido fornecido ou o usuário não tem permissões de acesso para o agente Invalid bot schema name or access denied. Check the bot schema name and try again.
Buscar erro de token Erro ao buscar o token de linha direta Something went wrong while fetching the token. Please try again.
Erro de atividade de postagem (repetição) Ocorreu um erro ao postar a atividade e uma repetição é necessária. Something went wrong while posting the activity: retry.
Erro de atividade de postagem (tempo limite) Tempo limite durante a espera por mensagem de saída ou postActivity Timed out while posting activity: Please retry.
Erro de atividade de postagem (atividade inválida) A atividade de entrada não tem texto ou nome para invocar o evento. Invalid activity: At least one of text, name, or attachments must be provided.
Erro de atividade de postagem (ID do usuário não encontrada ou token não encontrado) O token não é encontrado no armazenamento de sessão ou a ID do usuário não é encontrada no token Error retrieving user ID: {error message}
Erro de atividade de postagem (geral) Erro não especificado ao postar a atividade Something went wrong while posting the activity: Please try again.
Erro de conexão de linha direta Erro ao criar uma conexão de linha direta com o bot. Something went wrong while creating direct line connection: Please try again.
Erro geral Um erro inesperado que não se enquadra nas categorias acima An unexpected error occurred while sending activity: Please try again.
  • Última atualização em