Algunos productos y funciones están en proceso de cambio de nombre. Las funciones de guía generativa y flujos también se están migrando a una sola consola consolidada.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

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 que se adapten a tus requisitos.

Prueba de herramientas

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

También puedes usar la función de prueba de herramientas cuando agregas 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 compatibles son las siguientes:

Code Interpreter: Es una herramienta propia de Google que combina la capacidad de generación y ejecución de código, y te permite realizar varias tareas, como análisis de datos, visualización de datos, procesamiento de texto y 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 que se adapten a tus casos de uso.

Esquema de ejemplo:

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

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

Puedes probar que 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 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

Puedes usar la referencia de esquema interna @dialogflow/sessionId como un tipo de esquema de parámetro. Con este tipo de esquema de parámetro, el ID de sesión de Dialogflow CX para la conversación actual se proporciona 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. 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. No se admite el tipo object.
No puedes especificar parámetros de consulta en el editor de ejemplos de la consola.
Los cuerpos de solicitud y respuesta deben estar vacíos o usar el formato application/json.

Generación de esquemas de herramientas de OpenAPI

Cuando proporciones un esquema, haz clic en Usar Gemini para crear tu esquema con IA generativa.

Proporciona los siguientes detalles para guiar la generación:

Una URL de solicitud
Un método HTTP, como GET o POST
Entrada de muestra.
Resultado de muestra.
Es una instrucción de texto que describe la herramienta.

Después de generar el esquema, puedes editarlo según sea necesario y agregar URLs y métodos adicionales de forma manual.

Autenticación de la API de la herramienta de OpenAPI

Puedes usar las siguientes opciones de autenticación cuando llames a una API externa.

Autenticación del agente de servicio de Dialogflow CX

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

Puedes usar un token de ID para acceder a las funciones de Cloud Run y a 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..

Si las funciones de Cloud Run y los servicios de Cloud Run están en el mismo proyecto de recursos, no necesitas permisos adicionales de Identity and Access Management (IAM) para llamarlos.

Autenticación de la cuenta de servicio

Las cuentas de servicio pueden autenticar las solicitudes de herramientas a 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, puedes otorgarles roles para acceder a los recursos de tu proyecto, al igual que lo harías con cualquier otra principal. Puedes usar el correo electrónico de la cuenta de servicio para generar un token de acceso que envías en el encabezado Authorization de la solicitud de la herramienta.

Si configuras la herramienta para usar cuentas de servicio, debes tener los siguientes permisos:

roles/iam.serviceAccountUser

Para permitir que Dialogflow CX genere tokens, otorga al agente de servicio de Dialogflow CX los siguientes permisos:

roles/iam.serviceAccountTokenCreator

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

Autenticación de la clave de API

Puedes configurar la autenticación con 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 CX 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 valor sin procesar.

OAuth

El flujo de credenciales de cliente de OAuth se admite para la autenticación de servidor a servidor:

Puedes usar este flujo si Generative AI App Builder es el propietario del recurso y no necesitas la autorización del usuario final.
Debes configurar el ID de cliente, el secreto del cliente y el extremo de token de un proveedor de OAuth en Dialogflow CX.
Te recomendamos que proporciones tu secreto del cliente con Secret Manager. Los agentes exportados no contendrán secretos del cliente con valores sin procesar después del 15 de agosto de 2025.
Dialogflow CX intercambia un token de acceso de OAuth de un proveedor de OAuth y lo pasa en el encabezado de autorización de la solicitud.

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 configuras la autenticación de herramientas, puedes designar un parámetro de sesión para que actúe como el token del portador. Por ejemplo, usa $session.params.<parameter-name-for-token> para especificar el token.

En el entorno de ejecución, asigna el token del 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 lo proporciones con Secret Manager. Después del 15 de agosto de 2025, los agentes exportados no contendrán tokens del portador con valores sin procesar.

Autenticación TLS mutua

Para obtener más información, consulta Autenticación 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 los webhooks.

Certificado de la AC personalizado

Para obtener más información, consulta Certificados de la AC personalizados.

Autenticación de Secret Manager

Si usas OAuth, una clave de API o un token del portador, puedes almacenar las credenciales como secretos con Secret Manager.

Sigue estos pasos para autenticar tu herramienta con secretos:

Crea tu secreto si aún no tienes uno.
Otorga al agente de servicio de Dialogflow el rol de Descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) en el secreto nuevo.
Copia tu credencial en el portapapeles.
Agrega una versión nueva a tu secreto. Pega tu credencial como el valor del Secret.
- Omite cualquier carácter de línea nueva al final del Secret.
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, luego, haz clic en Versión del Secret en Secreto del cliente y pega el nombre de la versión del Secret en el cuadro de entrada Versión del Secret.
- Si usas una clave de API, selecciona Clave de API como el Tipo de autenticación y, luego, haz clic en Versión del Secret en Clave de API. Pega el nombre de la versión del Secret en el cuadro de entrada Versión del Secret.
- Si usas un token del portador, selecciona Token del portador como el Tipo de autenticación y, luego, haz clic en Versión del Secret en Token del portador. Pega el nombre de la versión del Secret en el cuadro de entrada Versión del Secret.
Haz clic en Guardar.

Acceso a redes privadas de la herramienta de OpenAPI

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

Para configurar una herramienta de OpenAPI orientada 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.
Asegúrate de que exista la cuenta de servicio del agente de servicio de Dialogflow CX con la siguiente dirección para tu proyecto de agente:
```
service-agent-project-number@gcp-sa-dialogflow.
```
Otorga a la cuenta de servicio del agente de servicio de Dialogflow CX los siguientes roles de IAM:
- servicedirectory.viewer del proyecto del Directorio de servicios
- servicedirectory.pscAuthorizedService del proyecto de red
Proporciona el servicio del Directorio de servicios junto con el esquema de OpenAPI y la información de autenticación opcional cuando crees la herramienta.

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

Las entradas de la herramienta de OpenAPI se derivan de la conversación del usuario con el LLM usando 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.

Puedes especificar los parámetros de sesión que necesitas pasar como entrada con el siguiente 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.

Si no hay parámetros de sesión disponibles, la entrada generada por el LLM se pasa a la herramienta.

Valores predeterminados de la herramienta de OpenAPI

Puedes usar el esquema de OpenAPI para especificar valores predeterminados. Estos valores predeterminados solo se aplican cuando no hay un valor de entrada generado por LLM o un valor de entrada basado en parámetros de sesión disponible para ese parámetro o propiedad.

Puedes especificar valores predeterminados 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: Breed of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

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

Herramientas de almacenamiento de datos

Para obtener más información sobre el uso de las herramientas de almacén de datos con una guía, consulta las herramientas de almacén de datos.

Herramientas de conector

Las herramientas de conector te permiten configurar un agente para que realice 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. Puedes crear varias herramientas para una sola conexión con el objetivo de agrupar diferentes acciones y que las use tu agente.

La herramienta de conector admite los siguientes tipos de conectores:

Puedes usar ejemplos para ayudar a los agentes a usar las herramientas de conector de forma eficaz, ya que demuestran cómo llamar a las herramientas y usar las respuestas.

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 elegiste, y haz clic en Crear conexión. Se abrirá la creación de Integration Connectors con varios campos precompletados.

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

Acciones del conector

Puedes hacer que dos tipos de acciones estén disponibles para tu agente en cada herramienta de conector. Para obtener más información, consulta Entidades, operaciones y acciones.

Operaciones CRUD de entidades:

Cada conexión tiene entidades que corresponden a los objetos de esa fuente de datos (para BigQuery, estas son tablas; para Salesforce, son objetos, como Order o Case).

Puedes realizar operaciones CRUD en cada entidad:
- Crear: Valida y crea una entidad con los valores de campo especificados.
- List: Búsqueda basada en filtros de instancias de entidades.
- Actualización: Es un método basado en filtros para alterar los valores de los campos de entidades.
- Borrar: Borra una entidad.
- Get: Recupera una sola entidad con el entityId.
Nota: La operación Obtener solo se puede usar para recuperar un registro único de una entidad que tenga una clave primaria. A menudo, es más práctico usar la operación List con una filterClause para recuperar una entidad.

Para obtener más información sobre las operaciones CRUD de entidades, consulta la documentación de conectores.
Acciones específicas del conector:

Muchos conectores admiten una acción ExecuteCustomQuery, que te permite ejecutar una consulta en SQL en la fuente de datos, en la que cada una de las entidades de la fuente de datos se puede referenciar como tablas. Para obtener más información, consulta la lista de 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.

Configura campos de entrada y salida para las operaciones CRUD

Si seleccionas campos de entrada o salida específicos para 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 para el agente.

Especificar un conjunto de campos de salida reduce el tamaño de la respuesta de la herramienta para mitigar los límites de tokens. Esto permite que el agente controle el resultado exponiendo solo los campos relevantes.

Autenticación

Si la conexión que usas permite la anulación de la autenticación, configura la herramienta para pasar credenciales de los parámetros de sesión especificados.

Completa estas credenciales en los parámetros de la sesión. Luego, la herramienta los pasa automáticamente a la fuente de datos para la autenticación cuando se llaman acciones.

Herramientas de funciones

Si tienes capacidades a las que puede acceder tu código de cliente, pero no las herramientas de OpenAPI, puedes usar herramientas de funciones. El lado del cliente siempre ejecuta las herramientas de función, no el agente.

El proceso es el siguiente:

El código de cliente envía una solicitud de detección de intents.
El agente detecta que se requiere una herramienta de función, y la respuesta de intent de detección contiene el nombre de la herramienta junto con los argumentos de entrada. Esta sesión se detiene hasta que se recibe otra solicitud de intent de detección con el resultado de la herramienta.
El código de tu cliente llama a la herramienta.
Tu código de cliente envía otra solicitud de detección de intents 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 intents 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 intents 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

Puedes ejecutar herramientas de OpenAPI y de almacén de datos en el cliente, de forma similar a las herramientas de funciones, aplicando una anulación de API cuando interactúas con la sesión.