Skip to main content
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: 
{
  "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:
CampoValor
Nombreconsultar_stock
DescripcionConsulta el stock disponible de un producto por su codigo SKU. Retorna cantidad disponible y ubicacion en almacen.
MetodoGET
URLhttps://api.tuempresa.com/products/{sku}/stock
Requiere authNo (para que funcione en el widget)
  1. En Headers, agrega:
    • Authorization: Bearer tu-token-interno
  2. 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):
CampoValor
Nombrecrear_ticket
DescripcionCrea un ticket de soporte con el asunto y descripcion proporcionados por el usuario.
MetodoPOST
URLhttps://api.tuempresa.com/tickets
Body templateVer abajo
Body template: 
{
  "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

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.
  • 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.)