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.
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 herramientas. Se abrirá la herramienta de entrada en el simulador. Proporciona la entrada de la herramienta y, luego, haz clic en Ver resultado para verificar el resultado correcto de la herramienta.
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 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.
- Se puede usar un token de acceso para acceder a otras Google Cloud APIs después de otorgar los roles requeridos a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
Autenticación de la cuenta de servicio
- Las cuentas de servicio se pueden usar para autenticar solicitudes de herramientas a cualquier API de Google que las admita. Debido a que las cuentas de servicio son principales, pueden acceder a los recursos de tu proyecto si les otorgas un rol, al igual que lo harías con cualquier otra principal. El correo electrónico de la cuenta de servicio se usará para generar un token de acceso que se enviará en el encabezado
Authorizationde la solicitud de la herramienta. Para usar esta función, se requieren los siguientes permisos:
roles/iam.serviceAccountUseral usuario que crea o actualiza la herramienta para usar la autenticación de la cuenta de servicio.roles/iam.serviceAccountTokenCreatoral agente de servicio de Dialogflow.
Si intentas usar cuentas de servicio en varios proyectos, asegúrate de que la política de la organización las admita. Se deben otorgar ambos permisos en el proyecto que contiene la cuenta de servicio.
- Las cuentas de servicio se pueden usar para autenticar solicitudes de herramientas a cualquier API de Google que las admita. Debido a que las cuentas de servicio son principales, pueden acceder a los recursos de tu proyecto si les otorgas un rol, al igual que lo harías con cualquier otra principal. El correo electrónico de la cuenta de servicio se usará para generar un token de acceso que se enviará en el encabezado
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.
- Te recomendamos que proporciones tu clave de API con Secret Manager.
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.
- Te recomendamos que proporciones tu secreto de cliente con Secret Manager.
- 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 invocarla por tu cuenta en el cliente y pasar el resultado de la llamada a la función 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> } } ... }- Si necesitas configurar un token estático en lugar de recuperarlo desde un parámetro de sesión, te recomendamos que proporciones el token con Secret Manager.
Autenticación mutua de TLS
- Consulta la documentación sobre la autenticación TLS mutua.
- Se admiten certificados de cliente personalizados. Puedes configurar los certificados del 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.
Autenticación de Secret Manager
Si usas OAuth, una clave de API o un token de portador, puedes almacenar las credenciales como secretos con Secret Manager. Estos son los pasos necesarios para autenticar tu herramienta con secretos:
- Crea tu secreto si aún no tienes uno.
- Otorga al agente de servicio de Dialogflow el rol de Usuario con acceso a secretos de Secret Manager (
roles/secretmanager.secretAccessor) en el secreto nuevo. - Copia tu credencial en el portapapeles.
- Agrega una nueva versión del secreto a tu secreto. Pega tu credencial como el valor del Secret.
- Omite cualquier carácter de salto de línea al final.
- Copia el nombre de la versión del secreto que acabas de agregar. El formato del nombre es
projects/{project_id}/secrets/{secret_id}/versions/{version_id}". - Abre la pantalla de edición de la herramienta y, luego, haz lo siguiente:
- Si usas OAuth, selecciona OAuth como Tipo de autenticación y, luego, haz clic en Versión secreta en Secreto de cliente y pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
- Si usas una clave de API, selecciona Clave de API como Tipo de autenticación y, luego, haz clic en Versión secreta en Clave de API. Pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
- Si usas un token portador, selecciona Token portador como Tipo de autenticación y, luego, haz clic en Versión secreta en Token portador. Pega el nombre de la versión secreta en el cuadro de entrada Versión secreta.
- Haz clic en Guardar.
Acceso a redes privadas de la herramienta 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 de OpenAPI
Las entradas de la herramienta de API abierta se derivan de la conversación de los usuarios con el LLM con 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
Para obtener información sobre el uso de herramientas de almacén de datos con un libro de jugadas, consulta la documentación de las herramientas de almacén de datos.
Herramientas de conectores
Un agente puede usar las herramientas de conectores para realizar acciones con tus conexiones configuradas en Integration Connectors. Cada herramienta de conector se configura con una sola conexión y una o más acciones. Si es necesario, se pueden crear varias herramientas para una sola conexión para agrupar diferentes acciones para que las use tu agente.
La herramienta de conectores admite los siguientes tipos de conectores:
- BigQuery
- CloudSQL: SQL Server
- Administración de servicios de Jira
- Base de datos de Oracle
- PayPal
- Salesforce
- Marketing Cloud de Salesforce
- ServiceNow
- SharePoint
- Stripe
- Zendesk
Se deben usar ejemplos para mejorar el uso de las herramientas de conectores por parte del agente, lo que demuestra cómo el agente debe llamar a la herramienta y usar la respuesta.
Crear una conexión
Para crear una conexión y conectarla a tu agente, puedes navegar a Tools > Create, seleccionar el tipo de herramienta Connector, el tipo de conector que elegiste y usar el botón Create Connection. Esto te llevará a la creación de conectores de integración con varios campos completados previamente.
Como alternativa, puedes navegar a Conectores de integración y seguir las instrucciones para crear una conexión.
Acciones del conector
Para cada herramienta de conector, hay dos tipos de acciones que se pueden poner a disposición de tu agente (consulta Entidades, operaciones y acciones para obtener más información):
Operaciones CRUD de entidades
Cada una de tus conexiones tiene "entidades" correspondientes a los objetos de esa fuente de datos (para BigQuery, son tablas; para Salesforce, son objetos, como "Order" o "Case").
Puedes realizar operaciones CRUD en cada entidad:- Create: Crea una entidad con valores de campo especificados.
- List: Búsqueda basada en filtros de instancias de entidades
- Actualizar: Es un método basado en filtros para alterar los valores de los campos de entidad.
- Borrar: Borra una entidad.
- Get recupera una sola entidad con el entityId
Obtén más información sobre los detalles de las operaciones CRUD de entidades en la documentación de Connectors.
- Create: Crea una entidad con valores de campo especificados.
Acciones específicas del conector
Muchos conectores admiten una acción 'ExecuteCustomQuery', que permite ejecutar una consulta de SQL en la fuente de datos, en la que se puede hacer referencia a cada una de las entidades de la fuente de datos como tablas. Consulta esta lista para ver los conectores compatibles.
Las acciones adicionales difieren según el tipo de conector. Por ejemplo, consulta las acciones del conector de BigQuery o las acciones del conector de Salesforce.
Cómo configurar campos de entrada y salida para operaciones CRUD
Si seleccionas campos de entrada o salida específicos para que use la acción de tu 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 (útil si los límites de tokens son un problema) y simplifica el manejo de la salida por parte del agente, ya que solo expone los campos relevantes.
Autenticación
Si la conexión que usas está configurada para permitir la anulación de autenticación, la herramienta se puede configurar para pasar credenciales de los parámetros de sesión especificados.
Como creador del agente, eres responsable de cómo se propagan estas credenciales a los parámetros de sesión, y la herramienta las pasará automáticamente a la fuente de datos para usarlas en la autenticación cuando se llamen a las acciones de la herramienta.
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 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 cliente envía otra solicitud de detección de intents que proporciona el resultado de la herramienta como argumentos de salida.