Guía de inicio rápido: 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 este envía una respuesta. Cuando implementas tu sistema para controlar las interacciones, tienes dos opciones: usar 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 conversación a fin de enviar la entrada del usuario final a la API.
  • A menos que tus respuestas de agente sean estáticas (poco comunes), debes alojar un servicio de webhook para manejar la entrega habilitada para webhook.

Cuando usas una integración, tu sistema solo necesita controlar lo siguiente:

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

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

Diagrama de flujo de la API.

  1. El usuario final escribe o dice algo, conocido como entrada de 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 intent de detección.
  3. La API de Dialogflow recibe la solicitud de intent de detección. Coincide con la entrada a un intent o parámetro 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 a tu servicio de webhook, de lo contrario, va al paso 6.
  4. Tu servicio de webhook recibe la solicitud de webhook. Tu servicio realiza las acciones necesarias, como llamar a API externas, consultar o actualizar una base de datos, etcétera.
  5. Tu 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, usa la respuesta proporcionada en la respuesta de webhook. Si no se llamó a ningún webhook, usa la respuesta estática que se define en el agente. Dialogflow envía una respuesta de intent de detección a tu interfaz de usuario o sistema de integración.
  7. Tu interfaz de usuario o sistema de integración recibe 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.

Propósito 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 Compila un agente.

Recopila ID

En los siguientes ejemplos se requieren varios IDs 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 Google Cloud 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 de nombre de la copia .
  5. Esto copia el nombre completo de la 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. Puedes crear un ID de sesión único al comienzo de una conversación y usarlo para cada turno de la conversación. Para probar la API, puedes usar cualquier ID de string que tenga un máximo de 36 bytes, como test-session-123.

Llama al intent de detección

En los siguientes ejemplos, se llama al método Sessions.detectIntent.

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

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

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: El ID del proyecto de Google Cloud.
  • AGENT_ID: Es el ID del agente.
  • REGION_ID: Es el ID de región
  • SESSION_ID: Es el ID de sesión.
  • END_USER_INPUT: La entrada del usuario final

HTTP method and 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:

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

Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 


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

Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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.

Anterior
Interacciones con una integración
Siguiente
Información general sobre las funciones generativas