> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sofiachat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Herramientas

> Funciones HTTP que el agente puede ejecutar: catálogo de integraciones, parámetros, pruebas y autenticación.

<Info>Espacios → nodo **Agente** → pestaña **Funciones**, o clic en un nodo **ƒ** del lienzo</Info>

Una **herramienta** (o función) permite al agente *hacer* algo además de responder: consultar el estado de una póliza en tu sistema, buscar un pedido, crear un ticket, agendar una cita. Técnicamente es una llamada HTTP a una URL de tu empresa; el agente decide cuándo usarla según su descripción y le pide al cliente los datos que necesita.

## Crear una herramienta

**+ Nueva función** abre el **catálogo de integraciones**:

* **Catálogo** con plantillas listas por categoría: **CRM** (HubSpot, Salesforce), **Productividad** (Google Sheets, Slack, Email), **Comunicación** (WhatsApp) y **Datos** (PostgreSQL, Webhooks). Al elegir una, la función se crea con URL, método y parámetros ya definidos; solo falta configurar la autenticación.
* **Función HTTP personalizada**: formulario en blanco para tu propia API.

| Campo           | Notas                                                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nombre**      | Corto y descriptivo: *consultar\_saldo*, *buscar\_pedido*.                                                                                                                                                                |
| **Descripción** | **Lo que lee el agente para decidir cuándo usarla.** Escribe cuándo y para qué: *"Consulta el saldo pendiente y la fecha de vencimiento de un cliente a partir de su NIT. Úsala cuando el cliente pregunte cuánto debe."* |
| **URL**         | El endpoint de tu sistema.                                                                                                                                                                                                |
| **Método**      | GET · POST · PUT · DELETE                                                                                                                                                                                                 |
| **Tipo body**   | JSON · Form Data                                                                                                                                                                                                          |

## Configurar una herramienta

Clic en la función abre su ficha con cuatro pestañas:

### Config

Los mismos campos de la creación. **Guardar función** al terminar.

### Parámetros

Los datos que el agente debe obtener (del cliente o del contexto) para llamar a la herramienta. **+ Agregar parámetro**:

| Campo           | Notas                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------- |
| **Nombre**      | Como lo espera tu API (`nit`, `numero_pedido`).                                          |
| **Tipo**        | string · number · boolean · object                                                       |
| **Descripción** | Cómo debe obtenerlo el agente: *"NIT del cliente sin guiones. Pídelo si no lo ha dado."* |
| **Requerido**   | Si está marcado, el agente no llamará a la herramienta sin ese dato.                     |

### Probar

Ejecuta la herramienta con valores de prueba **antes de activarla con clientes**: rellena los parámetros, pulsa **Ejecutar prueba** y revisa el código de estado, la latencia y la respuesta JSON. Una función que responde error aquí, responderá error en la conversación.

### Auth

Si tu API requiere credenciales, asocia un **autenticador**. Las credenciales nunca se muestran al cliente ni al agente; Sofia Chat las inyecta en cada llamada.

| Tipo         | Cómo funciona                                                                          | Campos                                                                                                                                                                                                                           |
| ------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key**  | Una clave fija que se envía en cada petición                                           | Nombre del campo (por defecto `Authorization`), la clave, y dónde va: **Header** o **Query Param**                                                                                                                               |
| **Endpoint** | Sofia Chat obtiene un token llamando a tu endpoint de login y lo renueva cuando caduca | URL y método del login, parámetros (usuario/contraseña u otros), **Token Path** (dónde está el token en la respuesta, p. ej. `data.access_token`), **Refresh Path**, **Tiempo de vida** en segundos, y parámetros personalizados |

Los autenticadores son de la organización: crea uno y reutilízalo en todas las funciones que llamen al mismo sistema. Clic en un autenticador de la lista lo asigna a la función (*· Activo*); otro clic lo quita.

## Eliminar

**Eliminar función** (pie de la ficha) borra la función y su configuración tras confirmar. El agente deja de poder usarla de inmediato.

## Medir

En el [Dashboard](/guia/02-dashboard) las métricas *Cant. Llamadas a Función*, *Tasa de Error de Funciones* y *Tiempo de Ejecución de Funciones* muestran cuánto se usan y si fallan. Una tasa de error que sube de golpe casi siempre es un sistema tuyo caído o una credencial vencida.

<Tip>
  **Empieza con una herramienta de solo lectura** (consultar estado de algo) y compruébala una semana con clientes reales antes de dar al agente herramientas que escriban en tus sistemas (crear tickets, modificar datos).
</Tip>