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 compilar herramientas personalizadas según tus requisitos.
Limitaciones
Se aplica la siguiente limitación:
- Debes crear un almacén de datos (o conectar uno existente) cuando crees una herramienta de almacén de datos para un agente.
- No se admiten apps con almacenes de datos divididos y no divididos.
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 propia de Google que combina la capacidad de generación y ejecución de código y permite al usuario realizar varias tareas, como análisis de datos, 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. 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
De forma opcional, puedes usar la referencia de esquema interna @dialogflow/sessionId
como tipo de esquema de parámetros.
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,queryyheader. Aún no se admite el tipo de parámetrocookie. - Los parámetros definidos por el esquema de OpenAPI admiten los siguientes tipos de datos:
string,number,integer,booleanyarray. Todavía no se admite el tipoobject. - Actualmente, no puedes especificar parámetros de consulta en el editor de ejemplos de la consola.
- El cuerpo de la solicitud y la respuesta deben estar vacíos o ser JSON.
Autenticación de la API de la herramienta 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 o un token de acceso 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.
- Un token de acceso se puede usar para acceder a otras APIs de Google Cloud después de otorgar los roles necesarios a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
- Clave de API
- Para configurar la autenticación de claves 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 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:
- Este flujo se puede usar si la consola de Agent Builder es el propietario del recurso y no se necesita la autorización del usuario final.
- El ID de cliente, el secreto del cliente y el extremo de token del proveedor de OAuth deben configurarse en Dialogflow.
- Dialogflow intercambia un token de acceso de OAuth del proveedor de OAuth y lo pasa en el encabezado de autenticación de la solicitud.
Para otros flujos de OAuth que requieren autorización del usuario final, como el flujo de código de autorización y el flujo de PKCE, haz lo siguiente:
- Deberás implementar tu propia IU de acceso y obtener el token de acceso del cliente.
Luego, puedes hacer lo siguiente:
a. Usa la opción de autenticación de token de 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 de función para invocar la herramienta 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 el token de portador de forma dinámica desde el cliente. Este token se incluye en el encabezado de autenticació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 de portador. Por ejemplo, usa
$session.params.<parameter-name-for-token>para especificar el token. - En el entorno 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> } } ... }Autenticación mutua de TLS
- Consulta la documentación sobre la autenticación TLS mutua.
- Se admiten certificados de cliente personalizados. Puedes configurar certificados de cliente a nivel del agente en la pestaña de 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 AC personalizado
- Consulta la documentación sobre certificados de AC personalizados.
Acceso a redes privadas de la herramienta OpenAPI
La herramienta OpenAPI se integra al 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
servicedirectory.viewerdel proyecto del Directorio de serviciosservicedirectory.pscAuthorizedServicedel 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 los parámetros de sesión de la herramienta OpenAPI
Las entradas de la herramienta de API abierta se derivan de la conversación de los usuarios 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 entrada de parámetros 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 un parámetro de sesión disponible, 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 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 LLM, valor del parámetro de sesión o valor predeterminado, la entrada no se especificará.
Herramientas de almacén de datos
Un agente puede usar las herramientas de almacenes de datos para responder las preguntas de los usuarios finales desde tus almacenes de datos. Puedes configurar un almacén de datos de cada tipo por herramienta, y esta consultará cada uno de estos almacenes de datos para obtener respuestas. De forma predeterminada, el agente llamará a la herramienta del almacén de datos en tu nombre. Como alternativa, puedes ejecutar herramientas de almacén de datos en el lado del cliente.
El tipo de almacén de datos puede ser uno de los siguientes:
PUBLIC_WEB: Es un almacén de datos que contiene contenido web público.UNSTRUCTURED: Es 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 de contenido que se usó para generar la respuesta. El agente también puede proporcionar instrucciones sobre cómo continuar 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 para una pregunta específica.
Los ejemplos se pueden usar para mejorar aún más el comportamiento 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 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 creas 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 obligatoria: una cadena filter, un objeto estructurado userMetadata y una cadena fallback.
El parámetro filter te permite filtrar las búsquedas de tus datos estructurados o no estructurados con metadatos. Esta cadena debe seguir la sintaxis de la expresión de filtro compatible para los almacenes de datos.
Se recomienda usar varios ejemplos y ejemplos detallados para dirigir al LLM de la guía sobre cómo propagar este parámetro. En el caso de una cadena de filtro no 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 ser el siguiente:
"filter": "country: ANY(\"Canada\")"
Prácticas recomendadas para filtrar:
Especifica los campos disponibles para filtrar y los valores válidos para cada uno de estos campos, de modo que el libro de jugadas comprenda las restricciones para crear filtros válidos. Por ejemplo, para filtrar los resultados de un almacén de datos que contiene información del menú, podría haber un campo
mealcon "desayuno", "almuerzo" y "cena" como valores válidos, y un camposervingSizeque puede ser cualquier número entero de 0 a 5. Tus instrucciones podrían verse de la siguiente manera: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 la guía es para un público de usuarios externos, es posible que debas agregar instrucciones para evitar que la guía 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."También es útil proporcionar un ejemplo de este caso.
El parámetro userMetadata proporciona información sobre el usuario final. Se pueden propagar cualquier par clave-valor en este parámetro. Estos metadatos se pasan a la herramienta del almacén de datos para fundamentar mejor los resultados de la búsqueda y la respuesta de la herramienta. Se recomienda proporcionar varios ejemplos para indicarle al LLM de la guía de instrucciones cómo propagar este parámetro.
Un ejemplo de un valor de parámetro userMetadata para definir mejor los resultados de la búsqueda
relevantes para un usuario específico podría ser el siguiente:
"userMetadata": {
"favoriteColor": "blue",
...
}
El parámetro fallback proporciona una respuesta con la que la herramienta del 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 de la guía de instrucciones cómo propagar el resguardo para 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 durante las pruebas descubres que algunas respuestas no cumplen con tus expectativas, las siguientes personalizaciones están disponibles en la página de herramientas de un almacén de datos:
Cómo fundamentar la confianza
Para cada respuesta generada a partir del contenido de tus almacenes de datos conectados, la guía de consulta evalúa un nivel de confianza, que mide la confianza en que toda la información de la respuesta está respaldada por la información de los almacenes de datos. Para personalizar las respuestas que se permiten, selecciona el nivel de confianza más bajo que te resulte adecuado. Solo se mostrarán las respuestas que tengan ese nivel de confianza o uno superior.
Hay 5 niveles de confianza para elegir: VERY_LOW, LOW, MEDIUM,
HIGH y VERY_HIGH.
Configuración de resumen
Puedes seleccionar el modelo generativo que usa un controlador de 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 LLM de resumen.
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 durante 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: La guía de referencia usa un módulo de reescritura para reescribir la consulta original del usuario en un formato más preciso.$sources: La guía de consulta 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 second 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 conversaciones 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 indicarle al LLM que muestre "NOT_ENOUGH_INFORMATION" cuando no pueda proporcionar una respuesta. La guía de procedimientos transformará esta constante en un mensaje fácil de entender para el usuario.
Configuración de la carga útil
La configuración de la 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 mensajero.
Frases prohibidas (configuración a nivel de la guía)
Tienes la opción de definir frases específicas que no se deben permitir. Se configuran a nivel de la guía de instrucciones y las usan los LLM de la guía de instrucciones y las herramientas del almacén de datos. Si la respuesta generada o partes de la instrucción del LLM, como las entradas del usuario, contienen alguna de las frases prohibidas textualmente, no se mostrará esa respuesta.
Herramientas de funciones
Si tu código cliente puede acceder a la funcionalidad, pero las herramientas de OpenAPI no, puedes usar herramientas de funciones. Las herramientas de funciones siempre se ejecutan del lado del cliente, no del agente.
El proceso es el siguiente:
- Tu código de 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 pausa 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 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
Al igual que las herramientas de funciones, las herramientas de OpenAPI y de almacén de datos se pueden ejecutar en el cliente aplicando una anulación de 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:
- Tu código cliente envía una solicitud de detección de intents que especifica la ejecución del cliente.
- El 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 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 intents que proporciona el resultado de la herramienta como argumentos de salida.