Estamos cambiando el nombre de algunos productos y funciones. Las funciones de guía y flujo generativos también se están migrando a una única consola consolidada. Consulta los detalles.

Esta página se ha traducido con Cloud Translation API.

Interacciones con la API

En cada turno de conversación, se produce una interacción. Durante una interacción, un usuario final envía información a Conversational Agents (Dialogflow CX) y Conversational Agents (Dialogflow CX) envía una respuesta. Tiene dos opciones para implementar su sistema de gestión de interacciones: usar la API o usar una integración.

Cuando utilice la API, su sistema debe gestionar lo siguiente:

Crea un agente.
Proporcionar una interfaz de usuario para los usuarios finales.
Llama a la API de Dialogflow en cada turno de conversación para enviar la entrada del usuario final a la API.
A menos que las respuestas de tu agente sean puramente estáticas (lo cual es poco habitual), debes alojar un servicio de webhook para gestionar el cumplimiento habilitado para webhook.

Cuando se usa una integración, el sistema solo tiene que gestionar lo siguiente:

Crea un agente.
Implementa un servicio de webhook (opcional).

En el siguiente diagrama se muestran los pasos que se llevan a cabo en un turno de conversación de una sesión.

Diagrama de flujo de la API.

El usuario final escribe o dice algo, lo que se conoce como entrada del usuario final.
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 intención.
La API de Dialogflow recibe la solicitud de detección de intent. Coincide con la entrada de un intent o un parámetro de formulario, define los parámetros según sea necesario y actualiza el estado de la sesión. Si necesita llamar a un webhook de respuesta habilitado, envía una solicitud de webhook a tu servicio de webhook. De lo contrario, ve al paso 6.
Tu servicio de webhook recibe la solicitud de webhook. Tu servicio realiza las acciones necesarias, como llamar a APIs externas, consultar o actualizar una base de datos, etc.
Tu servicio de webhook crea una respuesta y envía una respuesta de webhook a Conversational Agents (Dialogflow CX).
Conversational Agents (Dialogflow CX) crea una respuesta de detección de intención. Si se ha llamado a un webhook, se usa la respuesta proporcionada en la respuesta del webhook. Si no se ha llamado a ningún webhook, se usa la respuesta estática definida en el agente. Los agentes conversacionales (Dialogflow CX) envían una respuesta de detección de intención a tu interfaz de usuario o sistema de integración.
Tu interfaz de usuario o sistema de integración recibe la respuesta de detección de intención y reenvía la respuesta de texto o audio al usuario final.
El usuario final ve o escucha la respuesta.

Objetivo de la guía

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

Antes de empezar

Antes de leer esta guía, debes hacer lo siguiente:

Consulta los conceptos básicos de los flujos.
Sigue los pasos de configuración.
Crea un agente o sigue usando el que creaste en Crear un agente con flujos o Crear un agente con guiones.

Recoger IDs

Las muestras que se muestran a continuación requieren varios IDs como entrada. Para encontrar el ID de tu proyecto, el ID de la región y el ID del agente, sigue estos pasos:

Consola de Dialogflow CX

Abre la consola de Dialogflow CX.
Selecciona tu Google Cloud proyecto para abrir el selector de agentes.
Haz clic en la opción menú de un agente de la lista.
Haga clic en el nombre de la copia botón.
De esta forma, se copia el nombre identificativo completo de tu agente, que incluye el ID de tu 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

Consola Aplicaciones de IA

Ve a la consola de aplicaciones de IA:

Consola Aplicaciones de IA
El ID de tu proyecto se muestra en la parte superior de la consola.
En la columna Ubicación se muestran los IDs de región.
Selecciona una aplicación.
El segmento de la ruta de la URL del navegador después de agents/ contiene el ID de la aplicación del agente.

También necesitas un ID de sesión. Una sesión representa una conversación entre un agente de Conversational Agents (Dialogflow CX) y un usuario final. Crea un ID de sesión único al principio de una conversación y lo usas en cada turno de la conversación. Para probar la API, puedes usar cualquier ID de cadena que tenga como máximo 36 bytes, como test-session-123.

Llamar a la detección de intents

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

Seleccione 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++	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
Ruby	No disponible	No disponible

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

PROJECT_ID: tu ID de proyecto de Google Cloud
AGENT_ID: tu ID de agente
REGION_ID: tu ID de región
SESSION_ID: tu ID de 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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 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: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

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

$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

Deberías recibir una respuesta JSON similar a la siguiente:

{
  "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. Para obtener más información, consulta el artículo Configurar la autenticación en 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

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

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

Puesta en producción

Antes de ejecutar tu agente en producción, asegúrate de implementar las prácticas recomendadas para la puesta en producción.

Interacciones con una integración

Términos importantes

Interacciones con la API Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Objetivo de la guía

Antes de empezar

Recoger IDs

Consola de Dialogflow CX

Consola Aplicaciones de IA

Llamar a la detección de intents

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Java

Node.js

Python

Puesta en producción

Interacciones con la API