Configurar e criar agentes multilíngues

Agentes multilíngues se comunicam com clientes em idiomas diferentes, mantendo todo o conteúdo em um único agente. Em muitos casos, eles detectam automaticamente o idioma desejado com base na configuração do navegador da Web do usuário do agente e respondem no mesmo idioma, fornecendo uma experiência mais personalizada e envolvente para os clientes.

Ao criar um agente, especifique seu idioma principal.

Depois de adicionar idiomas secundários a um agente, você será responsável por fornecer as traduções para mensagens em tópicos criados. Para agentes que usam orquestração gerativa, as mensagens geradas são traduzidas automaticamente.

Quando um cliente inicia uma sessão com um agente publicado, o agente seleciona um de seus idiomas para corresponder ao idioma especificado no cliente ou navegador do cliente. Se o agente não puder detectar o idioma do cliente ou do navegador ou se o idioma detectado não for um dos idiomas especificados para o agente, o agente usará como padrão o idioma principal.

Você pode criar um agente para alterar o idioma que ele usa durante uma conversa (consulte Fazer um agente mudar para outro idioma). Você também pode configurar um agente que usa orquestração generativa para alternar dinamicamente idiomas para seguir o idioma usado na conversa atual (consulte Configurar um agente para alternar idioma dinâmico).

Para obter a lista de idiomas com suporte, consulte Suporte a idiomas.

Adicionar idiomas a um agente

1. Vá para a página Configurações do agente e selecione Idiomas.

2. Selecione Adicionar idiomas.

3. No painel Adicionar idiomas , selecione os idiomas que deseja adicionar ao agente e selecione Adicionar.

4. Examine a lista de idiomas e feche a página Configurações .

Gerenciar a localização de um agente multilíngue

No Copilot Studio, você executa todos os tópicos e edição de conteúdo no idioma principal do agente. Esta seção explica como baixar cadeias de texto do seu agente e traduzi-las para os idiomas secundários do agente. Depois de carregar as cadeias de caracteres traduzidas, você pode alternar o idioma no painel de teste e verificar se as conversas nos idiomas secundários também fluem conforme o esperado.

Preparar conteúdo localizado

Quando você baixa o arquivo de localização para um idioma secundário pela primeira vez, todas as cadeias de caracteres estão no idioma principal do agente. Depois de baixar um arquivo de localização, use-o com seu processo de localização preferido.

1. Vá para a página Configurações do agente e selecione Idiomas.

2. Na página Idiomas , na lista de idiomas secundários, selecione Carregar para o idioma que você deseja atualizar.

3. No painel Atualizar localizações , selecione o formato JSON ou ResX para baixar o arquivo de localização atual para esse idioma.

   Observação

   O arquivo baixado contém o conteúdo de localização mais recente para o agente. Se você precisar baixar versões anteriores do arquivo de localização, abra a solução do agente.

4. Abra o arquivo baixado e substitua as strings do idioma principal pelo texto traduzido apropriado.

5. Retorne ao painel Atualizar localizações , selecione Procurar e carregue o arquivo traduzido.

6. Feche o painel Atualizar localizações e a página Configurações .

Atualizar conteúdo localizado

Se você fizer alterações nas cadeias de caracteres de idioma primário, também deverá atualizar o conteúdo nos idiomas secundários. Esse processo inclui conteúdo novo e conteúdo modificado. As alterações incrementais não são traduzidas automaticamente. Você deve baixar o arquivo JSON ou ResX do idioma secundário e atualizar as cadeias de caracteres não traduzidas utilizando seu processo de localização preferido.

O cenário a seguir é típico do fluxo de trabalho para conteúdo traduzido. Você traduziu anteriormente seu idioma principal (en-US) para um idioma secundário (fr-FR) e adicionou e modificou conteúdo no idioma principal. Quando você baixa o arquivo de localização para o idioma secundário, todo o novo conteúdo está no idioma primário (en-US). No entanto, o conteúdo modificado ainda aparece no idioma secundário. Como o conteúdo modificado usa a mesma ID, você deve comparar o novo arquivo com o arquivo carregado anteriormente.

Disponibilizar conteúdo dinâmico de Cartões Adaptáveis para localização

Os arquivos de localização não incluem strings de tipo misto dos Cartões Adaptáveis. Se você precisar localizar um Cartão Adaptável em que uma cadeia de caracteres possa incluir texto estático e variáveis (conteúdo dinâmico), use a solução alternativa a seguir. O procedimento mostra como usar um nó de Set text variable para armazenar a cadeia de caracteres completa com o texto estático e variáveis em uma variável intermediária. Em seguida, você faz referência apenas a essa variável intermediária em seu Cartão Adaptável. Quando você baixa um arquivo de localização para o agente, o valor da variável intermediária, com o texto estático e as referências de variável, está disponível para localização como parte de uma ação setVariable.

Para tornar o conteúdo dinâmico de um Cartão Adaptável localizável:

1. Adicione um nó Definir valor de variável antes do Cartão Adaptável. Esta etapa cria uma representação YAML que você pode atualizar usando o editor de códigos para converter o nó em um nó Definir variável de texto. Não é possível criar nós Definir variável de texto diretamente da tela de criação.

2. No nó Definir valor de variável , crie uma nova variável, mas ainda não defina o valor.

3. Abra o editor de código do tópico.

4. No editor de códigos, localize a parte que representa o nó Definir valor de variável e substitua kind: SetVariable por kind: SetTextVariable. Essa alteração converte o nó Definir valor de variável em um nó Definir variável de texto.

5. Feche o editor de códigos.

6. Selecione o campo inferior do nó Definir variável de texto e insira a cadeia de caracteres completa com o texto estático e as variáveis que você deseja mostrar em seu Cartão Adaptável. Insira uma variável da mesma forma que você inseriria uma variável em uma mensagem.

7. Atualize seu Cartão Adaptável com uma referência a essa nova variável.

8. Salve o tópico. Agora você pode baixar o arquivo de localização e verificar se ele inclui o conteúdo dinâmico para seus Cartões Adaptáveis.

Testar um agente multilíngue

1. Abra o painel de teste.

2. Selecione os três pontos (...) no topo do painel de teste e selecione o idioma que deseja. O painel de teste se recarrega, desta vez usando o idioma selecionado. A tela de criação permanece no idioma primário e você não pode salvar as alterações feitas em um tópico até voltar para o idioma primário.

3. Para testar o agente, insira uma mensagem no idioma selecionado.

Você também pode definir o idioma do navegador para um dos idiomas do agente e ir para o site de demonstração predefinido. O site de demonstração é aberto no idioma especificado e o agente conversa nesse idioma.

Fazer um agente mudar para outro idioma

Ao criar conteúdo, você pode configurar o agente para alternar para outro idioma no meio de uma conversa. A lógica pode estar presente em qualquer tópico no agente. No entanto, a melhor prática é alternar o idioma diretamente após um nó de Pergunta, o que garante que todas as mensagens a seguir até o próximo nó de Pergunta estejam no mesmo idioma.

Para alterar o idioma atual do agente, defina a User.Language do sistema como um dos idiomas secundários do agente. Essa seleção altera o idioma falado pelo seu agente imediatamente.

Configurar um agente para alternância de linguagem dinâmica

Você pode configurar um agente para detectar o idioma que um cliente usa e responder no mesmo idioma. Com essa configuração, o agente pode alternar idiomas várias vezes ao longo de uma única conversa. O cenário a seguir mostra como configurar um agente para alternar entre holandês e inglês. Você pode estendê-lo para qualquer combinação dos idiomas compatíveis com o agente.

Este cenário usa um tópico com um gatilho de tópico Mensagem recebida. Este gatilho de tópico permite que seu agente examine todas as mensagens recebidas. Este tópico usa um prompt personalizado para detectar o idioma e uma condição para definir a variável do sistema de linguagem do agente.

1. Crie um tópico.

2. Substitua o tipo de gatilho padrão para o tópico por uma mensagem é recebida.

3. Adicione um prompt ao tópico:

   1. Selecione o ícone Adicionar nó abaixo do nó Gatilho.

   2. Selecione Adicionar uma ferramenta>Novo prompt.

   3. No editor de prompt, insira um nome representativo para seu prompt, como "Detectar idioma".

   4. No painel Instruções, insira "Determinar em qual idioma esta mensagem é escrita em: ".

   5. Na parte inferior do painel Instruções , selecione Adicionar conteúdo e selecione Texto. Uma janela aparece convidando você a inserir um nome e uma mensagem de exemplo.

   6. Para Nome, insira "Mensagem". Para dados de exemplo, insira "Mensagem do usuário" e selecione Fechar.

   7. No painel de resposta Modelo , alterne o formato De saída para JSON.

   8. Selecione Testar. A solicitação mostra um literal JSON, com uma única propriedade identificando o idioma como inglês.

      

   9. Clique em Salvar. Um nó Solicitação é exibido na tela.

4. Configure o nó Solicitação:

   1. Para Entrada, selecione a variávelActivity.Text do sistema (o texto da mensagem de entrada).
   2. Para Saída, crie uma nova variável chamada DetectedLanguage.

5. Ramificar sua lógica com base no idioma detectado:

   1. Adicione uma condição abaixo do nó Prompt.

   2. Baseie sua condição na variável DetectedLanguage.structuredOutput.languagepersonalizada, que contém o nome do idioma detectado.

   3. Adicione um branch de condição para cada idioma que você precisa detectar.

   4. Em cada ramificação, adicione um nó Definir valor da variável para definir a variável de sistema User.Language da maneira indicada. A imagem a seguir mostra um tópico com uma condição para alternar entre holandês e inglês.

      

Solucionar problemas de um agente multilíngue

Esta seção fornece dicas para entender o comportamento inesperado do agente multilíngue.

Comportamento agente multilíngue para idiomas que não estão configurados

Se um usuário configurar seu navegador para um idioma que você não configurou para o agente, o agente retornará ao idioma principal.

Especifique o idioma primário para um agente ao criar o agente. Você não pode alterar o idioma primário após a criação, mas pode alterar a região para o idioma primário do agente, se mais de uma região estiver disponível.

Comportamento do agente multilíngue para traduções ausentes

Se você adicionar mensagens a um agente em seu idioma principal, mas não carregar as traduções para as novas mensagens, o agente mostrará as alterações não traduzidas em seu idioma principal. Sempre verifique se as traduções estão atualizadas depois de fazer alterações em um agente.

Os arquivos de localização não incluem strings de tipo misto dos Cartões Adaptáveis. Se você precisar localizar Cartões Adaptáveis em que uma cadeia de caracteres pode incluir texto estático e variáveis (conteúdo dinâmico), você deve usar uma solução alternativa. Saiba como armazenar uma cadeia de caracteres de tipo misto em uma variável de texto antes de usá-la em um Cartão Adaptável.

Erros ao publicar um agente multilíngue

Quando você tenta publicar um agente multilíngue, se vir a mensagem de erro "Falha na validação do bot" com o código de erro de resposta bruta, SynonymsNotUnique, o arquivo de localização conterá sinônimos duplicados ou um sinônimo que corresponder a um valor DisplayName. Normalmente, você encontra esse erro quando um nó contém um Entity.Definition.'closedListItem' no qual um dos seguintes cenários ocorreu:

• Um dos Synonyms elementos não é exclusivo.
• Um dos Synonyms elementos tem o mesmo valor que o elemento DisplayName.

Todos os Synonyms para a mesma entidade devem ser exclusivos e ter um nome diferente do elemento DisplayName.

Para corrigir o erro, examine o arquivo JSON ou ResX para seu idioma secundário e identifique todas as instâncias em que essa condição possa estar presente.