Sortie structurée

Quand vous branchez la réponse d'un run directement dans votre code, le texte libre ne suffit pas : le modèle peut ajouter une phrase, oublier un champ ou entourer le JSON de balises Markdown. Avec output_schema, vous décrivez la forme attendue en JSON Schema, et un run réussi porte toujours un output.json conforme, déjà décodé. Sinon il échoue avec un code précis : jamais d'entre-deux.

Sans schéma, rien ne change pour vos runs : output.json vaut simplement null.

Décrire la forme attendue

output_schema est un objet JSON Schema (draft 2020-12). Exemple pour une commande :

{
  "type": "object",
  "properties": {
    "order_id": { "type": "string" },
    "status": { "type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"] },
    "total": { "type": "number" }
  },
  "required": ["order_id", "status", "total"],
  "additionalProperties": false
}

Pour que tous les hébergeurs l'acceptent, restez dans ce sous-ensemble :

• toutes les propriétés dans required ;
• additionalProperties: false sur chaque objet ;
• des types simples (string, number, integer, boolean, enum, tableaux, objets imbriqués) ;
• pas de $ref externe.

leem n'impose pas ce sous-ensemble, mais un hébergeur peut refuser un schéma plus libre (output_schema_rejected, voir plus bas).

Les limites

• La racine est "type": "object".
• 32 Ko au plus une fois encodé en JSON.
• Seuls les $ref locaux (#/$defs/...) sont acceptés. Aucune référence externe n'est jamais résolue, et un $ref qui ne pointe sur rien est refusé.
• Une boucle de $ref qui ne descend jamais dans les données (seulement par allOf, anyOf, oneOf, not, if/then/else ou dependentSchemas) est refusée. Une structure récursive qui descend dans les données, comme un arbre dont items renvoie à #, reste acceptée.
• Le JSON produit est soumis au plafond de sortie (100 000 caractères) et n'est jamais tronqué.

Un schéma invalide est refusé dès la création : 400 invalid_parameter, avec param valant output_schema.

Sur un agent ou sur un run

output_schema se pose sur l'agent (POST ou PATCH /v1/agents) pour un usage stable, ou sur un run (POST /v1/runs) pour le remplacer ponctuellement. Sur un run :

Sur un agent, null retire le schéma. Le schéma effectif est figé sur le run à sa création : modifier l'agent ensuite ne change pas un run déjà créé. GET /v1/runs/{run} renvoie output_schema à true ou false pour dire si un output.json est attendu ; le schéma lui-même n'est pas renvoyé.

Modèles compatibles

La sortie structurée est garantie sur certains modèles seulement : ceux dont structured_output vaut true dans GET /v1/models. Le champ est présent sur chaque modèle, à true ou false :

curl https://leem-api.lcom-corp.com/v1/models -H "Authorization: Bearer $LEEM_API_KEY"

Cette valeur peut changer avec le temps : vérifiez-la de nouveau dans GET /v1/models avant de choisir un modèle, et après un échec output_schema_unsupported.

Avec un autre modèle, la création est refusée en 422 output_schema_unsupported, avant toute consommation : sur POST /v1/runs, et sur POST ou PATCH /v1/agents quand l'appel porte un schéma ou un modèle. Un agent sans modèle explicite n'est vérifié qu'à la création de ses runs.

Exemple complet

Un agent avec un schéma :

curl https://leem-api.lcom-corp.com/v1/agents \
  -X POST \
  -H "Authorization: Bearer $LEEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extracteur de commande",
    "instructions": "Tu extrais les informations de la commande décrite dans le message.",
    "output_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "status": { "type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"] },
        "total": { "type": "number" }
      },
      "required": ["order_id", "status", "total"],
      "additionalProperties": false
    }
  }'

Puis un run de cet agent :

curl https://leem-api.lcom-corp.com/v1/runs \
  -X POST \
  -H "Authorization: Bearer $LEEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agt_01k6examplea0000000000000", "input": "La commande CMD-9912 a été expédiée hier, pour un total de 45000."}'

Une fois le run terminé, GET /v1/runs/{run} renvoie :

{
  "data": {
    "id": "run_01k6exampler000000000000",
    "status": "succeeded",
    "output_schema": true,
    "output": {
      "json": { "order_id": "CMD-9912", "status": "shipped", "total": 45000 },
      "text": "La commande CMD-9912 est expédiée, pour un total de 45000.",
      "files": [],
      "charts": []
    },
    "error": null
  }
}

(Réponse abrégée : les autres champs sont ceux décrits dans Lancer un run.)

output.json est présent partout où le run est présenté : GET /v1/runs/{run}, l'événement terminal du flux SSE et les webhooks. Il n'y a pas de nouvel événement SSE et le JSON n'est pas diffusé morceau par morceau : le flux text.delta reste celui du texte, puis le JSON arrive avec l'événement terminal. output.text est toujours conservé à côté, y compris quand le run échoue après la boucle de l'agent.

Fonctionnement et facturation

1. L'agent travaille comme d'habitude (mêmes tours, mêmes outils). Sa réponse finale devient output.text.
2. Un appel de mise en forme supplémentaire, au même modèle et sans outil, produit le JSON. Il est facturé comme les autres appels.
3. leem valide ce JSON contre le schéma. S'il n'est pas conforme, une seule correction est tentée : c'est un appel de plus, lui aussi facturé.
4. Les crédits consommés le sont même en cas d'échec, corrections comprises. Un appel de mise en forme refusé avant d'être servi (output_schema_rejected, output_schema_unsupported) n'est pas facturé.

Échecs d'un run avec schéma

Un run qui n'obtient pas de JSON conforme est failed, avec l'un de ces error.code :

Dans les trois cas, output.text contient la réponse de l'agent et les crédits utilisés restent débités. La liste complète des codes figure dans Erreurs et limites.

Version 1.2

La sortie structurée est apparue avec la version 1.2 de /v1. Tous les ajouts sont facultatifs : output_schema sur les agents et les runs, output.json et output_schema sur le run, structured_output sur les modèles, 422 output_schema_unsupported et les trois codes d'échec ci-dessus. Un run sans schéma reste inchangé, hormis output.json: null et output_schema: false.