Ferramentas

Com o uso de ferramentas, é possível conectar apps de agentes a sistemas externos. Esses sistemas podem aumentar o conhecimento dos apps de agentes e capacitá-los executar tarefas complexas com eficiência.

Você pode usar ferramentas integradas ou criar ferramentas personalizadas para atender às suas necessidades.

Limitações

Considere as seguintes limitações:

Ferramentas integradas

As ferramentas integradas são hospedadas pelo Google. Ative essas ferramentas nos apps do agente sem a necessidade de configuração manual.

As ferramentas integradas com suporte são:

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

O app do agente é otimizado para determinar como e quando essas ferramentas precisam ser invocadas. mas você pode fornecer outros exemplos para 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 OpenAPI

Um app agente pode se conectar a uma API externa usando uma ferramenta OpenAPI fornecendo o esquema OpenAPI. Por padrão, o app do 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

Também é possível 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 da 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âmetros aceitos são path, query e header. O tipo de parâmetro cookie ainda não é compatível.
  • Os parâmetros definidos pelo esquema OpenAPI são compatíveis com os 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 exemplos 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 token de acesso usando Agente de serviço do Dialogflow. O token será adicionado ao cabeçalho HTTP de autorização quando o Dialogflow chama uma API externa.
    • Um token de ID pode ser usado para acessar os serviços do Cloud Functions e do Cloud Run depois de conceder os papéis roles/cloudfunctions.invoker e roles/run.invoker à service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Se os serviços do Cloud Functions e do Cloud Run estiverem no mesmo projeto de recurso, você não precisará de outras permissões do IAM para chamá-los.
    • Um token de acesso pode ser usado para acessar outras APIs do Google Cloud depois que você concede os papéis necessários service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • Chave de API
    • É possível configurar a autenticação da chave de API fornecendo o nome dela, localização da solicitação (cabeçalho ou string de consulta) e a chave de API para que o Dialogflow transmita essa chave na solicitação.
  • OAuth
    • O fluxo de credenciais do cliente OAuth tem suporte para autenticação de servidor para servidor. O ID do cliente, a chave secreta do cliente e o endpoint do token do provedor OAuth precisam precisam ser configurados no Dialogflow. O Dialogflow troca um token de acesso OAuth e a passa no cabeçalho Auth da solicitação.
    • Para outros fluxos do OAuth, você precisa usar a ferramenta de funções para integrar com sua própria interface de login para trocar o token.

  • Token do portador

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

  • Autenticação TLS mútua

  • Certificado de CA personalizado

Acesso à rede particular da ferramenta OpenAPI

A ferramenta OpenAPI se integra Acesso a redes privadas do Diretório de serviços, para se conectar a destinos de 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 segmente 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. O agente de serviço do Dialogflow conta de serviço com o seguinte endereço deve existir para seu 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. Fornecer o serviço do diretório de serviços com o esquema OpenAPI e informações de autenticação opcionais ao criar a ferramenta.

Ferramentas de repositório de dados

Um app agente pode usar ferramentas de repositório de dados para obter respostas a perguntas de usuários finais de suas armazenamentos de dados. Você pode configurar um repositório de dados de cada tipo por ferramenta, e a ferramenta consultará cada um desses repositórios de dados para obter respostas. Por padrão, o app do agente chamará a ferramenta de repositório de dados em seu nome. Como alternativa, é possível 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 público da Web.
  • UNSTRUCTURED: um repositório de dados que contém dados particulares não estruturados.
  • STRUCTURED: um repositório de dados que contém dados estruturados (por exemplo, perguntas frequentes).

O exemplo a seguir mostra como referenciar 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 usado para gerar a resposta. O app do agente pode fornecer mais instruções sobre como proceder com a resposta dos repositórios de dados ou em como responder quando não há 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 app 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 seu app, use o link Ferramentas 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 requestBody da ferramenta fornece três entradas opcionais com a string query obrigatória - uma string filter, um objeto estruturado userMetadata e uma string fallback.

Com o parâmetro filter, é possível filtrar as consultas de pesquisa das estruturados ou não estruturados com metadados. Essa string deve seguir o sintaxe de expressão de filtro compatível para repositórios de dados. Vários exemplos e exemplos detalhados são incentivados a orientar o LLM do agente sobre como para preencher esse parâmetro. No caso de uma string de filtro inválida, o valor será ignorado ao executar a consulta de pesquisa.

Exemplo de string filter para refinar os resultados da pesquisa com base no local pode ser semelhante a esta:

  "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 agente entenda as restrições para criar filtros válidos. Por exemplo: para filtrar os resultados de um repositório de dados com informações do menu, 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 assim:

    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 agente for para um público-alvo externo de usuários, talvez seja necessário adicionar instruções para que o agente de responder ao usuário com informações sobre como criar esses 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."

    Também é útil fornecer um exemplo desse caso.

O parâmetro userMetadata fornece informações sobre o usuário final. Qualquer um pares de chave-valor podem ser preenchidos nesse parâmetro. Esses metadados são transmitidos na ferramenta de repositório de dados para informar melhor os resultados de pesquisa e a ferramenta resposta. Recomendamos que você forneça vários exemplos para instruir LLM de agente sobre como preencher esse parâmetro.

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

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

O parâmetro fallback fornece uma resposta que a ferramenta de repositório de dados deve responder. caso não haja uma resposta resumida válida para a consulta. Vários exemplos podem ser fornecido para instruir o LLM do agente sobre como preencher o substituto para informações relacionadas a diferentes tópicos. Também não haverá na saída da ferramenta. Essa otimização pode ser usada para reduzir a latência e o limite de uso dos 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, o as seguintes personalizações estão disponíveis na página "Ferramenta" para uma ferramenta de repositório de dados:

Confiança do embasamento

Para cada resposta gerada com base no conteúdo dos seus repositórios de dados conectados, o agente avalia um nível de confiança, que mede a confiança de que todos as informações na resposta são compatíveis com as informações nos repositórios de dados. Você pode personalizar quais respostas permitir selecionando as respostas com o qual você se sente confortável. Apenas respostas iguais ou superiores a esse valor nível de confiança será mostrado.

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 agente de repositório de dados para o solicitação generativa de resumo. Se nenhum for selecionado, um modelo padrão é 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 compatíveis.
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 do LLM de resumo.

O comando é um modelo de texto que pode conter marcadores de posição predefinidos. Os espaços reservados serão substituídos pelos valores apropriados no tempo de 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 agente usa um módulo de reescrita para reescrever a consulta original do usuário em um formato mais preciso.

  • $sources: o agente usa o Enterprise Search para procurar origens 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 first 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

Um comando personalizado instrui o LLM a retornar "NOT_ENOUGH_INFORMATION" quando não consegue fornecer uma resposta. O agente transformará essa constante em uma mensagem fácil de usar para o usuário.

Configurações de payload

As configurações de payload fornecem uma maneira de adicionar os snippets de repositório de dados como conteúdo avançado no o payload de resposta, que é renderizado no messenger.

Frases banidas (configuração no nível do agente)

Você tem a opção de definir frases específicas que não devem ser permitidas. Eles são configurados no nível do agente e usados por ambos LLMs e ferramentas de repositório de dados. Se a resposta gerada ou partes do LLM comando, como as entradas do usuário, contém uma das frases banidas 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 podem ser acessados por ferramentas OpenAPI, use ferramentas de função. As ferramentas de função são sempre executadas no lado do cliente, e não pelo app dele.

O processo é o seguinte:

  1. Seu código de cliente envia uma solicitação de detecção de intent.
  2. O app do agente detecta que uma ferramenta de função é necessária. e a resposta da intent de detecção contém o nome da ferramenta junto a argumentos de entrada. Esta sessão fica pausada até que outra solicitação de detecção de intent seja recebida com o resultado da ferramenta.
  3. Seu código de cliente chama a ferramenta.
  4. Seu código de 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

Como ferramentas de funções, OpenAPI e ferramentas de repositório de dados pode ser executado 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. Seu código de cliente envia uma solicitação de detecção de intent que especifica a execução do cliente.
  2. O app do agente detecta que uma ferramenta é necessária. e a resposta da intent de detecção contém o nome da ferramenta junto a argumentos de entrada. Esta sessão fica pausada até que outra solicitação de detecção de intent seja recebida com o resultado da ferramenta.
  3. Seu código de cliente chama a ferramenta.
  4. Seu código de cliente envia outra solicitação de detecção de intent que fornece o resultado da ferramenta como argumentos de saída.
Anterior
Interface do usuário
Próxima
Práticas recomendadas