Interazioni con l'API

Per ogni turno di conversazione, si verifica un'interazione. Durante un'interazione, un utente finale invia input a Dialogflow CX e Dialogflow CX invia una risposta. Quando implementi il sistema per gestire le interazioni, hai due opzioni: utilizzare l'API o un'integrazione.

Quando utilizzi l'API, il sistema deve gestire quanto segue:

• Crea un agente.
• Fornisci un'interfaccia utente per gli utenti finali.
• Chiama l'API Dialogflow per ogni turno di conversazione per inviare input utente finale all'API.
• A meno che le risposte dell'agente non siano puramente statiche (cosa rara), devi ospitare un servizio webhook per gestire il fulfillment abilitato per i webhook.

Quando utilizzi un' integrazione, il sistema deve gestire solo quanto segue:

• Crea un agente.
• (Facoltativo) Implementa un servizio webhook.

Il seguente diagramma mostra i passaggi che si verificano per un turno di conversazione di una sessione.

Nota: le comunicazioni tra i sistemi e le integrazioni e Dialogflow CX sono criptate in transito. Inoltre, le comunicazioni dei componenti interni di Google vengono criptate utilizzando Application Layer Transport Security (ALTS).

1. L'utente finale digita o dice qualcosa, noto come input dell'utente finale.
2. L'interfaccia utente o il sistema di integrazione riceve l'input e lo inoltra all'API Dialogflow in una richiesta di rilevamento dell'intent.
3. L'API Dialogflow riceve la richiesta di rilevamento dell'intent. Abbina l'input a un intent o a un parametro del modulo, imposta i parametri in base alle esigenze e aggiorna lo stato della sessione. Se deve chiamare un fulfillment abilitato per i webhook, invia una richiesta webhook al servizio webhook, altrimenti vai al passaggio 6.
4. Il servizio webhook riceve la richiesta webhook. Il servizio esegue tutte le azioni necessarie, ad esempio chiamare API esterne, eseguire query o aggiornare un database e così via.
5. Il servizio webhook crea una risposta e la invia a Dialogflow CX.
6. Dialogflow CX crea una risposta di rilevamento dell'intent. Se è stato chiamato un webhook, utilizza la risposta fornita nella risposta webhook. Se non è stato chiamato alcun webhook, utilizza la risposta statica definita nell'agente. Dialogflow CX invia una risposta di rilevamento dell'intent all'interfaccia utente o al sistema di integrazione.
7. L'interfaccia utente o il sistema di integrazione riceve la risposta di rilevamento dell'intent e inoltra la risposta di testo o audio all'utente finale.
8. L'utente finale vede o ascolta la risposta.

Finalità

Scopri come chiamare l'API per un turno di conversazione per un agente senza utilizzare un'integrazione. Questa guida non mostra come implementare un'interfaccia utente per l'utente finale.

Prima di iniziare

Prima di leggere questa guida:

• Leggi le nozioni di base sui flussi.
• Esegui i passaggi di configurazione.
• Crea un agente o continua a utilizzare l'agente che hai creato in Creare un agente utilizzando i flussi o Creare un agente utilizzando i playbook.

Raccogli gli ID

I seguenti esempi richiedono diversi ID come input. Trova l'ID progetto, l'ID regione e l'ID agente utilizzando uno di questi metodi:

Console di Dialogflow CX

1. Apri la console di Dialogflow CX.
2. Seleziona il progetto.
3. Fai clic sul menu opzioni per un agente nell'elenco.
4. Fai clic sul pulsante copia nome .
5. Viene copiato il nome identificativo completo dell'agente, che include l'ID progetto, l'ID regione e l'ID agente nel formato:
   projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID

Generative AI App Builder

1. Vai a Generative AI App Builder:

   Generative AI App Builder

2. L'ID progetto è mostrato nella parte superiore della console.

3. La colonna Località mostra gli ID regione.

4. Seleziona un'app.

5. Il segmento del percorso dell'URL del browser dopo agents/ contiene l'ID dell'app agente.

Ti serve anche un ID sessione. Una sessione rappresenta una conversazione tra un agente Dialogflow CX e un utente finale. Crea un ID sessione univoco all'inizio di una conversazione e utilizzalo per ogni turno della conversazione. Per testare l'API, puoi utilizzare qualsiasi ID stringa di massimo 36 byte, ad esempio test-session-123.

Chiama detectIntent

I seguenti esempi chiamano il metodo Sessions.detectIntent. Vai al riferimento dell'API Session

Seleziona un protocollo e una versione per il riferimento della sessione:

Protocollo	V3	V3beta1
REST	Risorsa sessione	Risorsa sessione
RPC	Interfaccia sessione	Interfaccia sessione
C++	SessionsClient	Non disponibile
C#	SessionsClient	Non disponibile
Vai	SessionsClient	Non disponibile
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Non disponibile	Non disponibile
Python	SessionsClient	SessionsClient
Ruby	Non disponibile	Non disponibile

Close

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: l'ID del tuo progetto Google Cloud
• AGENT_ID: l'ID agente
• REGION_ID: il tuo ID regione
• SESSION_ID: il tuo ID sessione
• END_USER_INPUT: l'input utente finale

Metodo HTTP e URL:

POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent

Corpo JSON della richiesta:

{
  "queryInput": {
    "text": {
      "text": "END_USER_INPUT"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "responseId": "38e8f23d-eed2-445e-a3e7-149b242dd669",
  "queryResult": {
    "text": "I want to buy a shirt",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Ok, let's start a new order."
          ]
        }
      },
      {
        "text": {
          "text": [
            "I'd like to collect a bit more information from you."
          ]
        }
      },
      {
        "text": {
          "text": [
            "What color would you like?"
          ]
        }
      },
      {}
    ],
    "currentPage": {
      "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/flows/00000000-0000-0000-0000-000000000000/pages/ce0b88c4-9292-455c-9c59-ec153dad94cc",
      "displayName": "New Order"
    },
    "intent": {
      "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
      "displayName": "order.new"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": { ... },
    "match": {
      "intent": {
        "name": "projects/PROJECT_ID/locations/us-central1/agents/133b0350-f2d2-4928-b0b3-5b332259d0f7/intents/0adebb70-a727-4687-b8bc-fbbc2ac0b665",
        "displayName": "order.new"
      },
      "resolvedInput": "I want to buy a shirt",
      "matchType": "INTENT",
      "confidence": 1
    }
  }
}

Java

Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.cx.v3beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.cx.v3beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.cx.v3beta1.QueryInput;
import com.google.cloud.dialogflow.cx.v3beta1.QueryResult;
import com.google.cloud.dialogflow.cx.v3beta1.SessionName;
import com.google.cloud.dialogflow.cx.v3beta1.SessionsClient;
import com.google.cloud.dialogflow.cx.v3beta1.SessionsSettings;
import com.google.cloud.dialogflow.cx.v3beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntent {

  // DialogFlow API Detect Intent sample with text inputs.
  public static Map<String, QueryResult> detectIntent(
      String projectId,
      String locationId,
      String agentId,
      String sessionId,
      List<String> texts,
      String languageCode)
      throws IOException, ApiException {
    SessionsSettings.Builder sessionsSettingsBuilder = SessionsSettings.newBuilder();
    if (locationId.equals("global")) {
      sessionsSettingsBuilder.setEndpoint("dialogflow.googleapis.com:443");
    } else {
      sessionsSettingsBuilder.setEndpoint(locationId + "-dialogflow.googleapis.com:443");
    }
    SessionsSettings sessionsSettings = sessionsSettingsBuilder.build();

    Map<String, QueryResult> queryResults = Maps.newHashMap();
    // Instantiates a client.

    // Note: close() needs to be called on the SessionsClient object to clean up resources
    // such as threads. In the example below, try-with-resources is used,
    // which automatically calls close().
    try (SessionsClient sessionsClient = SessionsClient.create(sessionsSettings)) {
      // Set the session name using the projectID (my-project-id), locationID (global), agentID
      // (UUID), and sessionId (UUID).
      SessionName session =
          SessionName.ofProjectLocationAgentSessionName(projectId, locationId, agentId, sessionId);

      // TODO : Uncomment if you want to print session path
      // System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input.
      for (String text : texts) {
        // Set the text (hello) for the query.
        TextInput.Builder textInput = TextInput.newBuilder().setText(text);

        // Build the query with the TextInput and language code (en-US).
        QueryInput queryInput =
            QueryInput.newBuilder().setText(textInput).setLanguageCode(languageCode).build();

        // Build the DetectIntentRequest with the SessionName and QueryInput.
        DetectIntentRequest request =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .build();

        // Performs the detect intent request.
        DetectIntentResponse response = sessionsClient.detectIntent(request);

        // Display the query result.
        QueryResult queryResult = response.getQueryResult();

        // TODO : Uncomment if you want to print queryResult
        // System.out.println("====================");
        // System.out.format("Query Text: '%s'\n", queryResult.getText());
        // System.out.format(
        //     "Detected Intent: %s (confidence: %f)\n",
        //     queryResult.getIntent().getDisplayName(),
        //         queryResult.getIntentDetectionConfidence());

        queryResults.put(text, queryResult);
      }
    }
    return queryResults;
  }
}

Node.js

Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = 'my-project';
// const location = 'global';
// const agentId = 'my-agent';
// const query = 'Hello';
// const languageCode = 'en'

// Imports the Google Cloud Some API library
const {SessionsClient} = require('@google-cloud/dialogflow-cx');
/**
 * Example for regional endpoint:
 *   const location = 'us-central1'
 *   const client = new SessionsClient({apiEndpoint: 'us-central1-dialogflow.googleapis.com'})
 */
const client = new SessionsClient();

async function detectIntentText() {
  const sessionId = Math.random().toString(36).substring(7);
  const sessionPath = client.projectLocationAgentSessionPath(
    projectId,
    location,
    agentId,
    sessionId
  );
  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
      },
      languageCode,
    },
  };
  const [response] = await client.detectIntent(request);
  for (const message of response.queryResult.responseMessages) {
    if (message.text) {
      console.log(`Agent Response: ${message.text.text}`);
    }
  }
  if (response.queryResult.match.intent) {
    console.log(
      `Matched Intent: ${response.queryResult.match.intent.displayName}`
    );
  }
  console.log(
    `Current Page: ${response.queryResult.currentPage.displayName}`
  );
}

detectIntentText();

Python

Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

def run_sample():
    # TODO(developer): Replace these values when running the function
    project_id = "YOUR-PROJECT-ID"
    # For more information about regionalization see https://cloud.google.com/dialogflow/cx/docs/how/region
    location_id = "YOUR-LOCATION-ID"
    # For more info on agents see https://cloud.google.com/dialogflow/cx/docs/concept/agent
    agent_id = "YOUR-AGENT-ID"
    agent = f"projects/{project_id}/locations/{location_id}/agents/{agent_id}"
    # For more information on sessions see https://cloud.google.com/dialogflow/cx/docs/concept/session
    session_id = uuid.uuid4()
    texts = ["Hello"]
    # For more supported languages see https://cloud.google.com/dialogflow/es/docs/reference/language
    language_code = "en-us"

    detect_intent_texts(agent, session_id, texts, language_code)


def detect_intent_texts(agent, session_id, texts, language_code):
    """Returns the result of detect intent with texts as inputs.

    Using the same `session_id` between requests allows continuation
    of the conversation."""
    session_path = f"{agent}/sessions/{session_id}"
    print(f"Session path: {session_path}\n")
    client_options = None
    agent_components = AgentsClient.parse_agent_path(agent)
    location_id = agent_components["location"]
    if location_id != "global":
        api_endpoint = f"{location_id}-dialogflow.googleapis.com:443"
        print(f"API Endpoint: {api_endpoint}\n")
        client_options = {"api_endpoint": api_endpoint}
    session_client = SessionsClient(client_options=client_options)

    for text in texts:
        text_input = session.TextInput(text=text)
        query_input = session.QueryInput(text=text_input, language_code=language_code)
        request = session.DetectIntentRequest(
            session=session_path, query_input=query_input
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print(f"Query text: {response.query_result.text}")
        response_messages = [
            " ".join(msg.text.text) for msg in response.query_result.response_messages
        ]
        print(f"Response text: {' '.join(response_messages)}\n")

Produzione

Prima di eseguire l'agente in produzione, segui le best practice di produzione.