Tâches asynchrones

7.1 Créer une tâche

Un client crée une tâche en envoyant en POST la requête de réponse qu’il veut exécuter, enveloppée dans une enveloppe de tâche. Un en-tête Idempotency-Key est recommandé (section 9.2).

POST /lmsp/v1/tasks
Authorization: Bearer <token>
Idempotency-Key: 01J8M7C4Y3N5P8R2T6V9X1Z4BH

{
  "type": "response",
  "input": {
    "model": "qwen3:14b-q4_k_m",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Write a long report."
          }
        ]
      }
    ]
  },
  "on_restart": "fail"
}

Le service DOIT persister la tâche avant de répondre. Il renvoie ensuite :

HTTP/1.1 202 Accepted

{
  "id": "task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC",
  "object": "task",
  "type": "response",
  "status": "queued",
  "created_at": 1794200100,
  "updated_at": 1794200100,
  "response_id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW",
  "events_url": "/lmsp/v1/tasks/task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC/events",
  "on_restart": "fail",
  "response": null,
  "error": null
}

GET /lmsp/v1/tasks/{task_id} renvoie l’objet tâche. Les clients qui n’utilisent pas les flux d’événements interrogent régulièrement ce point de terminaison. Un identifiant inconnu donne 404 avec task_not_found. Une tâche terminée ressemble à ceci :

{
  "id": "task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC",
  "object": "task",
  "type": "response",
  "status": "succeeded",
  "created_at": 1794200100,
  "updated_at": 1794200162,
  "response_id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW",
  "events_url": "/lmsp/v1/tasks/task_01J8M8R5X3V7B2N4Q9T1W6Y0ZC/events",
  "on_restart": "fail",
  "response": {
    "id": "resp_01J8M8R5X4B9D2F6H1K3N7Q0ZW",
    "object": "response",
    "created_at": 1794200100,
    "status": "completed",
    "model": "qwen3:14b-q4_k_m",
    "output": [
      {
        "id": "msg_01J8M8R6A2C5E8G1J4M7P0S3VY",
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "Local model services make on-device inference a shared, discoverable utility..."
          }
        ]
      }
    ],
    "usage": {
      "input_tokens": 12,
      "output_tokens": 1480,
      "total_tokens": 1492
    },
    "error": null,
    "incomplete_details": null
  },
  "error": null
}

7.2 Machine à états

queued --> loading --> running --> succeeded
  |           |           |
  |           |           +--> failed
  |           |           +--> cancelling --> cancelled
  |           +--------------> failed
  +--------------------------> cancelled

Les états terminaux sont succeeded, failed et cancelled. Une tâche dans un état terminal NE DOIT PAS changer de nouveau. Une tâche dont la réponse se termine à l’état incomplete, par exemple à la limite de tokens, est succeeded.

Chaque transition est atomique, si bien qu’une tâche n’est jamais à la fois annulée et terminée. La première transition validée l’emporte.

7.3 Annulation

POST /lmsp/v1/tasks/{task_id}/cancel

Le service renvoie 200 OK et l’objet tâche courant. Une tâche queued passe immédiatement à cancelled. Une tâche loading ou running passe à cancelling jusqu’à l’arrêt du backend, puis à cancelled.

L’annulation DOIT être idempotente. Annuler une tâche déjà cancelling ou cancelled renvoie la tâche courante et ne produit aucune nouvelle erreur.

Annuler une tâche qui a déjà succeeded ou failed reçoit la réponse 409 avec task_not_cancelable. Un identifiant inconnu donne 404 avec task_not_found.

7.4 Flux d’événements

GET /lmsp/v1/tasks/{task_id}/events
Accept: text/event-stream

Ce point de terminaison est facultatif. Il est disponible lorsque la capacité event_resume vaut true.

• Les événements sont les événements de réponse de la section 6.3, pour la réponse que produit la tâche. La numérotation et la reprise suivent la section 6.4.
• Le flux commence par response.created, qui est enregistré à l’acceptation de la tâche. Il se termine par un seul événement final qui correspond à l’issue : response.completed, response.incomplete, response.failed ou response.cancelled.
• Un client qui se connecte tardivement reçoit d’abord les événements qu’il a manqués, puis les événements en direct. Le service ferme le flux après l’événement final.
• Les événements sont conservés pendant une durée de conservation (section 11.2). Les événements plus anciens donnent 410 Gone avec event_history_expired.

7.5 Sémantique du redémarrage

on_restart indique ce qui arrive à une tâche inachevée lorsque le service redémarre :

Une tâche à l’état cancelling lors du redémarrage du service achève son annulation et passe à cancelled, quelle que soit sa politique.

retry n’est pas recommandé comme valeur par défaut, car la tâche a peut-être déjà exécuté des outils ou produit des effets de bord externes. Un client qui choisit retry DOIT le combiner avec un Idempotency-Key et rendre idempotents ses appels d’outils.