Chamando uma extensão customizada

Chamando a extensão de uma etapa

Para chamar uma extensão customizada por meio de uma ação:

1. No editor de ação, crie ou abra a etapa da qual deseja chamar a extensão.

2. Opcional: no campo Assistant says (O assistente diz ), digite uma mensagem a ser exibida ao cliente antes de o ramal ser chamado (por exemplo, " Please wait while I retrieve your account balance...).

A saída dessa etapa é enviada ao canal com a variável de contexto global ' skip_user_input definida como ' true. Essa variável instrui o canal a exibir a mensagem, mas _não_ a solicitar uma resposta do cliente. Em vez disso, o canal envia uma mensagem vazia, permitindo que o assistente de IA prossiga com a chamada para o ramal.

Todas as integrações de canal incorporadas (como o bate-papo na Web) respeitam a variável de contexto " skip_user_input. Se você estiver usando a API para desenvolver um cliente personalizado, é sua responsabilidade incluir a verificação lógica dessa variável. Para obter mais informações, consulte Processamento da entrada do usuário.

1. No editor de etapa, clique em E depois.

2. Clique em Usar uma extensão.

3. Na janela Configuração de extensão, especifique as informações a seguir:

   • No campo Extensão, selecione a extensão que deseja chamar.

   • No campo Operação, selecione a operação que deseja executar. (Uma _operação_ é um método ou função suportada pela extensão.)

4. Especificar valores para cada um dos parâmetros de entrada necessários. Um _parâmetro_ é um valor de entrada enviado a uma operação, como o ID de um registro de cliente que você deseja recuperar ou a localização a ser usada para uma previsão do tempo.

Para designar um valor a um parâmetro, clique no campo de entrada para o valor. É possível selecionar na lista de variáveis disponíveis ou gravar uma expressão para especificar o valor.

Cada parâmetro possui um tipo de dados (como _number_ ou _string_). A variável selecionada deve ser compatível com o tipo de dados do parâmetro; para obter mais informações, consulte Variáveis compatíveis para parâmetros.

Você deve especificar valores para todos os parâmetros necessários antes de continuar.

1. Para especificar um valor para quaisquer parâmetros opcionais, clique em Parâmetros opcionais. Em seguida, é possível repetir esse processo para cada parâmetro opcional que deseja usar.

2. Clique em Aplicar. (Se o botão Aplicar não estiver disponível, certifique-se de ter especificado valores para todos os parâmetros necessários.)

Agora a seção E depois do editor de etapa mostra uma visão geral da chamada para a extensão:

Para fazer mudanças, clique em Editar extensão para reabrir a janela Configuração de extensão.

Acessando dados de resposta de extensão

Após chamar uma extensão, os valores dos dados de resposta são armazenados em variáveis de ação especiais que podem ser acessadas em etapas subsequentes.

É possível acessar essas variáveis da mesma maneira que você acessa outras variáveis de ação. Elas podem ser referenciadas no texto Assistente diz, avaliadas como parte de uma condição de etapa ou designadas a uma variável de sessão para que outras ações possam acessá-las. As variáveis de resposta são mostradas na lista de variáveis disponíveis, categorizadas sob o nome da extensão e a etapa da qual foram chamadas:

Cada chamada para uma extensão cria um conjunto separado de variáveis de resposta. Se a ação chamar a mesma extensão várias vezes de etapas diferentes, certifique-se de selecionar as variáveis da etapa correta.

Cada variável representa um valor do corpo de resposta. Para facilitar o acesso a esses valores, os dados são extraídos de objetos complexos, aninhados e mapeados para variáveis de resposta individuais. O nome de cada variável reflete sua localização dentro do corpo de resposta (por exemplo, body.name ou body.customer.address.zipcode).

Por exemplo, esta etapa de ação usa uma expressão para verificar a propriedade availability em uma resposta de extensão:

Se uma variável de resposta contiver uma matriz, você poderá escrever uma expressão que use métodos de matriz para acessar os elementos da matriz. Por exemplo, você pode usar o contains() método em uma condição de etapa para verificar se a matriz contém um determinado valor, ou o join() método para formatar os dados da matriz como uma string que possa ser incluída na resposta de um assistente de IA. Para obter mais informações sobre métodos de matriz, consulte Métodos de matriz.

Verificando o sucesso ou a falha

Talvez você queira que seu assistente de IA seja capaz de lidar com erros que ocorrem ao chamar uma extensão personalizada. Você pode fazer isso verificando a variável Ran successfully de resposta que é retornada junto com a resposta da chamada à extensão. Essa variável é um valor booleano (true ou false).

Se você definir condições de etapa que verifiquem a Ran successfully variável, poderá criar etapas que permitam ao seu assistente de IA responder de maneira diferente, dependendo do sucesso ou não da chamada para o ramal. (Para obter mais informações sobre condições de etapa, consulte Condições de etapa.)

O exemplo a seguir mostra uma condição de etapa que verifica uma falha de uma extensão na etapa 3. Usando essa condição, é possível criar uma etapa que informe ao cliente que houve um erro e que ofereça uma conexão com um agente para o cliente obter mais ajuda.

Condicionamento do status HTTP

Além da variável Ran successfully, talvez você também queira criar uma condição de etapa com base no status HTTP da resposta. Ao fazer isso, você pode criar etapas que tratam a situação de forma diferente, dependendo da causa da falha. Por exemplo, se a chamada falhar devido a um erro de tempo limite ( HTTP status 408), talvez você queira tentar novamente a chamada.

Existem muitos códigos de status HTTP possíveis, e métodos diferentes usam códigos de status diferentes para indicar vários tipos de sucesso ou falha. Para condicionar o status HTTP, você precisa saber quais códigos de status HTTP o serviço externo retorna e em que circunstâncias. Esses códigos de status são normalmente especificados no documento OpenAPI que descreve a API externa.

Para criar uma condição de etapa com base no código de status HTTP, siga estas etapas:

1. Para o valor que você deseja testar, clique em Expression (Expressão).

2. No campo de expressão, digite um sinal de dólar ($) para mostrar a lista de variáveis disponíveis.

3. Selecione qualquer variável que seja um valor de resposta da extensão. (Não importa qual variável é selecionada, contanto que seja uma variável de resposta de extensão).

A expressão é atualizada automaticamente para mostrar uma referência à variável selecionada no formato ${step_xxx_result_y.body.variablename}. Por exemplo, se você selecionou uma variável de resposta chamada body.id, a referência poderá ser ${step_596_result_1.body.id}.

1. Dentro das chaves, ({}), edite essa referência para remover .body.variablename. O resultado deve ser algo como ${step_596_result_1}.

2. Após a chave de fechamento (}), inclua .status. A referência resultante identifica o código de status retornado da chamada para a extensão (por exemplo, ${step_596_result_1}.status).

Para obter mais informações sobre a gravação de expressões, consulte Gravando expressões.

1. Complete a expressão adicionando um operador e um valor de comparação, para que a expressão seja avaliada como um valor booleano (verdadeiro/falso). Por exemplo, a expressão a seguir testa o status 408 do site HTTP, que indica um erro de tempo limite:

    ${step_549_result_1}.status==408

Falhas na depuração da extensão personalizada

Se as suas chamadas para uma extensão estiverem falhando, talvez você queira depurar o problema vendo informações detalhadas sobre o que está sendo enviado e retornado da API do sistema. Para fazer isso, você pode usar o Inspector no painel Preview:

1. Vá para a página Actions (Ações) ou para o editor de ações e clique em Preview (Visualizar ) para abrir o painel Preview (Visualizar).

Não é possível acessar o Inspector a partir da visualização do assistente de IA na página de visualização, que mostra apenas o que um cliente veria. Em vez disso, use o recurso de visualização que faz parte da página Ações, que lhe dá acesso a informações adicionais.

1. Interaja com seu assistente de IA como um cliente faria.

2. Sempre que um ramal é chamado, o painel de visualização mostra uma mensagem que lhe dá acesso a informações detalhadas:

Clique em Inspect (Inspecionar ) para ver detalhes sobre a chamada para o ramal.

Você também pode clicar no ícone para mostrar ou ocultar o Inspetor. Entretanto, você deve clicar em Inspect (Inspecionar ) no painel de visualização para mostrar informações sobre uma chamada específica para um ramal.

A guia Overview (Visão geral ) do Inspector mostra as seguintes informações sobre uma chamada para um ramal:

Nas tabelas Request parameters (Parâmetros de solicitação ) e Response properties (Propriedades de resposta ), nomes longos de propriedades podem ser truncados para mostrar apenas a última parte do caminho JSON. Para ver o caminho completo e o nome da propriedade, passe o ponteiro do mouse sobre o nome da propriedade na tabela.

1. Clique na guia Advanced (Avançado ) no inspetor de extensão se quiser ver os dados brutos de solicitação e resposta:

   • A solicitação é exibida como um comando ` cURL `, que você pode executar em uma linha de comando ou importar para uma ferramenta como o Postman. (Por motivos de segurança, o conteúdo de qualquer cabeçalho ' Authorization não é incluído)

   • A resposta é mostrada como os dados JSON completos retornados da API do sistema.

Falhas de depuração para pesquisa de conversação ou ações baseadas em habilidades

Se suas chamadas para a pesquisa de conversação ou ações baseadas em habilidades falharem, talvez você queira depurar o problema vendo as informações detalhadas sobre o que está sendo enviado e retornado da API do sistema.

O inspetor de pesquisa de conversação é exibido somente quando a pesquisa de conversação está ativada em sua integração de pesquisa. Se estiver usando a integração de pesquisa do serviço personalizado, você deverá usar somente a pesquisa no lado do servidor ao configurar a integração de pesquisa. A pesquisa no lado do cliente não é compatível com o inspetor de pesquisa de conversação.

Para ver as informações detalhadas para analisar o problema, use o Inspector no painel Preview:

1. Vá para a página Ações ou, no editor de ações, clique em Visualizar para abrir o painel Visualizar.

Não é possível acessar o Inspetor a partir da visualização do assistente de IA na página de Visualização. Em vez disso, use o recurso de visualização que faz parte da página Ações, que lhe dá acesso a informações adicionais.

1. Interaja com seu assistente de IA como um cliente faria.

2. Sempre que uma extensão é chamada, o painel de visualização exibe uma mensagem para acessar as informações detalhadas:

Você também pode clicar no ícone para mostrar ou ocultar o inspetor de extensões. Clique em Inspect (Inspecionar ) no painel de visualização para mostrar informações sobre uma chamada específica para a integração de pesquisa.

1. Use a guia Overview (Visão geral ) para encontrar os motivos da falha de suas chamadas para a Pesquisa de Conversação.

Entenda as duas fases da extensão de pesquisa antes de conhecer os campos que são exibidos na guia Overview (Visão geral ).

• Fase de recuperação

: Representa a fase inicial da pesquisa, na qual um mecanismo de pesquisa de documentos externo é acionado para recuperar o conjunto inicial de resultados.

• Fase de geração de respostas

: Representa a fase em que os dados são recuperados e enviados a um LLM para gerar uma resposta legível para o usuário.

A guia Overview (Visão geral) do Inspector mostra as seguintes informações sobre a chamada para a integração de pesquisa.

1. A guia Advanced mostra as seguintes informações sobre a chamada para a integração da pesquisa.

Reconfiguração de uma extensão ausente

Uma extensão pode ficar indisponível se alguém a remover do assistente de IA na página Integrações, ou se a ação for exportada e depois importada para um assistente de IA diferente, no qual a extensão necessária não esteja configurada. Se isso acontecer, qualquer etapa de ação que chame a extensão se tornará inválida.

Para corrigir o problema, siga estas etapas:

1. Se necessário, recrie a extensão usando a mesma especificação OpenAPI que foi usada anteriormente. (Para obter mais informações, consulte “Criação de uma extensão personalizada ”.)

2. Certifique-se de que a extensão foi adicionada ao assistente de IA. (Para obter mais informações, consulte Adicionar uma extensão ao seu assistente.)

3. No editor de ações, edite a etapa de ação que chama o ramal e verifique se a chamada para o ramal está configurada corretamente. Se o assistente de IA reconhecer a extensão necessária, a configuração da extensão será restaurada automaticamente.

Se você vir a mensagem Extension not fully configured, isso significa que o criador de assistentes de IA não encontrou a extensão necessária. Clique em “Editar extensão ”.

1. Na janela de configuração de ramal, selecione o ramal para o qual deseja ligar.

Se o criador de assistentes de IA reconhecer uma extensão disponível que tenha sido criada usando o mesmo documento OpenAPI, aparecerá uma mensagem sugerindo que você selecione essa extensão. No entanto, você pode selecionar qualquer extensão disponível.

1. Verifique se os valores corretos estão especificados nos campos Operação e Parâmetros.

2. Clique em Aplicar.

3. Se você selecionou uma extensão que não é idêntica à que foi usada para criar a ação, talvez seja necessário modificar as etapas subsequentes que acessam as propriedades de resposta da extensão. Verifique todas as etapas posteriores que se referem às propriedades de resposta e certifique-se de que as referências ainda sejam válidas e corretas.