Herramientas

Las herramientas permiten que un agente haga más que responder con texto: verificar el estado de un pedido, buscar a un cliente en tu CRM, crear un ticket o leer un archivo de Google Drive. El modelo decide cuándo llamar a una herramienta a partir de su nombre y su descripción.

Hay tres tipos, y cada uno se encuentra en Build, en la barra lateral:

Tipo	Dónde	Qué es
Herramientas personalizadas	Tools	Un endpoint HTTP tuyo, descrito para que el agente pueda llamarlo.
Herramientas predefinidas	Predefined Tools	Capacidades integradas que se incluyen con VirtuAI.
Servidores MCP	MCP Servers	Herramientas de un servidor que usa el Model Context Protocol, incluidos servidores listos para usar de Google, GitHub, Slack y HubSpot.

Una herramienta no hace nada hasta que se adjunta a un agente. Adjunta herramientas, herramientas predefinidas y servidores MCP en el lienzo visual del agente.

Herramientas personalizadas

Abre Tools y selecciona Add tool.

Información básica

Campo	Qué hace
Tool Name	Obligatorio. El nombre que ve el modelo, por ejemplo, get_order_status. Letras, números, guiones bajos y guiones, hasta 128 caracteres.
LLM Description	Obligatorio. Le indica al modelo qué hace la herramienta y cuándo llamarla. No se muestra a los usuarios.
Visual Description	Opcional. Una descripción breve para los usuarios que se muestra en las listas de herramientas. Hasta 180 caracteres.

Configuración de la API

Campo	Qué hace
API Endpoint	Obligatorio. La URL a la que se llama. Puede contener parámetros, por ejemplo, https://api.example.com/orders/{{order_id}}.
HTTP Method	GET, POST, PUT, DELETE o PATCH.
Timeout (seconds)	De 1 a 300. El valor predeterminado es 30.
Headers (JSON)	Encabezados que se envían con cada llamada, como un objeto JSON. Los valores pueden contener parámetros con la misma forma {{name}}.
Authentication	None o Google Cloud Run (IAM / Service Account).

Con Google Cloud Run (IAM / Service Account), VirtuAI firma cada llamada con un token de identidad para el host del endpoint, mediante la cuenta de servicio de Cloud Run guardada en la configuración del espacio de trabajo como CLOUD_RUN_SERVICE_ACCOUNT_JSON. Otorga a esa cuenta de servicio el rol de invocador de Cloud Run (Cloud Run Invoker) en el servicio de destino.

Precaución

Los valores de los encabezados se almacenan con la herramienta, y cualquier persona que pueda editar herramientas en el espacio de trabajo (tools.edit) puede leerlos. Quienes solo pueden ver herramientas ven los nombres de los encabezados, con los valores enmascarados. Prefiere la autenticación de IAM de Cloud Run o una clave limitada exactamente a lo que la herramienta necesita.

Parámetros

Los parámetros son las entradas que el modelo completa cuando llama a la herramienta. Selecciona Add Parameter para cada uno.

Campo	Qué hace
Name	El nombre del parámetro, por ejemplo, order_id.
Type	string, integer, number, boolean, array u object.
Description	Qué es el valor y su formato, por ejemplo, “Número de pedido, como ORD-1234”. El modelo lee esto.
Required	Si el modelo siempre debe proporcionarlo.

Cómo se envían los parámetros:

• Un parámetro escrito en el endpoint o en un encabezado como {{name}} se sustituye allí.
• Los parámetros restantes van en la cadena de consulta para GET y DELETE, y en un cuerpo JSON para POST, PUT y PATCH. Para un cuerpo JSON, se agrega Content-Type: application/json, a menos que lo establezcas tú.

La tarjeta Preview muestra el método, el endpoint, el tiempo de espera y los nombres de los parámetros mientras escribes.

Qué recibe el agente

• Una respuesta JSON se pasa al agente tal como está. Cualquier otra respuesta se pasa como texto.
• Un error HTTP (estado 400 o superior), un tiempo de espera agotado o una falla de conexión llegan al agente como un mensaje de error que puede explicar o del que puede recuperarse. Las herramientas creadas con este formulario no se reintentan si fallan.
• Si el widget de voz web usa tu API, esta también puede devolver datos para que el widget los muestre.

Cómo escribir buenas herramientas

El modelo decide cuándo llamar a una herramienta, y con qué datos, a partir de su nombre, su descripción y las descripciones de sus parámetros. Sé explícito:

• Indica qué hace la herramienta y cuándo usarla; por ejemplo, “Úsala cuando el cliente pregunte dónde está su pedido”.
• Describe cada entrada y su formato, con un ejemplo.
• Describe lo que se devuelve, incluidos los casos de error.
• Mantén una acción por herramienta. get_order y cancel_order son más fáciles de usar correctamente que una sola herramienta order con un selector de modo.

Antes de que el agente entre en producción, prueba cada herramienta en el chat, incluida una llamada en la que la herramienta falle. Para detectar un agente que responde sin llamar a la herramienta, agrega la herramienta a un caso de evaluación con el evaluador tool_trajectory.

Herramientas predefinidas

Predefined Tools enumera las herramientas integradas. No puedes cambiar lo que hacen; el ícono de lápiz edita la Visual description for users que se muestra en las listas de herramientas (hasta 180 caracteres).

Herramientas	Qué hacen
reminder_tool, list_reminders_tool, delete_reminder_tool	Crean, enumeran y borran recordatorios para la conversación actual, únicos o recurrentes (diarios, semanales o mensuales). Los recordatorios funcionan en Google Chat; en otros canales, el agente le indica al usuario que no son compatibles.
builder_*	Crean y configuran agentes, herramientas, bases de conocimiento, servidores MCP y conjuntos de datos de evaluación. Son la base del Agent Builder.
browser__*	Controlan un navegador Chrome: navegar, buscar, hacer clic, escribir, desplazarse, completar formularios, extraer contenido, tomar capturas de pantalla y guardar páginas como PDF. Necesitan una sesión del navegador conectada a través de la CLI de VirtuAI.

Precaución

Las herramientas builder_* permiten que un agente cree y modifique otros agentes en tu espacio de trabajo. Adjúntalas solo a los agentes que usan los administradores del espacio de trabajo.

Servidores MCP

El Model Context Protocol (MCP) es un estándar abierto para exponer herramientas a los agentes de IA. Un servidor MCP que se agrega a tu espacio de trabajo se puede adjuntar a cualquier agente, y sus herramientas se convierten en herramientas del agente.

Abre MCP Servers y crea un servidor. Elige Predefined o Custom.

Servidores predefinidos

Servidores listos para usar en los que cada usuario accede con su propia cuenta:

Grupo	Servidores
Google Workspace	Gmail, Google Drive, Google Calendar, Google Chat, Google Contacts
Google Cloud · Datos y análisis	BigQuery, Pub/Sub, Firestore, Bigtable, Dataproc (Managed Spark)
Google Cloud · Almacenamiento y procesamiento	Cloud Storage, Compute Engine, Cloud Run, Google Kubernetes Engine, Memorystore (Redis)
Google Cloud · Bases de datos	Cloud SQL, AlloyDB, Cloud Spanner, Database Center
Google Cloud · Observabilidad	Cloud Logging, Cloud Monitoring, Cloud Trace, Error Reporting
Herramientas para desarrolladores	GitHub
Comunicación	Slack
CRM	HubSpot

1. Ingresa un Server Name (letras, números, guiones bajos y guiones, hasta 128 caracteres) y una Description.
2. Selecciona el servicio. El formulario enumera los Required OAuth Scopes.
3. Selecciona Create Server y adjunta el servidor a un agente.

Antes de que los usuarios puedan conectarse, un administrador del espacio de trabajo debe agregar el cliente de OAuth del proveedor en la configuración del espacio de trabajo:

Proveedor	Configuración
Google	GOOGLE_MCP_CLIENT_ID, GOOGLE_MCP_CLIENT_SECRET, GOOGLE_MCP_REDIRECT_URI
GitHub	GITHUB_MCP_CLIENT_ID, GITHUB_MCP_CLIENT_SECRET
Slack	SLACK_MCP_CLIENT_ID, SLACK_MCP_CLIENT_SECRET
HubSpot	HUBSPOT_MCP_CLIENT_ID, HUBSPOT_MCP_CLIENT_SECRET

Para Google, crea un cliente de OAuth de tipo aplicación web en la consola de Google Cloud y registra allí el URI de redireccionamiento, por ejemplo, https://yourdomain.com/api/oauth/google/callback.

Luego, los usuarios conectan su propia cuenta desde el menú de herramientas del agente en el chat web. El token de cada usuario se almacena por separado, por lo que el agente actúa con los permisos de la persona con la que está hablando, y un solo consentimiento abarca todos los servicios del mismo proveedor.

Servidores personalizados

Para cualquier otro servidor MCP, pega su conexión como JSON en Configuration (JSON). Se admiten tres transportes: streamable_http, sse y stdio.

Un servidor remoto mediante HTTP:

{
  "transport": "streamable_http",
  "url": "https://mcp.example.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_TOKEN" }
}

Un servidor que se inicia como un comando:

{
  "transport": "stdio",
  "command": "npx",
  "args": ["@some/mcp-server"],
  "env": { "API_KEY": "..." }
}

Elegir qué herramientas ve un agente

Después de guardar el servidor, vuelve a abrirlo y selecciona List tools para ver lo que ofrece. De forma predeterminada, todas las herramientas están disponibles para los agentes. Desmarca las que no necesites, o usa Enable all y Disable all, y luego selecciona Save Changes.

La definición de cada herramienta se envía al modelo en cada turno, por lo que inhabilitar las herramientas que no usas ahorra contexto y facilita que se elija la correcta. Si la lista se obtuvo sin una cuenta autorizada, algunos servidores devuelven menos herramientas; conecta la integración y selecciona Refresh.