Migrazione da Dialogflow ES a Dialogflow CX

Gli agenti Dialogflow CX ti offrono controlli e strumenti di conversazione più potenti rispetto agli agenti Dialogflow ES. Se il tuo agente Dialogflow ES gestisce conversazioni complesse, ti consigliamo di eseguire la migrazione a Dialogflow CX.

Questa guida descrive come eseguire la migrazione di un agente da Dialogflow ES a Dialogflow CX. Questi due tipi di agenti presentano molte differenze fondamentali, quindi non esiste un modo semplice per eseguire questa migrazione.

Se utilizzi questa guida per una migrazione, fornisci un feedback positivo o negativo facendo clic sul pulsante Invia feedback qui sopra. Utilizzeremo questo feedback per migliorare questa guida nel tempo.

A livello generale, il processo consigliato è un processo ibrido automatizzato/manuale. Utilizzerai uno strumento che legge alcuni dati dell'agente Dialogflow ES, li scrive nell'agente Dialogflow CX e acquisisce un elenco di cose da fare. Quindi, ricrea l'agente Dialogflow CX completo utilizzando le best practice, la lista di cose da fare e i dati migrati dallo strumento.

Informazioni su Dialogflow CX

Prima di tentare questa migrazione, devi avere una solida comprensione di come funzionano i flussi di Dialogflow CX. Puoi iniziare da qui:

• Nozioni di base sul flusso

Ti consigliamo inoltre di leggere altri documenti sui concetti che includono funzionalità che probabilmente ti serviranno nel nuovo agente. Concentrati su quanto segue:

• Panoramica della console
• Agenti
• Flussi
• Pagine
• Gestori di stato
• Intenti
• Parametri
• Evasioni
• Webhook

Comprendere le differenze tra Dialogflow ES e Dialogflow CX

Questa sezione elenca le differenze più importanti tra Dialogflow ES e Dialogflow CX. Quando esegui i passaggi di migrazione manuale in un secondo momento, fai riferimento a questa sezione per indicazioni.

Controllo della struttura e del percorso della conversazione

Dialogflow ES fornisce quanto segue per il controllo della struttura e del percorso della conversazione:

• Gli intent vengono utilizzati come elementi di base dell'agente. In qualsiasi momento della conversazione, viene abbinata un'intent e, in un certo senso, ogni intent è un nodo della conversazione.
• Contesto viene utilizzato per controllare la conversazione. Il contesto viene utilizzato per controllare quali intent possono essere abbinati in un dato momento. Il contesto scade dopo un determinato numero di turni di conversazione, quindi questo tipo di controllo può essere impreciso per le conversazioni lunghe.

Dialogflow CX fornisce una gerarchia di risorse strutturali e controlli più precisi sul percorso della conversazione:

• Pagine sono i nodi del grafico per la conversazione. Le conversazioni di Dialogflow CX sono simili alle macchine a stati. In qualsiasi momento della conversazione, una pagina è attiva. In base all'input o agli eventi dell'utente finale, la conversazione potrebbe passare a un'altra pagina. È comune che una pagina rimanga attiva per più turni di conversazione.
• I flussi sono gruppi di pagine correlate. Ogni flusso deve gestire un argomento di conversazione di alto livello.
• I gestori di stato vengono utilizzati per controllare le transizioni e le risposte. Esistono tre tipi di gestori di stato:
  • Percorso di intent: contiene un intent che deve essere abbinato, risposte facoltative e transizione di pagina facoltativa.
  • Percorso con condizione: contiene una condizione che deve essere soddisfatta, risposte facoltative e transizione di pagina facoltativa.
  • Gestore eventi: contiene un nome evento da richiamare, risposte facoltative e transizione di pagina facoltativa.
• Scope viene utilizzato per controllare se è possibile chiamare un gestore di stato. La maggior parte dei gestori sono associati a una pagina o a un intero flusso. Se la pagina o il flusso associato è attivo, l'handler è incluso nell'ambito e può essere chiamato. Una route di intent Dialogflow CX nell'ambito è simile a un intent Dialogflow ES con un contesto di input attivo.

Quando progetti i flussi e le pagine del tuo agente, assicurati di comprendere i consigli nella sezione relativa al flusso della guida alla progettazione dell'agente.

Compilazione dei moduli

Dialogflow ES utilizza la compilazione degli slot per raccogliere i parametri richiesti dall'utente finale:

• Questi parametri sono parametri di intent contrassegnati come obbligatori.
• L'intent continua a essere abbinato finché non vengono raccolti tutti i parametri obbligatori.
• Puoi definire una richiesta che chiede all'utente finale di fornire un valore.

Dialogflow CX utilizza la compilazione del modulo per raccogliere i parametri richiesti dall'utente finale:

• Questi parametri sono associati a una pagina e vengono raccolti mentre la pagina è attiva.
• Utilizzi i percorsi delle condizioni per le pagine per determinare che la compilazione del modulo è completata. Questi percorsi di condizione in genere passano a un'altra pagina.
• Puoi definire un prompt, nonché gestori di riproposta per gestire correttamente più tentativi di raccolta di un valore.

Transizioni

Dialogflow ES esegue automaticamente la transizione da un intent all'altro quando l&#39input utentee finale corrisponde a un intent. Questa corrispondenza può verificarsi solo per gli intent che non hanno un contesto di input o per gli intent che hanno un contesto di input attivo.

Dialogflow CX esegue la transizione da una pagina all'altra quando un gestore di stato nell'ambito soddisfa i suoi requisiti e fornisce una destinazione di transizione. Utilizzando queste transizioni, puoi guidare in modo affidabile gli utenti finali nelle conversazioni. Esistono diversi modi per controllare queste transizioni:

• La corrispondenza degli intent può attivare una route intent.
• Il soddisfacimento di una condizione può attivare un percorso di condizioni.
• L'invocazione di un evento può attivare un gestore di eventi.
• I gestori di richieste ripetute possono causare una transizione quando l'utente finale non riesce a fornire un valore dopo diversi tentativi.
• Puoi utilizzare target di transizione simbolici per i target di transizione.

Risposte dell'agente

Le risposte dell'agente Dialogflow ES vengono inviate all'utente finale quando viene trovato un intent corrispondente:

• L'agente può selezionare un messaggio per la risposta da un elenco di possibili risposte.
• Le risposte possono essere specifiche per la piattaforma, che può utilizzare formati di risposta avanzata.
• Le risposte possono essere generate da webhook.

Le risposte dell'agente Dialogflow CX vengono inviate all'utente finale quando viene chiamato il fulfillment. A differenza del fulfillment di Dialogflow ES, che coinvolge sempre un webhook, il fulfillment di Dialogflow CX può o meno coinvolgere la chiamata di un webhook, a seconda che la risorsa di fulfillment abbia un webhook configurato. Le risposte statiche e dinamiche basate sulle risposte webhook sono controllate dal completamento. Esistono diversi modi per creare risposte dell'agente:

• L'intent può essere fornito a qualsiasi tipo di gestore degli stati.
• È possibile concatenare più risposte durante un turno conversazionale tramite la coda delle risposte. In alcuni casi, questa funzionalità può semplificare la progettazione dell'agente.
• Dialogflow CX non supporta le risposte specifiche per la piattaforma integrate. Tuttavia, fornisce più tipi di risposta, incluso un payload personalizzato che può essere utilizzato per risposte specifiche della piattaforma.

Parametri

I parametri di Dialogflow ES hanno le seguenti caratteristiche:

• Definito solo negli intent.
• Impostato tramite input utente finale, eventi, webhook e chiamate API.
• A cui viene fatto riferimento nelle risposte, nelle richieste dei parametri, nel codice webhook e nei valori dei parametri:
  • Il formato di riferimento di base è $parameter-name.
  • I riferimenti supportano la sintassi dei suffissi .original, .partial e .recent.
  • I riferimenti possono specificare il contesto attivo: #context-name.parameter-name.
  • I riferimenti possono specificare i parametri evento: #event-name.parameter-name.

I parametri di Dialogflow CX hanno le seguenti caratteristiche:

• Definito nei moduli di intent e pagine.
• I parametri di intent e modulo vengono propagati ai parametri di sessione, dove sono disponibili per il riferimento per la durata della sessione.
• Impostato tramite input utente finale, webhook, preimpostazione del parametro di fulfillment e chiamate API.
• A cui si fa riferimento in risposte, prompt dei parametri, gestori di riproposta, preimpostazioni dei parametri e codice webhook:
  • Il formato di riferimento è $session.params.parameter-id per i parametri di sessione e $intent.params.parameter-id per i parametri intent.
  • I riferimenti ai parametri di intent supportano la sintassi dei suffissi .original e .resolved. I parametri di sessione non supportano questa sintassi.

Entità di sistema

Dialogflow ES supporta molte entità di sistema.

Dialogflow CX supporta molte delle stesse entità di sistema, ma ci sono alcune differenze. Durante la migrazione, verifica che le entità di sistema che utilizzi in Dialogflow ES siano supportate anche da Dialogflow CX per la stessa lingua. In caso contrario, devi creare entità personalizzate per questi elementi.

Eventi

Gli eventi Dialogflow ES hanno le seguenti caratteristiche:

• Può essere richiamato da chiamate API o webhook per trovare una corrispondenza con un intent.
• Possono impostare i parametri.
• Un numero ridotto di eventi viene richiamato dalle piattaforme di integrazione.

Gli eventi Dialogflow CX hanno le seguenti caratteristiche:

• Può essere richiamato da chiamate API o webhook per chiamare un gestore di eventi.
• Impossibile impostare i parametri.
• Molti eventi integrati possono essere utilizzati per gestire la mancanza diinput utentet dell'utente finale, l&#39input utentee finale non riconosciuto, i parametri invalidati da un webhook e gli errori del webhook.
• Le invocazioni possono essere controllate dalle stesse regole di ambito degli altri gestori di stato.

Intent integrati

Dialogflow ES supporta i seguenti intent integrati:

• Intent di benvenuto
• Intent di riserva
• Intenti di follow-up predefiniti

Di seguito viene descritto il supporto di Dialogflow CX per gli intent integrati:

• Sono supportati gli intent di benvenuto.
• Gli intent di fallback non vengono forniti. Utilizza gli eventi no-match nei gestori di eventi.
• Per gli esempi negativi, utilizza l'intent negativo predefinito.
• Gli intent di follow-up predefiniti non sono forniti. Devi creare questi intent come richiesto dal tuo agente. Ad esempio, probabilmente dovrai creare un intent per gestire le risposte negative a una domanda dell'agente ("no", "no, grazie", "no, non voglio" e così via). Gli intent di Dialogflow CX sono riutilizzabili nell'agente, quindi devi definirli una sola volta. L'utilizzo di intent diversi per questi intent comuni, in ambiti diversi, ti offre un controllo molto migliore sulla conversazione.

Webhook

I webhook di Dialogflow ES hanno le seguenti caratteristiche:

• Puoi configurare un servizio webhook per l'agente.
• Ogni intent può essere contrassegnato come utilizzo del webhook.
• Non è previsto un supporto integrato per la gestione degli errori dei webhook.
• Le azioni intent o i nomi intent vengono utilizzati dai webhook per determinare da quale punto dell'agente è stato chiamato.
• La console fornisce l'editor in linea.

Gli webhook di Dialogflow CX hanno le seguenti caratteristiche:

• Puoi configurare più servizi webhook per l'agente.
• Ogni evasione può specificare facoltativamente una chiamata webhook.
• Esiste un supporto integrato per la gestione degli errori dei webhook.
• Un webhook di fulfillment di Dialogflow CX contiene un tag. Questo tag è simile a un'azione Dialogflow ES, ma viene utilizzato solo quando vengono chiamati webhook. Il servizio webhook può utilizzare questi tag per determinare da quale punto dell'agente è stato chiamato.
• La console non dispone di un editor di codice webhook integrato. È comune utilizzare Cloud Run Functions, ma esistono molte opzioni.

Quando esegui la migrazione a Dialogflow CX, devi modificare il codice webhook, in quanto le proprietà di richiesta e risposta sono diverse.

Integrazioni

Le integrazioni di Dialogflow ES e le integrazioni di Dialogflow CX supportano piattaforme diverse. Per le piattaforme supportate da entrambi i tipi di agenti, potrebbero esserci differenze nella configurazione.

Se l'integrazione di Dialogflow ES che utilizzavi non è supportata da Dialogflow CX, potresti dover cambiare piattaforma o implementare l'integrazione autonomamente.

Altre funzionalità solo di Dialogflow CX

Esistono molte altre funzionalità fornite solo da Dialogflow CX. Ti consigliamo di utilizzare queste funzionalità durante la migrazione. Ad esempio:

• NLU avanzato
• Impostazioni avanzate per il parlato (fine della sensibilità vocale, timeout di assenza di voce e così via)
• Cronologia delle modifiche
• Logica condizionale
• Input DTMF per le integrazioni di telefonia
• Webhook specifici per l'ambiente
• Esperimenti
• Gruppi di itinerari
• Cercare i dati degli agenti
• Impostazioni di sicurezza (oscuramento e conservazione dei dati)
• Funzioni di sistema per risposte e condizioni avanzate
• Scenari di test
• Convalida dei dati dell'agente

Best practice

Prima della migrazione, acquisisci familiarità con le best practice per la progettazione di agenti Dialogflow CX. Molte di queste best practice di Dialogflow CX sono simili a quelle di Dialogflow ES, ma alcune sono specifiche di Dialogflow CX.

Informazioni sullo strumento di migrazione

Lo strumento di migrazione copia la maggior parte dei dati di Dialogflow ES nell'agente Dialogflow CX e scrive in un file TODO un elenco di elementi che devono essere migrati manualmente. Lo strumento copia solo i tipi di entità personalizzati e le frasi di addestramento dell'intent. Ti consigliamo di personalizzare questo strumento in base alle tue esigenze specifiche.

Codice dello strumento di migrazione

Ecco il codice dello strumento. Ti consigliamo di esaminare il codice di questo strumento, in modo da capire cosa fa. Potresti voler modificare questo codice per gestire situazioni specifiche nel tuo agente. Nei passaggi riportati di seguito, eseguirai questo strumento.

// 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()
}

Migrazione degli strumenti dei tipi di entità

I tipi di entità Dialogflow ES e i tipi di entità Dialogflow CX sono molto simili, quindi sono il tipo di dati più semplice da migrare. Lo strumento copia semplicemente i tipi di entità così come sono.

Migrazione degli intent dello strumento

Le intent di Dialogflow ES e le intent di Dialogflow CX sono molto diverse.

Gli intent Dialogflow ES vengono utilizzati come elementi costitutivi dell'agente e contengono frasi di addestramento, risposte, contesto per il controllo della conversazione, configurazioni webhook, eventi, azioni e parametri di riempimento degli slot.

Dialogflow CX ha spostato la maggior parte di questi dati in altre risorse. Gli intent Dialogflow CX hanno solo frasi di addestramento e parametri, il che li rende riutilizzabili nell'agente. Lo strumento copia solo questi due tipi di dati sugli intent negli intent Dialogflow CX.

Limitazioni dello strumento di migrazione

Lo strumento di migrazione non supporta quanto segue:

• Mega agent: lo strumento non può leggere da più sub-agenti, ma puoi chiamarlo più volte per ogni sub-agente.
• Agenti multilingue: devi modificare lo strumento per creare frasi di addestramento ed entità multilingue.
• Verifica delle entità di sistema per le lingue diverse dall'inglese: Lo strumento crea elementi TODO quando trova entità di sistema non supportate da Dialogflow CX, supponendo che l'inglese sia la lingua predefinita e che utilizzi una regione degli Stati Uniti. Il supporto delle entità di sistema varia in base alla lingua e alla regione. Per altre lingue e regioni, devi modificare lo strumento per eseguire questo controllo.

Passaggi essenziali per la migrazione

Le seguenti sottosezioni descrivono i passaggi di migrazione da eseguire. Non è necessario seguire questi passaggi manuali in ordine e potresti persino doverli eseguire contemporaneamente o in un ordine diverso. Leggi i passaggi e inizia a pianificare le modifiche prima di apportarle effettivamente.

Dopo aver eseguito lo strumento di migrazione, puoi ricompilare l'agente Dialogflow CX. Avrai ancora una discreta quantità di lavoro di migrazione da svolgere, ma la maggior parte dei dati inseriti manualmente sarà presente nell'agente Dialogflow CX e nel file TODO.

Crea l'agente Dialogflow CX

Se non l'hai ancora fatto, crea l'agente Dialogflow CX. Assicurati di utilizzare la stessa lingua predefinita dell'agente Dialogflow ES.

Esegui lo strumento di migrazione

Per eseguire lo strumento, segui questi passaggi:

1. Se non lo hai ancora fatto, installa Go sulla tua macchina.
2. Crea una directory per il codice dello strumento denominata migrate.
3. Copia il codice dello strumento riportato sopra in un file di questa directory chiamato main.go.
4. Modifica il codice, se necessario, per il tuo caso.

5. Crea un modulo Go in questa directory. Ad esempio:

   go mod init migrate
   

6. Installa le librerie client Go di Dialogflow ES V2 e Dialogflow CX V3:

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

7. Assicurati di aver configurato l'autenticazione della libreria client.

8. Esegui lo strumento e salva l'output nel file:

   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
   

Risoluzione dei problemi dello strumento di migrazione

Se si verificano errori durante l'esecuzione dello strumento, controlla quanto segue:

Errore

Risoluzione

Errore RPC che indica che una parte della frase di addestramento menziona un parametro non definito per l'intent.

Ciò può accadere se in precedenza hai utilizzato l'API Dialogflow ES per creare parametri di intent in modo incoerente con le frasi di addestramento. Per risolvere il problema, rinomina il parametro Dialogflow ES dalla console, verifica che le frasi di addestramento utilizzino correttamente il parametro e poi fai clic su Salva. Ciò può verificarsi anche se le frasi di addestramento fanno riferimento a parametri inesistenti.

Dopo aver corretto gli errori, dovrai cancellare intent ed entità dell'agente Dialogflow CX prima di eseguire di nuovo lo strumento di migrazione.

Trasferire i dati degli intent di Dialogflow ES a Dialogflow CX

Lo strumento esegue la migrazione delle frasi di addestramento e dei parametri degli intent agli intent Dialogflow CX, ma ci sono molti altri campi degli intent Dialogflow ES da migrare manualmente.

Un intent Dialogflow ES potrebbe richiedere una pagina Dialogflow CX corrispondente, un intent Dialogflow CX corrispondente o entrambi.

Se una corrispondenza dell'intent Dialogflow ES viene utilizzata per la transizione della conversazione da un nodo di conversazione specifico a un altro, nell'agente devono essere presenti due pagine correlate a questo intent:

• La pagina originale che contiene l'intent route, che passerà alla pagina successiva: L'intent route nella pagina originale potrebbe contenere messaggi di fulfillment di Dialogflow CX simili alle risposte dell'intent di Dialogflow ES. In questa pagina potresti avere molti percorsi di intent. Mentre la pagina originale è attiva, questi percorsi di intent possono far passare la conversazione a molti percorsi possibili. Molti intent di Dialogflow ES condivideranno la stessa pagina originale di Dialogflow CX.
• La pagina successiva, che è la destinazione di transizione per la route di intent nella pagina originale: Il fulfillment di ingresso di Dialogflow CX per la pagina successiva potrebbe contenere messaggi di fulfillment di Dialogflow CX simili alle risposte dell'intent di Dialogflow ES.

Se un intent Dialogflow ES contiene parametri obbligatori, devi creare una pagina Dialogflow CX corrispondente con gli stessi parametri in un modulo.

È comune che un intent Dialogflow CX e una pagina Dialogflow CX condividano lo stesso elenco di parametri, il che significa che un singolo intent Dialogflow ES ha una pagina Dialogflow CX corrispondente e un intent Dialogflow CX corrispondente. Quando viene trovata una corrispondenza con un intent Dialogflow CX con parametri in una route di intent, la conversazione spesso passa a una pagina con gli stessi parametri. I parametri estratti dalla corrispondenza dell'intent vengono propagati ai parametri di sessione, che sono disponibili per compilare parzialmente o completamente i parametri del modulo della pagina.

Gli intent di fallback e gli intent di follow-up predefiniti non esistono in Dialogflow CX. Consulta gli intent integrati.

La tabella seguente descrive come mappare dati di intent specifici dalle risorse Dialogflow ES a Dialogflow CX:

Dati sugli intent di Dialogflow ES	Dati Dialogflow CX corrispondenti	Azione richiesta
Frasi di addestramento	Frasi di addestramento dell'intent	Eseguita la migrazione tramite lo strumento. Lo strumento verifica il supporto delle entità di sistema e crea elementi TODO per le entità di sistema non supportate.
Risposte dell'agente	Messaggi di risposta di evasione	Vedi risposte dell'agente.
Contesto per il controllo della conversazione	Nessuno	Consulta la sezione Controllo della struttura e del percorso della conversazione.
Impostazione webhook	Configurazione del webhook di fulfillment	Consulta webhook.
Eventi	Gestori di eventi a livello di flusso o di pagina	Vedi eventi.
Azioni	Tag webhook di fulfillment	Consulta webhook.
Parametri	Parametri di intent e/o parametri del modulo della pagina	Eseguita la migrazione ai parametri intent per strumento. Se i parametri sono obbligatori, lo strumento crea elementi TODO da migrare eventualmente in una pagina. Vedi parametri.
Prompt dei parametri	Prompt dei parametri del modulo della pagina	Consulta Compilazione dei moduli.

Creare flussi

Crea un flusso per ogni argomento di conversazione di alto livello. Gli argomenti di ogni flusso devono essere distinti, in modo che la conversazione non salti frequentemente da un flusso all'altro.

Se utilizzavi un mega-agente, ogni subagente deve diventare uno o più flussi.

Inizia con i percorsi di conversazione di base

È consigliabile testare l'agente con il simulatore durante l'iterazione delle modifiche. Pertanto, all'inizio della conversazione, devi concentrarti sui percorsi di conversazione di base e testarli man mano che apporti modifiche. Una volta che questi funzionano, passa a percorsi di conversazione più dettagliati.

Gestori di stato a livello di flusso e a livello di pagina

Quando crei i gestori di stato, valuta se devono essere applicati a livello di flusso o di pagina. Un gestore a livello di flusso è nell'ambito ogni volta che il flusso (e quindi qualsiasi pagina all'interno del flusso) è attivo. Un gestore a livello di pagina è incluso nell'ambito solo quando la pagina specifica è attiva. I gestori a livello di flusso sono simili agli intent di Dialogflow ES senza contesto di input. I gestori a livello di pagina sono simili agli intent di Dialogflow ES con contesto di input.

Codice webhook

Le proprietà della richiesta e della risposta webhook sono diverse per Dialogflow CX. Consulta la sezione sui webhook.

Connettori di conoscenza

Dialogflow CX non supporta ancora i connettori di knowledge. Dovrai implementarli come intent normali o attendere che Dialogflow CX supporti i connettori della knowledge base.

Impostazioni dell'agente

Esamina le impostazioni dell'agente Dialogflow ES e modifica le impostazioni dell'agente Dialogflow CX in base alle esigenze.

Nota :se le impostazioni dell'agente non prevedono l'addestramento automatico, dovrai addestrare manualmente l'agente prima di testare le modifiche.

Utilizzare il file TODO

Lo strumento di migrazione genera un file CSV. Gli elementi di questo elenco si concentrano su particolari dati che potrebbero richiedere attenzione. Importa questo file in un foglio di lavoro. Risolvi ogni elemento del foglio di lavoro, utilizzando una colonna per contrassegnare il completamento.

Migrazione dell'utilizzo dell'API

Se il tuo sistema utilizza l'API Dialogflow ES per le chiamate in fase di runtime o di progettazione, dovrai aggiornare questo codice per utilizzare l'API Dialogflow CX. Se utilizzi solo le chiamate di rilevamento dell'intent in fase di runtime, questo aggiornamento dovrebbe essere piuttosto semplice.

Integrazioni

Se l'agente utilizza le integrazioni, consulta la sezione Integrazioni e apporta le modifiche necessarie.

Passaggi di migrazione consigliati

Le seguenti sottosezioni descrivono i passaggi di migrazione consigliati.

Convalida

Utilizza la convalida dell'agente per verificare che l'agente segua le best practice.

Test

Durante l'esecuzione dei passaggi di migrazione manuale indicati sopra, devi testare l'agente con il simulatore. Una volta che l'agente sembra funzionare, confronta le conversazioni tra gli agenti Dialogflow ES e Dialogflow CX e verifica che il comportamento sia simile o migliorato.

Durante il test di queste conversazioni con il simulatore, devi creare scenari di test per evitare regressioni future.

Ambienti

Esamina i tuoi ambienti Dialogflow ES e aggiorna i tuoi ambienti Dialogflow CX in base alle necessità.