Herramientas del Agente

En DYPAI, 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 DYPAI resuelva los IDs.

Schemas de entrada

El schema de entrada le dice al LLM qué argumentos puede pasar. DYPAI 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. DYPAI invoca el endpoint tool dentro del mismo proyecto — con el contexto de usuario del agente (así ${current_user_id} y el auth funcionan como siempre).
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. DYPAI incluye varios guardrails, configurables por agente:

Auth dentro de las tools

Las tools heredan el contexto de quien llama. Si un usuario con auth JWT habla con tu agente:

• Cualquier tool que el agente llame corre como ese usuario
• ${current_user_id} en SQL resuelve al ID del usuario
• Se aplican normalmente las reglas de row-level security y los checks de rol
• Un usuario solo puede actuar sobre sus propios datos a través del agente

Esto significa que no necesitas "versiones para agente" separadas de tus endpoints. El endpoint que ya escribiste para GET /my-orders con auth JWT simplemente funciona.

¿Qué endpoints son buenas tools?

Límites

Siguientes pasos