Incorporando o agente em aplicativos web

Editar online

O chat integrado permite que os aplicativos integrem agentes diretamente nas experiências da web e do cliente. Essa integração oferece suporte a comunicação segura, personalização flexível da interface do usuário e tratamento de eventos para proporcionar experiências de conversação ricas, além de introduzir considerações importantes de segurança para garantir que o acesso, a identidade e o contexto do usuário sejam tratados corretamente.

Este procedimento define os pré-requisitos e as etapas que você precisa seguir para incorporar o agente em um aplicativo da web.

Ambientes de rascunho e ao vivo para chat incorporado

Os ambientes de teste e de produção influenciam qual versão do seu agente você deseja invocar por meio do script incorporado e como as alterações são refletidas em tempo de execução. Compreender qual ambiente o seu script incorporado tem como alvo ajuda a evitar testes não intencionais na produção ou a exibição de comportamentos incompletos aos usuários.

  • Rascunho

O ambiente de teste destina-se ao desenvolvimento e à validação. Os scripts incorporados que você copia do Draft são direcionados especificamente à variante de rascunho, onde é possível testar alterações de configuração, lógica de conversação e comportamento da interface do usuário sem afetar os usuários.

  • Em tempo real

O ambiente de produção representa a versão implantada e pronta para produção do seu agente. As incorporações ao vivo oferecem um comportamento estável e versionado, adequado para ambientes de produção. As alterações feitas no rascunho não são refletidas na versão ativa até que você implante explicitamente o seu agente.

Pré-requisitos

Para executar o agente com sucesso no chat incorporado, seu aplicativo deve atender aos seguintes requisitos:

  • Incluir um componente do lado do servidor (local ou na nuvem)

É necessário um servidor para armazenar e utilizar chaves privadas com segurança, assinar solicitações e interagir com as APIs d watsonx Orchestrate.

  • Inclua um contêiner root HTML

A página de incorporação deve conter um elemento HTML com o ID root.

  • Usar o modo estrito do HTML

A página que incorpora o chat online deve declarar o modo estrito de HTML incluindo a <!DOCTYPE html> diretiva.

  • Configurar a segurança do chat integrado

A segurança está ativada por padrão nos ambientes de teste e de produção, mas não está configurada. Você deve configurá-lo explicitamente, conforme descrito na seção “Configurando a segurança para o chat integrado ”. Você poderá ver o widget de bate-papo no aplicativo da web, mas ele não será inicializado a menos que as chaves criptográficas necessárias sejam configuradas e validadas pelo serviço.

  • Incorpore o script no elemento <body>

Coloque o script dentro da <body> tag para garantir que o DOM esteja disponível quando o script for executado e que o elemento raiz possa ser resolvido corretamente no momento da inicialização.

Procedimento para incorporar agentes em aplicações web

Você pode incorporar o widget de chat para um agente em seu aplicativo usando o script incorporado gerado a partir da interface do usuário do agente. Se preferir gerar o script usando um comando da CLI, consulte a seção “Integração de agentes com aplicações web” na documentação do _ IBMwatsonx Orchestrate Agent Development Kit_. O procedimento a seguir concentra-se no fluxo de trabalho baseado na interface do usuário.

Nota:

  • Para a implantação local do IBM watsonx Orchestrate :

  • Versão 5.2.1: Não é possível copiar o script incorporado da interface do usuário do agente. Use a documentação do ADK para obter o script incorporado. Para obter mais detalhes, consulte “Incorporar o chat da web do Agent ”.

  • Versões 5.2.2 e posteriores: você pode copiar diretamente os scripts incorporados da interface do usuário do agente.

  1. Acesse a configuração do agente:

    • Vá para a página de configuração do agente.

    • Navegue até Canais > Agente incorporado.

  2. Selecione o ambiente:

    • Use o modo Rascunho para testar e visualizar o widget de chat no aplicativo web.

    • Use o modo Live para obter o script do agente implantado. Esta guia permanece desativada até que o agente seja implantado.

  3. Copie o script incorporado:

    • Clique em Copiar para a área de transferência para copiar o script gerado.

O código a seguir é um exemplo do script incorporado:

    <script>
      window.wxOConfiguration = {
        orchestrationID: "your-orgID_orchestrationID", // Adds control over chat display mode (e.g., fullscreen)
        hostURL: "https://dl.watson-orchestrate.ibm.com", // or region-specific host
        rootElementID: "root",
        showLauncher: false,
        deploymentPlatform: "ibmcloud", // Required for IBM Cloud embed, can be skipped for other embed scenarios
        crn: "your-org-crn", // Required for IBM Cloud embed, can be skipped for other embed scenarios. For more information, see https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID&interface=ui
        chatOptions: {
          agentId: "your-agent-id",
          agentEnvironmentId: "your-agent-env-id",
        },
      };
      setTimeout(function () {
        const script = document.createElement("script");
        script.src = `${window.wxOConfiguration.hostURL}/wxochat/wxoLoader.js?embed=true`;
        script.addEventListener("load", function () {
          wxoLoader.init();
        });
        document.head.appendChild(script);
      }, 0);
    </script>

  1. Adicione o script à sua página da web:

    • Edite o código HTML da página onde deseja que o widget de chat apareça.

    • Cole o script incorporado dentro da <body> tag, o mais próximo possível da tag de </body> fechamento, para obter o melhor desempenho de carregamento da página.

    • Certifique-se de que o root elemento esteja presente.

Exemplo de estrutura HTML:

    <body>
      <div id="root"></div>
      <script src="path-to-embed-script.js"></script>
    </body>

Agora você pode abrir o site para visualizar o widget de chat e testar a integração.

O quê fazer em seguida

Cole o mesmo script em cada página onde deseja que o chat do agente apareça. Não inclua o script mais de uma vez na mesma página para evitar conflitos de carregamento.

Use as APIs disponíveis para aplicar estilos e layouts personalizados à interface do usuário do chat, habilitar feedback ou lidar com variáveis de contexto para personalizar as conversas dos usuários com um agente. Para obter mais informações, consulte os recursos a seguir: