Interaktionen mit der API

Für jede Unterhaltungsrunde findet eine Interaktion statt. Während einer Interaktion sendet ein Endnutzer eine Eingabe an Dialogflow und Dialogflow eine Antwort. Sie haben zwei Möglichkeiten, Ihr System für die Verarbeitung von Interaktionen zu implementieren: über die API oder eine Integration.

Bei Verwendung der API muss Ihr System Folgendes verarbeiten:

• Erstellen Sie einen Agent.
• Stellen Sie Endnutzern eine Benutzeroberfläche zur Verfügung.
• Rufen Sie die Dialogflow API für jede Unterhaltungsrunde auf, um Endnutzereingaben an die API zu senden.
• Wenn die Agent-Antworten nicht nur statisch sind (seltener), müssen Sie einen Webhook-Dienst für die Verarbeitung der Webhook-aktivierten Auftragsausführung hosten.

Wenn Sie eine Integration ausführen, muss Ihr System nur Folgendes verarbeiten:

• Erstellen Sie einen Agent.
• Optional einen Webhook-Dienst implementieren

Das folgende Diagramm zeigt die Schritte, die für einen Sprecherwechsel einer Sitzung ausgeführt werden.

1. Der Endnutzer gibt etwas ein oder sagt etwas. Dies wird als Endnutzereingabe bezeichnet.
2. Ihre Benutzeroberfläche oder Ihr Integrationssystem empfängt die Eingabe und leitet sie in einer Anfrage zur Intent-Erkennung an die Dialogflow API weiter.
3. Die Dialogflow API empfängt die Anfrage zur Intent-Erkennung. Sie ordnet die Eingabe einem Intent- oder Formularparameter zu, legt bei Bedarf Parameter fest und aktualisiert den Sitzungsstatus. Falls eine Webhook-fähige Auftragsausführung aufgerufen werden muss, wird eine Webhook-Anfrage an Ihren Webhook-Dienst gesendet. Fahren Sie andernfalls mit Schritt 6 fort.
4. Ihr Webhook-Dienst empfängt die Webhook-Anfrage. Der Dienst führt alle erforderlichen Aktionen aus, z. B. das Aufrufen externer APIs, das Abfragen oder Aktualisieren einer Datenbank usw.
5. Ihr Webhook-Dienst erstellt eine Antwort und sendet eine Webhook-Antwort an Dialogflow.
6. Dialogflow erstellt eine Antwort für die Intent-Erkennung. Wenn ein Webhook aufgerufen wurde, verwendet es die Webhook-Antwort. Wenn kein Webhook aufgerufen wurde, verwendet es die im Agent definierte statische Antwort. Dialogflow sendet eine Antwort auf die Intent-Erkennung an Ihre Benutzeroberfläche oder Ihr Integrationssystem.
7. Ihre Benutzeroberfläche oder Ihr Integrationssystem empfängt die Antwort zur Intent-Erkennung und leitet die Text- oder Audioantwort an den Endnutzer weiter.
8. Der Endnutzer sieht oder hört die Antwort.

Zweck des Leitfadens

In dieser Anleitung erfahren Sie, wie Sie die API für eine Unterhaltungsrunde für einen Agent aufrufen, der keine Integration verwendet (Schritt 2 im obigen Diagramm). In diesem Leitfaden wird nicht beschrieben, wie Sie eine Benutzeroberfläche für Ihren Endnutzer implementieren.

Hinweis

Bevor Sie diese Anleitung lesen, sollten Sie mit Folgendem vertraut sein:

1. Dialogflow CX-Grundlagen
2. Einrichtungsschritte ausführen
3. Erstellen Sie einen neuen Agent oder verwenden Sie den zuvor unter Agent erstellen erstellten Agent weiter.

IDs erfassen

Die folgenden Beispiele erfordern mehrere IDs als Eingabe. So finden Sie Ihre Projekt-ID, Regions-ID und Agent-ID:

1. Öffnen Sie die Dialogflow CX Console.
2. Wählen Sie Ihr GCP-Projekt aus, um die Agent-Auswahl zu öffnen.
3. Klicken Sie auf das Dreipunkt-Menü für einen Agent in der Liste.
4. Klicken Sie auf die Schaltfläche zum Kopieren des Namens .
5. Hiermit wird der vollständige identifizierende Name Ihres Agents kopiert, einschließlich Ihrer Projekt-ID, Regions-ID und Agent-ID im folgenden Format:
   projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID

Außerdem ist eine Sitzungs-ID erforderlich. Eine Sitzung stellt eine Unterhaltung zwischen einem Dialogflow-Agent und einem Endnutzer dar. Sie erstellen eine eindeutige Sitzungs-ID am Anfang einer Unterhaltung und verwenden sie für jede Runde der Unterhaltung. Zum Testen der API können Sie eine beliebige String-ID verwenden, die maximal 36 Byte groß ist, z. B. test-session-123.

Intent-Erkennung des Anrufs

In den folgenden Beispielen wird die Methode detectIntent des Typs Sessions aufgerufen. Zur API-Referenz-Sitzung

Wählen Sie ein Protokoll und eine Version für die Sitzungsreferenz aus:

Protokoll	V3	V3beta1
REST	Sitzungsressource	Sitzungsressource
RPC	Sitzungsoberfläche	Sitzungsoberfläche
C#	Nicht verfügbar	Nicht verfügbar
Go	Nicht verfügbar	Nicht verfügbar
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Nicht verfügbar	Nicht verfügbar
Python	SessionsClient	SessionsClient
Ruby	Nicht verfügbar	Nicht verfügbar

Schließen

REST UND BEFEHLSZEILE

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• PROJECT_ID: ID Ihres GCP-Projekts
• AGENT_ID: Agent-ID
• REGION_ID: Ihre Regions-ID
• SESSION_ID: Ihre Sitzungs-ID
• END_USER_INPUT: Endnutzereingabe

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Hinweis: Legen Sie für die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS den Pfad zur privaten Schlüsseldatei des Dienstkontos fest.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-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)

Hinweis: Legen Sie für die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS den Pfad zur privaten Schlüsseldatei des Dienstkontos fest.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "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

Auf GitHub ansehen Feedback

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
    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.of(projectId, locationId, agentId, sessionId);
      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();

        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

Auf GitHub ansehen Feedback

/**
 * 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
  );
  console.info(sessionPath);

  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
      },
      languageCode,
    },
  };
  const [response] = await client.detectIntent(request);
  console.log(`User Query: ${query}`);
  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

Auf GitHub ansehen Feedback

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")

Produktion

Bevor Sie den Agent in der Produktion ausführen, müssen Sie die Best Practices für die Produktion implementieren.