Estamos cambiando el nombre de algunos productos y funciones. Las funciones de guía y flujo generativos también se están migrando a una única consola consolidada. Consulta los detalles.

Esta página se ha traducido con Cloud Translation API.

Herramientas de guía

Con las herramientas, puedes conectar guías a sistemas externos. Estos sistemas pueden aumentar los conocimientos de los manuales de procedimientos y permitirles ejecutar tareas complejas de forma eficiente.

Puedes usar las herramientas integradas o crear herramientas personalizadas que se adapten a tus necesidades.

Pruebas de herramientas

Una vez que hayas creado una herramienta, puedes usar la función de prueba para verificar que funciona. Cuando estés viendo una herramienta, haz clic en el botón Probar situado encima del panel de herramientas. Se abrirá la herramienta para introducir datos en el simulador. Proporciona la entrada de la herramienta y, a continuación, haz clic en Ver salida para comprobar que la salida de la herramienta es correcta.

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

Herramientas integradas

Google aloja las herramientas integradas. Puedes activar estas herramientas en los agentes sin necesidad de configurarlas manualmente.

Las herramientas integradas admitidas son las siguientes:

Code Interpreter: herramienta propia de Google que combina la capacidad de generar y ejecutar código, y que permite al usuario realizar varias tareas, como analizar y visualizar datos, procesar texto o resolver 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 adaptarlos a tus casos prácticos.

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 mediante una herramienta de OpenAPI proporcionando el esquema OpenAPI. De forma predeterminada, el agente llamará a la API en tu nombre.

Puedes comprobar que la herramienta está configurada correctamente con la función de prueba disponible en la página de la herramienta. Esta función también está disponible en la vista de ejemplo cuando añades una invocación de herramienta al ejemplo.

También puedes ejecutar herramientas de OpenAPI en el lado del 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

También puede usar la referencia de esquema interno @dialogflow/sessionId como tipo de esquema de parámetro. Con este tipo de esquema de parámetro, se proporcionará el ID de sesión de Dialogflow de la conversación actual como valor de parámetro. Por ejemplo:

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

Limitaciones de las herramientas de OpenAPI

Se aplican las siguientes limitaciones:

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. El tipo object aún no se admite.
Actualmente, no puedes especificar parámetros de consulta en el editor de ejemplos de la consola.
El cuerpo de la solicitud y de la respuesta deben estar vacíos 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 la solicitud
Un método HTTP (GET, POST, etc.)
Entrada de ejemplo
Ejemplo de salida
Una petición de texto que describa la herramienta

Una vez que se haya generado, puedes editarlo según sea necesario y añadir manualmente más URLs y métodos.

Autenticación de la API de herramientas de OpenAPI

Se admiten las siguientes opciones de autenticación al llamar a una API externa:

Autenticación del agente de servicio de Dialogflow

Dialogflow puede generar un token de ID mediante el agente de servicio de Dialogflow. El token se añade al encabezado HTTP de autorización cuando Dialogflow llama a una API externa.

Un token de ID se puede usar para acceder a funciones de Cloud Run y servicios de Cloud Run después de asignar 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 están en el mismo proyecto de recursos, no necesitas permisos de gestión de identidades y accesos adicionales para llamarlos.

Autenticación de 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 has hecho, crea una cuenta de servicio.

Como las cuentas de servicio son principales, pueden acceder a los recursos de tu proyecto concediéndoles un rol, al igual que harías con cualquier otro principal. La dirección de correo 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 configure la herramienta para usar cuentas de servicio debe tener los siguientes permisos:

roles/iam.serviceAccountUser

Para que Conversational Agents (Dialogflow CX) genere 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

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

OAuth

El flujo de credenciales de cliente de OAuth se admite para la autenticación de servidor a servidor:
- Este flujo se puede usar si la consola de aplicaciones de IA es el propietario del recurso y no se necesita la autorización del usuario final.
- El ID de cliente, el secreto de cliente y el endpoint de token del proveedor de OAuth deben configurarse en Dialogflow.
  - Te recomendamos que proporciones tu secreto de cliente mediante Secret Manager. Después del 15 de agosto del 2025, los agentes exportados ya no incluirán secretos de cliente con valores sin procesar.
- Dialogflow intercambia un token de acceso de OAuth del proveedor de OAuth y lo transfiere en el encabezado de autorización de la solicitud.
En el caso de otros flujos de OAuth que requieran la autorización del usuario final, como el flujo de código de autorización y el flujo de PKCE, sigue estos pasos:
1. Deberás implementar tu propia interfaz de usuario de inicio de sesión y obtener el token de acceso en el lado del cliente.
2. Luego, puedes hacer lo siguiente:
  
  a. Usa la opción de autenticación de token de portador para enviar el token a la herramienta OpenAPI. Dialogflow incluirá este token en el encabezado de autorización al invocar la herramienta.
  
  b. Usa la herramienta Función para invocarla tú mismo en el lado del cliente y pasar el resultado de la llamada a la herramienta a Dialogflow.

Token de portador

Puedes configurar la autenticación de portador para transferir de forma dinámica el token de portador desde el cliente. Este token se incluye en el encabezado de autorización de la solicitud.
Al configurar la autenticación de herramientas, puede 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 Bearer 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 obtenerlo de un parámetro de sesión, te recomendamos que lo proporciones mediante Secret Manager. Después del 15 de agosto del 2025, los agentes exportados ya no incluirán tokens de portador con valores sin procesar.

Autenticación TLS mutuo

Consulta la documentación sobre la autenticación TLS mutua.
Se admiten certificados de cliente personalizados. Puede configurar certificados de cliente a nivel de agente en la pestaña Seguridad de los ajustes 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 el protocolo TLS mutuo en todas las herramientas y webhooks.

Certificado de AC personalizado

Consulta la documentación sobre certificados de CA personalizados.

Autenticación de Secret Manager

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

Crea tu secreto si aún no tienes uno.
Asigna el rol Permiso para acceder a los recursos de Secret Manager (roles/secretmanager.secretAccessor) al agente de servicio de Dialogflow en el nuevo secreto.
Copia tus credenciales en el portapapeles.
Añade una nueva versión del secreto al secreto. Pega tu credencial como valor del secreto.
- Omite cualquier carácter de nueva línea al final.
Copia el nombre de la versión del secreto que acabas de añadir. El formato del nombre es projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Abre la pantalla de edición de la herramienta y haz lo siguiente:
- Si usas OAuth, selecciona OAuth como Tipo de autenticación y, a continuación, haz clic en Versión del secreto en Secreto de 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 Tipo de autenticación y, a continuación, 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 Bearer, selecciona Token Bearer como Tipo de autenticación y, a continuación, haz clic en Versión secreta en Token Bearer. Pega el nombre de la versión del secreto en el cuadro de entrada Versión del secreto.
Haz clic en Guardar.

Acceso a redes privadas de la herramienta OpenAPI

La herramienta OpenAPI se integra con el acceso a la red privada de Service Directory, por lo que puede conectarse a destinos de API dentro de tu red de VPC. De esta forma, el tráfico se mantiene en la red de Google Cloud y se aplican IAM y Controles de Servicio de VPC.

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

Sigue las instrucciones de Configuración de red privada de Service Directory para configurar tu red de VPC y tu endpoint de Service Directory.
Tu proyecto de agente debe tener la cuenta de servicio del agente de servicio de Dialogflow con la siguiente dirección:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Asigna los siguientes roles de IAM a la cuenta de servicio Agente de servicio de Dialogflow:
- servicedirectory.viewer del proyecto de Directorio de servicios
- servicedirectory.pscAuthorizedService del proyecto de red
Proporciona el servicio Service Directory junto con el esquema de OpenAPI y la información de autenticación opcional al crear la herramienta.

Acceso a parámetros de sesión de herramientas de OpenAPI

Las entradas de la herramienta de API abierta se derivan de la conversación de los usuarios con el LLM mediante el esquema como guía. En algunos casos, es posible que las entradas se tengan que derivar de los parámetros de sesión recogidos durante un flujo o que se proporcionen como entrada de parámetro de consulta junto con la entrada del usuario.

El parámetro de sesión que se debe transferir como entrada se puede especificar 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.

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

Valores predeterminados de la herramienta OpenAPI

El esquema de la API abierta se puede usar para especificar valores predeterminados. Los valores predeterminados solo se usan si no hay ningún valor de entrada generado por LLM o ningún valor de entrada basado en parámetros 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 un 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 cómo usar las herramientas de almacén de datos con un manual de estrategias, consulta la documentación sobre las herramientas de almacén de datos.

Herramientas de conectores

Un agente puede usar las herramientas de conectores para realizar acciones con las conexiones que hayas configurado en Integration Connectors. Cada herramienta de conector se configura con una sola conexión y una o varias acciones. Si es necesario, se pueden crear varias herramientas para una misma conexión con el fin de agrupar diferentes acciones para que las use tu agente.

La herramienta de conectores admite los siguientes tipos de conectores:

Los ejemplos deben usarse para mejorar el uso de las herramientas de conectores por parte del agente. Para ello, se debe mostrar cómo debe llamar el agente a la herramienta y usar la respuesta.

Crear una conexión

Para crear una conexión y conectarla a tu agente, ve a Herramientas > Crear, selecciona el tipo de herramienta Conector y el tipo de conector que hayas elegido, y usa el botón Crear conexión. Se te dirigirá a la página de creación de Integration Connectors con varios campos rellenados automáticamente.

También puedes ir a Integration Connectors y seguir las instrucciones para crear una conexión.

Acciones del conector

En 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 (en BigQuery, son tablas; en Salesforce, son objetos, como "Pedido" o "Caso").

Puedes realizar operaciones CRUD en cada entidad:
- Crear: crea una entidad con los valores de campo especificados.
- Lista: búsqueda de instancias de entidades basada en filtros
- Actualización: método basado en filtros para modificar los valores de los campos de las entidades
- Eliminar: elimina una entidad.
- Get obtiene una sola entidad mediante entityId.
Nota: La operación Get solo se puede usar para obtener un único registro de una entidad que tenga una clave principal. A menudo, es más práctico usar la operación List con una filterClause para recuperar una entidad.

Consulta más información sobre los detalles de las operaciones CRUD de entidades en la documentación de conectores.
Acciones específicas de conectores

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

Las acciones adicionales varían en función del tipo de conector. Por ejemplo, consulta las acciones del conector de BigQuery o las acciones del conector de Salesforce.

Configurar campos de entrada y salida para operaciones CRUD

Si seleccionas campos de entrada o salida específicos para que los use la acción de la herramienta de 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 del agente.

Especificar un conjunto de campos de salida reduce el tamaño de la respuesta de la herramienta (lo que resulta útil si te preocupa el límite de tokens) y simplifica la gestión de la salida por parte del agente, ya que solo se exponen los campos relevantes.

Autenticación

Si la conexión que estás usando está configurada para permitir la sustitución de la autenticación, la herramienta se puede configurar para que transfiera las credenciales de los parámetros de sesión especificados.

Como creador del agente, eres responsable de cómo se rellenan estas credenciales en los parámetros de sesión. La herramienta las transferirá automáticamente a la fuente de datos para usarlas en la autenticación cuando se llamen las acciones de la herramienta.

Herramientas de funciones

Si tienes una función a la que se puede acceder mediante tu código de cliente, pero no mediante 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:

Tu código de cliente envía una solicitud de detección de intención.
El agente detecta que se necesita una herramienta de función y la respuesta de detección de intención contiene el nombre de la herramienta junto con los argumentos de entrada. Esta sesión se pausa hasta que se reciba otra solicitud de detección de intenciones 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 intención que proporciona el resultado de la herramienta como argumentos de salida.

En el siguiente ejemplo se muestra el esquema de entrada y 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 muestra la solicitud y la respuesta iniciales de detección de intención mediante 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 lado del cliente

Al igual que las herramientas de funciones, las herramientas de OpenAPI y de almacenamiento de datos se pueden ejecutar en el lado del cliente aplicando una anulación de API al interactuar con la sesión.

Por ejemplo:

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