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

# Tools HTTP personalizadas

> Ejemplo de como crear y usar tools HTTP para conectar tu API

Este ejemplo muestra como crear una tool HTTP que conecte tu agente con una API externa.

## Escenario

Tienes una API de e-commerce y quieres que tu agente pueda consultar el stock de productos.

**Tu API:**

```
GET https://api.tuempresa.com/products/{sku}/stock
Authorization: Bearer tu-token-interno
```

**Respuesta:**

```json theme={null}
{
  "sku": "PROD-001",
  "name": "Camiseta Azul",
  "stock": 42,
  "warehouse": "Lima Central"
}
```

## Paso 1: Crear la tool en la plataforma

1. Ve a **Tools** > **Crear Tool**
2. Configura:

| Campo         | Valor                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| Nombre        | `consultar_stock`                                                                                                    |
| Descripcion   | `Consulta el stock disponible de un producto por su codigo SKU. Retorna cantidad disponible y ubicacion en almacen.` |
| Metodo        | `GET`                                                                                                                |
| URL           | `https://api.tuempresa.com/products/{sku}/stock`                                                                     |
| Requiere auth | `No` (para que funcione en el widget)                                                                                |

3. En **Headers**, agrega:
   * `Authorization`: `Bearer tu-token-interno`

4. Guarda la tool

## Paso 2: Probar en el Studio

1. Ve a **Studio** (click en "Studio" desde la configuracion del agente)
2. En el panel derecho, selecciona la tab **Probar agente**
3. Escribe: "¿Tienen stock de la camiseta PROD-001?"
4. El agente deberia:
   * Detectar que necesita consultar stock
   * Ejecutar `consultar_stock` con SKU=PROD-001
   * Responder con la informacion del stock

## Paso 3: Verificar en el widget

Una vez que funciona en el Studio, el widget automaticamente tendra acceso a la tool (porque `requiresAuth: false`). Tambien puedes verificarlo en la tab **Widget Preview** del Studio.

## Ejemplo: Tool POST

Para tools que envian datos (ej: crear un ticket de soporte):

| Campo         | Valor                                                                                  |
| ------------- | -------------------------------------------------------------------------------------- |
| Nombre        | `crear_ticket`                                                                         |
| Descripcion   | `Crea un ticket de soporte con el asunto y descripcion proporcionados por el usuario.` |
| Metodo        | `POST`                                                                                 |
| URL           | `https://api.tuempresa.com/tickets`                                                    |
| Body template | Ver abajo                                                                              |

**Body template:**

```json theme={null}
{
  "subject": "{asunto}",
  "description": "{descripcion}",
  "priority": "medium"
}
```

El agente completa las variables `{asunto}` y `{descripcion}` automaticamente basandose en la conversacion.

## Ejemplo: Tool con Human-in-the-Loop

Si quieres que el usuario confirme antes de crear el ticket:

1. Crea la tool `crear_ticket` como arriba
2. Ve a **Instrucciones** > **Crear instruccion**
3. Configura:
   * Trigger: `INTENT`
   * Condicion: "El usuario quiere crear un ticket de soporte"
   * Tool asociada: `crear_ticket`
   * Accion: **Confirm** con mensaje "¿Confirmas que quieres crear el ticket de soporte?"

Ahora el flujo sera:

```
Usuario: "Quiero reportar un bug en la facturacion"
Agente: Detecta intent → Se activa instruccion
Widget: "¿Confirmas que quieres crear el ticket?" [No] [Si]
Usuario: "Si"
Agente: Ejecuta crear_ticket → "Tu ticket #1234 ha sido creado exitosamente"
```

## Tips

<Tip>
  **La descripcion de la tool es critica.** El agente la lee para decidir cuando usarla. Se especifico sobre que hace, que parametros necesita y que retorna.
</Tip>

* Prueba siempre en el **Studio** (tab "Probar agente") antes de publicar
* Usa `requiresAuth: true` para tools que acceden a datos sensibles del usuario
* Configura **custom headers** si tu API necesita headers adicionales (version, region, etc.)