🇬🇧 English version
Format de réponse LLM
Forcer la sortie JSON à la frontière du provider plutôt que de rafistoler les prompts. Un seul value object,
LlmResponseFormat, est traduit par chaque provider selon ce que son API déclare pouvoir honorer.
Pourquoi
La plupart des API LLM savent contraindre la forme d'une réponse au niveau de la couche API.
Demandez response_format: {"type": "json_object"} Ă DeepSeek et l'API garantit du JSON
valide — pas d'accolades {/} cassĂ©es, pas de prose en prĂ©ambule ; demandez un JSON Schema Ă
OpenAI, Gemini ou Anthropic et le vendeur valide la réponse contre ce schéma côté serveur.
C'est une seconde barrière qui complète la grammaire GBNF (serveurs compatibles llama.cpp, derrière
Llm:Grammar) et le StructuredOutputResolver en aval.
Pour Orkeon, cela compte surtout pour :
- les livrables
structured_outputqui doivent parser proprement - les agents managers hiérarchiques qui retournent des décisions JSON
- les workflows scriptés en TypeScript qui attendent des objets typés
Les trois formats
Type |
Construit avec | Sens |
|---|---|---|
text |
LlmResponseFormat.Text() |
Le défaut du provider. Ne produit rien sur le fil — écrire text ou ne rien écrire est équivalent. |
json_object |
LlmResponseFormat.JsonObject() |
Du JSON bien formé, sans schéma. |
json_schema |
LlmResponseFormat.JsonSchema(name, schema, strict = true) |
Du JSON validé contre un JSON Schema (LlmJsonSchema : le schéma voyage en chaîne JSON ; strict demande au vendeur de rejeter tout écart, ignoré là où aucun mode strict n'existe). |
Type est une chaîne ouverte : toute autre valeur est transmise telle quelle (le mapper YAML
logue un avertissement, event id 101), si bien qu'une nouvelle valeur vendeur fonctionne sans
nouvelle version du framework.
Cascade — deux couches, quatre surfaces
La config de base et l'override de task sont fusionnés une seule fois par tour : par ChatOptionsComposer sur la boucle du client de chat, par LlmConfigResolver.Resolve(baseConfig, taskOverride) sur les boucles de repli.
Priorité du plus fort au plus faible : override de task → config de base.
Chaque champ est résolu indépendamment (Profile, ResponseFormat, Temperature, MaxTokens, TopP,
Thinking, Cache), et un champ null sur un override n'efface jamais une valeur héritée.
| Surface | Atterrit dans | Où elle s'écrit |
|---|---|---|
| 1. Défaut crew | config de base | llm: du YAML de crew — fusionné champ par champ dans le llm: de chaque agent |
| 2. Agent | config de base | llm: du YAML d'agent, agentBuilder().withResponseFormat(...) / .withResponseSchema(...), la LlmConfig de l'agent en C# |
| 3. Task | override de task (LlmConfigOverride) |
llm_override: du YAML de task, taskBuilder().withResponseFormat(...) / .withResponseSchema(...), CrewTaskBuilder.WithResponseFormat(...) / .WithLlmOverride(...) |
| 4. Au niveau script | config de base | llmConfig.with({ responseFormat }) sur la config passée à agentBuilder().llm(...) |
Un appel, en C# ou dans un script (ctx.llm.complete/chat/stream(..., { responseFormat })), passe sa propre LlmConfig, hors de la cascade.
Surfaces YAML
Défaut crew
llm:
model: deepseek-flash
response_format: json_object # every agent of this crew replies in JSON
Override agent (gagne sur la crew)
agents:
extractor:
role: "Invoice extractor"
llm:
model: deepseek-flash
response_format: json_object # only this agent forces JSON
Override task (gagne sur l'agent — le chirurgical)
tasks:
extract_invoice:
description: "Extract fields. Reply as a json object."
expected_output: "JSON object with all invoice fields"
llm_override:
response_format: json_object
temperature: 0.0
Le bloc llm_override: accepte profile (la task s'exécute sur ce profil LLM de l'hôte
au lieu de celui de son agent), response_format, response_schema, temperature,
max_tokens, top_p, thinking et cache — les champs du llm: de niveau agent, moins model.
Le bloc cache: d'une task (mĂŞme forme que celui d'un agent) remplace celui de l'agent en entier ;
un bloc sans point d'arrĂŞt coupe le cache de l'agent pour cette task.
JSON Schema
response_schema: accompagne response_format: json_schema, au niveau agent, crew ou task.
schema est le JSON Schema sous forme de chaîne JSON (un bloc scalaire le garde lisible) ;
name vaut response par défaut, strict vaut true :
llm:
model: gpt-5.6-sol
response_format: json_schema
response_schema:
name: invoice
strict: true
schema: |
{"type": "object",
"properties": {"number": {"type": "string"}, "total": {"type": "number"}},
"required": ["number", "total"], "additionalProperties": false}
Un response_schema: seul implique json_schema. json_schema sans schéma se replie sur
json_object avec un avertissement (event id 102).
Surfaces TypeScript / .ork.ts
// Builder — agent (the host's configured provider, here DeepSeek)
const extractor = agentBuilder()
.name("extractor")
.role("Invoice extractor")
.llm(llm.default_.with({ model: "deepseek-flash" }))
.withResponseFormat("json_object")
.build();
// Builder — task (overrides agent on this task only)
const task = taskBuilder()
.description("Return invoice fields as JSON")
.expectedOutput("JSON")
.agent(extractor)
.withResponseSchema("invoice", {
type: "object",
properties: { number: { type: "string" }, total: { type: "number" } },
required: ["number", "total"],
})
.build();
// A call passes its own LlmConfig, outside the cascade
const res = await ctx.llm.complete(
"Return the answer as a json object",
{ responseFormat: "json_object" }
);
.llm(...) prend un LlmConfig — llm.default_, llm.model("…"), llm.profile("…") ou
.with({...}) sur l'un d'eux — et refuse une chaîne ou un objet littéral. Le fournisseur est
celui de l'hôte, ou celui du profil de l'hôte que nomme llm.profile(...) ; .llm(...) règle le
modèle. Un format de réponse est vérifié contre le fournisseur sur lequel l'agent tourne vraiment. withResponseSchema(name, schema, strict?) prend un objet
littéral ou une chaîne JSON et implique json_schema. ctx.llm.extract(prompt, schema) envoie le
schéma comme contrainte json_schema (nom extract, strict: false, car un schéma écrit à la main
porte rarement le additionalProperties: false et le required complet qu'exige un schéma strict)
quand le fournisseur en valide une (ResponseFormatSupport.JsonSchema), et demande json_object
sinon ; un responseFormat
explicite sur l'appel l'emporte, "text" compris.
Surface fluent C#
var task = new CrewTaskBuilder()
.Description("Extract as JSON")
.ExpectedOutput("JSON")
.WithResponseFormat(LlmResponseFormat.JsonSchema("invoice", invoiceSchemaJson))
.Build();
// A call passes its own LlmConfig, outside the cascade. Start from the provider's own
// configuration: built empty, it would reset the provider's penalties.
var config = (provider.BaseConfig ?? LlmConfig.OnProfile()) with
{
ResponseFormat = LlmResponseFormat.JsonObject(),
};
await provider.GenerateAsync(prompt, config, ct);
WithResponseFormat accepte aussi une chaîne ("json_object") ; WithLlmOverride(LlmConfigOverride)
pose le patch de task complet.
Sur le fil
- Famille compatible OpenAI (tous les providers sauf Anthropic et Ollama) —
OpenAICompatibleProviderBaseécritresponse_formatune seule fois, pour chaque provider qui déclare la capacité :{"type": "json_object"}, ou{"type": "json_schema", "json_schema": {"name", "strict", "schema"}}. - Anthropic —
output_config.format, schéma uniquement : Anthropic n'a pas d'équivalent dejson_object, une demande de JSON sans schéma est donc signalée (avertissement structuré) plutôt qu'envoyée. - Ollama —
format: l'objet schéma lui-même, ou"json"pourjson_object.
Ce qu'un provider ne peut pas honorer n'est jamais abandonné en silence :
- un provider qui déclare
Nonen'envoie rien et logueOption 'response_format' was declared but … does not support it(event id110) ; - un schéma envoyé à un provider
JsonObjectest rétrogradé enjson_objectavec le même avertissement (response_format.schema) — décrivez la forme dans le prompt.
Le garde-fou du mot-clé "json"
Le mode JSON de DeepSeek exige que le prompt (message system ou user) contienne le mot
"json" quelque part — faute de quoi l'API peut émettre un flux d'espaces blancs sans fin
jusqu'à épuisement de max_tokens. Chaque provider qui déclare RequiresJsonKeywordInPrompt
(DeepSeek seul) logue un Warning structuré (event id 100, LogMissingJsonKeyword)
quand il détecte la situation :
DeepSeek was asked for a JSON response format but no system/user message contains the
word 'json'. This API may then emit an unbounded whitespace stream until max_tokens.
Add 'json' to the prompt to be safe.
Nous ne mutons pas le prompt à votre place — l'appelant garde le contrôle. Ajoutez "Reply as a json object." au message system et l'avertissement disparaît.
Matrice de support des providers
Le support est piloté par capacité (LlmProviderCapabilities.ResponseFormat — voir le
comparatif des providers). La déclaration est par
provider alors que la réalité est par modèle : un modèle qui refuse le champ répond avec
l'erreur du vendeur, qui remonte en LlmResponse.Error et fait échouer la tâche avec cette
raison.
| Provider | Capacité déclarée | Notes |
|---|---|---|
| OpenAI, Azure OpenAI, Grok, Gemini, Mistral, Together AI | JsonSchema |
Validation de schéma côté serveur. |
| Anthropic | JsonSchema |
Dialecte propre (output_config) — schéma uniquement, pas de json_object nu. |
| Ollama | JsonSchema |
Dialecte propre (format). |
| DeepSeek, Kimi, Qwen, HuggingFace, Z.AI | JsonObject |
JSON bien formé garanti ; un schéma est rétrogradé avec un avertissement. DeepSeek exige en plus le mot-clé json (ci-dessus). |
| MiniMax | None |
Accepté mais non contraignant (un schéma est ignoré, json_object revient clôturé en markdown) ; un format déclaré produit l'avertissement structuré de capacité. |
| OpenRouter | JsonSchema |
Documenté par endpoint. Le provider n'envoie pas provider.require_parameters : un endpoint sans prise en charge du schéma peut donc encore l'ignorer. |
| Mammouth AI | None |
Accepté mais non contraignant (json_object rend du JSON nu, un schéma strict n'est pas appliqué) ; un format déclaré produit l'avertissement structuré de capacité. |
Livrables structured_output
Une tâche dont le livrable est source: structured_output porte son schéma (schema_inline ou
schema_path) sous deux formes, et l'adaptateur du client de chat envoie celle que le fournisseur
honore — jamais les deux, ce que llama-server refuse :
- une grammaire GBNF, sur un point d'accès que les réglages déclarent capable de la prendre
(
"Llm": { "Grammar": true }— Docker Model Runner,llama-server) ; - sinon un format de réponse
json_schema(nomstructured_output,strict: false, car le mode strict d'OpenAI refuse un schéma qui laisse un objet ouvert ou une propriété optionnelle), sur un fournisseur qui déclareJsonSchemadans la matrice ci-dessus ; - sinon rien ne contraint : la grammaire atteint le fournisseur, qui l'abandonne avec un
avertissement structuré nommant
Llm:Grammar.
Un format de réponse que la crew pose elle-même (llm: / llm_override:) l'emporte toujours sur
le schéma du livrable. Dans tous les cas, StructuredOutputResolver vérifie encore la réponse
au parsing JSON avant d'écrire le fichier.
Comment ça circule dans l'orchestrateur
La cascade est fusionnée exactement une fois par tour par LlmConfigResolver.Resolve. Sur le chemin du client de chat, ChatOptionsComposer l'appelle sur la configuration de l'agent et l'override de la tâche, puis traduit la configuration fusionnée sur les ChatOptions champ par champ : il ne fusionne rien lui-même, et chaque champ atteint le fournisseur tel qu'écrit. Les autres sites d'appel n'ont pas de client de chat et l'appellent tels quels : LegacyTextAgentLoop et OutputValidationCoordinator (base : la configuration de l'agent), et NativeToolCallingAgentLoop (base : BuildNativeLlmConfig, la configuration de l'agent plus le prompt système et les outils). ExecutionOrchestrator les pilote :
- Boucle legacy
[TOOL_CALL]basée texte —_llmProvider.ChatAsync(prompt, effectiveConfig, …) - Boucle de tool-calling natif —
_fullProvider.ChatAsync(messages, effectiveConfig, …).BuildNativeLlmConfigs'amorce depuisagent.LlmConfig, si bien que le nom du modèle et la config Thinking survivent à l'entrée du chemin natif ; un agent sans config reçoit une configuration qui ne nomme aucun modèle (LlmConfig.OnProfile()), et le fournisseur exécute l'appel sur le sien. - Retry de correction de validation —
_llmProvider.ChatAsync(correctionPrompt, effectiveConfig, …)
Les 6 stratégies de process (Sequential, Hierarchical, Autonomous, Graph, Parallel, Consensual) exécutent les tâches via IAgentExecutionService.ExecuteTaskAsync, qui délègue à ExecutionOrchestrator.ExecuteTaskCoreAsync — elles bénéficient de la cascade gratuitement.
LlmBasedManager (le manager LLM en mode Hierarchical) n'applique pas d'override de task : ses appels tournent sur le LLM que la crew donne à son manager — le fournisseur posé par WithManagerLlm, sinon le profil et le modèle de l'agent manager, sinon le profil par défaut — avec la configuration propre de ce fournisseur pour tout le reste (ni format de réponse, ni override de task).
Référence
- Value objects :
Orkeon.Domain.SharedKernel.ValueObjects.LlmResponseFormat,LlmJsonSchema - Record de patch :
Orkeon.Domain.SharedKernel.ValueObjects.LlmConfigOverride - Fusion :
Orkeon.Domain.SharedKernel.ValueObjects.LlmConfigResolver.Resolve - Traduction wire :
Orkeon.Infrastructure.LLMs.Base.OpenAICompatibleProviderBase.ApplyProviderSpecificOptions(virtuelle — Kimi, OpenRouter, Qwen, Together AI et Z.AI la surchargent et appellent la base pourresponse_format) ;AnthropicLlmProvideretOllamaLlmProviderpour leurs dialectes propres - Mapping YAML :
Orkeon.Infrastructure.Configuration.Yaml.YamlCrewMapper(sonMapResponseFormatprivé) ; l'export estOrkeon.Infrastructure.Configuration.YamlCrewExporter.MapResponseFormat - Doc API DeepSeek : https://api-docs.deepseek.com/api/create-chat-completion