Guía de inicio rápido: Interacciones con la API

Si no usas una integración, debes escribir código para interactuar con los usuarios finales. Para cada turno de conversación, tu código llama a la API de Dialogflow a fin de consultar al agente. En esta guía, se muestra cómo interactuar con un agente mediante la API de REST en la línea de comandos y las bibliotecas cliente.

Antes de comenzar

Si no planeas usar la API, puedes omitir esta guía de inicio rápido.

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

  1. Aprende los conceptos básicos de Dialogflow.
  2. Realiza los pasos de configuración.
  3. Realiza los pasos de la guía de inicio rápido Compila un agente. En los siguientes pasos, se continúa trabajando en el agente que comenzaste en esa guía. Si ya no tienes ese agente, puedes descargar build-agent-quickstart.zip y, luego, importar el archivo.

Sesiones

Una sesión representa una conversación entre un agente de Dialogflow y un usuario final. La sesión se crea al comienzo de una conversación y se usa para cada turno de la conversación. Una vez terminada la conversación, se deja de usar la sesión.

No se debe usar la misma sesión para conversaciones simultáneas con diferentes usuarios finales. Dialogflow mantiene los contextos activos en ese momento para cada sesión activa. Dialogflow almacena los datos de la sesión durante 20 minutos.

Cada sesión se determina como única por un ID de sesión que generó tu sistema. Para crear una sesión nueva, debes proporcionar un ID de sesión nuevo en una solicitud de detección de intent. Un ID de sesión es una string de 36 bytes de tamaño como máximo. Tu sistema se encarga de generar ID de sesión únicos. Pueden ser números aleatorios, identificadores de usuario final con hash o cualquier otro valor que te resulte conveniente generar.

Detecta intents

Cuando usas la API para interactuar, tu servicio interactúa directamente con el usuario final. Para cada turno de la conversación, el servicio envía expresiones del usuario final a Dialogflow mediante llamadas al método detectIntent o streamingDetectIntent del tipo Sessions. Dialogflow responde con información sobre el intent coincidente, la acción, los parámetros y la respuesta definida para ese intent. Tu servicio realiza acciones según sea necesario (por ejemplo, consultas a la base de datos o llamadas a la API externa) y envía un mensaje al usuario final. Este proceso continúa hasta que la conversación finaliza.

En los ejemplos siguientes, se muestra cómo detectar intents. En cada ejemplo se acepta un subconjunto de las siguientes entradas:

  • ID del proyecto: Usa el ID del proyecto que creaste en los pasos de configuración.
  • ID de sesión: En el contexto de la prueba de un agente, puedes usar lo que quieras. En los ejemplos, se suele usar “123456789”.
  • Texto o textos: Se refiere a la única expresión del usuario final o a la lista de expresiones del usuario final. Si se proporcionan varias expresiones, las llamadas al código de muestra detectan el intent de cada expresión. Intenta usar “I know french” (Sé francés).
  • Código de lenguaje: El código de lenguaje de la expresión del usuario final. Usa “en-US” para este agente de muestra.

REST

Para detectar un intent, llama al método detectIntent en el recurso Sessions.

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.
  • SESSION_ID: Es un ID de sesión.

HTTP method and URL: 

POST https://dialogflow.googleapis.com/v2/projects/PROJECT_ID/agent/sessions/SESSION_ID:detectIntent

Cuerpo JSON de la solicitud: 

{
  "query_input": {
    "text": {
      "text": "I know french",
      "language_code": "en-US"
    }
  }
}

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": "856510ca-f617-4e25-b0bb-a26c0a59e030-19db3199",
  "queryResult": {
    "queryText": "I know french",
    "parameters": {
      "language": "French",
      "language-programming": ""
    },
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Wow! I didn't know you knew French. How long have you known French?",
    "fulfillmentMessages": [
      {
        "text": {
          "text": [
            "Wow! I didn't know you knew French. How long have you known French?"
          ]
        }
      }
    ],
    "outputContexts": [
      {
        "name": "projects/PROJECT_ID/agent/sessions/123456789/contexts/set-language-followup",
        "lifespanCount": 2,
        "parameters": {
          "language": "French",
          "language.original": "french",
          "language-programming": "",
          "language-programming.original": ""
        }
      }
    ],
    "intent": {
      "name": "projects/PROJECT_ID/agent/intents/fe45022f-e58a-484f-96e8-1cbd6628f648",
      "displayName": "set-language"
    },
    "intentDetectionConfidence": 1,
    "languageCode": "en"
  }
}

Ten en cuenta estos aspectos sobre la respuesta:

  • El campo queryResult.intent contiene el intent coincidente.
  • El valor del campo queryResult.fulfillmentMessages contiene la respuesta del intent. Esta es la respuesta que el sistema debe enviarle al usuario final.
  • El valor del campo queryResult.parameters contiene los parámetros extraídos de la expresión del usuario final.
  • El campo queryResult.outputContext contiene el contexto activo.

Go

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. 

func DetectIntentText(projectID, sessionID, text, languageCode string) (string, error) {
	ctx := context.Background()

	sessionClient, err := dialogflow.NewSessionsClient(ctx)
	if err != nil {
		return "", err
	}
	defer sessionClient.Close()

	if projectID == "" || sessionID == "" {
		return "", errors.New(fmt.Sprintf("Received empty project (%s) or session (%s)", projectID, sessionID))
	}

	sessionPath := fmt.Sprintf("projects/%s/agent/sessions/%s", projectID, sessionID)
	textInput := dialogflowpb.TextInput{Text: text, LanguageCode: languageCode}
	queryTextInput := dialogflowpb.QueryInput_Text{Text: &textInput}
	queryInput := dialogflowpb.QueryInput{Input: &queryTextInput}
	request := dialogflowpb.DetectIntentRequest{Session: sessionPath, QueryInput: &queryInput}

	response, err := sessionClient.DetectIntent(ctx, &request)
	if err != nil {
		return "", err
	}

	queryResult := response.GetQueryResult()
	fulfillmentText := queryResult.GetFulfillmentText()
	return fulfillmentText, nil
}

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.v2.DetectIntentResponse;
import com.google.cloud.dialogflow.v2.QueryInput;
import com.google.cloud.dialogflow.v2.QueryResult;
import com.google.cloud.dialogflow.v2.SessionName;
import com.google.cloud.dialogflow.v2.SessionsClient;
import com.google.cloud.dialogflow.v2.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntentTexts {

  // DialogFlow API Detect Intent sample with text inputs.
  public static Map<String, QueryResult> detectIntentTexts(
      String projectId, List<String> texts, String sessionId, String languageCode)
      throws IOException, ApiException {
    Map<String, QueryResult> queryResults = Maps.newHashMap();
    // Instantiates a client
    try (SessionsClient sessionsClient = SessionsClient.create()) {
      // Set the session name using the sessionId (UUID) and projectID (my-project-id)
      SessionName session = SessionName.of(projectId, sessionId);
      System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input
      for (String text : texts) {
        // Set the text (hello) and language code (en-US) for the query
        TextInput.Builder textInput =
            TextInput.newBuilder().setText(text).setLanguageCode(languageCode);

        // Build the query with the TextInput
        QueryInput queryInput = QueryInput.newBuilder().setText(textInput).build();

        // Performs the detect intent request
        DetectIntentResponse response = sessionsClient.detectIntent(session, queryInput);

        // Display the query result
        QueryResult queryResult = response.getQueryResult();

        System.out.println("====================");
        System.out.format("Query Text: '%s'\n", queryResult.getQueryText());
        System.out.format(
            "Detected Intent: %s (confidence: %f)\n",
            queryResult.getIntent().getDisplayName(), queryResult.getIntentDetectionConfidence());
        System.out.format(
            "Fulfillment Text: '%s'\n",
            queryResult.getFulfillmentMessagesCount() > 0
                ? queryResult.getFulfillmentMessages(0).getText()
                : "Triggered Default Fallback Intent");

        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): UPDATE these variables before running the sample.
 */
// projectId: ID of the GCP project where Dialogflow agent is deployed
// const projectId = 'PROJECT_ID';
// sessionId: String representing a random number or hashed user identifier
// const sessionId = '123456';
// queries: A set of sequential queries to be send to Dialogflow agent for Intent Detection
// const queries = [
//   'Reserve a meeting room in Toronto office, there will be 5 of us',
//   'Next monday at 3pm for 1 hour, please', // Tell the bot when the meeting is taking place
//   'B'  // Rooms are defined on the Dialogflow agent, default options are A, B, or C
// ]
// languageCode: Indicates the language Dialogflow agent should use to detect intents
// const languageCode = 'en';

// Imports the Dialogflow library
const dialogflow = require('@google-cloud/dialogflow');

// Instantiates a session client
const sessionClient = new dialogflow.SessionsClient();

async function detectIntent(
  projectId,
  sessionId,
  query,
  contexts,
  languageCode
) {
  // The path to identify the agent that owns the created intent.
  const sessionPath = sessionClient.projectAgentSessionPath(
    projectId,
    sessionId
  );

  // The text query request.
  const request = {
    session: sessionPath,
    queryInput: {
      text: {
        text: query,
        languageCode: languageCode,
      },
    },
  };

  if (contexts && contexts.length > 0) {
    request.queryParams = {
      contexts: contexts,
    };
  }

  const responses = await sessionClient.detectIntent(request);
  return responses[0];
}

async function executeQueries(projectId, sessionId, queries, languageCode) {
  // Keeping the context across queries let's us simulate an ongoing conversation with the bot
  let context;
  let intentResponse;
  for (const query of queries) {
    try {
      console.log(`Sending Query: ${query}`);
      intentResponse = await detectIntent(
        projectId,
        sessionId,
        query,
        context,
        languageCode
      );
      console.log('Detected intent');
      console.log(
        `Fulfillment Text: ${intentResponse.queryResult.fulfillmentText}`
      );
      // Use the context from this response for next queries
      context = intentResponse.queryResult.outputContexts;
    } catch (error) {
      console.log(error);
    }
  }
}
executeQueries(projectId, sessionId, queries, languageCode);

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 detect_intent_texts(project_id, 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."""
    from google.cloud import dialogflow

    session_client = dialogflow.SessionsClient()

    session = session_client.session_path(project_id, session_id)
    print("Session path: {}\n".format(session))

    for text in texts:
        text_input = dialogflow.TextInput(text=text, language_code=language_code)

        query_input = dialogflow.QueryInput(text=text_input)

        response = session_client.detect_intent(
            request={"session": session, "query_input": query_input}
        )

        print("=" * 20)
        print("Query text: {}".format(response.query_result.query_text))
        print(
            "Detected intent: {} (confidence: {})\n".format(
                response.query_result.intent.display_name,
                response.query_result.intent_detection_confidence,
            )
        )
        print("Fulfillment text: {}\n".format(response.query_result.fulfillment_text))

Idiomas adicionales

C#: sigue lasinstrucciones de configuración de C# en la página Bibliotecas cliente y, luego, visita la documentación de referencia de Dialogflow para .NET.

PHP: sigue las instrucciones de configuración de PHP en la página Bibliotecas cliente y, luego, visita la documentación de referencia de Dialogflow para PHP.

Ruby: sigue las instrucciones de configuración de Ruby en la página Bibliotecas cliente y, luego, visita la documentación de referencia de Dialogflow para Ruby.

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
Descripción general de la consola de Dialogflow