Referencias a recursos

Las instructions de una habilidad o de una regla pueden citar recursos con la misma sintaxis que usa el chat de NiuCore. Una habilidad que dice «buscá en {{workspace:31}} antes de responder» no solo nombra la biblioteca: cuando se adjunta a un turno, la lleva con ella.

{
  "name": "Responder reclamos",
  "instructions": "Antes de responder, buscá la política vigente en {{workspace:31}} y, si el cliente pide un reintegro, usá la plantilla de {{file:902}}. Seguí además {{skill:147}}.",
  "level": "company",
  "visibility": "public"
}

#Sintaxis

• El separador puede ser : o -; al guardar se reescribe siempre con :, así que el GET te devuelve la forma canónica ({{skill-3}} → {{skill:3}}).
• Solo cuentan los tipos de la tabla, en minúsculas. {{cliente}} o {{Skill:3}} quedan como texto literal: son tus propias variables.
• Hasta 20 referencias distintas por tipo y 60 en total por texto.

#Validación al guardar

POST y PATCH sobre /skills y /rules validan las referencias antes de escribir nada, contra los permisos del usuario dueño de la credencial. Si alguna no pasa, responden 422 prompt_refs_invalid y la habilidad o regla queda como estaba.

{
  "status": "error",
  "message": "Hay referencias no disponibles o inválidas en el texto.",
  "message_code": "prompt_refs_invalid",
  "data": [
    {
      "denied": [{ "type": "workspace", "id": 88 }],
      "invalid": ["{{file:abc}}"],
      "unsupported": ["{{agent:5}}"],
      "over_limit": [],
      "cycle": []
    }
  ],
  "meta": { "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77" }
}

• Un PATCH que no cambia instructions no revalida nada: podés renombrar una habilidad aunque cite un recurso que después se revocó.
• Si cambiás el texto, se revalidan todas las referencias, también las que ya estaban. Un token inválido o no admitido que ya estaba guardado se conserva, para no impedirte editar el resto.
• instructions tiene un máximo de 12 000 caracteres en una habilidad y 4 000 en una regla; pasarse devuelve 422 prompt_text_too_long.

#En un turno de la API

Cuando adjuntás una habilidad con attachments.skill_ids, el turno recibe su contenido con las citas resueltas, y las bibliotecas, archivos, habilidades, conectores y herramientas que cita se suman al turno — pero solo los que están dentro del alcance de tu credencial. Una credencial limitada a la biblioteca 31 no alcanza la 88 porque una habilidad la nombre: esa cita se omite en silencio.

• Las citas a personas y contextos compartidos no llegan a un turno de la API: la credencial no tiene esos tipos de recurso.
• Adjuntar recursos sigue exigiendo su scope compañero (libraries:read, skills:read, connectors:use). Lo que suma una habilidad nunca excede lo que la credencial ya podía adjuntar.
• Los tokens {{…}} escritos directamente en content no son un canal soportado: usá attachments. Un token en content que apunte fuera del alcance de la credencial hace fallar el turno.

#Agentes