Alguns produtos e funcionalidades estão em processo de mudança de nome. As funcionalidades de fluxo e manual generativos também estão a ser migradas para uma única consola consolidada. Veja os detalhes.

Esta página foi traduzida pela API Cloud Translation.

Ferramentas de guias interativos

Com as ferramentas, pode associar manuais de procedimentos a sistemas externos. Estes sistemas podem aumentar o conhecimento dos manuais de procedimentos e permitir-lhes executar tarefas complexas de forma eficiente.

Pode usar ferramentas incorporadas ou criar ferramentas personalizadas de acordo com os seus requisitos.

Testes de ferramentas

Depois de criar uma ferramenta, pode usar a funcionalidade de teste de ferramentas para verificar se funciona. Quando estiver a ver uma ferramenta, clique no botão Testar acima do painel de ferramentas. Esta ação abre a ferramenta de introdução no simulador. Introduza informações na ferramenta e, em seguida, clique em Ver resultado para verificar o resultado correto da ferramenta.

Também pode usar a funcionalidade de teste de ferramentas quando adiciona uma ferramenta a um exemplo.

Ferramentas integradas

As ferramentas integradas são alojadas pela Google. Pode ativar estas ferramentas em agentes sem necessidade de configuração manual.

As ferramentas integradas suportadas são:

Code Interpreter: uma ferramenta original da Google que combina a capacidade de geração e execução de código e permite ao utilizador realizar 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 seu agente está otimizado para determinar como e quando estas ferramentas devem ser invocadas, mas pode fornecer exemplos adicionais para se adequarem aos seus exemplos de utilização.

Os exemplos devem ter um esquema semelhante ao seguinte:

{
  "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 estabelecer ligação a uma API externa através de uma ferramenta OpenAPI fornecendo o esquema OpenAPI. Por predefinição, o agente chama a API em seu nome.

Pode testar se a ferramenta está configurada corretamente através da funcionalidade de ferramenta de teste disponível na página da ferramenta. Esta funcionalidade também está disponível na vista de exemplo quando adiciona uma invocação de ferramenta ao exemplo.

Em alternativa, pode 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

Opcionalmente, pode usar a referência do esquema interno @dialogflow/sessionId como tipo de esquema de parâmetros. Com este tipo de esquema de parâmetros, o ID da sessão do Dialogflow para a conversa atual é fornecido como um valor de parâmetro. Por exemplo:

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

Limitações das ferramentas da OpenAPI

Aplicam-se as seguintes limitações:

Os tipos de parâmetros suportados são path, query e header. O tipo de parâmetro cookie ainda não é suportado.
Os parâmetros definidos pelo esquema OpenAPI suportam os seguintes tipos de dados: string, number, integer, boolean e array. O tipo object ainda não é suportado.
Atualmente, não pode especificar parâmetros de consulta no editor de exemplos da consola.
O corpo do pedido e da resposta tem de estar vazio ou ser JSON.

Geração de esquemas de ferramentas OpenAPI

Quando fornece um esquema, pode usar o botão Usar o Gemini para usar a IA generativa para criar o seu esquema. Pode fornecer o seguinte para orientar a geração:

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

Depois de gerado, pode editá-lo conforme necessário e adicionar manualmente URLs e métodos adicionais.

Autenticação da API da ferramenta OpenAPI

As seguintes opções de autenticação são suportadas quando chama uma API externa:

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

O Dialogflow pode gerar um token de ID através do agente de serviço do Dialogflow. O token é adicionado no cabeçalho HTTP de autorização quando o Dialogflow chama uma API externa.

Pode usar um token de ID para aceder a funções do Cloud Run e serviços do Cloud Run depois de conceder as funções roles/cloudfunctions.invoker e roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Se as funções do Cloud Run e os serviços do Cloud Run estiverem no mesmo projeto de recursos, não precisa de autorização do IAM adicional para os chamar.

Autenticação da conta de serviço

As contas de serviço podem ser usadas para autenticar pedidos de ferramentas em quaisquer APIs Google que o suportem.

Se ainda não o tiver feito, crie uma conta de serviço.

Uma vez que as contas de serviço são principais, podem aceder a recursos no seu projeto concedendo-lhe uma função, tal como faria para qualquer outro principal. O email da conta de serviço é usado para gerar um token de acesso, que é enviado no cabeçalho Authorization do pedido da ferramenta.

O utilizador que está a configurar a ferramenta para usar contas de serviço tem de ter as seguintes autorizações:

roles/iam.serviceAccountUser

Para que os agentes conversacionais (Dialogflow CX) gerem tokens, o agente do serviço Dialogflow tem de ter as seguintes autorizações:

roles/iam.serviceAccountTokenCreator

A conta de serviço também tem de ter autorizações para aceder ao serviço que está a alojar a ferramenta.

Chave da API

Pode configurar a autenticação da chave da API indicando o nome da chave, a localização do pedido (cabeçalho ou string de consulta) e a chave da API para que o Dialogflow transmita a chave da API no pedido.
Recomendamos que forneça a chave da API através do Secret Manager. Após 15 de agosto de 2025, os agentes exportados vão deixar de conter chaves da API de valor bruto.

OAuth

O fluxo de credenciais do cliente OAuth é suportado para autenticação de servidor a servidor:
- Este fluxo pode ser usado se a consola do Vertex AI Agent Builder for o proprietário do recurso e não for necessária autorização do utilizador final.
- O ID de cliente, o segredo do cliente e o ponto final do token do fornecedor OAuth têm de ser configurados no Dialogflow.
  - Recomendamos que forneça o segredo do cliente através do Secret Manager. Após 15 de agosto de 2025, os agentes exportados vão deixar de conter segredos de clientes de valores não processados.
- O Dialogflow troca uma chave de acesso OAuth do fornecedor OAuth e transmite-a no cabeçalho de autorização do pedido.
Para outros fluxos OAuth que requerem autorização do utilizador final, como o fluxo de código de autorização e o fluxo PKCE:
1. Tem de implementar a sua própria IU de início de sessão e obter o token de acesso no lado do cliente.
2. Depois, pode:
  
  a. Use a opção de autenticação de token de portador para transmitir o token à ferramenta OpenAPI. O Dialogflow inclui este token no cabeçalho de autorização quando invoca a ferramenta.
  
  b. Use a ferramenta de funções para invocar a ferramenta no lado do cliente e transmitir o resultado da chamada da ferramenta para o Dialogflow.

Símbolo do portador

Pode configurar a autenticação Bearer para transmitir dinamicamente o token Bearer do cliente. Este token está incluído no cabeçalho de autorização do pedido.
Quando configurar a autenticação de ferramentas, pode 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.

Em tempo de execução, atribua o token Bearer ao parâmetro de sessão:

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

Se precisar de configurar um token estático em vez de obter o token de um parâmetro de sessão, recomendamos que forneça o token através do Secret Manager. Após 15 de agosto de 2025, os agentes exportados vão deixar de conter tokens de portador de valor não processado.

Autenticação TLS mútua

Consulte a documentação sobre a autenticação TLS mútua.
Os certificados de cliente personalizados são suportados. Pode configurar certificados de cliente ao nível do agente no separador Segurança nas definições do agente. O certificado (formato PEM) e a chave privada (formato PEM) são campos obrigatórios. Uma vez definido, este certificado de cliente é usado durante o TLS mútuo para todas as ferramentas e webhooks.

Certificado da AC personalizado

Consulte a documentação sobre certificados da AC personalizados.

Autenticação do Secret Manager

Se usar OAuth, chave de API ou token de portador, pode armazenar as credenciais como segredos através do Secret Manager. Seguem-se os passos necessários para autenticar a sua ferramenta através de segredos:

Crie o seu segredo se ainda não tiver um.
Conceda ao agente do serviço Dialogflow a função Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) no novo segredo.
Copie a credencial para a área de transferência.
Adicione uma nova versão do segredo ao seu segredo. Cole a credencial como o valor secreto.
- Omita qualquer caráter de nova linha no final.
Copie o nome da versão do Secret que acabou de adicionar. O formato do nome é projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Abra o ecrã de edição da ferramenta e, de seguida:
- Se usar o OAuth, selecione OAuth como o Tipo de autenticação e, de seguida, clique em Versão do segredo em Segredo do cliente e cole o nome da versão do segredo na caixa de entrada Versão do segredo.
- Se usar a chave da API, selecione Chave da API como o Tipo de autenticação e, de seguida, clique em Versão secreta em Chave da API. Cole o nome da versão do Secret na caixa de entrada Versão do Secret.
- Se usar o token de portador, selecione Token de portador como o Tipo de autenticação e, de seguida, clique em Versão secreta em Token de portador. Cole o nome da versão do Secret na caixa de entrada Versão do Secret.
Clique em Guardar.

Acesso à rede privada da ferramenta OpenAPI

A ferramenta OpenAPI integra-se com o acesso à rede privada do Service Directory, para que possa estabelecer ligação a destinos de API na sua rede VPC. Isto mantém o tráfego na rede do Google Cloud e aplica o IAM e os VPC Service Controls.

Para configurar uma ferramenta OpenAPI que segmente uma rede privada:

Siga a configuração da rede privada do Service Directory para configurar a sua rede VPC e o ponto final do Service Directory.
A conta de serviço do agente de serviço do Dialogflow com o seguinte endereço tem de existir para o projeto do seu agente:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Conceda à conta de serviço do agente de serviço do Dialogflow as seguintes funções do IAM:
- servicedirectory.viewer do projeto de diretório de serviços
- servicedirectory.pscAuthorizedService do projeto de rede
Forneça o serviço de diretório de serviços juntamente com o esquema OpenAPI e as informações de autenticação opcionais quando 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 utilizadores com o MDG através do esquema como guia. Em algumas situações, as entradas podem ter de ser derivadas de parâmetros de sessão recolhidos durante um fluxo ou fornecidas como uma entrada de parâmetro de consulta juntamente com a entrada do utilizador.

O parâmetro de sessão que tem de ser transmitido como 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 não estiver disponível nenhum parâmetro de sessão, a entrada gerada pelo MDG é transmitida à ferramenta.

Valores predefinidos da ferramenta OpenAPI

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

Os valores predefinidos podem ser especificados como parte do esquema da seguinte forma:

     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 não estiver presente nenhum valor gerado pelo MDG, valor do parâmetro de sessão ou valor predefinido, a entrada não é especificada.

Ferramentas de armazenamento de dados

Para ver informações sobre a utilização de ferramentas de armazenamento de dados com um manual de estratégias, consulte a documentação das ferramentas de armazenamento de dados.

Ferramentas de conetores

As ferramentas de conector podem ser usadas por um agente para realizar ações através das associações configuradas em Conetores de integração. Cada ferramenta de conector é configurada com uma única associação e uma ou mais ações. Se necessário, é possível criar várias ferramentas para uma única associação de modo a agrupar diferentes ações para o seu agente usar.

A ferramenta de conetores suporta os seguintes tipos de conetores:

Os exemplos devem ser usados para melhorar a utilização das ferramentas de conector pelo agente, mostrando como o agente deve chamar a ferramenta e usar a resposta.

Crie uma associação

Para criar uma associação e associá-la ao seu agente, pode navegar para Ferramentas > Criar, selecionar o tipo de ferramenta Conetor, o tipo de conetor escolhido e usar o botão Criar associação. Esta ação navega para a criação de conectores de integração com vários campos pré-preenchidos.

Em alternativa, pode navegar para Conectores de integração e seguir as instruções para criar uma associação.

Ações do conetor

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

Operações CRUD de entidades

Cada uma das suas associações tem "entidades" correspondentes aos objetos dessa origem de dados (para o BigQuery, são tabelas; para o Salesforce, são objetos, como "Encomenda" ou "Registo").

Pode realizar operações CRUD em cada entidade:
- Create: cria uma entidade com valores de campos especificados
- Lista: pesquisa baseada em filtros de instâncias de entidades
- Atualização: método baseado em filtros para alterar os valores dos campos das entidades
- Delete: elimina uma entidade
- Get obtém uma única entidade através do entityId
Nota: a operação Get só pode ser usada para obter um único registo de uma entidade que tenha uma chave principal. Muitas vezes, é mais prático usar a operação List com uma filterClause para obter uma entidade.

Saiba mais acerca dos detalhes das operações CRUD de entidades na documentação dos conetores.
Ações específicas do conetor

Muitos conetores suportam uma ação "ExecuteCustomQuery", que permite executar uma consulta SQL na origem de dados, onde cada uma das entidades da origem de dados pode ser referenciada como tabelas. Consulte esta lista para ver os conetores suportados.

As ações adicionais variam consoante o tipo de conetor. Por exemplo, consulte as ações do conetor do BigQuery ou as ações do conetor do Salesforce.

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 do conetor a usar, pode limitar a complexidade destas ações para o agente.

Por exemplo, se só precisar de criar uma entidade com um subconjunto dos respetivos campos, a configuração deste 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 tokens forem uma preocupação) e simplifica o processamento da saída por parte do agente, expondo apenas os campos relevantes.

Autenticação

Se a ligação que está a usar estiver configurada para permitir a substituição da autenticação, pode configurar a ferramenta para transmitir credenciais de parâmetros de sessão especificados.

Enquanto criador do agente, é responsável pela forma como estas credenciais são preenchidas nos parâmetros da sessão, e a ferramenta transmite-as automaticamente à origem de dados para utilização na autenticação quando as ações da ferramenta são chamadas.

Ferramentas de funções

Se tiver funcionalidades acessíveis pelo seu código de cliente, mas não acessíveis pelas ferramentas da OpenAPI, pode usar ferramentas de funções. As ferramentas de funções são sempre executadas do lado do cliente e não pelo agente.

O processo é o seguinte:

O seu código de cliente envia um pedido de intenção de deteção.
O agente deteta que é necessária uma ferramenta de função e a resposta de intenção de deteção contém o nome da ferramenta, juntamente com argumentos de entrada. Esta sessão está pausada até ser recebido outro pedido de intenção de deteção com o resultado da ferramenta.
O seu código de cliente chama a ferramenta.
O código do cliente envia outro pedido de intenção de deteção que fornece o resultado da ferramenta como argumentos de saída.

O exemplo seguinte 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 seguinte mostra o pedido e a resposta iniciais de deteção de intenção com 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 seguinte mostra o segundo pedido detect 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 por parte do cliente

Tal como as ferramentas de funções, as ferramentas de OpenAPI e de armazenamento de dados podem ser executadas no lado do cliente aplicando uma substituição de API quando interage com a sessão.

Por exemplo:

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