Interações com a API

Para cada conversa, ocorre uma interação. Durante uma interação, um usuário final envia uma entrada para os agentes de conversação (Dialogflow CX), que envia uma resposta. Você tem duas opções ao implementar seu sistema para lidar com interações: usando a API ou uma integração.

Ao usar a API, o sistema precisa processar o seguinte:

• Crie um agente.
• Forneça uma interface do usuário para usuários finais.
• Chame a API Dialogflow para cada turno de conversa para enviar a entrada do usuário final para a API.
• A menos que as respostas do agente sejam puramente estáticas (incomum), é necessário hospedar um serviço de webhook para processar o fulfillment ativado para webhook.

Ao usar uma integração, seu sistema só precisa processar o seguinte:

• Crie um agente.
• Como alternativa, implemente um serviço de webhook.

O diagrama a seguir mostra as etapas que ocorrem em uma rodada de conversa de uma sessão.

Observação: as comunicações entre seus sistemas e integrações e o Dialogflow são criptografadas em trânsito. Além disso, as comunicações de componentes internos do Google são criptografadas usando Application Layer Transport Security (ALTS).

1. O usuário final digita ou diz algo, conhecido como entrada do usuário final.
2. O sistema de interface do usuário ou integração recebe a entrada e a encaminha para a API Dialogflow em uma solicitação de detecção de intent.
3. A API Dialogflow recebe a solicitação de detecção de intent. Ele corresponde a entrada a um parâmetro de intent ou formulário, define parâmetros conforme necessário e atualiza o estado da sessão. Se ele precisar chamar um fulfillment ativado para webhook, ele enviará uma solicitação de webhook para seu serviço de webhook. Caso contrário, vá para a etapa 6.
4. O serviço de webhook recebe a solicitação de webhook. Seu serviço realiza todas as ações necessárias, como chamar APIs externas, consultar ou atualizar um banco de dados etc.
5. Seu serviço de webhook cria uma resposta e envia uma resposta de webhook de volta para os agentes de conversação (Dialogflow CX).
6. Os agentes de conversação (Dialogflow CX) criam uma resposta de intent de detecção. Se um webhook foi chamado, ele usará a resposta fornecida na resposta do webhook. Se nenhum webhook foi chamado, ele usa a resposta estática definida no agente. Os agentes de conversação (Dialogflow CX) enviam uma resposta de detecção de intent para a interface do usuário ou o sistema de integração.
7. O sistema da interface do usuário recebe a resposta de intent de detecção e encaminha o texto ou a áudio para o usuário final.
8. O usuário final vê ou ouve a resposta.

Finalidade do guia

Neste guia, você verá como chamar a API para uma conversa de um agente que não esteja usando uma integração (etapa 2 do diagrama acima). Este guia não mostra como implementar uma interface do usuário para o usuário final.

Antes de começar

Faça o seguinte antes de ler este guia:

1. Leia os conceitos básicos do fluxo.
2. Execute as etapas de configuração.
3. Crie um novo agente ou continue usando o que você criou em Criar um agente usando fluxos ou Criar um agente usando playbooks.

Coletar IDs

As amostras abaixo exigem vários IDs como entrada. Para encontrar o ID do projeto, o ID da região e o ID do agente:

Console do Dialogflow CX

1. Abra o console do Dialogflow CX.
2. Selecione seu projeto do Google Cloud para abrir o seletor de agentes.
3. Clique no menu de opções de um agente na lista.
4. Clique no botão "Copiar nome ".
5. Isso copia o nome completo de identificação do agente, que inclui o ID do projeto, o ID da região e o ID do agente no formato:
   projects/PROJECT_ID/locations/REGION_ID/agentes/AGENT_ID

Console do Agent Builder

1. Acesse o console do Criador de agentes:

   Console do Criador de agentes

2. O ID do projeto é mostrado na parte de cima do console.

3. A coluna Local mostra os IDs das regiões.

4. Selecione um app.

5. O segmento de caminho do URL do navegador após agents/ contém o ID do app do agente.

Você também precisa de um código de sessão. Uma sessão representa uma conversa entre um agente de agentes de conversação (Dialogflow CX) e um usuário final. Você cria um código de sessão exclusivo no início de uma conversa e o usa para cada turno da conversa. Para testar a API, use qualquer ID de string com no máximo 36 bytes, como test-session-123.

Chamar intent de detecção

Os exemplos a seguir chamam o método Sessions.detectIntent. Acessar a referência da API Session

Selecione um protocolo e uma versão para a referência de sessão:

Protocolo	V3	V3beta1
REST	Recurso da sessão	Recurso da sessão
RPC (remote procedure call)	Interface da sessão	Interface da sessão
C++	SessionsClient	Indisponível
C#	SessionsClient	Indisponível
Go	SessionsClient	Indisponível
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Indisponível	Indisponível
Python	SessionsClient	SessionsClient
Ruby	Indisponível	Indisponível

Fechar

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• PROJECT_ID: o ID do projeto do Google Cloud
• AGENT_ID: seu ID de agente
• REGION_ID: o ID da sua região
• SESSION_ID: seu ID de sessão
• END_USER_INPUT: a entrada do usuário final

Método HTTP e URL:

POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent

Corpo JSON da solicitação:

{
  "queryInput": {
    "text": {
      "text": "END_USER_INPUT"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

{
  "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 autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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")

Produção

Antes de executar seu agente na produção, implemente as práticas recomendadas de produção.