Como migrar do Dialogflow ES para o CX

Os agentes do Dialogflow CX oferecem controles de conversa e ferramentas mais avançados do que os agentes do Dialogflow ES. Se o agente do Dialogflow ES lida com conversas complexas, considere migrar para o Dialogflow CX.

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

Se você usar este guia para uma migração, envie comentários positivos ou negativos clicando no botão Enviar feedback acima. Usaremos esse feedback para melhorar o guia ao longo do tempo.

De modo geral, o recomendado é um processo híbrido automatizado/manual. Você usará uma ferramenta que lê alguns dos dados do agente do Dialogflow ES. grava os dados no agente do Dialogflow CX, e captura uma lista de tarefas. Depois, recrie seu agente CX completo 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, é necessário ter um bom entendimento de como o Dialogflow CX funciona. Você pode começar aqui:

1. Princípios básicos
2. Vídeos de introdução
3. Guias de início rápido

Você também deve ler os documentos conceituais adicionais com os atributos que você provavelmente vai precisar no novo agente. Concentre-se no seguinte:

• Visão geral do Console
• Agentes
• Fluxos
• Páginas
• Gerenciadores de estado
• Intents
• Parâmetros
• Fulfillments
• Webhooks

Entenda as diferenças de ES/CX

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

Controle do caminho da conversa e da estrutura

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

• Intents e como os elementos básicos do agente. A qualquer momento da conversa, uma intent é correspondida, e, de certa forma, cada intent é um nó para a conversa.
• Contexto é usado para controlar a conversa. O contexto é usado para controlar quais intents podem ser correspondidas a qualquer momento. O contexto expira depois de um certo número de rodadas de conversa, portanto, esse tipo de controle pode ser impreciso em conversas longas.

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

• Páginas são nós de gráfico para a conversa. As conversas CX são semelhantes a máquinas de estado. Em qualquer ponto da conversa, uma página está ativa. Com base na entrada ou nos eventos do usuário final, a conversa pode mudar para outra página. É comum que uma página permaneça ativa em vários turnos de conversa.
• Fluxos são grupos de páginas relacionadas. Cada fluxo precisa lidar com um tópico de conversa de alto nível.
• Gerenciadores de estado são usados para controlar transições e respostas. Há três tipos de gerenciadores 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.
• Escopo é usado para controlar se um gerenciador de estado pode ser chamado. A maioria dos gerenciadores é associada a uma página ou a um fluxo inteiro. Se a página ou fluxo associado estiver ativo, o manipulador está no escopo e pode ser chamado. Uma rota de intent CX no escopo é semelhante a uma intent ES com um contexto de entrada ativo.

Ao projetar os fluxos e as páginas do agente, certifique-se de entender os conselhos seção de fluxo do guia de design do agente.

Preenchimento de formulário

Usos da Espanha preenchimento de slot para coletar os parâmetros obrigatórios do usuário final:

• Esses são parâmetros de intent marcados como obrigatórios.
• A correspondência da intent continua até que todos os parâmetros necessários sejam coletados.
• É possível definir um prompt solicitando que o usuário final forneça um valor.

Usos do CX preenchimento de formulário para coletar os parâmetros obrigatórios do usuário final:

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

Transições

O 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 intents com um contexto de entrada ativo.

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

• A correspondência de intent pode acionar uma rota de intent.
• Atender a uma condição pode acionar uma rota de condição.
• A invocação de um evento pode acionar um manipulador de eventos.
• Gerenciadores de novo prompt podem causar uma transição quando o usuário final falha depois de várias tentativas.
• Você pode usar destinos de transição simbólica para metas de transição.

Respostas do agente

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

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

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

• O fulfillment pode ser fornecido para qualquer tipo de gerenciador de estado.
• Várias respostas podem ser concatenadas durante a rodada de uma conversa por meio do fila de resposta. Em alguns casos, esse recurso pode simplificar o design do agente.
• A CX não oferece suporte a respostas integradas específicas da plataforma. No entanto, oferece vários tipos de resposta, incluindo um payload personalizado que pode ser usado para respostas específicas da plataforma.

Parâmetros

Parâmetros de ES têm as seguintes características:

• Definido apenas em intents.
• Definidos pela entrada do usuário final, eventos, webhooks e chamadas de API.
• referenciadas em respostas, prompts de parâmetro, código do webhook; valores de parâmetro:
  • O formato de referência básico é $parameter-name.
  • As referências dão suporte à 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.

Parâmetros de CX têm as seguintes características:

• Definidas em intents e formulários de página.
• Os parâmetros de intent e formulário são propagados para os parâmetros de sessão, quando disponíveis para consulta durante a sessão.
• Definidos pela entrada do usuário final, webhooks predefinição do parâmetro de fulfillment, e chamadas de API.
• Mencionado em respostas, prompts de parâmetro, gerenciadores de nova solicitação, predefinições de parâmetro e código do 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âmetro da intent são compatíveis com a sintaxe de sufixo .original e .resolved. Os parâmetros de sessão não oferecem suporte a esta sintaxe.

Entidades do sistema

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

A CX oferece suporte a vários entidades do sistema, mas tem algumas diferenças. Durante a migração, Verifique se as entidades do sistema que você está usando no ES também são compatíveis com CX para o mesmo idioma. Caso contrário, crie entidades personalizadas para elas.

Eventos

Eventos da Espanha têm as seguintes características:

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

Eventos 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 tratar a falta de entradas do usuário final, a entrada não reconhecida do usuário final, parâmetros invalidados por um webhook e erros de webhook.
• As invocações podem ser controladas pela mesma regras de escopo que outros gerenciadores de estado.

Intents incorporadas

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

• Intent de boas-vindas
• Intents substitutas
• Intents de continuidade predefinidas

Veja a seguir a descrição do suporte de CX para intents integradas:

• Intents de boas-vindas são suportados.
• As intents substitutas não foram fornecidas. Use o sem correspondência em manipuladores de eventos.
• Para exemplos negativos, use o método intent negativa padrão.
• As intents de continuidade predefinidas não foram fornecidas. Crie essas intents conforme exigido pelo agente. Por exemplo: é provável que você precise criar uma intent para lidar com respostas negativas a uma pergunta do agente ("não", "não, obrigado", "não, não" e assim por diante). As intents CX são reutilizáveis em todo o agente, então você só precisa defini-los uma vez. Ao usar rotas de intent diferentes para essas intents comuns, em diferentes escopos, oferece muito mais controle sobre a conversa.

Webhooks

Webhooks de ES têm as seguintes características:

• É possível configurar um serviço de webhook para o agente.
• Cada intent pode ser marcada como usando o webhook.
• Não há suporte integrado para processar erros de webhook.
• Ações ou nomes de intents são usados por webhooks para determinar de onde ela foi chamada no agente.
• O console oferece editor inline.

Webhooks de CX têm as seguintes características:

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

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

Integrações

Integrações com ES e Integrações com CX oferecem suporte a diferentes plataformas. Para plataformas compatíveis com os dois tipos de agente, pode haver diferenças na configuração.

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

Mais recursos exclusivos do CX

Há muitos outros recursos que são oferecidos apenas pelo CX. Considere usar esses recursos ao fazer a migração. Exemplo:

• PLN avançado
• Configurações avançadas de fala (sensibilidade de fim de fala, tempo limite de fala, etc.)
• Histórico de alterações
• Lógica condicional
• Entrada DTMF para integrações de telefonia
• Webhooks específicos do ambiente
• Experimentos
• Grupos de rotas
• Pesquisar dados do agente
• Configurações de segurança (encobrimento 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 da migração, familiarize-se com Práticas recomendadas de design de agentes CX: Muitas dessas práticas recomendadas para CX são parecidas com as de ES, mas alguns são exclusivos da CX.

Sobre a ferramenta de migração

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

Código da ferramenta de migração

Veja o código da ferramenta. Revise o código dessa ferramenta para que você entenda o que ele faz. Altere 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

Tipos de entidade ES e Tipos de entidade CX são muito semelhantes, por isso são o tipo de dados mais fácil de migrar. A ferramenta apenas copia os tipos de entidade no estado em que se encontram.

Migração de intents da ferramenta

Intents de ES e Intents de CX são muito diferentes.

As intents 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. As intents CX só têm frases e parâmetros de treinamento, o que torna as intents reutilizáveis em todo o agente. A ferramenta copia apenas esses dois tipos de dados de intent para as intents de CX.

Limitações da ferramenta de migração

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

• Megaagentes: a ferramenta não pode ler de vários subagentes. mas é possível chamar a ferramenta várias vezes em cada subagente.
• Agentes multilíngues: modifique a ferramenta para criar frases de treinamento multilíngues e entradas de entidades.
• Verificação de entidade do sistema para idiomas diferentes do inglês: A ferramenta cria itens TODO quando encontra entidades do sistema que não estão oferecido pela CX, supondo que o inglês é o idioma padrão, e que usa uma região dos EUA. O suporte à entidade do sistema varia de acordo com o idioma e a região. Para outras linguagens e regiões, modifique a ferramenta para fazer essa verificação.

Etapas essenciais de migração

As subseções abaixo descrevem as etapas de migração a serem seguidas. Você não precisa seguir essas etapas manuais em ordem, e talvez seja necessário realizar essas etapas simultaneamente ou em uma ordem diferente. Leia as etapas e comece a planejar suas mudanças antes de realmente fazer alterações.

Depois de executar a ferramenta de migração, recrie seu agente CX. Você ainda terá uma boa quantidade de trabalho de migração a fazer, mas a maior parte dos dados inseridos manualmente vai estar presente no agente CX e o arquivo TODO.

crie seu agente do Dialogflow CX

Caso ainda não tenha feito isso, Crie seu agente do Dialogflow CX. Use o mesmo idioma padrão do agente ES.

Executar a ferramenta de migração

Siga estas etapas para executar a ferramenta:

1. Caso ainda não tenha feito isso, instale o Go na sua máquina.
2. Crie um diretório chamado migrate para o código da ferramenta.
3. Copie o código da ferramenta acima. para um arquivo neste diretório chamado main.go.
4. Modifique o código, se necessário.

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

   go mod init migrate
   

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

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

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

8. Execute a ferramenta e salve a saída no 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 com a ferramenta de migração

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

Erro	Resolução
Erro de RPC quando uma parte da frase de treinamento menciona um parâmetro não definido para a intent.	Isso pode acontecer se você já usou a API ES para criar parâmetros de intent de uma forma inconsistente com as frases de treinamento. Para corrigir isso, renomeie o parâmetro ES do console, verifique se suas 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, será necessário limpar o agente CX de intents e entidades antes de executar a ferramenta de migração novamente.

Como transferir dados da intent ES para CX

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

Uma intent ES pode precisar de uma página CX correspondente, uma intent de CX correspondente, ou ambos.

Se uma correspondência de intent ES for usada para fazer a transição da conversa de um nó de conversa para outro, Você precisa ter duas páginas no agente relacionadas a esta intent:

• A página original que contém a rota da intent que passará para a próxima página: A rota da intent na página original podem ter mensagens de fulfillment de CX semelhantes às respostas de intent ES. É possível que você tenha muitas rotas de intent nesta página. Enquanto a página original estiver ativa, essas rotas de intent podem fazer a transição da conversa muitos caminhos possíveis. Muitas intents de ES vão compartilhar a mesma página original da CX.
• Na próxima página, que é o destino da transição para a rota da intent na página original: O fulfillment da entrada de CX para a próxima página podem ter mensagens de fulfillment de CX semelhantes às respostas de intent ES.

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

É comum que uma intent e uma página de CX compartilhem a mesma lista de parâmetros, o que significa que uma única intent ES tem uma página CX correspondente e uma intent de CX correspondente. Quando uma intent CX com parâmetros em uma rota de intent é correspondida, a conversa geralmente muda para uma página com os mesmos parâmetros. Os parâmetros extraídos da correspondência de intent são propagados para os parâmetros de sessão, que estão disponíveis para preencher parcial ou totalmente os parâmetros de formulário de página.

As intents substitutas e as intents de continuidade predefinidas não existem no CX. Consulte intents integradas.

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

Dados de intent de ES	Dados do CX correspondentes	Ação necessária
Frases de treinamento	Frases de treinamento de intent	Migrado por ferramenta. A ferramenta verifica o suporte à entidade do sistema e cria itens "TODO" para entidades sem suporte.
Respostas do agente	Mensagens de resposta de fulfillment	Consulte as respostas do agente.
Contexto para controle da conversa	Nenhum	Consulte Controle de caminho da conversa e da estrutura.
Configuração do webhook	Configuração do webhook de fulfillment	Consulte webhooks.
Eventos	Manipuladores de eventos no nível do fluxo ou da página	Veja os eventos.
Ações	Tags do 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 criará itens "TODO" para possivelmente migrar para uma página. Consulte os parâmetros.
Comandos de parâmetros	Prompts de parâmetro de formulário de página	Consulte o preenchimento de formulário.

Criar fluxos

Crie um fluxo para cada tópico de conversa de alto nível. Os tópicos em cada fluxo devem ser distintos, para que a conversa não pule os fluxos com frequência.

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

Comece com caminhos de conversa básicos

É melhor testar seu agente com o simulador enquanto itera as mudanças. Portanto, inicialmente, você deve se concentrar nos caminhos básicos de conversa no início da conversa, e testar à medida que você faz as alterações. Depois de fazer isso, passaremos para caminhos de conversa mais detalhados.

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

Ao criar gerenciadores de estado, considere se elas devem ser aplicadas no nível do fluxo ou da página. Um gerenciador de nível de fluxo está no escopo sempre que o fluxo (e, portanto, qualquer página dentro do fluxo) está ativo. Um gerenciador no nível da página só é incluído no escopo quando uma página específica está ativa. Os gerenciadores de fluxo são semelhantes às intents ES sem contexto de entrada. Os gerenciadores no nível da página são semelhantes às intents ES com contexto de entrada.

Código do webhook

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

Conectores de conhecimento

O CX não oferece suporte conectores de conhecimento ainda. Você precisará implementá-las como intents normais ou aguardar até que o Dialogflow CX dá suporte a conectores de conhecimento.

Configurações do agente

Revise sua Configurações do agente ES, e ajuste suas Configurações do agente CX conforme necessário.

Observação: se as configurações do agente não tiverem o treinamento automático definido, você precisará treinar manualmente o agente antes de testar as alterações.

Use o arquivo TODO

A ferramenta de migração gera um arquivo CSV. Os itens desta lista são focados em dados específicos que podem precisar de atenção. Importe esse arquivo para uma planilha. Resolva cada item da planilha, usando uma coluna para marcar a conclusão.

Migração do uso da API

Se o sistema usa a API ES para chamadas de tempo de execução ou de design, você terá que atualizar esse código para usar API CX. Se você usar apenas as chamadas de intent de detecção no tempo de execução, essa atualização será bastante simples.

Integrações

Caso seu agente use integrações, consulte seção sobre integrações, e faça as alterações necessárias.

Etapas de migração recomendadas

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

Validação

Usar validação de agente para verificar se o agente segue as práticas recomendadas.

Teste

Ao executar as etapas de migração manual acima, teste seu agente com as simulador. Quando o agente estiver funcionando, compare as conversas entre os agentes de ES e CX, e verificar se o comportamento é semelhante ou melhor.

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

Ambientes

Revise sua Ambientes ES e atualize sua Ambientes CX conforme necessário.