Ferramentas

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

É possível usar ferramentas integradas ou criar ferramentas personalizadas para atender aos seus requisitos.

Ferramentas integradas

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

As ferramentas integradas com suporte são:

  • Code Interpreter: uma ferramenta própria do Google que combina os recursos de geração e execução de código e permite que o usuário realize várias tarefas, como análise e visualização de dados, processamento de texto, soluçã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 mais exemplos de acordo com seus casos de uso.

Os exemplos precisam ter o seguinte esquema:

{
  "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 personalizadas

As seções a seguir descrevem as ferramentas personalizadas.

Ferramentas OpenAPI

Um agente generativo pode se conectar a uma API externa usando uma ferramenta OpenAPI fornecendo o esquema OpenAPI. Por padrão, o agente generativo vai chamar a API em seu nome. Como alternativa, execute as 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

Opcionalmente, use a referência de esquema interna @dialogflow/sessionId como o 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 é 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 da 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 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 opções de autenticação a seguir são compatíveis 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 o Agente de serviço do Dialogflow (em inglês). O token é 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 a 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 recursos, você não precisará de outra permissão do IAM para chamá-los.
    • É possível usar um token de acesso para acessar outras APIs do Google Cloud depois de conceder os papéis necessários a 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 da chave, o local da solicitação (cabeçalho ou string de consulta) e a chave de API para que o Dialogflow a transmita na solicitação.
  • OAuth
    • O fluxo de credenciais do cliente OAuth é compatível com a autenticação de servidor para servidor. 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 OAuth e o transmite no cabeçalho Auth da solicitação.
    • Para outros fluxos do OAuth, é necessário usar a ferramenta de funções para fazer a integração com sua própria UI de login e trocar o token.
  • Autenticação TLS mútua
  • Certificado de CA personalizado

Ferramentas de repositório de dados

As ferramentas de repositório de dados podem ser usadas por um agente generativo para respostas a perguntas do usuário final nos seus armazenamentos de dados. É possível configurar um repositório de dados de cada tipo por ferramenta, e a ferramenta consultará cada um desses armazenamentos para encontrar respostas. Por padrão, o agente generativo vai chamar a ferramenta de repositório de dados em seu nome. Outra opção é 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 com 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 que foi usada para gerar a resposta. O agente generativo pode fornecer mais instruções sobre como proceder com a resposta dos armazenamentos de dados ou como responder quando não houver resposta. É possível usar exemplos para melhorar ainda mais o comportamento do agente generativo. 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"
            }
          ]
        }
      }
    ]
  }
}

Ferramentas de funções

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

O processo é o seguinte:

  1. O código do cliente envia uma solicitação de detecção de intent.
  2. O agente generativo detecta que uma ferramenta de função é necessária, e a resposta de detecção de intent contém o nome da ferramenta com 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. Seu código de 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 abaixo mostra o esquema de entrada e saída de uma ferramenta de funções:

{
  "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 de intent de detecção inicial 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 da OpenAPI e do 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 generativo detecta que uma ferramenta é necessária, e a resposta de detecção de intent contém o nome da ferramenta e 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. Seu código de 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.