Migrar do Dialogflow ES para o Dialogflow CX

Os agentes do Dialogflow CX oferecem controles e ferramentas de conversa mais eficientes do que os agentes do Dialogflow ES. Se o agente do Dialogflow ES processa conversas complexas, considere migrar para o Dialogflow CX.

Este guia descreve como migrar um agente do Dialogflow ES para o Dialogflow CX. Esses dois tipos de agentes têm muitas diferenças fundamentais, então não há uma maneira simples de realizar essa migração.

Se você usar este guia para uma migração, envie feedback positivo ou negativo clicando no botão Enviar feedback acima. Vamos usar esse feedback para melhorar este guia com o tempo.

De modo geral, o processo recomendado é um híbrido automatizado/manual. Você vai usar uma ferramenta que lê alguns dos dados do seu agente do Dialogflow ES, grava esses dados no seu agente do Dialogflow CX e captura uma lista de tarefas. Em seguida, recrie o agente completo do Dialogflow CX usando as práticas recomendadas, a lista de tarefas e os dados migrados pela ferramenta.

Entender o Dialogflow CX

Antes de tentar essa migração, você precisa entender bem como os fluxos do Dialogflow CX funcionam. Comece aqui:

• Noções básicas sobre fluxos

Leia também outros documentos de conceitos que têm recursos que você provavelmente vai precisar no seu novo agente. Concentre-se no seguinte:

• Visão geral do console
• Agentes
• Fluxos
• Páginas
• Manipuladores de estado
• Intents
• Parâmetros
• Atendimentos
• Webhooks

Entender as diferenças entre o Dialogflow ES e o Dialogflow CX

Esta seção lista as diferenças mais importantes entre o Dialogflow ES e o Dialogflow CX. Ao realizar etapas de migração manual mais tarde, consulte esta seção para receber orientações.

Estrutura e controle do caminho da conversa

O Dialogflow ES oferece o seguinte para controle de estrutura e caminho de conversa:

• As intents são usadas como elementos básicos do agente. Em qualquer ponto da conversa, uma intent é correspondida, e, de certa forma, cada intent é um nó para a conversa.
• O contexto é usado para controlar a conversa. O contexto é usado para controlar quais intents podem ser correspondidas a qualquer momento. O contexto expira após um determinado número de rodadas de conversa. Por isso, esse tipo de controle pode ser impreciso em conversas longas.

O Dialogflow CX oferece uma hierarquia de recursos de estrutura e controles mais precisos sobre o caminho da conversa:

• As páginas são nós de gráfico para a conversa. As conversas do Dialogflow CX são semelhantes a máquinas de estado. Em qualquer momento da conversa, uma página fica ativa. Com base na entrada ou nos eventos do usuário final, a conversa pode passar para outra página. É comum que uma página permaneça ativa por várias rodadas de conversa.
• Fluxos são grupos de páginas relacionadas. Cada fluxo precisa lidar com um tópico de conversa de alto nível.
• Os manipuladores de estado são usados para controlar transições e respostas. Há três tipos de manipuladores de estado:
  • Rota de intent: contém uma intent que precisa ser correspondida, respostas opcionais e transição de página opcional.
  • Rota de condição: contém uma condição que precisa ser atendida, respostas opcionais e transição de página opcional.
  • Manipulador de eventos: contém um nome de evento que precisa ser invocado, respostas opcionais e transição de página opcional.
• O escopo é usado para controlar se um manipulador de estado pode ser chamado. A maioria dos manipuladores está associada a uma página ou a um fluxo inteiro. Se a página ou o fluxo associado estiver ativo, o manipulador estará no escopo e poderá ser chamado. Uma rota de intent do Dialogflow CX no escopo é semelhante a uma intent do Dialogflow ES com um contexto de entrada ativo.

Ao criar os flows e as páginas do seu agente, entenda as recomendações na seção de flow do guia de design de agentes.

Preenchimento de formulário

O Dialogflow ES usa o preenchimento de slots para coletar os parâmetros necessários do usuário final:

• Esses parâmetros são parâmetros de intenção marcados como obrigatórios.
• A intent continua sendo correspondida até que todos os parâmetros obrigatórios sejam coletados.
• Você pode definir um comando pedindo que o usuário final forneça um valor.

O Dialogflow CX usa o preenchimento de formulário para coletar parâmetros obrigatórios do usuário final:

• Esses parâmetros são associados a uma página e coletados enquanto ela está ativa.
• Você usa rotas de condição para páginas e determina que o preenchimento do formulário está concluído. Essas rotas de condição geralmente fazem a transição para outra página.
• É possível definir um comando e processadores de repetição de comandos para lidar com várias tentativas de coletar um valor.

Transições

O Dialogflow ES faz a transição automática de uma intent para a próxima quando a entrada do usuário final corresponde a uma intent. Essa correspondência só pode ocorrer para intents sem contexto de entrada ou com um contexto de entrada ativo.

O Dialogflow CX faz a transição de uma página para a próxima quando um manipulador de estado no escopo atende aos requisitos e fornece um destino de transição. Com essas transições, é possível orientar os usuários finais de maneira confiável durante as conversas. Há várias maneiras de controlar essas transições:

• A correspondência de intent pode acionar uma rota de intent.
• Satisfazer uma condição pode acionar uma rota de condição.
• A invocação de um evento pode acionar um manipulador de eventos.
• Os gerenciadores de nova solicitação podem causar uma transição quando o usuário final não fornece um valor após várias tentativas.
• É possível usar alvos de transição simbólica para alvos de transição.

Respostas do agente

As respostas do agente do Dialogflow ES são enviadas ao usuário final quando uma intent é correspondida:

• O agente pode selecionar uma mensagem para a resposta em uma lista de respostas possíveis.
• As respostas podem ser específicas da plataforma, usando formatos de resposta avançados.
• As respostas podem ser geradas por webhooks.

As respostas do agente do Dialogflow CX são enviadas ao usuário final quando o fulfillment é chamado. Ao contrário do fulfillment do Dialogflow ES, que sempre envolve um webhook, o fulfillment do Dialogflow CX pode ou não envolver a chamada de um webhook, dependendo se o recurso de fulfillment tem um webhook configurado. As respostas estáticas e dinâmicas com base em respostas de webhook são controladas pelo fulfillment. Há várias maneiras de criar respostas do agente:

• O fulfillment pode ser fornecido a qualquer tipo de gerenciador de estado.
• Várias respostas podem ser concatenadas durante um turno de conversa usando a fila de respostas. Esse recurso pode simplificar o design do seu agente em alguns casos.
• O Dialogflow CX não é compatível com respostas integradas específicas da plataforma. No entanto, ele oferece vários tipos de resposta, incluindo um payload personalizado que pode ser usado para respostas específicas da plataforma.

Parâmetros

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

• Definido apenas em intents.
• Definido por entradas, eventos, webhooks e chamadas de API do usuário final.
• Referenciados em respostas, solicitações de parâmetros, código de webhook e valores de parâmetros:
  • O formato básico de referência é $parameter-name.
  • As referências são compatíveis com a sintaxe de sufixo .original, .partial e .recent.
  • As referências podem especificar o contexto ativo: #context-name.parameter-name.
  • As referências podem especificar parâmetros de evento: #event-name.parameter-name.

Os parâmetros do Dialogflow CX têm as seguintes características:

• Definido em intents e formulários de página.
• Os parâmetros de intent e formulário são propagados para parâmetros de sessão, onde ficam disponíveis para referência durante a sessão.
• Definido pela entrada do usuário final, webhooks, predefinição de parâmetro de fulfillment e chamadas de API.
• Referenciado em respostas, solicitações de parâmetros, manipuladores de novas solicitações, 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 intent.
  • As referências de parâmetros de intent são compatíveis com a sintaxe de sufixo .original e .resolved. Os parâmetros de sessão não são compatíveis com essa sintaxe.

Entidades do sistema

O Dialogflow ES é compatível com muitas entidades do sistema.

O Dialogflow CX é compatível com muitas das mesmas entidades de sistema, mas há algumas diferenças. Ao migrar, verifique se as entidades do sistema que você está usando no Dialogflow ES também são compatíveis com o Dialogflow CX no mesmo idioma. Caso contrário, crie entidades personalizadas para elas.

Eventos

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

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

Os eventos do Dialogflow CX têm as seguintes características:

• Pode ser invocado de chamadas de API ou webhooks para chamar um manipulador de eventos.
• Não é possível definir parâmetros.
• Muitos eventos integrados podem ser usados para lidar com falta de entrada do usuário final, entrada não reconhecida, parâmetros invalidados por um webhook e erros de webhook.
• As invocações podem ser controladas pelas mesmas regras de escopo que outros manipuladores de estado.

Intents incorporadas

O Dialogflow ES é compatível com as seguintes intents integradas:

• Intenção de boas-vindas
• Intents substitutas
• Intents de acompanhamento pré-definidos

A seguir, descrevemos o suporte do Dialogflow CX para intents integradas:

• Intents de boas-vindas são compatíveis.
• As intents substitutas não são fornecidas. Em vez disso, use os eventos no-match nos manipuladores de eventos.
• Para exemplos negativos, use o intent negativo padrão.
• Intents de acompanhamento pré-definidos não foram fornecidos. Crie essas intents conforme necessário para seu agente. Por exemplo, provavelmente será necessário criar uma intent para lidar com respostas negativas a uma pergunta do agente ("não", "não, obrigado", "não, não quero" etc.). Os intents do Dialogflow CX podem ser reutilizados em todo o agente, então você só precisa definir esses intents uma vez. Usar rotas de intents diferentes para esses intents comuns, em escopos diferentes, oferece um controle muito melhor sobre a conversa.

Webhooks

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

• É possível configurar um serviço de webhook para o agente.
• Cada intenção pode ser marcada como usando o webhook.
• Não há suporte integrado para lidar com erros de webhook.
• As ações ou os nomes de intents são usados por webhooks para determinar de onde no agente eles foram chamados.
• O console fornece o editor in-line.

Os webhooks do Dialogflow CX têm as seguintes características:

• É possível configurar vários serviços de webhook para o agente.
• Cada fulfillment pode especificar opcionalmente uma chamada de webhook.
• Há suporte integrado para tratamento de erros de webhook.
• Um webhook de fulfillment do Dialogflow CX contém uma tag. Essa tag é semelhante a uma ação do Dialogflow ES, mas só é usada ao chamar webhooks. O serviço de webhook pode usar essas tags para determinar de onde no agente ele foi chamado.
• O console não tem um editor de código de webhook integrado. É comum usar o Cloud Run functions, mas há muitas opções.

Ao migrar para o Dialogflow CX, você precisará mudar o código do webhook, já que as propriedades de solicitação e resposta são diferentes.

Integrações

As integrações do Dialogflow ES e as integrações do Dialogflow CX são compatíveis com plataformas diferentes. Para plataformas compatíveis com os dois tipos de agentes, pode haver diferenças na configuração.

Se a integração do Dialogflow ES que você estava usando não for compatível com o Dialogflow CX, talvez seja necessário mudar de plataforma ou implementar a integração por conta própria.

Mais recursos exclusivos do Dialogflow CX

Há muitos outros recursos fornecidos apenas pelo Dialogflow CX. Considere usar esses recursos durante a migração. Exemplo:

• PLN avançado
• Configurações avançadas de fala (sensibilidade ao fim da fala, sem tempo limite de fala etc.)
• Histórico de alterações
• Lógica condicional
• Entrada de DTMF para integrações de telefonia
• Webhooks específicos do ambiente
• Experimentos
• Grupos de rotas
• Pesquisar dados do agente
• Configurações de segurança (edição e retenção de dados)
• Funções do sistema para respostas e condições avançadas
• Casos de teste
• Validação de dados do agente

Práticas recomendadas

Antes de migrar, conheça as práticas recomendadas de design de agentes do Dialogflow CX. Muitas dessas práticas recomendadas do Dialogflow CX são semelhantes às do Dialogflow ES, mas algumas são exclusivas do Dialogflow CX.

Sobre a ferramenta de migração

A ferramenta de migração copia a maior parte dos dados do Dialogflow ES para o agente do Dialogflow CX e grava em um arquivo TODO com uma lista de itens que precisam ser migrados manualmente. A ferramenta copia apenas tipos de entidades personalizadas e frases de treinamento de intenção. Considere personalizar essa ferramenta para suas necessidades específicas.

Código da ferramenta de migração

Confira o código da ferramenta. Analise o código dessa ferramenta para entender o que ela faz. Talvez você queira mudar esse código para lidar com situações específicas no seu agente. Nas etapas abaixo, você vai executar essa 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 ferramentas de tipos de entidade

Os tipos de entidade do Dialogflow ES e os tipos de entidade do Dialogflow CX são muito semelhantes, então são o tipo de dados mais fácil de migrar. A ferramenta apenas copia os tipos de entidade como estão.

Migração de intents da ferramenta

As intenções do Dialogflow ES e as intenções do Dialogflow CX são muito diferentes.

As intents do Dialogflow ES são usadas como elementos básicos do agente e contêm frases de treinamento, respostas, contexto para controle de conversas, configurações de webhook, eventos, ações e parâmetros de preenchimento de slot.

O Dialogflow CX moveu a maioria desses dados para outros recursos. Os intents do Dialogflow CX têm apenas frases de treinamento e parâmetros, o que os torna reutilizáveis em todo o agente. A ferramenta copia apenas esses dois tipos de dados de intenção para as intenções do Dialogflow CX.

Limitações da ferramenta de migração

A ferramenta de migração não é compatível com o seguinte:

• Mega-agentes: a ferramenta não consegue ler vários subagentes, mas você pode chamá-la várias vezes para cada um deles.
• Agentes multilíngues: modifique a ferramenta para criar frases de treinamento e entradas de entidades multilíngues.
• Verificaçã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 compatíveis com o Dialogflow CX, presumindo que o inglês é o idioma padrão e que ele usa uma região dos EUA. A compatibilidade de entidades do sistema varia de acordo com o idioma e a região. Para outros idiomas e regiões, modifique a ferramenta para realizar essa verificação.

Etapas essenciais da migração

As subseções a seguir descrevem as etapas de migração. Não é necessário seguir essas etapas manuais em ordem, e talvez seja necessário fazer isso simultaneamente ou em uma ordem diferente. Leia as etapas e comece a planejar as mudanças antes de fazê-las.

Depois de executar a ferramenta de migração, recompile o agente do Dialogflow CX. Ainda será necessário fazer um trabalho considerável de migração, mas a maior parte dos dados inseridos manualmente estará presente no agente do Dialogflow CX e no arquivo TODO.

Criar um agente do Dialogflow CX

Se ainda não tiver feito isso, crie seu agente do Dialogflow CX. Use o mesmo idioma padrão do seu agente do Dialogflow ES.

Executar a ferramenta de migração

Siga estas etapas para executar a ferramenta:

1. Se você ainda não fez isso, instale o Go na sua máquina.
2. Crie um diretório para o código da ferramenta chamado migrate.
3. Copie o código da ferramenta acima para um arquivo nesse diretório chamado main.go.
4. Modifique o código se necessário para seu caso.

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

   go mod init migrate
   

6. Instale as bibliotecas de cliente Go do Dialogflow ES V2 e do Dialogflow CX V3:

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

7. Verifique se você configurou a autenticação da biblioteca de cliente.

8. Execute a ferramenta e salve a saída em um arquivo:

   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
   

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

Se você encontrar erros ao executar a ferramenta, verifique o seguinte:

Erro

Resolução

Erro de RPC em que uma parte da frase de treinamento menciona um parâmetro não definido para a intent.

Isso pode acontecer se você usou a API Dialogflow ES para criar parâmetros de intent de uma forma inconsistente com as frases de treinamento. Para corrigir isso, renomeie o parâmetro do Dialogflow ES no console, verifique se as frases de treinamento estão usando o parâmetro corretamente e clique em "Salvar". Isso também pode acontecer se as frases de treinamento fizerem referência a parâmetros inexistentes.

Depois de corrigir os erros, você precisará limpar o agente do Dialogflow CX de intents e entidades antes de executar a ferramenta de migração novamente.

Como mover dados de intent do Dialogflow ES para o Dialogflow CX

A ferramenta migra frases e parâmetros de treinamento de intents para intents do Dialogflow CX, mas há muitos outros campos de intents do Dialogflow ES para migrar manualmente.

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

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

• A página original que contém a rota de intent, que vai fazer a transição para a próxima página: a rota de intent na página original pode ter mensagens de fulfillment do Dialogflow CX semelhantes às respostas de intent do Dialogflow ES. Você pode ter muitas rotas de intent nessa página. Enquanto a página original está ativa, essas rotas de intent podem fazer a transição da conversa para muitos caminhos possíveis. Muitas intents do Dialogflow ES compartilham a mesma página original correspondente do Dialogflow CX.
• A próxima página, que é o destino da transição para a rota de intent na página original: o atendimento de entrada do Dialogflow CX para a próxima página pode ter mensagens de atendimento do Dialogflow CX semelhantes às respostas de intent do Dialogflow ES.

Se uma intent do Dialogflow ES tiver parâmetros obrigatórios, crie uma página correspondente do Dialogflow CX com os mesmos parâmetros em um formulário.

É comum que uma intent e uma página do Dialogflow CX compartilhem a mesma lista de parâmetros, o que significa que uma única intent do Dialogflow ES tem uma página e uma intent correspondentes do Dialogflow CX. Quando uma intent do Dialogflow CX com parâmetros em uma rota de intent é correspondida, a conversa geralmente faz a transição para uma página com os mesmos parâmetros. Os parâmetros extraídos da correspondência de intent 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 da página.

As intents de fallback e de acompanhamento predefinidas não existem no Dialogflow CX. Consulte intents integradas.

A tabela a seguir descreve como mapear dados de intent específicos do Dialogflow ES para recursos do Dialogflow CX:

Dados de intents do Dialogflow ES	Dados correspondentes do Dialogflow CX	Ação necessária
Frases de treinamento	Frases de treinamento de intent	Migrado por ferramenta. A ferramenta verifica o suporte a entidades do sistema e cria itens "A fazer" para entidades não compatíveis.
Respostas do agente	Mensagens de resposta de fulfillment	Consulte respostas do agente.
Contexto para controle de conversas	Nenhum	Consulte Controle da estrutura e do fluxo da conversa.
Configuração de webhook	Configuração do webhook de fulfillment	Consulte webhooks.
Eventos	Manipuladores de eventos no nível do fluxo ou da página	Consulte eventos.
Ações	Tags de webhook de fulfillment	Consulte webhooks.
Parâmetros	Parâmetros de intent e/ou parâmetros de formulário de página	Migrado para parâmetros de intent por ferramenta. Se os parâmetros forem obrigatórios, a ferramenta vai criar itens TODO para migrar possivelmente para uma página. Consulte parâmetros.
Solicitações de parâmetros	Solicitações de parâmetros de formulário da página	Consulte preenchimento de formulários.

Criar fluxos

Crie um fluxo para cada tópico de conversa de alto nível. Os temas em cada fluxo precisam ser distintos para que a conversa não fique pulando entre eles.

Se você estiver usando um mega-agente, cada subagente vai se tornar um ou mais fluxos.

Começar com fluxos de conversa básicos

É melhor testar o agente com o simulador enquanto itera nas mudanças. Portanto, concentre-se nos caminhos básicos de conversa no início da conversa e teste à medida que faz mudanças. Depois que eles estiverem funcionando, passe para caminhos de conversa mais detalhados.

Manipuladores de estado no nível do fluxo e da página

Ao criar manipuladores de estado, considere se eles devem ser aplicados no nível do fluxo ou da página. Um manipulador no nível do fluxo está no escopo sempre que o fluxo (e, portanto, qualquer página dentro dele) está ativo. Um manipulador no nível da página só está no escopo quando a página específica está ativa. Os manipuladores no nível do fluxo são semelhantes aos intents do Dialogflow ES sem contexto de entrada. Os manipuladores no nível da página são semelhantes às intents do Dialogflow ES com contexto de entrada.

Código do webhook

As propriedades de solicitação e resposta do webhook são diferentes no Dialogflow CX. Consulte a seção de webhooks.

Conectores de conhecimento

O Dialogflow CX ainda não é compatível com conectores de conhecimento. Você precisará implementar essas opções como intents normais ou esperar até que o Dialogflow CX ofereça suporte a conectores de conhecimento.

Configurações do agente

Revise as configurações do agente do Dialogflow ES e ajuste as configurações do agente do Dialogflow CX conforme necessário.

Observação: se as configurações do seu agente não tiverem o treinamento automático configurado, será necessário treinar o agente manualmente antes de testar as mudanças.

Usar o arquivo TODO

A ferramenta de migração gera um arquivo CSV. Os itens dessa lista se concentram em partes específicas de dados que podem precisar de atenção. Importe esse arquivo para uma planilha. Resolva cada item na planilha usando uma coluna para marcar a conclusão.

Migração de uso da API

Se o sistema usar a API Dialogflow ES para chamadas de tempo de execução ou de design, será necessário atualizar esse código para usar a API Dialogflow CX. Se você usar apenas as chamadas de detecção de intenção no momento da execução, essa atualização será bem simples.

Integrações

Se o agente usa integrações, consulte a seção de integrações e faça as mudanças necessárias.

Etapas de migração recomendadas

As subseções a seguir descrevem as etapas de migração recomendadas.

Validação

Use a validação do agente para verificar se ele segue as práticas recomendadas.

Teste

Ao realizar as etapas de migração manual acima, teste seu agente com o simulador. Depois que o agente parecer estar funcionando, compare as conversas entre os agentes do Dialogflow ES e do Dialogflow CX e verifique se o comportamento é semelhante ou melhor.

Ao testar essas conversas com o simulador, crie casos de teste para evitar regressões futuras.

Ambientes

Revise seus ambientes do Dialogflow ES e atualize os ambientes do Dialogflow CX conforme necessário.