Herramientas

Con herramientas, un agente no solo responde con el conocimiento: también consulta sistemas y hace acciones, como buscar una póliza por número, crear un ticket o registrar un lead en el CRM. Las credenciales quedan cifradas y cada llamada queda registrada en la conversación.

Para conectar herramientas hace falta el rol Constructor o Administrador. Se hace en dos pasos:

1. En Herramientas, conectás el sistema una vez para todo el workspace.
2. En cada agente, decidís qué acciones puede usar y cuáles piden confirmación.

En Herramientas, hacé clic en «Agregar herramienta» y elegí cómo se conecta el sistema:

Tipo	Cuándo usarlo	Admite
Importar OpenAPI	La API tiene especificación (Swagger u OpenAPI). Cada operación se convierte en una acción.	Swagger 2 u OpenAPI 3, en JSON o YAML
Endpoint HTTP	La API no tiene especificación: indicás la dirección, el método y los parámetros a mano.	REST con JSON
Servidor MCP	Un servidor Model Context Protocol: sus herramientas se descubren solas al conectarlo.	Streamable HTTP

Las tres comparten la sección «Autenticación». Las credenciales se guardan cifradas y no se vuelven a mostrar.

Tipo	Campos
Sin autenticación	Solo para APIs públicas.
Token (Bearer)	Token. Se envía como Authorization: Bearer ….
Clave de API en un encabezado	Encabezado (por defecto X-API-Key) y Clave.
Clave de API en la URL	Parámetro (por defecto api_key) y Clave.
Usuario y contraseña (Basic)	Usuario y Contraseña.

1. Elegí «Importar OpenAPI».
2. En «Especificación», elegí «Pegar» (pegá el JSON o YAML) o «Desde una dirección» (por ejemplo https://api.empresa.com/openapi.json; Sherlock la descarga una sola vez, al importar).
3. Dirección base (opcional): vacía usa la de la especificación. Completala si la especificación usa una dirección relativa o para apuntar a otro ambiente (por ejemplo, el de pruebas).
4. Nombre y descripción: cómo la ve tu equipo al habilitarla en un agente (por ejemplo «API de pólizas»). Si lo dejás vacío, se toma el título de la especificación.
5. Autenticación y «Importar».

Se importan todas las operaciones GET, POST, PUT, PATCH y DELETE, con sus parámetros de ruta, consulta, encabezado y cuerpo. La selección de qué puede usar cada agente se hace después, en el agente.

Para actualizarla, en el detalle de la herramienta → Configuración → «Importar una versión nueva» → «Pegar especificación nueva». Las operaciones se reemplazan y los agentes conservan las que sigan existiendo con el mismo nombre.

Para APIs sin especificación:

1. Dirección base: https://api.empresa.com/v1.
2. Operaciones: hacé clic en «Agregar operación» y completá método (GET, POST, PUT, PATCH, DELETE), ruta (/clientes/{dni}/polizas), «Qué hace» (lo lee el agente para decidir cuándo usarla) y «Detalles» opcionales («El DNI va sin puntos»).
3. Parámetros: nombre, tipo (texto, número, entero, sí/no), dónde va (query, ruta, header, body), si es obligatorio y una descripción. Lo que pongas entre llaves en la ruta, como {dni}, se agrega solo como parámetro de ruta obligatorio.
4. Autenticación y «Crear herramienta».

1. Elegí «Servidor MCP».
2. Dirección del servidor: normalmente termina en /mcp, por ejemplo https://mcp.empresa.com/mcp. El transporte es Streamable HTTP.
3. Autenticación: para servidores MCP usá «Token (Bearer)» o «Clave de API en un encabezado».
4. Nombre y descripción y «Conectar servidor».

Al conectar, Sherlock lista las herramientas del servidor y las guarda. Si el servidor cambia (por ejemplo, después de un despliegue), en el detalle → Configuración → «Actualizar lista».

Hacé clic en una herramienta de la lista para abrir su detalle:

• Operaciones (o Herramientas, en MCP): cada una con su método, ruta, descripción, el «Nombre para el agente» y sus parámetros.
• Probar: escribí los argumentos en JSON y hacé clic en «Ejecutar» (⌘/Ctrl + Enter). Llama a la API real y muestra si «Respondió bien» o «Falló», con la respuesta.
• Configuración: nombre, dirección, descripción y autenticación. Para conservar un secreto guardado, dejá el campo vacío.
• Eliminar herramienta: borra sus credenciales y operaciones. Los agentes que la usan la pierden desde la próxima conversación.

En el Estudio del agente, vista Diseño, pieza Herramientas:

1. En «APIs y servidores MCP», activá la herramienta.
2. En «Operaciones habilitadas», elegí las que puede usar. Si no marcás ninguna, puede usar todas («(todas)»). Conviene habilitar solo las necesarias.
3. Si alguna acción es sensible, activá «Pedir confirmación al usuario antes de ejecutar». Aplica a todas las operaciones habilitadas de esa herramienta.

El agente necesita un modelo que admita herramientas.

Con la confirmación activa, antes de ejecutar el agente le pregunta a la persona:

Para continuar necesito tu confirmación: API de pólizas · actualizarDomicilio (numero: 123456, domicilio: Av. Siempreviva 742). ¿Confirmás? (sí / no)

• Si responde «sí», «dale», «ok», «confirmo» o «adelante», se ejecuta sin volver a preguntar.
• Si responde «no», «cancelar» o «mejor no», el agente contesta «Listo, cancelé la acción. ¿Te ayudo con algo más?».
• Cualquier otra respuesta descarta la acción pendiente y sigue la conversación.

En el panel de prueba del Estudio la acción no queda pendiente: ves el pedido de confirmación, pero no se ejecuta.

Vienen con Sherlock, no necesitan configuración y se activan en cada agente («Herramientas integradas»):

Herramienta	Qué hace
Fecha y hora actual	Devuelve la fecha y hora actual en Argentina (o en otra zona horaria).
Calculadora	Evalúa una expresión aritmética: suma, resta, multiplicación, división, potencias y porcentajes.

Además, según cómo lo configures, cada agente puede buscar en su conocimiento (modo «Cuando lo necesite»), derivar a una persona (Derivación) y consultar a otros agentes (Colaboradores).

• Datos personales. El modelo ve los datos personales como marcadores (<AR_DNI_1>). Sherlock los reemplaza por el valor real solo para ejecutar la herramienta, y enmascara la respuesta de la API antes de devolvérsela al modelo. En la traza, «Datos enviados» y «Respuesta recibida» quedan enmascarados.
• Tiempos. Cada llamada a una API tiene un límite de 25 segundos. En un mismo mensaje el agente puede encadenar hasta 6 rondas de herramientas.
• Respuestas largas. La respuesta de una herramienta se recorta a 8.000 caracteres antes de pasársela al modelo.
• Errores. Si la API responde con error, el agente recibe el código y el mensaje y puede explicárselo a la persona. Todo queda en la traza como «Herramienta · con error».