Herramientas del Agente

En HeroMate, las tools son endpoints. Cualquier endpoint que ya tengas — una query SQL, un workflow que cobra una tarjeta, una función que envía un email — lo puedes activar como tool. El agente lee su descripción, decide cuándo llamarlo y recibe lo que el endpoint devuelva.

Esto significa que no escribes "tools del agente" aparte de tu app. El mismo endpoint list_products que tu frontend en React llama con useEndpoint() puede ser llamado por el agente dentro de una conversación.

Convertir un endpoint en tool

Definirlo vía YAML / MCP

Cuando tú (o tu asistente IA) defines un agente en YAML o a través del MCP, referencias las tools por su nombre de endpoint, no por UUID:

agent:
  provider: DYPAI Managed
  model: gpt-5-nano
  tools: [list_tasks, create_task]

El codec mapea esos nombres a los tool_ids (UUIDs) subyacentes automáticamente, y los vuelve a mapear a nombres cuando lee el workflow. No escribas tool_ids a mano con nombres dentro — pon los nombres de endpoint bajo tools y deja que HeroMate resuelva los IDs.

Schemas de entrada

El schema de entrada le dice al LLM qué argumentos puede pasar. HeroMate usa JSON Schema estándar.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Término de búsqueda para el nombre del producto"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "books"],
      "description": "Filtro opcional por categoría"
    },
    "max_price": {
      "type": "number",
      "description": "Precio máximo en EUR"
    }
  },
  "required": ["query"]
}

Consejos para buenos schemas:

• Usa description en cada campo. El LLM los lee.
• Usa enum para restringir opciones cuando hay una lista fija — el LLM no inventará valores.
• Marca los campos obligatorios para que el LLM sepa qué debe proporcionar.
• Simple. Un schema con 20 campos opcionales suele indicar que la tool debería partirse en dos.

Cómo usa el agente una tool

Cuando el agente decide llamar a una tool:

1. El LLM genera los argumentos que encajan con el schema de entrada.
2. HeroMate ejecuta el flujo de la tool dentro del mismo proyecto con el contexto del usuario que llamó al agente. No hace una nueva petición HTTP ni vuelve a aplicar la autenticación o los roles del endpoint de la tool.
3. El endpoint devuelve su respuesta normal.
4. Esa respuesta se devuelve al LLM como resultado de tool.
5. El agente decide si llamar a otra tool o producir la respuesta final.

Todo esto ocurre dentro de una sola ejecución. Tu frontend ve una única respuesta en streaming, no cinco peticiones separadas.

Guardrails

Los agentes pueden causar mucho daño si entran en bucle infinito o llaman a tools sin límite. HeroMate incluye varios guardrails, configurables por agente:

Auth dentro de las tools

Exige autenticación JWT en el endpoint del agente cuando las tools necesiten una identidad verificada y limita sus roles permitidos si corresponde. Las tools heredan el contexto de ese usuario: ${current_user_id} en SQL resuelve a su ID. Sin embargo, la llamada ejecuta directamente el flujo de la tool, sin volver a aplicar el modo de autenticación HTTP ni los roles permitidos del endpoint de la tool. HeroMate tampoco dispone de seguridad a nivel de fila (RLS).

Cada flujo usado como tool debe comprobar el rol del usuario y limitar las lecturas y escrituras a sus registros autorizados. Puedes reutilizar GET /my-orders desde la app y el agente, pero la protección JWT de su ruta HTTP por sí sola no protege la llamada interna: aplica esos controles dentro del flujo.

¿Qué endpoints son buenas tools?

Límites

Siguientes pasos