Interacciones con la API

Para cada turno de la conversación, se produce una interacción. Durante una interacción, un usuario final envía una entrada a Dialogflow, y Dialogflow envía una respuesta. Cuando implementas tu sistema, tienes dos opciones para controlar las interacciones: mediante la API o una integración.

Cuando usas la API, tu sistema debe controlar lo siguiente:

• Compila un agente.
• Proporciona una interfaz de usuario para los usuarios finales.
• Llama a la API de Dialogflow para cada turno de la conversación a fin de enviar entradas del usuario final a la API.
• A menos que las respuestas de tu agente sean puramente estáticas (poco común), necesitas alojar un servicio de webhook para controlar la entrega habilitada para webhook.

Cuando uses una integración, tu sistema solo deberá procesar los siguientes elementos:

• Compila un agente.
• De manera opcional, implementa un servicio de webhook.

En el siguiente diagrama, se muestran los pasos que se aplican para un turno de conversación de una sesión.

1. El usuario final escribe o dice algo, conocido como entrada del usuario final.
2. Tu interfaz de usuario o sistema de integración recibe la entrada y la reenvía a la API de Dialogflow en una solicitud de detección de intent.
3. La API de Dialogflow recibe la solicitud de intent de detección. Hace coincidir la entrada con un parámetro de intent o de formulario, establece los parámetros según sea necesario y actualiza el estado de la sesión. Si necesita llamar a una entrega habilitada para webhook, envía una solicitud de webhook al servicio de webhook. De lo contrario, avanza al paso 6.
4. El servicio de webhook recibe la solicitud del webhook. El servicio realiza cualquier acción necesaria, como llamar a API externas, consultar o actualizar una base de datos, etcétera.
5. El servicio de webhook compila una respuesta y envía una respuesta de webhook a Dialogflow.
6. Dialogflow crea una respuesta de intent de detección. Si se llamó a un webhook, este usará la respuesta proporcionada en la respuesta del webhook. Si no se llamó a ningún webhook, este usa la respuesta estática definida en el agente. Dialogflow envía una respuesta de intent de detección a tu interfaz de usuario o sistema de integración.
7. La interfaz de usuario o el sistema de integración reciben la respuesta de intent de detección y reenvía la respuesta de texto o audio al usuario final.
8. El usuario final ve o escucha la respuesta.

Objetivo de la guía

En esta guía, se muestra cómo llamar a la API para un turno de conversación en un agente que no usa una integración (paso 2 del diagrama anterior). En esta guía, no se muestra cómo implementar una interfaz de usuario para el usuario final.

Antes de comenzar

Debes hacer lo siguiente antes de leer esta guía:

1. Lee los conceptos básicos de Dialogflow CX.
2. Realiza los pasos de configuración.
3. Crea un agente nuevo o continúa usando el agente que creaste en Compilar un agente.

ID de recopilación

Los siguientes ejemplos requieren varios ID como entrada. Para encontrar el ID del proyecto, el ID de la región y el ID del agente, haz lo siguiente:

1. Abre la consola de Dialogflow CX.
2. Selecciona tu proyecto de GCP para abrir el selector de agentes.
3. Haz clic en el menú de opción de un agente de la lista.
4. Haz clic en el botón del nombre de la copia.
5. Esto copia el nombre completo de identificación de tu agente, que incluye el ID del proyecto, el ID de la región y el ID del agente con el siguiente formato:
   projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID

También necesitas un ID de sesión. Una sesión representa una conversación entre un agente de Dialogflow y un usuario final. Creas un ID de sesión único al comienzo de una conversación y lo usas para cada turno de la conversación. Para probar la API, puedes usar cualquier ID de string de 36 bytes como máximo, como test-session-123.

Intento de detección de llamadas

En los siguientes ejemplos, se llama al método detectIntent del tipo Sessions. Ir a la referencia de la API de sesión

Selecciona un protocolo y una versión para la referencia de la sesión:

Protocolo	V3	V3beta1
REST	Recurso de sesión	Recurso de sesión
RPC	Interfaz de sesión	Interfaz de sesión
C#	No disponible	No disponible
Go	No disponible	No disponible
Java	SessionsClient,	SessionsClient,
Node.js	SessionsClient,	SessionsClient,
PHP	No disponible	No disponible
Python	SessionsClient,	SessionsClient,
Ruby	No disponible	No disponible

Cerrar

REST &LINE; CMD LINE

Antes de usar cualquiera de los datos de la solicitud, reemplaza lo siguiente:

• PROJECT_ID: El ID de tu proyecto de GCP.
• AGENT_ID: Es el ID del agente.
• REGION_ID: Es el ID de tu región.
• SESSION_ID: Es el ID de tu sesión.
• END_USER_INPUT: la entrada del usuario final

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Asegúrate de haber establecido la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo de claves privadas de tu cuenta de servicio.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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)

Nota: Asegúrate de haber establecido la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo de claves privadas de tu cuenta de servicio.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Ver en GitHubComentarios

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

Ver en GitHubComentarios

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

Ver en GitHubComentarios

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

Producción

Antes de ejecutar el agente en producción, asegúrate de implementar las prácticas recomendadas de producción.