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

En esta guía de inicio rápido, se muestra cómo interactuar con un agente mediante la API de REST en la línea de comandos y con 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. Obtén más información sobre cómo crear un agente.

Crea un agente

En los pasos que se brindan esta guía, damos por sentado determinadas características de tu agente. Por eso, es recomendable que comiences con un agente nuevo. Debes borrar cualquier agente existente en tu proyecto antes de crear uno nuevo. Para borrar un agente existente, haz lo siguiente:

  1. Ve a la Consola de Dialogflow.
  2. Si se te solicita, accede a la consola de Dialogflow. Consulta Descripción general de la consola de Dialogflow para obtener más información.
  3. Selecciona el agente que deseas borrar.
  4. Haz clic en el botón de configuración settings ubicado junto al nombre del agente.
  5. Desplázate hasta la parte inferior de la pestaña de configuración General.
  6. Haz clic en Borrar este agente.
  7. Ingresa BORRAR en el campo de texto.
  8. Haz clic en Borrar.

Para crear un agente, haz lo siguiente:

  1. Ve a la Consola de Dialogflow.
  2. Si se te solicita, accede a la consola de Dialogflow. Consulta Descripción general de la consola de Dialogflow para obtener más información.
  3. Haz clic en Crear agente en el menú de la barra lateral izquierda. Si ya tienes otros agentes, haz clic en el nombre del agente, desplázate hasta la parte inferior y haz clic en Crear agente nuevo.
  4. Ingresa el nombre del agente, y el idioma y la zona horaria predeterminados.
  5. Si ya creaste un proyecto, ingrésalo. Si deseas permitir que la consola de Dialogflow cree el proyecto, selecciona Crear un proyecto de Google nuevo.
  6. Haz clic en el botón Crear.

Importa el archivo de ejemplo al agente

La importación agregará intents y entidades al agente. Si hay intents o entidades con el mismo nombre que los del archivo importado, se reemplazarán los primeros por los segundos.

Para importar el archivo, sigue estos pasos:

  1. Descarga el archivo RoomReservation.zip.
  2. Ve a la Consola de Dialogflow.
  3. Selecciona el agente.
  4. Haz clic en el botón de configuración settings ubicado junto al nombre del agente.
  5. Selecciona la pestaña Importar y exportar.
  6. Selecciona Importar desde ZIP y, luego, importa el archivo ZIP que descargaste.

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 en cada uno de sus turnos. Una vez terminada la conversación, se deja de usar la sesión.

No se debe usar la misma sesión para varias 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 con un ID de sesión que genera el 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. En cada turno de la conversación, el servicio envía las 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. El servicio realiza las acciones necesarias (por ejemplo, consultar la base de datos o hacer llamadas a API externas) y le envía un mensaje al usuario final. Este proceso continúa hasta que la conversación finaliza.

El agente que se importó en los pasos anteriores es un agente simple de reserva de salas de reuniones. Para examinar los intents, visita la consola de Dialogflow y selecciona tu agente nuevo.

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 expresión del usuario final única o 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 la expresión “reserve a meeting room for six people” ("Reserva una sala de reuniones para seis personas").
  • Código de idioma: El código de idioma de la expresión del usuario final. Usa “en-US” para este agente de muestra.

REST Y LÍNEA DE COMANDOS

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

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

  • project-id: el ID de tu proyecto de GCP
  • ID de sesión: 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": "reserve a meeting room for six people",
          "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": "50fcfcec-a315-4415-9075-5e0391e1f952",
      "queryResult": {
        "queryText": "reserve a meeting room for six people",
        "action": "room.reservation",
        "parameters": {
          "time": "",
          "date": "",
          "guests": 6,
          "duration": "",
          "location": ""
        },
        "fulfillmentText": "I can help with that. Where would you like to reserve a room?",
        "fulfillmentMessages": [
          {
            "text": {
              "text": [
                "I can help with that. Where would you like to reserve a room?"
              ]
            }
          }
        ],
        "outputContexts": [
          ...
        ],
        "intent": {
          "name": "projects/project-id/agent/intents/e8f6a63e-73da-4a1a-8bfc-857183f71228",
          "displayName": "room.reservation"
        },
        "intentDetectionConfidence": 1,
        "diagnosticInfo": {},
        "languageCode": "en-us"
      }
    }
    

Ten en cuenta estos aspectos sobre la respuesta:

  • El valor del campo queryResult.action es "room.reservation". Esto coincide con el campo de acción del intent coincidente.
  • El valor del campo queryResult.parameters.guests es 6. Este valor de parámetro se extrajo de la expresión del usuario final “reserve a meeting room for six people” ("Reserva una sala de reuniones para seis personas").
  • El valor del campo queryResult.fulfillmentMessages[0|1].text.text[0] solicita al usuario más información. Esta es la respuesta que el sistema debe enviarle al usuario final.

C#

        public static int DetectIntentFromTexts(string projectId,
                                                    string sessionId,
                                                    string[] texts,
                                                    string languageCode = "en-US")
            {
                var client = SessionsClient.Create();

                foreach (var text in texts)
                {
                    var response = client.DetectIntent(
                        session: new SessionName(projectId, sessionId),
                        queryInput: new QueryInput()
                        {
                            Text = new TextInput()
                            {
                                Text = text,
                                LanguageCode = languageCode
                            }
                        }
                    );

                    var queryResult = response.QueryResult;

                    Console.WriteLine($"Query text: {queryResult.QueryText}");
                    if (queryResult.Intent != null)
                    {
                        Console.WriteLine($"Intent detected: {queryResult.Intent.DisplayName}");
                    }
                    Console.WriteLine($"Intent confidence: {queryResult.IntentDetectionConfidence}");
                    Console.WriteLine($"Fulfillment text: {queryResult.FulfillmentText}");
                    Console.WriteLine();
                }

                return 0;
            }

Go

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


    /**
     * Returns the result of detect intent with texts as inputs.
     *
     * Using the same `session_id` between requests allows continuation of the conversation.
     *
     * @param projectId    Project/Agent Id.
     * @param texts        The text intents to be detected based on what a user says.
     * @param sessionId    Identifier of the DetectIntent session.
     * @param languageCode Language code of the query.
     * @return The QueryResult for each input text.
     */
    public static Map<String, QueryResult> detectIntentTexts(
        String projectId,
        List<String> texts,
        String sessionId,
        String languageCode) throws Exception {
      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
          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.getFulfillmentText());

          queryResults.put(text, queryResult);
        }
      }
      return queryResults;
    }

Node.js


    /**
     * 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: 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('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.sessionPath(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);

PHP

namespace Google\Cloud\Samples\Dialogflow;

    use Google\Cloud\Dialogflow\V2\SessionsClient;
    use Google\Cloud\Dialogflow\V2\TextInput;
    use Google\Cloud\Dialogflow\V2\QueryInput;

    /**
     * Returns the result of detect intent with texts as inputs.
     * Using the same `session_id` between requests allows continuation
     * of the conversation.
     */
    function detect_intent_texts($projectId, $texts, $sessionId, $languageCode = 'en-US')
    {
        // new session
        $sessionsClient = new SessionsClient();
        $session = $sessionsClient->sessionName($projectId, $sessionId ?: uniqid());
        printf('Session path: %s' . PHP_EOL, $session);

        // query for each string in array
        foreach ($texts as $text) {
            // create text input
            $textInput = new TextInput();
            $textInput->setText($text);
            $textInput->setLanguageCode($languageCode);

            // create query input
            $queryInput = new QueryInput();
            $queryInput->setText($textInput);

            // get response and relevant info
            $response = $sessionsClient->detectIntent($session, $queryInput);
            $queryResult = $response->getQueryResult();
            $queryText = $queryResult->getQueryText();
            $intent = $queryResult->getIntent();
            $displayName = $intent->getDisplayName();
            $confidence = $queryResult->getIntentDetectionConfidence();
            $fulfilmentText = $queryResult->getFulfillmentText();

            // output relevant info
            print(str_repeat("=", 20) . PHP_EOL);
            printf('Query text: %s' . PHP_EOL, $queryText);
            printf('Detected intent: %s (confidence: %f)' . PHP_EOL, $displayName,
                $confidence);
            print(PHP_EOL);
            printf('Fulfilment text: %s' . PHP_EOL, $fulfilmentText);
        }

        $sessionsClient->close();
    }

Python

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."""
        import dialogflow_v2 as 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.types.TextInput(
                text=text, language_code=language_code)

            query_input = dialogflow.types.QueryInput(text=text_input)

            response = session_client.detect_intent(
                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))

Ruby

# project_id = "Your Google Cloud project ID"
    # session_id = "mysession"
    # texts = ["hello", "book a meeting room"]
    # language_code = "en-US"

    require "google/cloud/dialogflow"

    session_client = Google::Cloud::Dialogflow::Sessions.new
    session = session_client.class.session_path project_id, session_id
    puts "Session path: #{session}"

    texts.each do |text|
      query_input = { text: { text: text, language_code: language_code } }
      response = session_client.detect_intent session, query_input
      query_result = response.query_result

      puts "Query text:        #{query_result.query_text}"
      puts "Intent detected:   #{query_result.intent.display_name}"
      puts "Intent confidence: #{query_result.intent_detection_confidence}"
      puts "Fulfillment text:  #{query_result.fulfillment_text}\n"
    end