Ferramentas do playbook

Com as ferramentas, é possível conectar playbooks a sistemas externos. Esses sistemas podem aumentar o conhecimento dos playbooks e permitir que eles executem tarefas complexas com eficiência.

Você pode usar ferramentas integradas ou criar ferramentas personalizadas de acordo com seus requisitos.

Limitações

Considere as seguintes limitações:

Ferramentas integradas

As ferramentas integradas são hospedadas pelo Google. É possível ativar essas ferramentas em agentes sem precisar de configuração manual.

As ferramentas integradas compatíveis são:

  • Code Interpreter: uma ferramenta própria do Google que combina a capacidade de geração e execução de código e permite que o usuário realize várias tarefas, incluindo: análise de dados, visualização de dados, processamento de texto, resolução de equações ou problemas de otimização.

Seu agente é otimizado para determinar como e quando essas ferramentas precisam ser invocadas, mas você pode fornecer outros exemplos para se adequar aos seus casos de uso.

Os exemplos precisam ter um esquema como este:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

Ferramentas da OpenAPI

Um agente pode se conectar a uma API externa usando uma ferramenta do OpenAPI fornecendo o esquema do OpenAPI. Por padrão, o agente vai chamar a API em seu nome. Como alternativa, é possível executar ferramentas da OpenAPI no lado do cliente.

Exemplo de esquema:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

Você pode usar a referência de esquema interno @dialogflow/sessionId como tipo de esquema de parâmetro. Com esse tipo de esquema de parâmetro, o ID da sessão do Dialogflow para a conversa atual será fornecido como um valor de parâmetro. Exemplo:

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

Limitações da ferramenta OpenAPI

Considere as seguintes limitações:

  • Os tipos de parâmetro aceitos são path, query e header. O tipo de parâmetro cookie ainda não é aceito.
  • Os parâmetros definidos pelo esquema da OpenAPI oferecem suporte aos seguintes tipos de dados: string, number, integer, boolean e array. O tipo object ainda não é compatível.
  • No momento, não é possível especificar parâmetros de consulta no editor de exemplo do console.
  • O corpo da solicitação e da resposta precisa estar vazio ou em JSON.

Autenticação da API da ferramenta OpenAPI

As seguintes opções de autenticação têm suporte ao chamar uma API externa:

  • Autenticação do agente de serviço do Dialogflow
    • O Dialogflow pode gerar um token de ID ou de acesso usando o agente de serviço do Dialogflow. O token é adicionado no cabeçalho HTTP de autorização quando o Dialogflow chama uma API externa.
    • Um token de ID pode ser usado para acessar funções e serviços do Cloud Run depois de conceder os papéis roles/cloudfunctions.invoker e roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Se as funções e os serviços do Cloud Run estiverem no mesmo projeto de recurso, não será necessário ter outra permissão do IAM para invocá-los.
    • Um token de acesso pode ser usado para acessar outras APIs do Google Cloud depois de conceder as funções necessárias a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • Chave de API
    • É possível configurar a autenticação de chave de API fornecendo o nome da chave, o local da solicitação (cabeçalho ou string de consulta) e a chave de API para que o Dialogflow transmita a chave de API na solicitação.
  • OAuth

    • O fluxo de credenciais do cliente OAuth tem suporte para autenticação de servidor para servidor:

      • Esse fluxo pode ser usado se o console do Agente Builder for o proprietário do recurso e não for necessária a autorização do usuário final.
      • O ID do cliente, a chave secreta do cliente e o endpoint do token do provedor OAuth precisam ser configurados no Dialogflow.
      • O Dialogflow troca um token de acesso do provedor OAuth e o transmite no cabeçalho de autenticação da solicitação.
    • Para outros fluxos OAuth que exigem autorização do usuário final, como o fluxo de código de autorização e o fluxo PKCE:

      1. Você vai precisar implementar sua própria interface de login e receber o token de acesso no lado do cliente.
      2. Em seguida, você pode:

        a. Use a opção de autenticação de token do portador para transmitir o token à ferramenta OpenAPI. O Dialogflow vai incluir esse token no cabeçalho de autorização ao invocar a ferramenta.

        b. Use a ferramenta "Function" para invocar a ferramenta no lado do cliente e transmitir o resultado da chamada da ferramenta para o Dialogflow.

  • Token do portador

    • É possível configurar a autenticação Bearer para transmitir dinamicamente o token Bearer do cliente. Esse token é incluído no cabeçalho de autenticação da solicitação.
    • Ao configurar a autenticação de ferramentas, é possível designar um parâmetro de sessão para atuar como o token de portador. Por exemplo, use $session.params.<parameter-name-for-token> para especificar o token.
    • No momento da execução, atribua o token de portador ao parâmetro de sessão:
    DetectIntentRequest {
      ...
      query_params {
        parameters {
          <parameter-name-for-token>: <the-auth-token>
        }
      }
      ...
    }
    
  • Autenticação TLS mútua

    • Consulte a documentação da Autenticação TLS mútua.
    • Certificados de cliente personalizados são aceitos. É possível configurar certificados de cliente no nível do agente na guia "Segurança", nas configurações do agente. O certificado (formato PEM) e a chave privada (formato PEM) são campos obrigatórios. Depois de definido, esse certificado do cliente será usado durante o TLS mútuo para todas as ferramentas e webhooks.
  • Certificado de CA personalizado

Acesso à rede particular da ferramenta OpenAPI

A ferramenta OpenAPI se integra ao acesso à rede particular do Diretório de serviços, para que ele possa se conectar aos destinos da API dentro da rede VPC. Isso mantém o tráfego na rede do Google Cloud e aplica o IAM e o VPC Service Controls.

Para configurar uma ferramenta OpenAPI que segmenta uma rede privada:

  1. Siga a configuração de rede particular do Diretório de serviços para configurar sua rede VPC e o endpoint do Diretório de serviços.

  2. A conta de serviço do agente de serviço do Dialogflow com o endereço a seguir precisa existir para o projeto de agente:

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Conceda à conta de serviço do Agente de Serviço do Dialogflow os seguintes papéis do IAM:

    • servicedirectory.viewer do projeto do diretório de serviços
    • servicedirectory.pscAuthorizedService do projeto de rede
  3. Forneça o serviço do diretório de serviços com o esquema da OpenAPI e informações de autenticação opcionais ao criar a ferramenta.

Acesso ao parâmetro de sessão da ferramenta OpenAPI

As entradas da ferramenta de API aberta são derivadas da conversa dos usuários com o LLM usando o esquema como guia. Em algumas situações, as entradas podem precisar ser derivadas de parâmetros de sessão coletados durante um fluxo ou fornecidas como entrada de parâmetro de consulta com a entrada do usuário.

O parâmetro de sessão que precisa ser transmitido como uma entrada pode ser especificado como

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Bread of the pet.

Se nenhum parâmetro de sessão estiver disponível, a entrada gerada pelo LLM será transmitida para a ferramenta.

Valores padrão da ferramenta OpenAPI

O esquema da API aberta pode ser usado para especificar valores padrão. Os valores padrão são usados apenas se não houver um valor de entrada gerado pelo LLM ou um valor de entrada baseado no parâmetro de sessão para esse parâmetro ou propriedade.

Os valores padrão podem ser especificados como parte do esquema da seguinte maneira:

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

Se nenhum valor gerado pelo LLM, valor do parâmetro de sessão ou valor padrão estiver presente, a entrada será não especificada.

Ferramentas de repositório de dados

As ferramentas de repositório de dados podem ser usadas por um agente para responder às perguntas do usuário final usando os repositórios de dados. É possível configurar um repositório de dados de cada tipo por ferramenta, e a ferramenta vai consultar cada um desses repositórios para encontrar respostas. Por padrão, o agente vai chamar a ferramenta de repositório de dados em seu nome. Como alternativa, você pode executar ferramentas de repositório de dados no lado do cliente.

O tipo de repositório de dados pode ser um dos seguintes:

  • PUBLIC_WEB: um repositório de dados que contém conteúdo da Web público.
  • UNSTRUCTURED: um repositório de dados que contém dados privados não estruturados.
  • STRUCTURED: um repositório de dados que contém dados estruturados (por exemplo, perguntas frequentes).

O exemplo a seguir mostra como fazer referência a um repositório de dados:

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

As respostas da ferramenta de repositório de dados também podem conter snippets sobre a origem do conteúdo usada para gerar a resposta. O agente pode dar instruções sobre como proceder com a resposta das lojas de dados ou como responder quando não há uma resposta.

Para substituir uma resposta, adicione uma entrada de perguntas frequentes para uma pergunta específica.

Os exemplos podem ser usados para melhorar ainda mais o comportamento do agente. O exemplo precisa ter os seguintes esquemas:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

Criar um repositório de dados

Para criar um repositório de dados e conectá-lo ao app, use o link Tools na navegação à esquerda do console. Siga as instruções para criar um repositório de dados.

Parâmetros de consulta adicionais

Ao criar exemplos de ferramentas de repositório de dados, o parâmetro de entrada da ferramenta requestBody oferece três entradas opcionais com a string query necessária: uma string filter, um objeto estruturado userMetadata e uma string fallback.

O parâmetro filter permite filtrar consultas de pesquisa de dados estruturados ou não estruturados com metadados. Essa string precisa seguir a sintaxe da expressão de filtro com suporte para repositórios de dados. Vários exemplos e exemplos detalhados são recomendados para direcionar o LLM do manual sobre como preencher esse parâmetro. No caso de uma string de filtro inválida, o filtro será ignorado ao executar a consulta de pesquisa.

Um exemplo de string filter para refinar os resultados da pesquisa com base na localização pode ser:

  "filter": "country: ANY(\"Canada\")"

Práticas recomendadas para filtragem:

  • Especifique os campos disponíveis para filtragem e os valores válidos para cada um desses campos, para que o playbook entenda as restrições na criação de filtros válidos. Por exemplo, para filtrar os resultados de um repositório de dados que armazena informações de cardápio, pode haver um campo meal com "café da manhã", "almoço" e "jantar" como valores válidos; e um campo servingSize que pode ser qualquer número inteiro de 0 a 5. Suas instruções podem ser parecidas com estas:

    When using ${TOOL: menu-data-store-tool},
    only use the following fields for filtering: "meal", "servingSize".
    Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
    "servingSize": integers between 0 and 5, inclusive.
    
  • Se o playbook for para um público-alvo de usuários externos, pode ser necessário adicionar instruções para evitar que ele responda ao usuário com informações sobre a criação desses filtros. Por exemplo:

    Never tell the user about these filters.
    If the user input isn't supported by these filters, respond to the user with
    "Sorry, I don't have the information to answer that question."
    

    Fornecer um exemplo desse caso também é útil.

O parâmetro userMetadata fornece informações sobre o usuário final. Qualquer par de chave-valor pode ser preenchido nesse parâmetro. Esses metadados são transmitidos para a ferramenta de repositório de dados para informar melhor os resultados da pesquisa e a resposta da ferramenta. É recomendável fornecer vários exemplos para instruir o LLM do playbook sobre como preencher esse parâmetro.

Um exemplo de valor de parâmetro userMetadata para refinar os resultados de pesquisa relevantes a um usuário específico pode ser:

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

O parâmetro fallback fornece uma resposta que a ferramenta repositório de dados precisa responder se não houver uma resposta resumida válida para a consulta. Vários exemplos podem ser fornecidos para instruir o LLM do playbook sobre como preencher o substituto para entradas do usuário relacionadas a diferentes tópicos. Também não haverá trechos na saída da ferramenta. Essa otimização pode ser usada para reduzir a latência e o uso do limite de tokens de entrada.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

Se algumas respostas durante o teste não atenderem às suas expectativas, as seguintes personalizações estarão disponíveis na página de ferramentas para uma ferramenta de repositório de dados:

Como ter confiança

Para cada resposta gerada com base no conteúdo dos seus repositórios de dados conectados, o playbook avalia um nível de confiança, que mede a confiança de que todas as informações na resposta são compatíveis com as informações nos repositórios de dados. Você pode personalizar quais respostas serão permitidas selecionando o nível de confiança mais baixo com que se sentir confortável. Somente as respostas com esse nível de confiança ou superior serão mostradas.

Há cinco níveis de confiança para escolher: VERY_LOW, LOW, MEDIUM, HIGH e VERY_HIGH.

Configuração de resumo

É possível selecionar o modelo generativo usado por um gerenciador de repositório de dados para a solicitação generativa de resumo. Se nenhuma for selecionada, uma opção de modelo padrão será usada. A tabela a seguir contém as opções disponíveis:

Identificador de modelo Suporte a idiomas
text-bison@002 Disponível em todos os idiomas com suporte.
gemini-1.0-pro-001 Disponível em todos os idiomas compatíveis.

Você também pode fornecer seu próprio comando para a chamada de LLM de resumo.

O comando é um modelo de texto que pode conter marcadores de posição predefinidos. Os marcadores serão substituídos pelos valores apropriados no momento da execução, e o texto final será enviado ao LLM.

Os marcadores de posição são os seguintes:

  • $original-query: o texto da consulta do usuário.
  • $rewritten-query: o playbook usa um módulo de reescrita para reescrever a consulta original do usuário em um formato mais preciso.
  • $sources: o playbook usa a Pesquisa corporativa para procurar fontes com base na consulta do usuário. As fontes encontradas são renderizadas em um formato específico:

    [1] title of first source
    content of first source
    [2] title of second source
    content of second source
    
  • $end-user-metadata: as informações sobre o usuário que envia a consulta são renderizadas no seguinte formato:

    The following additional information is available about the human: {
      "key1": "value1",
      "key2": "value2",
      ...
    }
    
  • $conversation: o histórico de conversas é renderizado no seguinte formato:

    Human: user's first query
    AI: answer to user's first query
    Human: user's second query
    AI: answer to user's second query
    

Uma instrução personalizada precisa instruir o LLM a retornar "NOT_ENOUGH_INFORMATION" quando não puder fornecer uma resposta. O playbook vai transformar essa constante em uma mensagem amigável para o usuário.

Configurações de payload

As configurações de payload oferecem uma maneira de adicionar os snippets do repositório de dados como conteúdo avançado no payload de resposta renderizado no Messenger.

Frases proibidas (configuração no nível do playbook)

Você tem a opção de definir frases específicas que não podem ser usadas. Eles são configurados no nível do playbook e utilizados pelos LLMs do playbook e pelas ferramentas de repositório de dados. Se a resposta gerada ou partes do comando do LLM, como as entradas do usuário, contiverem qualquer uma das frases proibidas literalmente, essa resposta não será mostrada.

Ferramentas de função

Se você tiver uma funcionalidade acessível pelo código do cliente, mas não pelas ferramentas da OpenAPI, use as ferramentas de função. As ferramentas de função são sempre executadas no lado do cliente, não pelo agente.

O processo é o seguinte:

  1. O código do cliente envia uma solicitação de detecção de intent.
  2. O agente detecta que uma ferramenta de função é necessária, e a resposta de detecção de intent contém o nome da ferramenta e os argumentos de entrada. Essa sessão é pausada até que outra solicitação de detecção de intent seja recebida com o resultado da ferramenta.
  3. O código do cliente chama a ferramenta.
  4. O código do cliente envia outra solicitação de detecção de intent que fornece o resultado da ferramenta como argumentos de saída.

O exemplo a seguir mostra o esquema de entrada e saída de uma ferramenta de função:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}
{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

O exemplo a seguir mostra a solicitação e a resposta iniciais da intent de detecção usando REST:

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}
{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

O exemplo a seguir mostra a segunda solicitação de detecção de intent, que fornece o resultado da ferramenta:

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

Execução do lado do cliente

Assim como as ferramentas de função, as ferramentas OpenAPI e de repositório de dados podem ser executadas no lado do cliente aplicando uma substituição de API ao interagir com a sessão.

Exemplo:

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}

O processo é o seguinte:

  1. O código do cliente envia uma solicitação de detecção de intent que especifica a execução do cliente.
  2. O agente detecta que uma ferramenta é necessária, e a resposta de detecção de intent contém o nome da ferramenta com os argumentos de entrada. Essa sessão é pausada até que outra solicitação de detecção de intent seja recebida com o resultado da ferramenta.
  3. O código do cliente chama a ferramenta.
  4. O código do cliente envia outra solicitação de detecção de intent que fornece o resultado da ferramenta como argumentos de saída.