Alguns produtos e recursos estão sendo renomeados. Os recursos de playbook generativo e fluxo também estão sendo migrados para um único console consolidado.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Ferramentas do playbook

Com as ferramentas, é possível conectar playbooks a sistemas externos. Esses sistemas podem melhorar o conhecimento de playbooks, permitindo que realizem tarefas complexas com eficiência.

É possível usar ferramentas integradas ou criar ferramentas personalizadas para atender às suas necessidades.

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 da ferramenta. 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 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 realizar várias tarefas, incluindo análise de dados, visualização de dados, processamento de texto e resolução de equações ou problemas de otimização.

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

Exemplo de 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 da OpenAPI

Um agente pode se conectar a uma API externa usando uma ferramenta OpenAPI ao fornecer o esquema OpenAPI. Por padrão, o agente vai chamar a API em seu nome.

Para verificar se a ferramenta está configurada corretamente, use o recurso de teste disponível na página dela. Esse recurso também está disponível na visualização de exemplo quando você adiciona uma invocação de ferramenta ao exemplo.

Como alternativa, é possível executar ferramentas 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

É possível usar a referência de esquema interno @dialogflow/sessionId como um tipo de esquema de parâmetro. Com esse tipo de esquema de parâmetro, o ID da sessão do Dialogflow CX 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âmetro aceitos são path, query e header. O tipo de parâmetro cookie 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 não é compatível.
Não é possível especificar parâmetros de consulta no editor de exemplos do console.
Os corpos de solicitação e resposta precisam estar vazios ou usar o formato application/json.

Geração de esquemas de ferramentas OpenAPI

Ao fornecer um esquema, clique em Usar o Gemini para criar seu esquema usando IA generativa.

Forneça os seguintes detalhes para orientar a geração:

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

Depois de gerar o esquema, você pode editá-lo conforme necessário e adicionar outros URLs e métodos manualmente.

Autenticação da API da ferramenta OpenAPI

É possível usar as seguintes opções de autenticação ao chamar uma API externa.

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

O Dialogflow CX pode gerar um token de ID usando o Agente de serviço do Dialogflow CX. O token é adicionado ao cabeçalho HTTP de autorização quando o Dialogflow CX chama uma API externa.

É possível usar um token de ID 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..

Se as funções do Cloud Run e os serviços do Cloud Run estiverem no mesmo projeto de recurso, não será necessária uma permissão adicional do Identity and Access Management (IAM) para chamá-los.

Autenticação da conta de serviço

As contas de serviço podem autenticar solicitações de ferramentas para qualquer API do Google que seja compatível.

Crie uma conta de serviço, caso ainda não tenha feito isso. Como as contas de serviço são principais, é possível conceder a elas papéis para acessar recursos no seu projeto, assim como você faria para qualquer outro principal. É possível usar o e-mail da conta de serviço para gerar um token de acesso que você envia no cabeçalho Authorization da solicitação da ferramenta.

Se você configurar a ferramenta para usar contas de serviço, precisará ter as seguintes permissões:

roles/iam.serviceAccountUser

Para permitir que o Dialogflow CX gere tokens, conceda ao agente de serviço do Dialogflow CX as seguintes permissões:

roles/iam.serviceAccountTokenCreator

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

Autenticação de chave de API

Para configurar a autenticação por chave de API, informe o nome da chave, o local da solicitação (cabeçalho ou string de consulta) e a chave de API para que o Dialogflow CX a transmita na solicitação.
Recomendamos fornecer 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 é compatível com a autenticação de servidor para servidor:

Use esse fluxo se o Generative AI App Builder for o proprietário do recurso e você não precisar da autorização do usuário final.
É preciso configurar o ID do cliente, a chave secreta do cliente e o endpoint do token de um provedor OAuth no Dialogflow CX.
Recomendamos fornecer a chave secreta do cliente usando o Secret Manager. Os agentes exportados não vão conter chaves secretas do cliente de valor bruto após 15 de agosto de 2025.
O Dialogflow CX troca um token de acesso OAuth de um provedor OAuth e o transmite no cabeçalho de autorização da solicitação.

Token do portador

É possível configurar a autenticação do portador para transmitir dinamicamente o token do portador do cliente. Esse token é incluído no cabeçalho de autorizaçã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 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 fornecer o token usando o Secret Manager. Após 15 de agosto de 2025, os agentes exportados não vão conter tokens do portador de valor bruto.

Autenticação TLS mútua

Para mais informações, consulte Autenticação TLS mútua.
Certificados do cliente personalizados são aceitos. É possível configurar certificados do 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

Para mais informações, consulte Certificados de CA personalizados.

Autenticação do Secret Manager

Se você usar o OAuth, a chave de API ou o token do portador, poderá armazenar as credenciais como secrets usando o Secret Manager.

Para autenticar sua ferramenta usando secrets, siga estas etapas:

Crie seu secret, caso ainda não tenha um.
Conceda ao agente de serviço do Dialogflow o papel de acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no novo secret.
Copie a credencial para a área de transferência.
Adicione uma nova versão do secret ao secret. Cole sua credencial como o valor do secret.
- Omita qualquer caractere de nova linha no final do valor do secret.
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}.
Abra a tela de edição da ferramenta e:
- Se você usar o OAuth, selecione OAuth como o Tipo de autenticação, 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 uma chave de API, selecione Chave de API como o Tipo de autenticação e 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 e 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.
Clique em Salvar.

Acesso à rede privada da ferramenta OpenAPI

A ferramenta OpenAPI se integra ao acesso à rede privada do Diretório de Serviços para se conectar aos destinos de API na sua 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:

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.
Verifique se a conta de serviço do agente de serviço do Dialogflow CX com o seguinte endereço existe para o projeto do agente:
```
service-agent-project-number@gcp-sa-dialogflow.
```
Conceda à conta de serviço do agente de serviço do Dialogflow CX os seguintes papéis do IAM:
- servicedirectory.viewer do projeto do diretório de serviços
- servicedirectory.pscAuthorizedService do projeto de rede
Forneça o serviço do Diretório de Serviços com o esquema OpenAPI e as informações de autenticação opcionais ao criar a ferramenta.

Acesso a parâmetros de sessão da ferramenta OpenAPI

As entradas da ferramenta OpenAPI são derivadas da conversa do usuário 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 com a entrada do usuário.

É possível especificar os parâmetros de sessão que precisam ser transmitidos como entrada usando o seguinte formato:

     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: Breed 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

É possível usar o esquema OpenAPI para especificar valores padrão. Esses valores padrão só se aplicam quando um valor de entrada gerado por LLM ou um valor de entrada baseado em parâmetro de sessão não está disponível para esse parâmetro ou propriedade.

É possível especificar valores padrão 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: Breed of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

Se não houver um valor gerado por LLM, um valor de parâmetro de sessão ou um valor padrão, a entrada não será especificada.

Ferramentas de repositório de dados

Para mais informações sobre como usar ferramentas de repositório de dados com um playbook, consulte as ferramentas de repositório de dados.

Ferramentas de conector

As ferramentas de conector permitem configurar um agente para realizar ações usando as conexões configuradas no Integration Connectors. Cada ferramenta de conector é configurada com uma única conexão e uma ou mais ações. É possível criar várias ferramentas para uma única conexão para agrupar diferentes ações para o agente usar.

A ferramenta de conector é compatível com os seguintes tipos de conector:

Você pode usar exemplos para ajudar os agentes a usar as ferramentas de conector de maneira eficaz, demonstrando como chamar as ferramentas e usar as respostas.

Crie uma conexão

Para criar uma conexão e conectá-la ao agente, acesse Ferramentas > Criar, selecione o tipo de ferramenta Conector e o tipo de conector escolhido e clique em Criar conexão. Isso abre a criação do Integration Connectors com vários campos preenchidos automaticamente.

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

Ações do conector

É possível disponibilizar dois tipos de ações para o agente em cada ferramenta de conector. Para mais informações, consulte Entidades, operações e ações.

Operações CRUD de entidade:

Cada conexão tem entidades correspondentes aos objetos dessa fonte de dados (para o BigQuery, são tabelas; para o Salesforce, são objetos, como Order ou Case).

É possível executar operações CRUD em cada entidade:
- Criar: valida e cria uma entidade com os valores de campo especificados.
- List: pesquisa baseada em filtros de instâncias de entidades.
- Atualização: método baseado em filtro para alterar valores de campos de entidades.
- Excluir: exclui uma entidade.
- Get: recupera uma única entidade usando o entityId.
Observação : a operação Get só pode ser usada para buscar um único registro de uma entidade que tenha uma chave primária. Geralmente, é mais prático usar a operação List com uma filterClause para recuperar uma entidade.

Para mais informações sobre as operações CRUD de entidade, consulte a documentação do Connectors.
Ações específicas do conector:

Muitos conectores são compatíveis com uma ação ExecuteCustomQuery, 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. Para mais informações, consulte a lista de conectores compatíveis.

As ações adicionais 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.

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, você pode limitar a complexidade dessas ações para o agente.

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

Especificar um conjunto de campos de saída reduz o tamanho da resposta da ferramenta para mitigar os limites de token. Isso permite que o agente processe a saída expondo apenas os campos relevantes.

Autenticação

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

Preencha essas credenciais nos parâmetros da sessão. A ferramenta as transmite automaticamente para a fonte de dados para autenticação ao chamar ações.

Ferramentas de função

Se você tiver recursos acessíveis pelo código do cliente, mas não pelas ferramentas OpenAPI, poderá usar as ferramentas de função. O lado do cliente sempre executa ferramentas de função, não o agente.

O processo é o seguinte:

O código do cliente envia uma solicitação de detecção de intent.
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.
O código do cliente chama a ferramenta.
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 demonstra 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 de detecção de intent 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

É possível executar ferramentas de OpenAPI e de repositório de dados no lado do cliente, assim como as ferramentas de função, aplicando uma substituição de API ao interagir com a sessão.