Ferramentas do playbook

Usando ferramentas, é possível conectar playbooks a sistemas externos. Esses sistemas podem aumentar o conhecimento e capacitar playbooks a realizar tarefas complexas com eficiência.

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

Teste de ferramentas

Depois de criar uma ferramenta, use o recurso de teste para verificar se ela funciona. Ao visualizar uma ferramenta, clique no botão Testar acima do painel. Isso abre a ferramenta para entrada no simulador. Forneça a entrada da ferramenta e clique em Ver saída para verificar se a saída está correta.

Também é possível usar o recurso de teste de ferramentas ao adicionar uma ferramenta a um exemplo.

Ferramentas integradas

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

As ferramentas integradas com suporte 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.

O agente é otimizado para determinar como e quando essas ferramentas devem ser invocadas, mas é possível fornecer outros exemplos para atender 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 OpenAPI ao fornecer o OpenAPI. Por padrão, o agente vai chamar a API em seu nome.

É possível testar se a ferramenta está configurada corretamente usando o recurso "Testar ferramenta" disponível na página da ferramenta. Esse recurso também está disponível na visualização de exemplo ao adicionar uma invocação de ferramenta ao exemplo.

Como alternativa, é possível executar ferramentas OpenAPI no lado do cliente.

Esquema de exemplo:

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, é 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 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âmetros aceitos são path, query e header. O tipo de parâmetro cookie ainda não é aceito.
  • Os parâmetros definidos pelo esquema OpenAPI aceitam os seguintes tipos de dados: string, number, integer, boolean, array. O tipo object ainda não é aceito.
  • 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.

Geração de esquema de ferramenta OpenAPI

Ao fornecer um esquema, é possível usar o botão Usar o Gemini para usar a IA generativa e criar o esquema. É possível fornecer o seguinte para orientar a geração:

  • Um URL da solicitação
  • Um método HTTP (GET, POST etc.)
  • Exemplo de entrada
  • Exemplo de saída
  • Um comando de texto que descreve a ferramenta

Depois que isso for gerado, edite conforme necessário e adicione outros URLs e métodos manualmente.

Autenticação de API de ferramenta OpenAPI

As seguintes opções de autenticação são aceitas ao chamar uma API externa:

Autenticação do agente de serviço do Dialogflow

O Dialogflow pode gerar um token de ID 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 as funções do Cloud Run e os 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ária outra permissão do IAM para chamá-los.

Autenticação da conta de serviço

As contas de serviço podem ser usadas para autenticar solicitações de ferramentas em qualquer API do Google que ofereça suporte a elas.

Crie uma conta de serviço se ainda não tiver feito isso, create a service account.

Como as contas de serviço são principais, elas podem acessar recursos no seu projeto ao conceder a ela um papel, assim como você faria para qualquer outro principal. O e-mail da conta de serviço será usado para gerar um token de acesso que será enviado no cabeçalho Authorization da solicitação da ferramenta.

O usuário que está configurando a ferramenta para usar contas de serviço precisa ter as seguintes permissões:

  • roles/iam.serviceAccountUser

Para que o Dialogflow CX gere tokens, o agente de serviço do Dialogflow precisa ter as seguintes permissões:

  • roles/iam.serviceAccountTokenCreator

A conta de serviço também precisa ter permissões para acessar o serviço que está hospedando a ferramenta.

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.
  • Recomendamos que você forneça sua chave de API usando o Secret Manager. Após 15 de agosto de 2025, os agentes exportados não vão mais conter chaves de API de valor bruto.

OAuth

  • O fluxo de credenciais do cliente OAuth é aceito para autenticação de servidor para servidor:

    • Esse fluxo pode ser usado se o console do Vertex AI Agent Builder for o proprietário do recurso e nenhuma autorização do usuário final for necessária.
    • O ID do cliente, a chave secreta do cliente e o endpoint do token do provedor OAuth precisam ser configurados no Dialogflow.
      • Recomendamos que você forneça a chave secreta do cliente usando o Secret Manager. Após 15 de agosto de 2025, os agentes exportados não vão mais conter chaves secretas do cliente de valor bruto.
    • O Dialogflow troca um token de acesso OAuth 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 do código de autorização e o fluxo PKCE:

    1. Você precisará implementar sua própria interface de login e receber o token de acesso no lado do cliente.

    2. É possível:

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

      b. Use a ferramenta de função 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 do portador para transmitir dinamicamente o token do portador do cliente. Esse token está incluído no cabeçalho de autenticação 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 de sessão:

    DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

  • Se você precisar configurar um token estático em vez de buscar o token de um parâmetro de sessão, recomendamos que forneça o token usando Secret Manager. Após 15 de agosto de 2025, os agentes exportados não vão mais conter tokens do portador de valor bruto.

Autenticação TLS mútua

  • Consulte a documentação de 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 de cliente será usado durante o TLS mútuo para todas as ferramentas e webhooks.

Certificado de CA personalizado

Autenticação do Secret Manager

Se você usar OAuth, chave de API ou token do portador, poderá armazenar as credenciais como secrets usando Secret Manager. Confira as etapas necessárias para autenticar sua ferramenta usando secrets:

  1. Crie seu secret se ainda não tiver um.
  2. Conceda ao agente de serviço do Dialogflow o papel Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no novo secret.
  3. Copie sua credencial para a área de transferência.
  4. Adicione uma nova versão do secret ao seu secret. Cole sua credencial como o valor do secret.
    • Omita qualquer caractere de nova linha no final.
  5. Copie o nome da versão do secret que você acabou de adicionar. O formato do nome é projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
  6. Abra a tela de edição da ferramenta e faça o seguinte:
    • Se você usar o OAuth, selecione OAuth como o Tipo de autenticação e clique em Versão do secret em Chave secreta do cliente e cole o nome da versão do secret na caixa de entrada Versão do secret.
    • Se você usar a chave de API, selecione Chave de API como o Tipo de autenticação, então clique em Versão do secret em Chave de API. Cole o nome da versão do secret na caixa de entrada Versão do secret.
    • Se você usar o token do portador, selecione Token do portador como o Tipo de autenticação, clique em Versão do secret em Token do portador. Cole o nome da versão do secret na caixa de entrada Versão do secret.
  7. Clique em Salvar.

Acesso à rede particular da ferramenta OpenAPI

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

Para configurar uma ferramenta OpenAPI que segmenta uma rede particular:

  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 service account 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 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 Open API 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 uma entrada de parâmetro de consulta junto 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ó serão usados se não houver um valor de entrada gerado pelo LLM ou um valor de entrada baseado em 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 de parâmetro de sessão ou valor padrão estiver presente, a entrada não será especificada.

Ferramentas de repositório de dados

Para informações sobre como usar ferramentas de repositório de dados com um playbook, consulte a documentação de ferramentas de repositório de dados.

Ferramentas de conector

As ferramentas de conexão podem ser usadas por um agente para realizar ações usando suas conexões configuradas nos Integration Connectors. Cada ferramenta de conector é configurada com uma única conexão e uma ou mais ações. Se necessário, é possível criar várias ferramentas para uma única conexão para agrupar diferentes ações para o agente usar.

A ferramenta de conector oferece suporte aos seguintes tipos de conector:

Os exemplos precisam ser usados para melhorar o uso de ferramentas de conector pelo agente, demonstrando como o agente deve chamar a ferramenta e usar a resposta.

Crie uma conexão

Para criar uma conexão e conectá-la ao agente, acesse Ferramentas > Criar, selecione o tipo de ferramenta Conector, o tipo de conector escolhido e use o botão Criar conexão. Isso vai direcionar você para a criação de Integration Connectors com vários campos pré-preenchidos.

Como alternativa, acesse o Integration Connectors e siga as instruções para criar uma conexão.

Ações do conector

Para cada ferramenta de conector, há dois tipos de ações que podem ser disponibilizadas para o agente (consulte Entidades, operações e ações para mais informações):

  1. Operações CRUD de entidades

    Cada uma das suas conexões tem "entidades" correspondentes aos objetos dessa fonte de dados (para o BigQuery, são tabelas; para o Salesforce, são objetos, como 'Pedido' ou 'Caso').

    É possível executar operações CRUD em cada entidade:

    • Criar: cria uma entidade com os valores de campo especificados
    • Listar: pesquisa baseada em filtros de instâncias de entidades
    • Atualizar: método baseado em filtro para alterar valores de campos de entidades
    • Excluir: exclui uma entidade
    • Receber : recupera uma única entidade usando o ID da entidade

    Saiba mais sobre os detalhes das operações CRUD de entidades na documentação dos conectores.

  2. Ações específicas do conector

    Muitos conectores oferecem suporte a uma 'ExecuteCustomQuery' ação, que permite executar uma consulta SQL na fonte de dados, em que cada uma das entidades da fonte de dados pode ser referenciada como tabelas. Consulte esta lista de conectores aceitos.

    Outras ações variam de acordo com o tipo de conector. Por exemplo, consulte as ações do conector do BigQuery ou as ações do conector do Salesforce.

Como configurar campos de entrada / saída para operações CRUD

Ao selecionar campos de entrada ou saída específicos para a ação da ferramenta de conector usar, é possível limitar a complexidade dessas ações para o agente.

Por exemplo, se você só precisar criar uma entidade com um subconjunto de campos, a configuração desse conjunto de campos na ação simplifica a ação para o agente.

A especificação de um conjunto de campos de saída reduz o tamanho da resposta da ferramenta (útil se os limites de token forem uma preocupação) e simplifica o processamento da saída pelo agente, expondo apenas os campos relevantes.

Autenticação

Se a conexão que você está usando estiver configurada para permitir a substituição da autenticação, a ferramenta poderá ser configurada para transmitir credenciais de parâmetros de sessão especificados.

Como criador do agente, você é responsável por como essas credenciais são preenchidas nos parâmetros de sessão, e a ferramenta as transmitirá automaticamente para a fonte de dados para uso na autenticação quando as ações da ferramenta forem chamadas.

Ferramentas de função

Se você tiver uma funcionalidade acessível pelo código do cliente, mas não pelas ferramentas OpenAPI, poderá usar 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 para detectar a intent.
  2. O agente detecta que uma ferramenta de função é necessária, e a resposta para detectar a intent contém o nome da ferramenta e os argumentos de entrada. Essa sessão é pausada até que outra solicitação para detectar a 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 para detectar a 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 para detectar a intent 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 para detectar a 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 para detectar a intent que especifica a execução do cliente.
  2. O agente detecta que uma ferramenta é necessária, e a resposta para detectar a intent contém o nome da ferramenta e os argumentos de entrada. Essa sessão é pausada até que outra solicitação para detectar a 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 para detectar a intent que fornece o resultado da ferramenta como argumentos de saída.
Anterior
Parâmetros do playbook
Avançar
Configurações do playbook