Herramientas

Mediante las herramientas, puedes conectar apps de agente a sistemas externos. Estos sistemas pueden aumentar el conocimiento de las apps de agente y permitirles ejecutar tareas complejas de manera eficiente.

Puedes usar las herramientas integradas o compilar herramientas personalizadas según tus requisitos.

Limitaciones

Se aplica la siguiente limitación:

Herramientas integradas

Las herramientas integradas están alojadas en Google. Puedes activar estas herramientas en apps de agente sin necesidad de una configuración manual.

Las herramientas integradas compatibles son las siguientes:

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

Tu app de agente está optimizada 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.

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

Una app de agente puede conectarse a una API externa con una herramienta de OpenAPI si proporcionas el esquema de OpenAPI. De forma predeterminada, la app del agente llamará a la API por ti. Como alternativa, puedes ejecutar las 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 forma opcional, puedes usar la referencia de esquema interno @dialogflow/sessionId como tipo de esquema de parámetro. Con este tipo de esquema de parámetro, el ID de sesión de Dialogflow para la conversación actual se proporcionará como un valor del 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.
  • Por el momento, no puedes especificar parámetros de consulta en el editor de ejemplo de la consola.
  • El cuerpo de la solicitud y la respuesta debe estar vacío o ser JSON.

Autenticación de la API de la herramienta de OpenAPI

Las siguientes opciones de autenticación son compatibles cuando se llama a una API externa:

  • Autenticación del agente de servicio de Dialogflow
    • Dialogflow puede generar un token de ID o un token de acceso con el agente de servicio de Dialogflow. El token se agrega al encabezado HTTP de autorización cuando Dialogflow llama a una API externa.
    • Se puede usar un token de ID para acceder a los servicios de Cloud Functions y 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 los servicios de Cloud Functions y Cloud Run están en el mismo proyecto de recursos, no necesitas permisos de IAM adicionales para llamarlos.
    • Se puede usar un token de acceso para acceder a otras APIs de Google Cloud después de otorgar las funciones necesarias a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • 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 la cadena de consulta) y la clave de API para que Dialogflow pase la clave de API en la solicitud.
  • OAuth
    • El flujo de credenciales de cliente de OAuth es compatible con la autenticación de servidor a servidor. El ID de cliente, el secreto del cliente y el extremo del token del proveedor de OAuth deben configurarse en Dialogflow. Dialogflow intercambia un token de acceso de OAuth y lo pasa en el encabezado de Auth de la solicitud.
    • Para otros flujos de OAuth, debes usar la herramienta de funciones para integrarla a tu propia IU de acceso para intercambiar el token.

  • Token del portador

    • Puedes configurar la autenticación del portador para pasar el token del portador de forma dinámica desde el cliente. Este token se incluye en el encabezado auth de la solicitud.
    • Cuando configuras la autenticación de la herramienta, 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>
    }
  }
  ...
}

  • Autenticación mutua de TLS

  • Certificado de la AC personalizado

Acceso a redes privadas de la herramienta de OpenAPI

La herramienta OpenAPI se integra al acceso a la red privada del Directorio de servicios, por lo que puede conectarse a los objetivos de la 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 dirigida a una red privada, sigue estos pasos:

  1. 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.

  2. 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

  3. 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.

Herramientas de almacén de datos

Una app de agente puede usar las herramientas de almacén de datos para responder las preguntas del usuario final de tus almacenes de datos. Puedes configurar un almacén de datos de cada tipo por herramienta, y la herramienta consultará cada uno de estos almacenes de datos para obtener respuestas. De forma predeterminada, la app del agente llamará a la herramienta del almacén de datos en tu nombre. Como alternativa, puedes ejecutar las herramientas del almacén de datos en el lado del cliente.

El tipo de almacén de datos puede ser uno de los siguientes:

  • PUBLIC_WEB: Un almacén de datos que incluye contenido web público.
  • UNSTRUCTURED: Un almacén de datos que contiene datos privados no estructurados.
  • STRUCTURED: Es un almacén de datos que contiene datos estructurados (por ejemplo, Preguntas frecuentes).

En el siguiente ejemplo, se muestra cómo hacer referencia a un almacén de datos:

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

Las respuestas de la herramienta del almacén de datos también pueden contener fragmentos sobre la fuente del contenido que se usó para generar la respuesta. La app del agente puede proporcionar más instrucciones sobre cómo proceder con la respuesta de los almacenes de datos o cómo responder cuando no hay una respuesta.

Para reemplazar una respuesta, agrega una entrada de Preguntas frecuentes de una pregunta específica.

Se pueden usar ejemplos para mejorar aún más el comportamiento de la app del agente. El ejemplo debe tener los siguientes esquemas:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

Crea un almacén de datos

Para crear un almacén de datos y conectarlo a tu app, puedes usar el vínculo Herramientas que se encuentra en el panel de navegación izquierdo de la consola. Sigue las instrucciones para crear un almacén de datos.

Parámetros de consulta adicionales

Cuando se crean ejemplos de herramientas de almacén de datos, el parámetro de entrada de la herramienta requestBody proporciona tres entradas opcionales junto con la cadena query requerida: una cadena filter, un objeto estructurado userMetadata y una cadena fallback.

El parámetro filter proporciona la capacidad de filtrar búsquedas de tus datos estructurados o no estructurados con metadatos. Esta string debe seguir la sintaxis de la expresión de filtro admitida para los almacenes de datos. Se recomienda incluir varios ejemplos y ejemplos detallados para indicarle al LLM del agente cómo propagar este parámetro. Si la cadena de filtro no es válida, se ignorará el filtro cuando se realice la búsqueda.

Un ejemplo de una cadena filter para definir mejor los resultados de la búsqueda según la ubicación podría verse de la siguiente manera:

  "filter": "country: ANY(\"Canada\")"

Prácticas recomendadas para el filtrado:

  • Especifica los campos disponibles para filtrar y los valores válidos para cada uno de estos campos, de modo que el agente comprenda las restricciones de la compilación de filtros válidos. Por ejemplo, para filtrar los resultados de un almacén de datos que contiene la información del menú, podría haber un campo meal con valores válidos para “desayuno”, “almuerzo” y “cena”, y un campo servingSize que puede ser cualquier número entero entre 0 y 5. Las instrucciones podrían verse así:

    When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.

  • Si el agente está destinado a un público de usuarios externos, puede ser necesario agregar instrucciones para evitar que el agente responda al usuario con información sobre la compilación de estos filtros. Por ejemplo:

    Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."

    Proporcionar un ejemplo de este caso también es útil.

El parámetro userMetadata proporciona información sobre el usuario final. Cualquier par clave-valor se puede propagar en este parámetro. Estos metadatos se pasan a la herramienta de almacén de datos para informar mejor los resultados de la búsqueda y la respuesta de la herramienta. Se recomienda proporcionar varios ejemplos para indicarle al LLM del agente cómo propagar este parámetro.

Un ejemplo de un valor del parámetro userMetadata para definir mejor los resultados de la búsqueda relevantes para un usuario específico podría verse de la siguiente manera:

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

El parámetro fallback proporciona una respuesta que la herramienta de almacén de datos debe responder si no hay una respuesta resumida válida para la consulta. Se pueden proporcionar varios ejemplos para indicarle al LLM del agente cómo propagar el resguardo de las entradas del usuario relacionadas con diferentes temas. Tampoco habrá fragmentos en el resultado de la herramienta. Esta optimización se puede usar para reducir la latencia y el uso del límite de tokens de entrada.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

Si encuentras que algunas respuestas durante la prueba no cumplen con tus expectativas, las siguientes personalizaciones están disponibles en la página Herramientas de una herramienta de almacén de datos:

Confianza de los fundamentos

Para cada respuesta generada a partir del contenido de tus almacenes de datos conectados, el agente evalúa un nivel de confianza, que mide la confianza de que toda la información de la respuesta esté respaldada por la información de los almacenes de datos. Puedes personalizar qué respuestas permitir. Para ello, selecciona el nivel de confianza más bajo con el que te sientas cómodo. Solo se mostrarán las respuestas que tengan ese nivel de confianza o uno superior.

Puedes elegir entre 5 niveles de confianza: VERY_LOW, LOW, MEDIUM, HIGH y VERY_HIGH.

Configuración de resumen

Puedes seleccionar el modelo generativo que usa el agente del almacén de datos para la solicitud generativa de resumen. Si no se selecciona ninguno, se usa una opción de modelo predeterminada. La siguiente tabla contiene las opciones disponibles:

Identificador de modelo Idiomas compatibles
text-bison@002 Disponible en todos los idiomas compatibles.
gemini-1.0-pro-001 Disponible en todos los idiomas compatibles.

También puedes proporcionar tu propia instrucción para la llamada de resumen de LLM.

La instrucción es una plantilla de texto que puede contener marcadores de posición predefinidos. Los marcadores de posición se reemplazarán por los valores adecuados en el tiempo de ejecución y el texto final se enviará al LLM.

Los marcadores de posición son los siguientes:

  • $original-query: Es el texto de la consulta del usuario.
  • $rewritten-query: El agente usa un módulo de reescritura para reescribir la consulta del usuario original en un formato más preciso.

  • $sources: El agente usa Enterprise Search para buscar fuentes según la consulta del usuario. Las fuentes encontradas se renderizan en un formato específico:

    [1] title of first source
content of first source
[2] title of second source
content of first source

  • $end-user-metadata: La información sobre el usuario que envía la consulta se renderiza en el siguiente formato:

    The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}

  • $conversation: El historial de la conversación se renderiza en el siguiente formato:

    Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

Una instrucción personalizada debe indicar al LLM que devuelva "NOT_ENOUGH_INFORMATION" cuando no pueda proporcionar una respuesta. El agente transformará esta constante en un mensaje fácil de usar para el usuario.

Configuración de carga útil

La configuración de carga útil proporciona una forma de agregar los fragmentos del almacén de datos como contenido enriquecido en la carga útil de respuesta que se renderiza en el mensaje.

Frases bloqueadas (configuración a nivel del agente)

Tienes la opción de definir frases específicas que no deberían permitirse. Estas se configuran a nivel del agente y las usan los LLM del agente y las herramientas del almacén de datos. Si la respuesta generada o partes de la instrucción de LLM, como las entradas del usuario, contienen alguna de las frases prohibidas al pie de la letra, esa respuesta no se mostrará.

Herramientas de funciones

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

El proceso es el siguiente:

  1. Tu código de cliente envía una solicitud de detección de intent.
  2. La app del 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 pausa hasta que se reciba otra solicitud de detección de intent con el resultado de la herramienta.
  3. El código del cliente llama a la herramienta.
  4. El 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 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 inicial de detección de intent y la respuesta 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 intent, 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, OpenAPI y las herramientas de almacén de datos se pueden ejecutar en el lado del cliente mediante la aplicación de 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
    }
  }
  ...
}

El proceso es el siguiente:

  1. El código del cliente envía una solicitud de detección de intent que especifica la ejecución del cliente.
  2. La app del agente detecta que se requiere una herramienta y la respuesta de detección de intent 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 intent con el resultado de la herramienta.
  3. El código del cliente llama a la herramienta.
  4. El código de cliente envía otra solicitud de detección de intent que proporciona el resultado de la herramienta como argumentos de salida.
Anterior
Interfaz de usuario
Siguiente
Prácticas recomendadas