Agentes en la API

Desde tu backend, con un access token, puedes saber qué agentes alcanza el token, qué tools tiene cada uno y si identifica a su usuario. Es de solo lectura: para hablar con un agente, la vía es su canal público, el widget o el SDK.

Los dos endpoints están también en /api/openapi.json y en el navegador de /api/docs de tu instancia, con sus esquemas campo a campo.

GET /api/agents

Los agentes que puede usar tu token, ordenados por nombre, y de cada uno los nombres de sus tools. Como en el resto de listados, lo que el token no permite no aparece (sin 403).

curl https://ur.tuempresa.com/api/agents \
  -H "Authorization: Bearer $UR_TOKEN"

[
  {
    "id": "0190c2a4-…",
    "name": "Soporte",
    "identifier": "soporte",
    "auth": {
      "mode": "optional",
      "issuer": {
        "issuer": "https://mi-app.example.com",
        "audience": "ur-soporte",
        "algorithms": ["ES256"]
      }
    },
    "tools": [
      { "name": "buscar_pedido", "requiresEndUser": true },
      { "name": "calculadora", "requiresEndUser": false }
    ]
  }
]

tools trae las que el agente puede llamar de verdad: si un administrador desactiva la plantilla de una tool en el catálogo, deja de salir aunque siga asignada. Un agente sin tools trae []. Cada una sale por el nombre de su instancia: una de búsqueda en RAG (rag_retrieve) le ofrece además al modelo <nombre>_list_paths, _list_tags, _process_file y _get_link. Con requiresEndUser: true, la tool solo existe para un usuario identificado: en una conversación anónima el modelo ni la ve.

auth dice si el agente identifica a su usuario y qué token acepta, lo justo para que tu backend sepa firmarlo:

• mode: off (anónimo), optional (anónimo o identificado) o required (sin un token válido, el canal responde 401).
• issuer: el iss que tiene que llevar el token (null si no se comprueba), su aud y los algoritmos con que puede ir firmado. Es null con mode: "off". Nunca trae claves ni secretos: ur no firma tokens, solo dice cuáles acepta.

GET /api/agents/{identifier}

Comprueba que el agente existe y que tu token puede usarlo. Devuelve lo mismo que un elemento del listado.

curl https://ur.tuempresa.com/api/agents/soporte \
  -H "Authorization: Bearer $UR_TOKEN"

{
  "id": "0190c2a4-…",
  "name": "Soporte",
  "identifier": "soporte",
  "auth": { "mode": "off", "issuer": null },
  "tools": [{ "name": "calculadora", "requiresEndUser": false }]
}

Aquí va el slug, no el UUID

En el widget y el SDK puedes usar indistintamente el identifier o el id del agente. En este endpoint solo se resuelve por identifier; un UUID devuelve 404.

Errores

Código	Cuándo
401	Token ausente o inválido; {"error":"Token expired"} si ya caducó
403	El token no tiene permiso sobre este agente
404	No existe ningún agente con ese identifier
429	Superado el límite por minuto del usuario dueño del token. Retry-After dice cuánto esperar