Você pode precisar solucionar problemas de uma integração entre o espaço de trabalho dos agentes de IA e outro sistema caso o comportamento não esteja ocorrendo conforme previsto. Este artigo descreve diversas etapas de solução de problemas que você pode executar para tentar identificar um problema de integração.
Este artigo contém os seguintes tópicos:
- Testar a integração no criador de integrações
- Verificar se os parâmetros da solicitação correspondem
- Verificar os registros de conversas referentes aos parâmetros de sessão
- Gerar valores brutos no cenário de falha
- Verificar o código do status HTTP
- Investigar erros técnicos no diálogo
Artigos relacionados:
Testar a integração no criador de integrações
Como a primeira etapa na solução de problemas de uma integração, teste-a no criador de integrações. Confirme se você está obtendo uma resposta e se vê os dados corretos nos parâmetros de sessão.
Verificar se os parâmetros da solicitação correspondem
Os parâmetros da solicitação que você está usando no criador de integrações — seja na consulta de URL, no corpo ou no cabeçalho — devem corresponder exatamente àqueles capturados no diálogo.
Verifique o seguinte:
- Não há erros de ortografia.
- Se você atualizou a ortografia ou o nome de um parâmetro em qualquer etapa no diálogo, as atualizações também foram feitas na integração.
- A correspondência de maiúsculas e minúsculas deve ser exata. Não há diferenciação nos parâmetros.
Dica: é recomendável adotar uma convenção de nomenclatura consistente para todos os parâmetros de solicitação ou sessão, como lowerCamelCase ou snake_case.
Verificar os registros de conversas referentes aos parâmetros de sessão
Consulte os registros de conversas para obter mais informações, como dados de sessão. Você pode pesquisar por conversas que usam a API filtrando por tags. Se a conversa usar a API, você conseguirá pesquisar por ela.
Quando você estiver nos registros de conversas, na parte superior esquerda, clique em Adicionar filtro.
No menu à esquerda, navegue para Rótulos.
Aqui, você pode filtrar a integração por nome ou pelo cenário. Por exemplo, se foi bem-sucedida, se falhou ou se houve um erro de API.
Para integrações desenvolvidas no criador de integrações, o nome começará com o prefixo API, seguido pelo nome da integração e, por fim, pelo nome do cenário.
Um exemplo da captura de tela a seguir é API-Chloe Demo: Apple Cart-Success:
- API = prefixo
- Chloe Demo: Apple Cart = nome da integração
- Success = nome do cenário
Para verificar rapidamente se uma integração funciona conforme o esperado, você pode passar o cursor do mouse sobre o símbolo da tag em um registro de conversa para ver as tags associadas à conversa.
Se você quiser ver apenas o motivo de uma conversa ter apresentado erro de API, na pesquisa de Rótulos, pesquise por apiError.
Em seguida, selecione sua conversa para ver mais informações.
Quando você está na conversa, é possível verificar o que consta nos dados da sessão.
Para fazer isso, clique em Detalhes na parte superior direita.
Depois de clicar em Detalhes, você verá a Visão geral da conversa. Em seguida, clique em Dados da sessão.
Agora, você pode ver os dados da sessão no chat. Observe que, na parte inferior, podemos ver os parâmetros da sessão provenientes da integração da API.
Verificar se há parâmetros da sessão no diálogo
Para verificar rapidamente se os parâmetros existem para a sessão, você pode registrá-los em uma mensagem do agente de IA pelo diálogo. É mais seguro fazer isso ao testar o diálogo em um ambiente de teste ou, se a integração estiver ativa, certifique-se de não salvar o diálogo ao fazer o teste.
Na mensagem do agente de IA abaixo, os parâmetro de sessão estão sendo registrados de maneira que fiquem visíveis durante o teste.
Gerar valores brutos no cenário de falha
Crie uma cadeia de caracteres de todos os dados contidos na resposta inserindo ‘data’ na função `$string(data)`. Isso pode ser registrado no cenário de falha durante o teste para ver rapidamente o que está sendo retornado.
Verificar o código do status HTTP
Quando você testar a integração, não se esqueça de verificar o código de status http retornado. Você verá isso na resposta à direita, com a chave `statusCode`.
2xx: Êxito
-
200 OK: a solicitação foi concluída com êxito, e o servidor respondeu com os dados esperados.
- Essa é a resposta ideal ao testar uma integração.
4xx: erros de cliente
Os erros neste intervalo geralmente indicam um problema com a solicitação enviada no criador de integrações.
-
400 – Solicitação inválida: o servidor não conseguiu entender a solicitação devido à sintaxe inválida ou aos parâmetros ausentes.
- Verifique se há erros, campos ausentes ou formatação incorreta na carga da solicitação.
-
401 – Não autorizado: a autenticação é necessária, mas não foi fornecida ou é inválida.
- Verifique a chave da API, o token ou outras credenciais de autenticação. Verifique duas vezes os cabeçalhos de autorização.
-
403 – Proibido: o servidor entendeu a solicitação, mas se recusa a autorizá-la.
- Certifique-se de que seus endereços IP estejam na lista de autorização ou verifique as permissões da API.
-
404 – Não encontrado: não foi possível encontrar o recurso solicitado no servidor.
- Verifique a URL ou o ponto de extremidade. Certifique-se de que o caminho correto esteja sendo usado e que o recurso exista.
5xx: erros de servidor
Os erros neste intervalo geralmente indicam um problema no servidor back-end.
-
500 – Erro interno do servidor: Um erro genérico indicando que algo deu errado no servidor back-end.
- Entre em contato com a equipe de back-end com detalhes da solicitação para depuração adicional.
-
502 – Gateway inválido: o servidor recebeu uma resposta inválida de um servidor upstream.
- Isso geralmente indica um problema com os serviços internos ou as dependências do back-end.
-
503 – Serviço indisponível: o servidor não consegue manipular atualmente a solicitação, possivelmente devido à sobrecarga ou manutenção.
- Tente novamente após algum tempo e verifique se há tempo de inatividade programado.
-
504 – Tempo limite do gateway: o servidor não recebeu uma resposta em tempo hábil de um servidor upstream.
- Certifique-se de que o serviço de back-end esteja operacional e verifique se há problemas de latência.
Investigar erros técnicos no diálogo
Às vezes, você pode ver uma mensagem com um erro técnico. O erro técnico inclui o texto a seguir:
“Sinto muito. Parece haver um problema técnico. Espero voltar a funcionar em breve.”
Neste cenário, é mais provável que o problema seja um erro de diálogo, em vez de algo relacionado à integração em si. Eis algumas dicas:
- Verifique o diálogo para garantir que o fluxo atinja a integração. Use mensagens de buffer para confirmar, e verifique se há problemas como funcionalidades de botão variadas, links quebrados ou referências circulares.
- Verifique se há algum parâmetro obrigatório presente. Parâmetros obrigatórios ausentes acionarão erros antes da execução da integração.
- Para conteúdo dinâmico, como cartões e carrosséis, verifique se todos os campos estão preenchidos. Valores indefinidos, em branco ou nulos podem comprometer esses componentes e causar erros.