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. En cada turno de conversación, tu código llama a la API de Dialogflow para consultar tu agente. En esta guía se muestra cómo interactuar con un agente mediante la API REST en la línea de comandos y mediante las bibliotecas de cliente.

Antes de empezar

Si no tienes previsto usar la API, puedes saltarte esta guía de inicio rápido.

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

  1. Conocer los conceptos básicos de Dialogflow.
  2. Sigue los pasos de configuración.
  3. Sigue los pasos de la guía de inicio rápido Crear un agente. Los pasos que se indican a continuación continúan trabajando en el agente que has creado en esa guía. Si ya no tienes ese agente, puedes descargar build-agent-quickstart.zip e importar el archivo.

Sesiones

Una sesión representa una conversación entre un agente de Dialogflow y un usuario final. Creas una sesión al principio de una conversación y la usas en cada turno de la conversación. Una vez que haya finalizado la conversación, dejarás de usar la sesión.

No debes usar la misma sesión para mantener conversaciones simultáneas con diferentes usuarios finales. Dialogflow mantiene los contextos activos de cada sesión activa. Dialogflow almacena los datos de las sesiones durante 20 minutos.

Cada sesión se determina como única mediante un ID de sesión generado por tu sistema. Para crear una sesión, debes proporcionar un nuevo ID de sesión en una solicitud de detección de intención. Un ID de sesión es una cadena de 36 bytes como máximo. Tu sistema es el responsable de generar IDs de sesión únicos. Pueden ser números aleatorios, identificadores de usuario final cifrados con hash o cualquier otro valor que le resulte cómodo generar.

Detectar un intent

Cuando usas la API para las interacciones, tu servicio interactúa directamente con el usuario final. En cada interacción, tu servicio envía expresiones de usuario final a Dialogflow llamando al método detectIntent o streamingDetectIntent del tipo Sessions. Dialogflow responde con información sobre la intención que coincide, la acción, los parámetros y la respuesta definidos para la intención. Tu servicio realiza las acciones necesarias (por ejemplo, consultas de bases de datos o llamadas a APIs externas) y envía un mensaje al usuario final. Este proceso continúa hasta que finaliza la conversación.

En los siguientes ejemplos se muestra cómo detectar intenciones. Cada ejemplo acepta un subconjunto de las siguientes entradas:

  • ID del proyecto: Usa el ID del proyecto que has creado en los pasos de configuración.
  • ID de sesión: Para probar un agente, puedes usar cualquier valor. Por ejemplo, "123456789" se usa con frecuencia en las muestras.
  • Texto o textos: se trata de una expresión de usuario final o de una lista de expresiones de usuario final. Si se proporcionan varias expresiones, el código de ejemplo llama a la detección de intenciones para cada expresión. Prueba a decir "I know french" ("Sé francés").
  • Código de idioma: código de idioma de la expresión del usuario final. Usa "en-US" para este agente de ejemplo.

REST

Para detectar la intención, llama al método detectIntent del recurso Sessions.

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

  • PROJECT_ID: tu ID de proyecto de Google Cloud
  • SESSION_ID: un ID de sesión

Método HTTP y 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, despliega una de estas opciones:

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

{
  "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 lo siguiente sobre la respuesta:

  • El campo queryResult.intent contiene el intent coincidente.
  • El valor del campo queryResult.fulfillmentMessages contiene la respuesta de la intención. Esta es la respuesta que tu sistema debe reenviar 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. Para obtener más información, consulta el artículo Configurar la autenticación en 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 "", fmt.Errorf("detect.DetectIntentText 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. 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.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. Para obtener más información, consulta el artículo Configurar la autenticación en 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. Para obtener más información, consulta el artículo Configurar la autenticación en 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 las instrucciones de configuración de C# en la página de bibliotecas de cliente y, a continuación, consulta la documentación de referencia de Dialogflow para .NET.

PHP Sigue las instrucciones de configuración de PHP en la página de bibliotecas de cliente y, a continuación, consulta la documentación de referencia de Dialogflow para PHP.

Ruby: Sigue las instrucciones de configuración de Ruby en la página de bibliotecas de cliente y, a continuación, consulta la documentación de referencia de Dialogflow para Ruby.

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.