Interações com a API

Para cada turno de conversa, ocorre uma interação. Durante uma interação, um utilizador final envia uma entrada para os agentes conversacionais (Dialogflow CX) e os agentes conversacionais (Dialogflow CX) enviam uma resposta. Tem duas opções quando implementa o seu sistema para processar interações: usar a API ou usar uma integração.

Quando usa a API, o seu sistema tem de processar o seguinte:

• Crie um agente.
• Oferecer uma interface do utilizador para utilizadores finais.
• Chame a API Dialogflow para cada interação de conversa para enviar a entrada do utilizador final para a API.
• A menos que as respostas do seu agente sejam puramente estáticas (incomum), tem de alojar um serviço de webhook para processar o cumprimento ativado por webhook.

Quando usa uma integração, o seu sistema só precisa de processar o seguinte:

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

O diagrama seguinte mostra os passos que ocorrem para uma interação conversacional de uma sessão.

Nota: as comunicações entre os seus sistemas e integrações, e o Dialogflow são encriptadas em trânsito. Além disso, as comunicações internas dos componentes da Google são encriptadas através da segurança de transporte da camada de aplicação (ALTS).

1. O utilizador final escreve ou diz algo, o que é conhecido como entrada do utilizador final.
2. A sua interface do utilizador ou sistema de integração recebe a entrada e encaminha-a para a API Dialogflow num pedido de deteção de intenção.
3. A Dialogflow API recebe o pedido de deteção de intenção. Corresponde à entrada a um parâmetro de intenção ou formulário, define os parâmetros conforme necessário e atualiza o estado da sessão. Se precisar de chamar um processamento de pedidos ativado por webhook, envia um pedido de webhook para o seu serviço de webhook, caso contrário, avance para o passo 6.
4. O seu serviço de webhook recebe o pedido de webhook. O seu serviço toma todas as medidas necessárias, como chamar APIs externas, consultar ou atualizar uma base de dados, etc.
5. O seu serviço de webhook cria uma resposta e envia uma resposta de webhook de volta aos agentes conversacionais (Dialogflow CX).
6. Os agentes conversacionais (Dialogflow CX) criam uma resposta de intenção de deteção. Se um webhook foi chamado, usa a resposta fornecida na resposta do webhook. Se não tiver sido chamado nenhum webhook, usa a resposta estática definida no agente. Os agentes conversacionais (Dialogflow CX) enviam uma resposta de intenção de deteção para a sua interface do utilizador ou sistema de integração.
7. A interface do utilizador ou o sistema de integração recebe a resposta de intenção de deteção e encaminha a resposta de texto ou áudio para o utilizador final.
8. O utilizador final vê ou ouve a resposta.

Finalidade do guia

Este guia mostra como chamar a API para uma interação conversacional para um agente que não está a usar uma integração (passo 2 do diagrama acima). Este guia não mostra como implementar uma interface do utilizador para o utilizador final.

Antes de começar

Antes de ler este guia, deve fazer o seguinte:

1. Leia as noções básicas sobre fluxos.
2. Execute os passos de configuração.
3. Crie um novo agente ou continue a usar o agente que criou em Crie um agente com fluxos ou Crie um agente com manuais de soluções

Recolha IDs

Os exemplos abaixo requerem vários IDs como entrada. Para encontrar o ID do projeto, o ID da região e o ID do agente:

Consola do Dialogflow CX

1. Abra a consola do Dialogflow CX.
2. Selecione o seu Google Cloud projeto 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. Esta ação copia o nome de identificação completo do seu 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/agents/AGENT_ID

Consola do Vertex AI Agent Builder

1. Aceda à consola do Vertex AI Agent Builder:

   Consola do Vertex AI Agent Builder

2. O ID do projeto é apresentado na parte superior da consola.

3. A coluna Localização mostra os IDs das regiões.

4. Selecione uma app.

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

Também precisa de um ID da sessão. Uma sessão representa uma conversa entre um agente de agentes conversacionais (Dialogflow CX) e um utilizador final. Cria um ID de sessão exclusivo no início de uma conversa e usa-o para cada interação da conversa. Para experimentar a API, pode usar qualquer ID de string com um máximo de 36 bytes, como test-session-123.

Intenção de deteção de chamadas

Os exemplos seguintes chamam o método Sessions.detectIntent. Aceda à referência da API Session

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

Protocolo	V3	V3beta1
REST	Recurso de sessão	Recurso de sessão
RPC	Interface de sessão	Interface de sessão
C++	SessionsClient	Não disponível
C#	SessionsClient	Não disponível
Ir	SessionsClient	Não disponível
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	Não disponível	Não disponível
Python	SessionsClient	SessionsClient
Ruby	Não disponível	Não disponível

Close

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• PROJECT_ID: o ID do seu projeto do Google Cloud
• AGENT_ID: o ID do seu agente
• REGION_ID: o seu ID da região
• SESSION_ID: o seu ID da sessão
• END_USER_INPUT: a entrada do utilizador 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 do pedido:

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

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 o seu agente em produção, certifique-se de que implementa as práticas recomendadas de produção.