Made for Agent
Idioma: Español

Reglas comunes

9.1 Versiones y extensiones

Cada solicitud LMSP PUEDE llevar estas cabeceras:

LMSP-Version: 1.0
LMSP-Client: example-client/1.2.0

LMSP-Version es la versión del protocolo a la que se dirige el cliente. LMSP-Client identifica el software cliente con fines de diagnóstico, como name/version. Un servicio NO DEBE cambiar el comportamiento del protocolo en función de esta última.

Reglas:

  • La v1 de la ruta indica la versión mayor.
  • Una solicitud que nombra una versión mayor desconocida se responde con 426 Upgrade Required y el código de error unsupported_protocol_version.
  • Los nuevos campos opcionales NO DEBEN romper la compatibilidad 1.x.
  • Los servicios y los clientes DEBEN ignorar los campos que no conocen.
  • Las extensiones privadas van en un objeto extensions y se nombran con notación de dominio inverso:
{
  "extensions": {
    "com.example.cache": {
      "enabled": true
    }
  }
}

9.2 Idempotencia

Las solicitudes que crean algo, como crear una respuesta, crear una tarea o cargar un modelo, aceptan una clave de idempotencia:

Idempotency-Key: <client-generated-unique-value>

El servicio almacena la clave junto con un resumen criptográfico del cuerpo de la solicitud y el resultado:

  • La misma clave con el mismo cuerpo devuelve el resultado original.
  • La misma clave con un cuerpo distinto se responde con 409 Conflict y idempotency_conflict.

Una clave se limita al cliente y al endpoint. DEBERÍA ser un valor único de como máximo 255 caracteres, como un ULID o un UUID. Un servicio DEBERÍA conservar las claves al menos 24 horas.

Un servicio PUEDE ignorar la clave en las solicitudes en streaming. Un cliente que necesita reintentos seguros usa una tarea.

9.3 Errores

Todo error de la interfaz LMSP usa application/problem+json (RFC 9457):

{
  "type": "urn:lmsp:error:model-not-found",
  "title": "Model not found",
  "status": 404,
  "code": "model_not_found",
  "detail": "No local model with id 'qwen3:14b-q4_k_m'",
  "request_id": "req_01J8M9S6Y4W8C3P5R1V7Z2A0DH",
  "retryable": false
}
Campo Obligatorio Significado
type Sí URI que identifica el tipo de error. LMSP usa urn:lmsp:error: seguido del código con guiones en lugar de guiones bajos.
title Sí Resumen breve y legible.
status Sí El código de estado HTTP.
code Sí Código de error legible por máquina, de la lista siguiente.
detail No Explicación legible de esta ocurrencia. NO DEBE contener secretos, prompts ni contenido generado.
request_id No Identificador de la solicitud, para correlacionarla con los registros del servicio.
retryable Sí Si repetir la solicitud más tarde puede tener éxito.

Códigos de error habituales:

Código Estado HTTP Reintentable Significado
invalid_request 400 No La solicitud está mal formada o tiene parámetros no válidos.
unauthorized 401 No Falta el token, no es válido, ha caducado o se ha revocado, o un código de emparejamiento es incorrecto.
forbidden 403 No El token no tiene el ámbito necesario, o falló la comprobación de Origin o Host.
model_not_found 404 No Ningún modelo local tiene este id.
model_not_ready 409 Sí El modelo no está cargado y no se carga bajo demanda.
model_load_failed 500 Sí Falló la carga del modelo.
context_length_exceeded 400 No La entrada no cabe en la ventana de contexto del modelo.
unsupported_capability 400 o 501 No El modelo o el servicio no admite lo que necesita la solicitud. Un endpoint opcional no implementado responde 501.
unsupported_protocol_version 426 No El servicio no admite la versión mayor solicitada.
response_not_found 404 No Ninguna respuesta almacenada tiene este id.
task_not_found 404 No Ninguna tarea tiene este id.
task_not_cancelable 409 No La tarea ya ha terminado correctamente o con un fallo.
idempotency_conflict 409 No La clave de idempotencia ya se usó con un cuerpo de solicitud distinto.
event_history_expired 410 No Los eventos solicitados son anteriores al período de retención.
rate_limited 429 Sí Demasiadas solicitudes.
resource_exhausted 503 Sí Al dispositivo se le acabó la memoria u otro recurso.
backend_unavailable 503 Sí No se puede acceder al entorno de ejecución del modelo.
server_restarted 503 Sí El servicio se reinició mientras la tarea estaba sin terminar.
internal_error 500 Varía Un fallo inesperado dentro del servicio.

El campo retryable es el que prevalece. La columna anterior muestra el valor habitual. Un servicio PUEDE definir más códigos. Un cliente DEBE tratar un código que no conoce según su estado HTTP y su campo retryable.

9.4 Comprobación de estado

GET /lmsp/v1/health
{
  "status": "ready",
  "service_id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
  "uptime_seconds": 86420,
  "loaded_models": 1,
  "active_tasks": 2,
  "storage": "ok"
}
Campo Significado
status starting, ready, degraded o stopping.
service_id El id del servicio de la descripción del servicio.
uptime_seconds Segundos desde que se inició el servicio.
loaded_models Número de modelos en estado ready.
active_tasks Número de tareas que están queued, loading, running o cancelling.
storage ok o error.

El estado HTTP es 200 OK cuando status es ready o degraded, y 503 Service Unavailable en caso contrario.

El endpoint de estado devuelve solo el estado operativo. NO DEBE devolver rutas de modelos, prompts, tokens de acceso ni otra información sensible.