Interaktionen mit der API

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

Wenn Sie die API verwenden, muss Ihr System Folgendes verarbeiten:

• Agent erstellen
• Benutzeroberfläche für Endnutzer bereitstellen
• Rufen Sie die Dialogflow API für jeden Sprecherwechsel 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 verwenden, muss Ihr System nur Folgendes verarbeiten:

• Agent erstellen
• Implementieren Sie optional einen Webhook-Dienst.

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

Hinweis :Kommunikation zwischen Ihren Systemen und Integrationen sowie Dialogflow sind bei der Übertragung verschlüsselt. Außerdem Die Kommunikation zwischen Google-internen Komponenten ist verschlüsselt mit Application Layer Transport Security (ALTS)

1. Der Endnutzer gibt etwas ein oder sagt etwas. Dies wird als Endnutzereingabe bezeichnet.
2. Ihr Benutzeroberflächen- oder 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 Conversational Agents (Dialogflow CX).
6. Konversations-Agents (Dialogflow CX) erstellen 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. Conversational Agents (Dialogflow CX) senden eine Antwort für die Intent-Erkennung an Ihre Benutzeroberfläche oder Ihr Integrationssystem.
7. Ihr Benutzeroberflächen- oder Integrationssystem empfängt die Antwort für die 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 Konversationsrunde für einen Agent aufrufen, der keine Integration verwendet (Schritt 2 im obigen Diagramm). In diesem Leitfaden erfahren Sie nicht, wie Sie eine Benutzeroberfläche für Ihren Endnutzer implementieren.

Hinweis

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

1. Grundlagen des Ablaufs lesen
2. Einrichtungsschritte ausführen
3. Erstellen Sie einen neuen Agenten oder verwenden Sie den Agenten, den Sie unter Agent mithilfe von Abläufen erstellen erstellt haben.

IDs erfassen

In den folgenden Beispielen sind mehrere IDs als Eingabe erforderlich. So ermitteln Sie die Projekt-ID, Regions-ID und Agent-ID:

1. Öffnen Sie die Dialogflow CX Console.
2. Wählen Sie Ihr Google Cloud-Projekt aus, um die Agent-Auswahl zu öffnen.
3. Klicken Sie in der Liste auf das Dreipunkt-Menü für einen Agent in der Liste.
4. Klicken Sie auf die -Schaltfläche Name kopieren.
5. Dadurch wird der vollständige identifizierende Name des Agents kopiert, der Ihre Projekt-ID, Regions-ID und Agent-ID im folgenden Format enthält:
   projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID

Außerdem benötigen Sie eine Sitzungs-ID. A Sitzung stellt eine Unterhaltung zwischen einem Conversational Agents (Dialogflow CX)-Agent und einem Endnutzer dar. Zu Beginn einer Unterhaltung erstellen Sie eine eindeutige Sitzungs-ID und verwenden sie für jede Unterhaltungsrunde. Zum Testen der API können Sie eine beliebige String-ID verwenden, die höchstens 36 Byte beträgt, z. B. test-session-123.

Intent-Erkennung aufrufen

In den folgenden Beispielen wird die Methode Sessions.detectIntent aufgerufen. Zur API-Referenz für Sitzungen

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++	SessionsClient	Nicht verfügbar
C#	SessionsClient	Nicht verfügbar
Go	SessionsClient	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

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

• PROJECT_ID: Ihre Google Cloud-Projekt-ID
• 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: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu haben Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt, die Sie automatisch bei der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

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

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto bei der gcloud-Befehlszeile angemeldet haben. Dazu führen Sie gcloud init oder gcloud auth login aus. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

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

$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

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

Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Dialogflow zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

/**
 * 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

Richten Sie zur Authentifizierung bei Dialogflow die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.

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, sollten Sie die Best Practices für die Produktion implementieren.