Migração do Dialogflow ES para agentes conversacionais (Dialogflow CX)

Os agentes conversacionais (Dialogflow CX) oferecem-lhe controlos e ferramentas de conversação mais poderosos do que os agentes Dialogflow ES. Se o seu agente Dialogflow ES processar conversas complexas, deve considerar migrar para agentes conversacionais (Dialogflow CX).

Este guia descreve como migrar um agente do Dialogflow ES para agentes conversacionais (Dialogflow CX). Estes dois tipos de agentes têm muitas diferenças fundamentais, pelo que não existe uma forma simples de fazer esta migração.

Se usar este guia para uma migração, envie feedback positivo ou negativo clicando no botão Enviar feedback acima. Vamos usar este feedback para melhorar este guia ao longo do tempo.

A um nível elevado, o processo recomendado é um processo híbrido automatizado/manual. Vai usar uma ferramenta que lê alguns dos dados do seu agente Dialogflow ES, escreve esses dados no seu agente de agentes conversacionais (Dialogflow CX) e captura uma lista de tarefas. Em seguida, recrie o agente de agentes conversacionais (Dialogflow CX) completo com base nas práticas recomendadas, na lista de tarefas, e nos dados migrados pela ferramenta.

Compreenda os agentes de conversação (Dialogflow CX)

Antes de tentar esta migração, deve ter uma compreensão sólida de como funcionam os fluxos dos agentes conversacionais (Dialogflow CX). Pode começar aqui:

• Noções básicas do Flow

Também deve ler documentos de conceitos adicionais que tenham funcionalidades de que provavelmente vai precisar no seu novo agente. Foque-se no seguinte:

• Vista geral da consola
• Agentes
• Fluxos
• Páginas
• Controladores de estado
• Intenções
• Parâmetros
• Realizações
• Webhooks

Compreenda as diferenças entre o Dialogflow ES e os agentes conversacionais (Dialogflow CX)

Esta secção lista as diferenças mais importantes entre o Dialogflow ES e os agentes conversacionais (Dialogflow CX). Quando realizar os passos de migração manual mais tarde, deve consultar esta secção para obter orientações.

Estrutura e controlo do caminho de conversa

O Dialogflow ES oferece o seguinte para controlo da estrutura e do caminho da conversa:

• As intenções são usadas como componentes fundamentais do agente. Em qualquer ponto da conversa, é encontrada uma intenção, e, de certa forma, cada intenção é um nó para a conversa.
• O contexto é usado para controlar a conversa. O contexto é usado para controlar que intenções podem ser correspondidas em qualquer momento. O contexto expira após um determinado número de interações conversacionais. Por isso, este tipo de controlo pode ser impreciso para conversas longas.

Os agentes conversacionais (Dialogflow CX) oferecem uma hierarquia de recursos de estrutura e controlos mais precisos sobre o caminho da conversa:

• As páginas são nós do gráfico para a conversa. As conversas dos agentes conversacionais (Dialogflow CX) são semelhantes a máquinas de estados. Em qualquer ponto da conversa, uma página está ativa. Com base na introdução ou nos eventos do utilizador final, a conversa pode transitar para outra página. É comum uma página permanecer ativa durante várias interações de conversa.
• Os fluxos são grupos de páginas relacionadas. Cada fluxo deve abordar um tópico de conversa de nível superior.
• Os controladores de estado são usados para controlar as transições e as respostas. Existem três tipos de controladores de estado:
  • Percurso de intenção: contém uma intenção que tem de corresponder, respostas opcionais e transição de página opcional.
  • Percurso de condição: contém uma condição que tem de ser cumprida, respostas opcionais e uma transição de página opcional.
  • Controlador do evento: contém um nome do evento que tem de ser invocado, respostas opcionais e transição de página opcional.
• Scope é usado para controlar se é possível chamar um controlador de estado. A maioria dos controladores está associada a uma página ou a um fluxo completo. Se a página ou o fluxo associado estiver ativo, o controlador está no âmbito e pode ser chamado. Uma rota de intenção de agentes conversacionais (Dialogflow CX) no âmbito é semelhante a uma intenção do Dialogflow ES com um contexto de entrada ativo.

Ao criar os fluxos e as páginas do seu agente, certifique-se de que compreende as recomendações na secção de fluxo do guia de design de agentes.

Preenchimento de formulários

O Dialogflow ES usa o preenchimento de espaços para recolher os parâmetros necessários do utilizador final:

• Estes parâmetros são parâmetros de intenção marcados como obrigatórios.
• A intenção continua a ser correspondida até que todos os parâmetros obrigatórios sejam recolhidos.
• Pode definir um comando que peça ao utilizador final para fornecer um valor.

Os agentes conversacionais (Dialogflow CX) usam o preenchimento de formulários para recolher os parâmetros necessários do utilizador final:

• Estes parâmetros estão associados a uma página e são recolhidos enquanto a página está ativa.
• Usa caminhos de condições para páginas para determinar que o preenchimento do formulário está concluído. Normalmente, estes trajetos de condições fazem a transição para outra página.
• Pode definir um comando, bem como gestores de novos comandos para processar corretamente várias tentativas de recolher um valor.

Transições

O Dialogflow ES faz a transição automaticamente de uma intenção para a seguinte quando a entrada do utilizador final corresponde a uma intenção. Esta correspondência só pode ocorrer para intenções que não tenham um contexto de entrada ou intenções que tenham um contexto de entrada ativo.

Os agentes conversacionais (Dialogflow CX) transitam de uma página para a seguinte quando um controlador de estado no âmbito satisfaz os respetivos requisitos e fornece um destino de transição. Com estas transições, pode orientar os utilizadores finais de forma fiável através das conversas. Existem várias formas de controlar estas transições:

• A correspondência de intenções pode acionar um trajeto de intenção.
• A satisfação de uma condição pode acionar uma rota de condição.
• A invocação de um evento pode acionar um controlador de eventos.
• Os controladores de repetição podem causar uma transição quando o utilizador final não consegue fornecer um valor após várias tentativas.
• Pode usar alvos de transição simbólicos para alvos de transição.

Respostas do agente

As respostas do agente do Dialogflow ES são enviadas ao utilizador final quando uma intenção é correspondida:

• O agente pode selecionar uma mensagem para a resposta a partir de uma lista de possíveis respostas.
• As respostas podem ser específicas da plataforma, que podem usar formatos de respostas avançadas.
• As respostas podem ser acionadas por webhooks.

As respostas do agente dos agentes conversacionais (Dialogflow CX) são enviadas ao utilizador final quando o preenchimento é chamado. Ao contrário do preenchimento do Dialogflow ES, que envolve sempre um webhook, o preenchimento dos agentes conversacionais (Dialogflow CX) pode ou não envolver a chamada de um webhook, dependendo se o recurso de preenchimento tem um webhook configurado. As respostas estáticas e dinâmicas baseadas em respostas de webhook são controladas pelo processamento de pedidos. Existem várias formas de criar respostas do agente:

• O preenchimento pode ser fornecido a qualquer tipo de controlador de estado.
• Podem ser concatenadas várias respostas durante uma interação conversacional através da fila de respostas. Em alguns casos, esta funcionalidade pode simplificar o design do seu agente.
• Os agentes conversacionais (Dialogflow CX) não suportam respostas específicas da plataforma incorporadas. No entanto, oferece vários tipos de respostas, incluindo uma carga útil personalizada que pode ser usada para respostas específicas da plataforma.

Parâmetros

Os parâmetros do Dialogflow ES têm as seguintes caraterísticas:

• Definido apenas em intenções.
• Definidas pela introdução do utilizador final, eventos, webhooks e chamadas API.
• Referenciado em respostas, comandos de parâmetros, código de webhook e valores de parâmetros:
  • O formato de referência básico é $parameter-name.
  • As referências suportam a sintaxe de sufixos .original, .partial e .recent.
  • As referências podem especificar o contexto ativo: #context-name.parameter-name.
  • As referências podem especificar parâmetros de eventos: #event-name.parameter-name.

Os parâmetros dos agentes de conversação (Dialogflow CX) têm as seguintes caraterísticas:

• Definido em intenções e formulários de páginas.
• Os parâmetros de intenção e formulário são propagados para os parâmetros de sessão, onde estão disponíveis para referência durante a sessão.
• Definido pela entrada do utilizador final, webhooks, predefinição do parâmetro de preenchimento e chamadas API.
• Referenciado em respostas, comandos de parâmetros, controladores de novos comandos, predefinições de parâmetros e código de webhook:
  • O formato de referência é $session.params.parameter-id para parâmetros de sessão e $intent.params.parameter-id para parâmetros de intenção.
  • As referências de parâmetros de intenção suportam a sintaxe de sufixo .original e .resolved. Os parâmetros de sessão não suportam esta sintaxe.

Entidades do sistema

O Dialogflow ES suporta muitas entidades do sistema.

Os agentes conversacionais (Dialogflow CX) suportam muitas das mesmas entidades do sistema, mas existem algumas diferenças. Quando migrar, verifique se as entidades do sistema que está a usar no Dialogflow ES também são suportadas pelos agentes conversacionais (Dialogflow CX) para o mesmo idioma. Caso contrário, deve criar entidades personalizadas para estes.

Eventos

Os eventos do Dialogflow ES têm as seguintes caraterísticas:

• Pode ser invocado a partir de chamadas API ou webhooks para corresponder a uma intenção.
• Pode definir parâmetros.
• Um pequeno número de eventos é invocado por plataformas de integração.

Os eventos de agentes conversacionais (Dialogflow CX) têm as seguintes caraterísticas:

• Pode ser invocado a partir de chamadas de API ou webhooks para chamar um controlador de eventos.
• Não é possível definir parâmetros.
• Muitos eventos incorporados podem ser usados para processar a falta de introdução do utilizador final, a introdução do utilizador final não reconhecida, os parâmetros invalidados por um webhook e os erros de webhook.
• As invocações podem ser controladas pelas mesmas regras de âmbito que outros controladores de estado.

Intenções integradas

O Dialogflow ES suporta os seguintes comandos intencionais incorporados:

• Intenção de boas-vindas
• Intenções alternativas
• Intenções de seguimento predefinidas

A secção seguinte descreve o suporte dos agentes de conversação (Dialogflow CX) para intenções incorporadas:

• As intenções de boas-vindas são suportadas.
• Não são fornecidas intenções alternativas. Em alternativa, use os eventos no-match nos controladores de eventos.
• Para exemplos negativos, use a intenção negativa predefinida.
• Não são fornecidas intenções de seguimento predefinidas. Tem de criar estas intenções conforme exigido pelo seu agente. Por exemplo, é provável que precise de criar uma intenção para processar respostas negativas a uma pergunta do agente ("não", "não, obrigado", "não, não quero" e assim sucessivamente). As intenções dos agentes conversacionais (Dialogflow CX) são reutilizáveis no seu agente, pelo que só precisa de as definir uma vez. A utilização de diferentes caminhos de intenção para estas intenções comuns, em diferentes âmbitos, dá-lhe um controlo muito melhor sobre a conversa.

Webhooks

Os webhooks do Dialogflow ES têm as seguintes caraterísticas:

• Pode configurar um serviço de webhook para o agente.
• Cada intenção pode ser marcada como usando o webhook.
• Não existe suporte integrado para processar erros de webhook.
• As ações de intenção ou os nomes de intenções são usados por webhooks para determinar a origem da chamada no agente.
• A consola oferece o editor inline.

Os webhooks de agentes de conversação (Dialogflow CX) têm as seguintes caraterísticas:

• Pode configurar vários serviços de webhook para o agente.
• Cada preenchimento pode especificar opcionalmente uma chamada de webhook.
• Existe suporte incorporado para a resolução de erros de webhook.
• Um webhook de processamento de agentes conversacionais (Dialogflow CX) contém uma etiqueta. Esta etiqueta é semelhante a uma ação do Dialogflow ES, mas só é usada quando chama webhooks. O serviço de webhook pode usar estas etiquetas para determinar a origem da chamada no agente.
• A consola não tem um editor de código de webhook incorporado. É comum usar as funções do Cloud Run, mas existem muitas opções.

Quando migrar para agentes conversacionais (Dialogflow CX), tem de alterar o código do webhook, uma vez que as propriedades de pedido e resposta são diferentes.

Integrações

As integrações do Dialogflow ES e as integrações de agentes conversacionais (Dialogflow CX) suportam diferentes plataformas. Para plataformas suportadas por ambos os tipos de agentes, pode haver diferenças na configuração.

Se a integração do Dialogflow ES que estava a usar não for suportada pelos agentes conversacionais (Dialogflow CX), pode ter de mudar de plataforma ou implementar a integração por si.

Mais funcionalidades exclusivas dos agentes conversacionais (Dialogflow CX)

Existem muitas outras funcionalidades fornecidas apenas pelos agentes de conversação (Dialogflow CX). Deve considerar usar estas funcionalidades durante a migração. Por exemplo:

• NLU avançado
• Definições de voz avançadas (sensibilidade ao fim da fala, tempo limite de silêncio, etc.)
• Histórico de alterações
• Lógica condicional
• Entrada DTMF para integrações de telefonia
• Webhooks específicos do ambiente
• Experiências
• Grupos de trajetos
• Dados do agente de pesquisa
• Definições de segurança (ocultação e retenção de dados)
• Funções do sistema para respostas e condições avançadas
• Casos de teste
• Validação dos dados dos agentes

Práticas recomendadas

Antes da migração, familiarize-se com as práticas recomendadas de design de agentes conversacionais (Dialogflow CX). Muitas destas práticas recomendadas para agentes de conversação (Dialogflow CX) são semelhantes às práticas recomendadas do Dialogflow ES, mas algumas são exclusivas dos agentes de conversação (Dialogflow CX).

Acerca da ferramenta de migração

A ferramenta de migração copia a maioria dos dados do Dialogflow ES para o seu agente de agentes conversacionais (Dialogflow CX) e escreve num ficheiro TODO com uma lista de itens que têm de ser migrados manualmente. A ferramenta só copia tipos de entidades personalizadas e expressões de preparação de intenções. Deve considerar personalizar esta ferramenta de acordo com as suas necessidades específicas.

Código da ferramenta de migração

Segue-se o código da ferramenta. Deve rever o código desta ferramenta, para compreender o que faz. Pode querer alterar este código para processar situações específicas no seu agente. Nos passos abaixo, vai executar esta ferramenta.

// Package main implements the ES to CX migration tool.
package main

import (
	"context"
	"encoding/csv"
	"flag"
	"fmt"
	"os"
	"strings"
	"time"

	v2 "cloud.google.com/go/dialogflow/apiv2"
	proto2 "cloud.google.com/go/dialogflow/apiv2/dialogflowpb"
	v3 "cloud.google.com/go/dialogflow/cx/apiv3"
	proto3 "cloud.google.com/go/dialogflow/cx/apiv3/cxpb"
	"google.golang.org/api/iterator"
	"google.golang.org/api/option"
)

// Commandline flags
var v2Project *string = flag.String("es-project-id", "", "ES project")
var v3Project *string = flag.String("cx-project-id", "", "CX project")
var v2Region *string = flag.String("es-region-id", "", "ES region")
var v3Region *string = flag.String("cx-region-id", "", "CX region")
var v3Agent *string = flag.String("cx-agent-id", "", "CX region")
var outFile *string = flag.String("out-file", "", "Output file for CSV TODO items")
var dryRun *bool = flag.Bool("dry-run", false, "Set true to skip CX agent writes")

// Map from entity type display name to fully qualified name.
var entityTypeShortToLong = map[string]string{}

// Map from ES system entity to CX system entity
var convertSystemEntity = map[string]string{
	"sys.address":         "sys.address",
	"sys.any":             "sys.any",
	"sys.cardinal":        "sys.cardinal",
	"sys.color":           "sys.color",
	"sys.currency-name":   "sys.currency-name",
	"sys.date":            "sys.date",
	"sys.date-period":     "sys.date-period",
	"sys.date-time":       "sys.date-time",
	"sys.duration":        "sys.duration",
	"sys.email":           "sys.email",
	"sys.flight-number":   "sys.flight-number",
	"sys.geo-city-gb":     "sys.geo-city",
	"sys.geo-city-us":     "sys.geo-city",
	"sys.geo-city":        "sys.geo-city",
	"sys.geo-country":     "sys.geo-country",
	"sys.geo-state":       "sys.geo-state",
	"sys.geo-state-us":    "sys.geo-state",
	"sys.geo-state-gb":    "sys.geo-state",
	"sys.given-name":      "sys.given-name",
	"sys.language":        "sys.language",
	"sys.last-name":       "sys.last-name",
	"sys.street-address":  "sys.location",
	"sys.location":        "sys.location",
	"sys.number":          "sys.number",
	"sys.number-integer":  "sys.number-integer",
	"sys.number-sequence": "sys.number-sequence",
	"sys.ordinal":         "sys.ordinal",
	"sys.percentage":      "sys.percentage",
	"sys.person":          "sys.person",
	"sys.phone-number":    "sys.phone-number",
	"sys.temperature":     "sys.temperature",
	"sys.time":            "sys.time",
	"sys.time-period":     "sys.time-period",
	"sys.unit-currency":   "sys.unit-currency",
	"sys.url":             "sys.url",
	"sys.zip-code":        "sys.zip-code",
}

// Issues found for the CSV output
var issues = [][]string{
	{"Field", "Issue"},
}

// logIssue logs an issue for the CSV output
func logIssue(field string, issue string) {
	issues = append(issues, []string{field, issue})
}

// convertEntityType converts an ES entity type to CX
func convertEntityType(et2 *proto2.EntityType) *proto3.EntityType {
	var kind3 proto3.EntityType_Kind
	switch kind2 := et2.Kind; kind2 {
	case proto2.EntityType_KIND_MAP:
		kind3 = proto3.EntityType_KIND_MAP
	case proto2.EntityType_KIND_LIST:
		kind3 = proto3.EntityType_KIND_LIST
	case proto2.EntityType_KIND_REGEXP:
		kind3 = proto3.EntityType_KIND_REGEXP
	default:
		kind3 = proto3.EntityType_KIND_UNSPECIFIED
	}
	var expansion3 proto3.EntityType_AutoExpansionMode
	switch expansion2 := et2.AutoExpansionMode; expansion2 {
	case proto2.EntityType_AUTO_EXPANSION_MODE_DEFAULT:
		expansion3 = proto3.EntityType_AUTO_EXPANSION_MODE_DEFAULT
	default:
		expansion3 = proto3.EntityType_AUTO_EXPANSION_MODE_UNSPECIFIED
	}
	et3 := &proto3.EntityType{
		DisplayName:           et2.DisplayName,
		Kind:                  kind3,
		AutoExpansionMode:     expansion3,
		EnableFuzzyExtraction: et2.EnableFuzzyExtraction,
	}
	for _, e2 := range et2.Entities {
		et3.Entities = append(et3.Entities, &proto3.EntityType_Entity{
			Value:    e2.Value,
			Synonyms: e2.Synonyms,
		})
	}
	return et3
}

// convertParameterEntityType converts a entity type found in parameters
func convertParameterEntityType(intent string, parameter string, t2 string) string {
	if len(t2) == 0 {
		return ""
	}
	t2 = t2[1:] // remove @
	if strings.HasPrefix(t2, "sys.") {
		if val, ok := convertSystemEntity[t2]; ok {
			t2 = val
		} else {
			t2 = "sys.any"
			logIssue("Intent<"+intent+">.Parameter<"+parameter+">",
				"This intent parameter uses a system entity not supported by CX English agents. See the migration guide for advice. System entity: "+t2)
		}
		return fmt.Sprintf("projects/-/locations/-/agents/-/entityTypes/%s", t2)
	}
	return entityTypeShortToLong[t2]
}

// convertIntent converts an ES intent to CX
func convertIntent(intent2 *proto2.Intent) *proto3.Intent {
	if intent2.DisplayName == "Default Fallback Intent" ||
		intent2.DisplayName == "Default Welcome Intent" {
		return nil
	}

	intent3 := &proto3.Intent{
		DisplayName: intent2.DisplayName,
	}

	// WebhookState
	if intent2.WebhookState != proto2.Intent_WEBHOOK_STATE_UNSPECIFIED {
		logIssue("Intent<"+intent2.DisplayName+">.WebhookState",
			"This intent has webhook enabled. You must configure this in your CX agent.")
	}

	// IsFallback
	if intent2.IsFallback {
		logIssue("Intent<"+intent2.DisplayName+">.IsFallback",
			"This intent is a fallback intent. CX does not support this. Use no-match events instead.")
	}

	// MlDisabled
	if intent2.MlDisabled {
		logIssue("Intent<"+intent2.DisplayName+">.MlDisabled",
			"This intent has ML disabled. CX does not support this.")
	}

	// LiveAgentHandoff
	if intent2.LiveAgentHandoff {
		logIssue("Intent<"+intent2.DisplayName+">.LiveAgentHandoff",
			"This intent uses live agent handoff. You must configure this in a fulfillment.")
	}

	// EndInteraction
	if intent2.EndInteraction {
		logIssue("Intent<"+intent2.DisplayName+">.EndInteraction",
			"This intent uses end interaction. CX does not support this.")
	}

	// InputContextNames
	if len(intent2.InputContextNames) > 0 {
		logIssue("Intent<"+intent2.DisplayName+">.InputContextNames",
			"This intent uses context. See the migration guide for alternatives.")
	}

	// Events
	if len(intent2.Events) > 0 {
		logIssue("Intent<"+intent2.DisplayName+">.Events",
			"This intent uses events. Use event handlers instead.")
	}

	// TrainingPhrases
	var trainingPhrases3 []*proto3.Intent_TrainingPhrase
	for _, tp2 := range intent2.TrainingPhrases {
		if tp2.Type == proto2.Intent_TrainingPhrase_TEMPLATE {
			logIssue("Intent<"+intent2.DisplayName+">.TrainingPhrases",
				"This intent has a training phrase that uses a template (@...) training phrase type. CX does not support this.")
		}
		var parts3 []*proto3.Intent_TrainingPhrase_Part
		for _, part2 := range tp2.Parts {
			parts3 = append(parts3, &proto3.Intent_TrainingPhrase_Part{
				Text:        part2.Text,
				ParameterId: part2.Alias,
			})
		}
		trainingPhrases3 = append(trainingPhrases3, &proto3.Intent_TrainingPhrase{
			Parts:       parts3,
			RepeatCount: 1,
		})
	}
	intent3.TrainingPhrases = trainingPhrases3

	// Action
	if len(intent2.Action) > 0 {
		logIssue("Intent<"+intent2.DisplayName+">.Action",
			"This intent sets the action field. Use a fulfillment webhook tag instead.")
	}

	// OutputContexts
	if len(intent2.OutputContexts) > 0 {
		logIssue("Intent<"+intent2.DisplayName+">.OutputContexts",
			"This intent uses context. See the migration guide for alternatives.")
	}

	// ResetContexts
	if intent2.ResetContexts {
		logIssue("Intent<"+intent2.DisplayName+">.ResetContexts",
			"This intent uses context. See the migration guide for alternatives.")
	}

	// Parameters
	var parameters3 []*proto3.Intent_Parameter
	for _, p2 := range intent2.Parameters {
		if len(p2.Value) > 0 && p2.Value != "$"+p2.DisplayName {
			logIssue("Intent<"+intent2.DisplayName+">.Parameters<"+p2.DisplayName+">.Value",
				"This field is not set to $parameter-name. This feature is not supported by CX. See: https://cloud.google.com/dialogflow/es/docs/intents-actions-parameters#valfield.")
		}
		if len(p2.DefaultValue) > 0 {
			logIssue("Intent<"+intent2.DisplayName+">.Parameters<"+p2.DisplayName+">.DefaultValue",
				"This intent parameter is using a default value. CX intent parameters do not support default values, but CX page form parameters do. This parameter should probably become a form parameter.")
		}
		if p2.Mandatory {
			logIssue("Intent<"+intent2.DisplayName+">.Parameters<"+p2.DisplayName+">.Mandatory",
				"This intent parameter is marked as mandatory. CX intent parameters do not support mandatory parameters, but CX page form parameters do. This parameter should probably become a form parameter.")
		}
		for _, prompt := range p2.Prompts {
			logIssue("Intent<"+intent2.DisplayName+">.Parameters<"+p2.DisplayName+">.Prompts",
				"This intent parameter has a prompt. Use page form parameter prompts instead. Prompt: "+prompt)
		}
		if len(p2.EntityTypeDisplayName) == 0 {
			p2.EntityTypeDisplayName = "@sys.any"
			logIssue("Intent<"+intent2.DisplayName+">.Parameters<"+p2.DisplayName+">.EntityTypeDisplayName",
				"This intent parameter does not have an entity type. CX requires an entity type for all parameters..")
		}
		parameters3 = append(parameters3, &proto3.Intent_Parameter{
			Id:         p2.DisplayName,
			EntityType: convertParameterEntityType(intent2.DisplayName, p2.DisplayName, p2.EntityTypeDisplayName),
			IsList:     p2.IsList,
		})
		//fmt.Printf("Converted parameter: %+v\n", parameters3[len(parameters3)-1])
	}
	intent3.Parameters = parameters3

	// Messages
	for _, message := range intent2.Messages {
		m, ok := message.Message.(*proto2.Intent_Message_Text_)
		if ok {
			for _, t := range m.Text.Text {
				warnings := ""
				if strings.Contains(t, "#") {
					warnings += " This message may contain a context parameter reference, but CX does not support this."
				}
				if strings.Contains(t, ".original") {
					warnings += " This message may contain a parameter reference suffix of '.original', But CX only supports this for intent parameters (not session parameters)."
				}
				if strings.Contains(t, ".recent") {
					warnings += " This message may contain a parameter reference suffix of '.recent', but CX does not support this."
				}
				if strings.Contains(t, ".partial") {
					warnings += " This message may contain a parameter reference suffix of '.partial', but CX does not support this."
				}
				logIssue("Intent<"+intent2.DisplayName+">.Messages",
					"This intent has a response message. Use fulfillment instead."+warnings+" Message: "+t)
			}
		} else {
			logIssue("Intent<"+intent2.DisplayName+">.Messages",
				"This intent has a non-text response message. See the rich response message information in the migration guide.")
		}
		if message.Platform != proto2.Intent_Message_PLATFORM_UNSPECIFIED {
			logIssue("Intent<"+intent2.DisplayName+">.Platform",
				"This intent has a message with a non-default platform. See the migration guide for advice.")
		}
	}

	return intent3
}

// migrateEntities migrates ES entities to your CX agent
func migrateEntities(ctx context.Context) error {
	var err error

	// Create ES client
	var client2 *v2.EntityTypesClient
	options2 := []option.ClientOption{}
	if len(*v2Region) > 0 {
		options2 = append(options2,
			option.WithEndpoint(*v2Region+"-dialogflow.googleapis.com:443"))
	}
	client2, err = v2.NewEntityTypesClient(ctx, options2...)
	if err != nil {
		return err
	}
	defer client2.Close()
	var parent2 string
	if len(*v2Region) == 0 {
		parent2 = fmt.Sprintf("projects/%s/agent", *v2Project)
	} else {
		parent2 = fmt.Sprintf("projects/%s/locations/%s/agent", *v2Project, *v2Region)
	}

	// Create CX client
	var client3 *v3.EntityTypesClient
	options3 := []option.ClientOption{}
	if len(*v3Region) > 0 {
		options3 = append(options3,
			option.WithEndpoint(*v3Region+"-dialogflow.googleapis.com:443"))
	}
	client3, err = v3.NewEntityTypesClient(ctx, options3...)
	if err != nil {
		return err
	}
	defer client3.Close()
	parent3 := fmt.Sprintf("projects/%s/locations/%s/agents/%s", *v3Project, *v3Region, *v3Agent)

	// Read each V2 entity type, convert, and write to V3
	request2 := &proto2.ListEntityTypesRequest{
		Parent: parent2,
	}
	it2 := client2.ListEntityTypes(ctx, request2)
	for {
		var et2 *proto2.EntityType
		et2, err = it2.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Printf("Entity Type: %s\n", et2.DisplayName)

		if *dryRun {
			convertEntityType(et2)
			continue
		}

		request3 := &proto3.CreateEntityTypeRequest{
			Parent:     parent3,
			EntityType: convertEntityType(et2),
		}
		et3, err := client3.CreateEntityType(ctx, request3)
		entityTypeShortToLong[et3.DisplayName] = et3.Name
		if err != nil {
			return err
		}

		// ES and CX each have a quota limit of 60 design-time requests per minute
		time.Sleep(2 * time.Second)
	}
	return nil
}

// migrateIntents migrates intents to your CX agent
func migrateIntents(ctx context.Context) error {
	var err error

	// Create ES client
	var client2 *v2.IntentsClient
	options2 := []option.ClientOption{}
	if len(*v2Region) > 0 {
		options2 = append(options2,
			option.WithEndpoint(*v2Region+"-dialogflow.googleapis.com:443"))
	}
	client2, err = v2.NewIntentsClient(ctx, options2...)
	if err != nil {
		return err
	}
	defer client2.Close()
	var parent2 string
	if len(*v2Region) == 0 {
		parent2 = fmt.Sprintf("projects/%s/agent", *v2Project)
	} else {
		parent2 = fmt.Sprintf("projects/%s/locations/%s/agent", *v2Project, *v2Region)
	}

	// Create CX client
	var client3 *v3.IntentsClient
	options3 := []option.ClientOption{}
	if len(*v3Region) > 0 {
		options3 = append(options3,
			option.WithEndpoint(*v3Region+"-dialogflow.googleapis.com:443"))
	}
	client3, err = v3.NewIntentsClient(ctx, options3...)
	if err != nil {
		return err
	}
	defer client3.Close()
	parent3 := fmt.Sprintf("projects/%s/locations/%s/agents/%s", *v3Project, *v3Region, *v3Agent)

	// Read each V2 entity type, convert, and write to V3
	request2 := &proto2.ListIntentsRequest{
		Parent:     parent2,
		IntentView: proto2.IntentView_INTENT_VIEW_FULL,
	}
	it2 := client2.ListIntents(ctx, request2)
	for {
		var intent2 *proto2.Intent
		intent2, err = it2.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Printf("Intent: %s\n", intent2.DisplayName)
		intent3 := convertIntent(intent2)
		if intent3 == nil {
			continue
		}

		if *dryRun {
			continue
		}

		request3 := &proto3.CreateIntentRequest{
			Parent: parent3,
			Intent: intent3,
		}
		_, err := client3.CreateIntent(ctx, request3)
		if err != nil {
			return err
		}

		// ES and CX each have a quota limit of 60 design-time requests per minute
		time.Sleep(2 * time.Second)
	}
	return nil
}

// checkFlags checks commandline flags
func checkFlags() error {
	flag.Parse()
	if len(*v2Project) == 0 {
		return fmt.Errorf("Need to supply es-project-id flag")
	}
	if len(*v3Project) == 0 {
		return fmt.Errorf("Need to supply cx-project-id flag")
	}
	if len(*v2Region) == 0 {
		fmt.Printf("No region supplied for ES, using default\n")
	}
	if len(*v3Region) == 0 {
		return fmt.Errorf("Need to supply cx-region-id flag")
	}
	if len(*v3Agent) == 0 {
		return fmt.Errorf("Need to supply cx-agent-id flag")
	}
	if len(*outFile) == 0 {
		return fmt.Errorf("Need to supply out-file flag")
	}
	return nil
}

// closeFile is used as a convenience for defer
func closeFile(f *os.File) {
	err := f.Close()
	if err != nil {
		fmt.Fprintf(os.Stderr, "ERROR closing CSV file: %v\n", err)
		os.Exit(1)
	}
}

func main() {
	if err := checkFlags(); err != nil {
		fmt.Fprintf(os.Stderr, "ERROR checking flags: %v\n", err)
		os.Exit(1)
	}
	ctx := context.Background()
	if err := migrateEntities(ctx); err != nil {
		fmt.Fprintf(os.Stderr, "ERROR migrating entities: %v\n", err)
		os.Exit(1)
	}
	if err := migrateIntents(ctx); err != nil {
		fmt.Fprintf(os.Stderr, "ERROR migrating intents: %v\n", err)
		os.Exit(1)
	}
	csvFile, err := os.Create(*outFile)
	if err != nil {
		fmt.Fprintf(os.Stderr, "ERROR opening output file: %v", err)
		os.Exit(1)
	}
	defer closeFile(csvFile)
	csvWriter := csv.NewWriter(csvFile)
	if err := csvWriter.WriteAll(issues); err != nil {
		fmt.Fprintf(os.Stderr, "ERROR writing CSV output file: %v", err)
		os.Exit(1)
	}
	csvWriter.Flush()
}

Migração de tipos de entidades com ferramentas

Os tipos de entidades do Dialogflow ES e os tipos de entidades dos agentes conversacionais (Dialogflow CX) são muito semelhantes, pelo que são o tipo de dados mais fácil de migrar. A ferramenta copia simplesmente os tipos de entidades tal como estão.

Migração de ferramentas de intenções

As intenções do Dialogflow ES e as intenções dos agentes conversacionais (Dialogflow CX) são muito diferentes.

As intenções do Dialogflow ES são usadas como os elementos base do agente; e contêm expressões de preparação, respostas, contexto para controlo de conversas, configurações de webhook, eventos, ações e parâmetros de preenchimento de espaços.

Os agentes conversacionais (Dialogflow CX) moveram a maioria destes dados para outros recursos. As intenções dos agentes conversacionais (Dialogflow CX) só têm expressões de formação e parâmetros, o que torna as intenções reutilizáveis no agente. A ferramenta apenas copia estes dois tipos de dados de intenção para as intenções dos seus agentes conversacionais (Dialogflow CX).

Limitações da ferramenta de migração

A ferramenta de migração não suporta o seguinte:

• Mega agentes: a ferramenta não consegue ler a partir de vários subagentes, mas pode chamar a ferramenta várias vezes em relação a cada subagente.
• Agentes multilingues: deve modificar a ferramenta para criar expressões de formação e entradas de entidades multilingues.
• Validação de entidades do sistema para idiomas que não sejam o inglês: A ferramenta cria itens TODO quando encontra entidades do sistema que não são suportadas por agentes conversacionais (Dialogflow CX), partindo do princípio de que o inglês é o idioma predefinido e que usa uma região dos EUA. O suporte de entidades do sistema varia consoante o idioma e a região. Para outros idiomas e regiões, deve modificar a ferramenta para realizar esta verificação.

Passos de migração essenciais

As subsecções seguintes descrevem os passos de migração a realizar. Não tem de seguir estes passos manuais pela ordem indicada e, por vezes, pode ter de os executar em simultâneo ou numa ordem diferente. Leia os passos e comece a planear as alterações antes de as fazer.

Depois de executar a ferramenta de migração, pode reconstruir o agente de agentes conversacionais (Dialogflow CX). Ainda terá uma quantidade razoável de trabalho de migração a fazer, mas a maioria dos dados introduzidos manualmente estará presente no agente de agentes conversacionais (Dialogflow CX) e no ficheiro TODO.

Crie o seu agente de agentes conversacionais (Dialogflow CX)

Se ainda não o fez, crie o seu agente de agentes conversacionais (Dialogflow CX). Certifique-se de que usa o mesmo idioma predefinido que o seu agente do Dialogflow ES.

Execute a ferramenta de migração

Siga os passos abaixo para executar a ferramenta:

1. Se ainda não o fez, instale o Go no seu computador.
2. Crie um diretório para o código da ferramenta denominado migrate.
3. Copie o código da ferramenta acima para um ficheiro neste diretório denominado main.go.
4. Modifique o código, se necessário, para o seu caso.

5. Crie um módulo Go neste diretório. Por exemplo:

   go mod init migrate
   

6. Instale as bibliotecas cliente Go do Dialogflow ES V2 e dos agentes conversacionais (Dialogflow CX) V3:

   go get cloud.google.com/go/dialogflow/apiv2
   go get cloud.google.com/go/dialogflow/cx/apiv3
   

7. Certifique-se de que configurou a autenticação da biblioteca de cliente.

8. Execute a ferramenta e guarde o resultado no ficheiro:

   go run main.go -es-project-id=<ES_PROJECT_ID> -cx-project-id=<CX_PROJECT_ID> \
   -cx-region-id=<CX_REGION_ID> -cx-agent-id=<CX_AGENT_ID> -out-file=out.csv
   

Resolução de problemas da ferramenta de migração

Se tiver erros ao executar a ferramenta, verifique o seguinte:

Erro

Resolução

Erro de RPC que indica que uma parte da expressão de treino menciona um parâmetro não definido para a intenção.

Isto pode acontecer se tiver usado anteriormente a API Dialogflow ES para criar parâmetros de intenção de uma forma inconsistente com as expressões de treino. Para corrigir este problema, mude o nome do parâmetro do Dialogflow ES na consola, verifique se as frases de preparação estão a usar o parâmetro corretamente e, de seguida, clique em guardar. Isto também pode acontecer se as suas expressões de treino fizerem referência a parâmetros inexistentes.

Depois de corrigir os erros, tem de limpar o agente de agentes conversacionais (Dialogflow CX) de intenções e entidades antes de executar novamente a ferramenta de migração.

Mover dados de intenções do Dialogflow ES para agentes conversacionais (Dialogflow CX)

A ferramenta migra as expressões de preparação e os parâmetros de intenções para intenções de agentes conversacionais (Dialogflow CX), mas existem muitos outros campos de intenções do Dialogflow ES que têm de ser migrados manualmente.

Uma intenção do Dialogflow ES pode precisar de uma página de agentes conversacionais (Dialogflow CX) correspondente, uma intenção de agentes conversacionais (Dialogflow CX) correspondente ou ambas.

Se uma correspondência de intenção do Dialogflow ES for usada para fazer a transição da conversa de um nó de conversa específico para outro, deve ter duas páginas no seu agente relacionadas com esta intenção:

• A página original que contém a rota de intenção, que vai transitar para a página seguinte: A rota de intenção na página original pode ter mensagens de processamento de pedidos de agentes conversacionais (Dialogflow CX) semelhantes às respostas de intenção do Dialogflow ES. Pode ter muitos caminhos de intenção nesta página. Enquanto a página original estiver ativa, estas rotas de intenção podem fazer a transição da conversa para muitos caminhos possíveis. Muitos intenções do Dialogflow ES partilham a mesma página original correspondente dos agentes conversacionais (Dialogflow CX).
• A página seguinte, que é o destino de transição para a rota de intenção na página original: O preenchimento de entrada dos agentes conversacionais (Dialogflow CX) para a página seguinte pode ter mensagens de preenchimento dos agentes conversacionais (Dialogflow CX) semelhantes às respostas de intenção do Dialogflow ES.

Se um intento do Dialogflow ES contiver parâmetros obrigatórios, deve criar uma página de agentes conversacionais (Dialogflow CX) correspondente com os mesmos parâmetros num formulário.

É comum uma intenção de agentes conversacionais (Dialogflow CX) e uma página de agentes conversacionais (Dialogflow CX) partilharem a mesma lista de parâmetros, o que significa que uma única intenção do Dialogflow ES tem uma página de agentes conversacionais (Dialogflow CX) correspondente e uma intenção de agentes conversacionais (Dialogflow CX) correspondente. Quando uma intenção de agentes conversacionais (Dialogflow CX) com parâmetros numa rota de intenção é correspondida, a conversa transita frequentemente para uma página com os mesmos parâmetros. Os parâmetros extraídos da correspondência de intenção são propagados para parâmetros de sessão, que estão disponíveis para preencher parcial ou totalmente os parâmetros do formulário de página.

Os intentos alternativos e os intentos de seguimento predefinidos não existem nos agentes conversacionais (Dialogflow CX). Consulte as intenções integradas.

A tabela seguinte descreve como mapear dados de intenções específicos dos recursos do Dialogflow ES para os agentes conversacionais (Dialogflow CX):

Dados de intenções do Dialogflow ES	Dados correspondentes de agentes de conversação (Dialogflow CX)	Ação necessária
Expressões de preparação	Expressões de preparação de intenções	Migrado por ferramenta. A ferramenta verifica a compatibilidade com entidades do sistema e cria itens TODO para entidades do sistema não suportadas.
Respostas do agente	Mensagens de resposta de processamento	Consulte as respostas do agente.
Contexto para o controlo da conversa	Nenhum	Consulte o artigo Controlo da estrutura e do caminho de conversa.
Definição do webhook	Configuração do webhook de processamento	Consulte os webhooks.
Eventos	Controladores de eventos ao nível do fluxo ou da página	Veja os eventos.
Ações	Etiquetas de webhook de processamento	Consulte os webhooks.
Parâmetros	Parâmetros de intenção e/ou parâmetros de formulário da página	Migrado para parâmetros de intenção por ferramenta. Se os parâmetros forem obrigatórios, a ferramenta cria itens TODO para uma possível migração para uma página. Consulte os parâmetros.
Comandos de parâmetros	Comandos de parâmetros de formulário da página	Veja o preenchimento de formulários.

Crie fluxos

Crie um fluxo para cada tópico de conversa de nível superior. Os tópicos em cada fluxo devem ser distintos, para que a conversa não salte frequentemente entre fluxos.

Se estava a usar um mega agente, cada subagente deve tornar-se um ou mais fluxos.

Comece com caminhos de conversa básicos

É melhor testar o agente com o simulador enquanto itera as alterações. Por isso, deve focar-se inicialmente nos caminhos de conversa básicos no início da conversa e testar à medida que faz alterações. Depois de os fazer funcionar, avance para caminhos de conversa mais detalhados.

Controladores de estado ao nível do fluxo versus ao nível da página

Ao criar controladores de estado, considere se devem ser aplicados ao nível do fluxo ou da página. Um controlador ao nível do fluxo está no âmbito sempre que o fluxo (e, por conseguinte, qualquer página no fluxo) está ativo. Um controlador ao nível da página só está no âmbito quando a página específica está ativa. Os processadores ao nível do fluxo são semelhantes às intenções do Dialogflow ES sem contexto de entrada. Os controladores ao nível da página são semelhantes às intenções do Dialogflow ES com contexto de entrada.

Código do webhook

As propriedades de pedido e resposta do webhook são diferentes para agentes conversacionais (Dialogflow CX). Consulte a secção sobre webhooks.

Conetores de conhecimentos

Os agentes conversacionais (Dialogflow CX) ainda não suportam conetores de conhecimentos. Tem de implementar estas como intenções normais ou aguardar até que os agentes conversacionais (Dialogflow CX) suportem os conetores de conhecimentos.

Definições do agente

Reveja as definições do agente Dialogflow ES e ajuste as definições do agente de agentes conversacionais (Dialogflow CX) conforme necessário.

Nota: se as definições do agente não tiverem a preparação automática configurada, tem de preparar manualmente o agente antes de testar as alterações.

Use o ficheiro TODO

A ferramenta de migração gera um ficheiro CSV. Os itens nesta lista focam-se em dados específicos que podem precisar de atenção. Importe este ficheiro para uma folha de cálculo. Resolva cada item na folha de cálculo, usando uma coluna para marcar a conclusão.

Migração da utilização da API

Se o seu sistema usar a API Dialogflow ES para chamadas de tempo de execução ou de tempo de design, tem de atualizar este código para usar a API Conversational Agents (Dialogflow CX). Se usar apenas as chamadas detect intent no tempo de execução, esta atualização deve ser relativamente simples.

Integrações

Se o seu agente usar integrações, consulte a secção de integrações e faça as alterações necessárias.

Passos de migração recomendados

As subsecções seguintes descrevem os passos de migração recomendados.

Validação

Use a validação de agentes para verificar se o seu agente segue as práticas recomendadas.

Testes

Ao executar os passos de migração manual acima, deve testar o seu agente com o simulador. Quando o seu agente parecer estar a funcionar, deve comparar as conversas entre os seus agentes Dialogflow ES e Conversacionais (Dialogflow CX) e verificar se o comportamento é semelhante ou melhorado.

Ao testar estas conversas com o simulador, deve criar casos de teste para evitar regressões futuras.

Ambientes

Reveja os seus ambientes do Dialogflow ES e atualize os seus ambientes de agentes conversacionais (Dialogflow CX) conforme necessário.