Herramientas de agente personalizadas

Dé a la IA acceso en tiempo real a sus sistemas: defina herramientas que el LLM puede llamar durante la generación de respuestas para obtener el estado de pedidos, consultar cuentas, verificar inventario y más.

Datos rápidos#

Para la visión conceptual, consulte la guía de herramientas de agente. Esta página es la referencia técnica.

Anatomía de una herramienta#

Una definición de herramienta tiene estos campos:

Ejemplo práctico — get_order_status (SERVER_SIDE)#

Definición de la herramienta

Esquema de parámetros (JSON Schema)

{
  "type": "object",
  "properties": {
    "order_number": {
      "type": "string",
      "description": "The customer's order number, e.g. ORD-10432"
    }
  },
  "required": ["order_number"]
}

Solicitud que recibe su endpoint

En una llamada a la herramienta, HelpStack envía los argumentos proporcionados por el LLM como cuerpo de la solicitud (para POST/PUT/PATCH), con sus cabeceras configuradas más Content-Type: application/json:

POST /orders/status HTTP/1.1
Host: api.YOURCOMPANY.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{ "order_number": "ORD-10432" }

Contrato de respuesta que debe respetar su endpoint

Devuelva JSON que el modelo pueda leer. Manténgalo pequeño — las respuestas están limitadas a ~10 KB y la llamada expira en ~10s.

{
  "status": "shipped",
  "carrier": "DHL",
  "tracking_number": "JD0140...",
  "estimated_delivery": "2026-06-02"
}

La IA recibe este payload como resultado de la herramienta y lo incorpora en su respuesta. No hay un envoltorio requerido — devuelva los campos que sean útiles, pero hágalos autodescriptivos para que el modelo los use correctamente.

Cómo escribir buenas descripciones#

La descripción es el campo más importante — es lo único que usa el LLM para decidir si y cuándo llamar a la herramienta.

• Indique qué devuelve la herramienta y cuándo llamarla ("Llama a esto cuando el cliente pregunte ...").
• Mencione las frases que los clientes realmente usan.
• Describa cada parámetro claramente en el description de su esquema.
• Mantenga el límite de ~2000 caracteres (el diálogo de guardado valida y muestra errores).

Seguridad y protección contra SSRF#

• Solo HTTPS. Las URLs HTTP sin cifrar son rechazadas.
• Lista de bloqueo SSRF. Los objetivos de red interna/privada (loopback, rangos RFC1918 privados, enlace local, endpoints de metadatos) están bloqueados para que una herramienta no pueda apuntar a infraestructura interna.
• Cabeceras secretas. Ponga claves de API/tokens en Headers, que pueden cifrarse/enmascararse en lugar de almacenarse en texto plano.
• Trate el endpoint de la herramienta como accesible desde Internet — autentique las solicitudes (p. ej. un token bearer en Headers) y valide la entrada en su lado.

Tiempos de espera y límites#

Los fallos degradan con elegancia — una herramienta rota o lenta nunca bloquea una respuesta; la IA simplemente continúa sin esos datos.

Herramientas de organización vs. de canal + filtrado semántico#

• Las herramientas pueden definirse a nivel de organización y a nivel de canal.
• Para una conversación dada, las herramientas de nivel de organización y de canal se fusionan, y una herramienta de canal reemplaza a una herramienta de organización con el mismo nombre.
• El conjunto fusionado se filtra semánticamente por relevancia para la consulta del cliente, de modo que un catálogo grande de herramientas no sobrecarga cada llamada al LLM — solo se ofrecen las herramientas relevantes.
• Las herramientas seleccionadas se convierten en definiciones de función de OpenAI/Anthropic y se ofrecen durante la generación de respuestas.

Importación desde OpenAPI#

Puede crear herramientas a partir de una API existente: pegue o suba una especificación OpenAPI 3.0 y HelpStack extrae sus operaciones en definiciones de herramienta que usted revisa y guarda. Esta es la forma más rápida de exponer una API REST existente a la IA.

Registro#

Cada llamada a una herramienta se registra en ToolCallLog. Vea el historial de llamadas de una herramienta (argumentos, resultado, tiempo) mediante:

GET /api/agent-tools/[id]/logs

Use los registros para depurar por qué una herramienta fue o no fue llamada, y para detectar tiempos de espera/errores.

Herramientas del lado del cliente (avanzado)#

Las herramientas CLIENT_SIDE se declaran de la misma manera (nombre, descripción, esquema de parámetros) pero se ejecutan en el navegador del visitante del sitio web, mediadas por el socket del widget:

1. La IA emite una llamada a herramienta para una herramienta CLIENT_SIDE.
2. El servidor emite tool:execute al widget.
3. El widget la ejecuta y responde con tool:result (o tool:error).
4. Hay un tiempo de espera de ~5s; en caso de tiempo de espera la llamada degrada con elegancia (herramienta no disponible).

No existe una API JS pública para registrar manejadores de herramientas del lado del cliente en el loader del widget hoy en día. La ejecución del lado del cliente está mediada por el servidor/iframe — trátela como una capacidad avanzada y no espere un fragmento estilo registerTool() en su página. Consulte Inserción del widget.

Relacionado#

• Guía de herramientas de agente
• Referencia de la API
• Inserción del widget
• Glosario