Algunos productos y funciones están en proceso de cambiar de nombre. Las funciones de flujo y de la guía generativa también se migrarán a una sola consola consolidada. Consulta los detalles.

Se usó la API de Cloud Translation para traducir esta página.

Herramientas de la guía

Con las herramientas, puedes conectar las guías a sistemas externos. Estos sistemas pueden aumentar el conocimiento de las guías y permitirles ejecutar tareas complejas de manera eficiente.

Puedes usar herramientas integradas o crear herramientas personalizadas para satisfacer tus requisitos.

Pruebas de herramientas

Una vez que hayas creado una herramienta, puedes usar la función de prueba para verificar que funcione. Cuando veas una herramienta, haz clic en el botón Probar que se encuentra sobre el panel de herramientas. Se abrirá la herramienta para ingresar datos en el simulador. Proporciona la entrada de la herramienta y, luego, haz clic en Ver salida para verificar que la salida de la herramienta sea correcta.

También puedes usar la función de prueba de herramientas cuando agregues una herramienta a un ejemplo.

Herramientas integradas

Google aloja las herramientas integradas. Puedes activar estas herramientas en los agentes sin necesidad de configuración manual.

Las herramientas integradas compatibles son las siguientes:

Code Interpreter: Es una herramienta de origen de Google que combina la capacidad de generación y ejecución de código, y permite al usuario realizar diversas tareas, como análisis y visualización de datos, procesamiento de texto, resolución de ecuaciones o problemas de optimización.

Tu agente está optimizado para determinar cómo y cuándo se deben invocar estas herramientas, pero puedes proporcionar ejemplos adicionales para que se adapten a tus casos de uso.

Los ejemplos deben tener un esquema como el siguiente:

{
  "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"
        }
      }
    ]
  }
}

Herramientas de OpenAPI

Un agente puede conectarse a una API externa con una herramienta de OpenAPI si proporciona el esquema de OpenAPI. De forma predeterminada, el agente llamará a la API en tu nombre.

Puedes probar si la herramienta está configurada correctamente con la función Probar herramienta disponible en la página de la herramienta. Esta función también está disponible en la vista de ejemplo cuando agregas una invocación de herramienta al ejemplo.

Como alternativa, puedes ejecutar herramientas de OpenAPI en el cliente.

Esquema de ejemplo:

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

De manera opcional, puedes usar la referencia de esquema interno @dialogflow/sessionId como tipo de esquema de parámetro. Con este tipo de esquema de parámetros, el ID de sesión de Dialogflow para la conversación actual se proporcionará como un valor de parámetro. Por ejemplo:

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

Limitaciones de la herramienta de OpenAPI

Se aplica la siguiente limitación:

Los tipos de parámetros admitidos son path, query y header. Aún no se admite el tipo de parámetro cookie.
Los parámetros definidos por el esquema de OpenAPI admiten los siguientes tipos de datos: string, number, integer, boolean y array. Aún no se admite el tipo object.
Actualmente, no puedes especificar parámetros de consulta en el editor de ejemplos de la consola.
El cuerpo de la solicitud y la respuesta debe estar vacío o ser JSON.

Generación de esquemas de herramientas de OpenAPI

Cuando proporciones un esquema, puedes usar el botón Usar Gemini para usar la IA generativa y crear tu esquema. Puedes proporcionar lo siguiente para guiar la generación:

URL de una solicitud
Un método HTTP (GET, POST, etcétera)
Muestra de entrada
Ejemplo de resultado
Un mensaje de texto que describe la herramienta

Una vez que se genere, puedes editarlo según sea necesario y agregar manualmente URLs y métodos adicionales.

Autenticación de la API de la herramienta de OpenAPI

Se admiten las siguientes opciones de autenticación cuando se llama a una API externa:

Autorización del agente de servicio de Dialogflow

Dialogflow puede generar un token de ID con el agente de servicio de Dialogflow. El token se agrega en el encabezado HTTP de autorización cuando Dialogflow llama a una API externa.

Se puede usar un token de ID para acceder a las funciones y los servicios de Cloud Run después de otorgar los roles roles/cloudfunctions.invoker y roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Si las funciones y los servicios de Cloud Run se encuentran en el mismo proyecto de recursos, no necesitas permisos de IAM adicionales para llamarlos.

Autenticación de la cuenta de servicio

Las cuentas de servicio se pueden usar para autenticar solicitudes de herramientas en cualquier API de Google que las admita.

Si aún no lo hiciste, crea una cuenta de servicio.

Debido a que las cuentas de servicio son principales, pueden acceder a los recursos de tu proyecto si les otorgas un rol, al igual que lo harías con cualquier otra principal. La dirección de correo electrónico de la cuenta de servicio se usará para generar un token de acceso que se enviará en el encabezado Authorization de la solicitud de la herramienta.

El usuario que configura la herramienta para usar cuentas de servicio debe tener los siguientes permisos:

roles/iam.serviceAccountUser

Para que los agentes conversacionales (Dialogflow CX) generen tokens, el agente de servicio de Dialogflow debe tener los siguientes permisos:

roles/iam.serviceAccountTokenCreator

La cuenta de servicio también debe tener permisos para acceder al servicio que aloja la herramienta.

Clave de API

Puedes configurar la autenticación de la clave de API proporcionando el nombre de la clave, la ubicación de la solicitud (encabezado o cadena de consulta) y la clave de API para que Dialogflow pase la clave de API en la solicitud.
Te recomendamos que proporciones tu clave de API con Secret Manager. Después del 15 de agosto de 2025, los agentes exportados ya no contendrán claves de API de valores sin procesar.

OAuth

El flujo de credenciales de cliente de OAuth es compatible con la autenticación de servidor a servidor:
- Este flujo se puede usar si la consola de AI Applications es el propietario del recurso y no se necesita autorización del usuario final.
- El ID de cliente, el secreto del cliente y el extremo del token del proveedor de OAuth deben configurarse en Dialogflow.
  - Te recomendamos que proporciones tu secreto del cliente con Secret Manager. Después del 15 de agosto de 2025, los agentes exportados ya no contendrán secretos del cliente con valores sin procesar.
- Dialogflow intercambia un token de acceso de OAuth del proveedor de OAuth y lo pasa en el encabezado de autorización de la solicitud.
Para otros flujos de OAuth que requieren la autorización del usuario final, como el flujo de código de autorización y el flujo de PKCE, haz lo siguiente:
1. Deberás implementar tu propia IU de acceso y obtener el token de acceso en el cliente.
2. Luego, puedes realizar una de estas dos acciones:
  
  a. Usa la opción de autenticación de token del portador para pasar el token a la herramienta de OpenAPI. Dialogflow incluirá este token en el encabezado de autorización cuando invoque la herramienta.
  
  b. Usa la herramienta Function para invocarla por tu cuenta en el cliente y pasar el resultado de la llamada a la herramienta a Dialogflow.

Token del portador

Puedes configurar la autenticación de portador para pasar de forma dinámica el token de portador desde el cliente. Este token se incluye en el encabezado de autorización de la solicitud.
Cuando configures la autenticación de herramientas, puedes designar un parámetro de sesión para que actúe como token de portador. Por ejemplo, usa $session.params.<parameter-name-for-token> para especificar el token.

En el tiempo de ejecución, asigna el token de portador al parámetro de sesión:

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

Si necesitas configurar un token estático en lugar de recuperarlo de un parámetro de sesión, te recomendamos que proporciones tu token con Secret Manager. Después del 15 de agosto de 2025, los agentes exportados ya no contendrán tokens de portador de valor sin procesar.

Autenticación mutua de TLS

Consulta la documentación sobre la autenticación de TLS mutua.
Se admiten certificados de cliente personalizados. Puedes configurar certificados de cliente a nivel del agente en la pestaña Seguridad de la configuración del agente. El certificado (formato PEM) y la clave privada (formato PEM) son campos obligatorios. Una vez configurado, este certificado de cliente se usará durante la TLS mutua para todas las herramientas y webhooks.

Certificado de CA personalizado

Consulta la documentación sobre certificados de CA personalizados.

Autenticación de Secret Manager

Si usas OAuth, una clave de API o un token de portador, puedes almacenar las credenciales como secretos con Secret Manager. Estos son los pasos necesarios para autenticar tu herramienta con secretos:

Crea tu secreto si aún no tienes uno.
Otorga a Dialogflow Service Agent el rol de Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) en el secreto nuevo.
Copia tu credencial en el portapapeles.
Agrega una versión nueva del secreto a tu secreto. Pega tu credencial como el valor del secreto.
- Omite cualquier carácter de salto de línea al final.
Copia el nombre de la versión del secreto que acabas de agregar. El formato del nombre es projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Abre la pantalla de edición de la herramienta y, luego, haz lo siguiente:
- Si usas OAuth, selecciona OAuth como el Tipo de autenticación y, luego, haz clic en Versión del secreto en Secreto del cliente y pega el nombre de la versión del secreto en el cuadro de entrada Versión del secreto.
- Si usas una clave de API, selecciona Clave de API como el Tipo de autenticación y, luego, haz clic en Versión secreta en Clave de API. Pega el nombre de la versión del secreto en el cuadro de entrada Versión del secreto.
- Si usas un token de portador, selecciona Token de portador como el Tipo de autenticación y, luego, haz clic en Versión secreta en Token de portador. Pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
Haz clic en Guardar.

Acceso a redes privadas de la herramienta de OpenAPI

La herramienta de OpenAPI se integra con el acceso a la red privada del Directorio de servicios, por lo que puede conectarse a destinos de API dentro de tu red de VPC. Esto mantiene el tráfico dentro de la red de Google Cloud y aplica IAM y los Controles del servicio de VPC.

Para configurar una herramienta de OpenAPI que se oriente a una red privada, sigue estos pasos:

Sigue las instrucciones de Configuración de la red privada del Directorio de servicios para configurar tu red de VPC y el extremo del Directorio de servicios.
Debe existir la cuenta de servicio del Agente de servicio de Dialogflow con la siguiente dirección para tu proyecto de agente:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Otorga a la cuenta de servicio del agente de servicio de Dialogflow los siguientes roles de IAM:
- servicedirectory.viewer del proyecto del Directorio de servicios
- servicedirectory.pscAuthorizedService del proyecto de red
Cuando crees la herramienta, proporciona el servicio del Directorio de servicios junto con el esquema de OpenAPI y la información de autenticación opcional.

Acceso a parámetros de sesión de la herramienta de OpenAPI

Las entradas de la herramienta de la API abierta se derivan de la conversación de los usuarios con el LLM utilizando el esquema como guía. En algunas situaciones, es posible que las entradas deban derivarse de los parámetros de sesión recopilados durante un flujo o proporcionarse como una entrada de parámetro de consulta junto con la entrada del usuario.

El parámetro de sesión que se debe pasar como entrada se puede especificar de la siguiente manera:

     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.

Si no hay disponible ningún parámetro de sesión de ese tipo, la entrada generada por el LLM se pasará a la herramienta.

Valores predeterminados de la herramienta de OpenAPI

El esquema de la API abierta se puede usar para especificar valores predeterminados. Los valores predeterminados solo se usan si no hay un valor de entrada generado por el LLM o un valor de entrada basado en el parámetro de sesión para ese parámetro o propiedad.

Los valores predeterminados se pueden especificar como parte del esquema de la siguiente manera:

     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

Si no hay ningún valor generado por el LLM, ningún valor de parámetro de sesión ni ningún valor predeterminado, la entrada no se especificará.

Herramientas de almacén de datos

Para obtener información sobre el uso de herramientas de almacén de datos con un playbook, consulta la documentación sobre las herramientas de almacén de datos.

Herramientas de conectores

Un agente puede usar las herramientas de conector para realizar acciones con tus conexiones configuradas en Integration Connectors. Cada herramienta de conector se configura con una sola conexión y una o más acciones. Si es necesario, se pueden crear varias herramientas para una sola conexión para agrupar diferentes acciones que tu agente puede usar.

La herramienta de conector admite los siguientes tipos de conectores:

Los ejemplos se deben usar para mejorar el uso de las herramientas de conector por parte del agente, ya que demuestran cómo el agente debe llamar a la herramienta y usar la respuesta.

Crear una conexión

Para crear una conexión y conectarla a tu agente, puedes navegar a Herramientas > Crear, seleccionar el tipo de herramienta Conector, el tipo de conector que elegiste y usar el botón Crear conexión. Esto te llevará a la creación de Integration Connectors con varios campos completados previamente.

Como alternativa, puedes navegar a Integration Connectors y seguir las instrucciones para crear una conexión.

Acciones del conector

Para cada herramienta de conector, hay dos tipos de acciones que se pueden poner a disposición de tu agente (consulta Entidades, operaciones y acciones para obtener más información):

Operaciones CRUD de entidades

Cada una de tus conexiones tiene "entidades" que corresponden a los objetos de esa fuente de datos (para BigQuery, son tablas; para Salesforce, son objetos, como "Pedido" o "Caso").

Puedes realizar operaciones CRUD en cada entidad:
- Create: Crea una entidad con los valores de campo especificados.
- List: Búsqueda basada en filtros de instancias de entidades
- Update: Método basado en filtros para modificar los valores de los campos de la entidad
- Borrar: Borra una entidad
- Get recupera una sola entidad con entityId
Nota: La operación Get solo se puede usar para recuperar un solo registro de una entidad que tenga una clave primaria. A menudo, es más práctico usar la operación List con un filterClause para recuperar una entidad.

Obtén más información sobre los detalles de las operaciones CRUD de entidades en la documentación de Connectors.
Acciones específicas del conector

Muchos conectores admiten una acción "ExecuteCustomQuery", que permite ejecutar una consulta en SQL en la fuente de datos, en la que se puede hacer referencia a cada una de las entidades de la fuente de datos como tablas. Consulta esta lista para ver los conectores compatibles.

Las acciones adicionales varían según el tipo de conector. Por ejemplo, consulta las acciones del conector de BigQuery o las acciones del conector de Salesforce.

Cómo configurar campos de entrada y salida para operaciones de CRUD

Si seleccionas campos de entrada o salida específicos para que los use la acción de la herramienta del conector, puedes limitar la complejidad de estas acciones para el agente.

Por ejemplo, si solo necesitas crear una entidad con un subconjunto de sus campos, configurar este conjunto de campos en tu acción simplifica la acción para el agente.

Especificar un conjunto de campos de salida reduce el tamaño de la respuesta de la herramienta (lo que resulta útil si los límites de tokens son un problema) y simplifica el manejo de la salida por parte del agente, ya que solo expone los campos pertinentes.

Autenticación

Si la conexión que usas está configurada para permitir la anulación de la autenticación, la herramienta se puede configurar para pasar las credenciales de los parámetros de sesión especificados.

Como creador del agente, eres responsable de cómo se propagan estas credenciales a los parámetros de la sesión, y la herramienta las pasará automáticamente a la fuente de datos para que se usen en la autenticación cuando se llamen las acciones de la herramienta.

Herramientas de funciones

Si tienes funcionalidad a la que se puede acceder con tu código de cliente, pero no con las herramientas de OpenAPI, puedes usar herramientas de funciones. Las herramientas de funciones siempre se ejecutan del lado del cliente, no por el agente.

El proceso es el siguiente:

El código del cliente envía una solicitud de detección de intent.
El agente detecta que se requiere una herramienta de función, y la respuesta de detección de intent contiene el nombre de la herramienta junto con los argumentos de entrada. Esta sesión se detiene hasta que se recibe otra solicitud de detección de intent con el resultado de la herramienta.
Tu código de cliente llama a la herramienta.
Tu código de cliente envía otra solicitud de detección de intent que proporciona el resultado de la herramienta como argumentos de salida.

En el siguiente ejemplo, se muestran el esquema de entrada y el de salida de una herramienta de función:

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

En el siguiente ejemplo, se muestran la solicitud y la respuesta iniciales de detección de intención con 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"
          }
        }
      }
    ]
  }
}

En el siguiente ejemplo, se muestra la segunda solicitud de detección de intención, que proporciona el resultado de la herramienta:

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

Ejecución del cliente

Al igual que las herramientas de funciones, las herramientas de OpenAPI y de almacén de datos se pueden ejecutar del lado del cliente aplicando una anulación de la API cuando se interactúa con la sesión.

Por ejemplo:

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