Streaming

Certains endpoints peuvent envoyer leur résultat pendant sa production au lieu de l'envoyer en une seule fois : une réponse du chat lorsque la requête définit "stream": true, et une exécution de workflow. Tous les streams utilisent la même enveloppe, décrite ici ; ce que transporte l'enveloppe dépend de l'endpoint. Cette page décrit l'enveloppe et le stream du chat ; les événements d'une exécution de workflow sont décrits avec l'endpoint de workflow.

Comment un stream est transmis #

Une réponse en streaming est une réponse HTTP ordinaire dont le corps arrive morceau par morceau :

• Statut 200, Content-Type: text/event-stream; charset=utf-8, encodage de transfert chunked (pas de Content-Length).
• Le corps est une suite de chunks. Chaque chunk est un objet JSON, et les objets sont écrits directement les uns après les autres, sans séparateur : pas de saut de ligne, pas de préfixe data:.

{"timestamp": 1759406400810, "data": "Unit tests", "error": null}{"timestamp": 1759406400834, "data": " catch", "error": null}{"timestamp": 1759406400851, "data": " regressions", "error": null}

Malgré le type de contenu, le corps n'est pas au format Server-Sent Events, si bien que EventSource et les bibliothèques clientes SSE ne peuvent pas le lire (et EventSource ne peut de toute façon pas envoyer un POST avec un corps). Lisez le corps comme un flux d'octets et découpez-le vous-même en objets JSON, voir Lire un stream. Une lecture réseau peut s'arrêter au milieu d'un objet ou contenir plusieurs objets ; utilisez donc toujours un tampon.

Les erreurs détectées avant le début du stream (authentification, autorisations, requête invalide, modèle inconnu, ...) sont renvoyées comme une réponse d'erreur normale avec leur propre statut HTTP et un corps {"detail": "..."}, voir Erreurs. Vérifiez le code de statut avant de lire le corps comme un stream.

Chunks #

Keepalive. Lorsque rien n'a été produit pendant environ une seconde (le modèle réfléchit, un outil s'exécute), le serveur envoie un chunk dont data vaut la chaîne vide "". Ignorez ces chunks ; ils servent uniquement à éviter que la connexion et les éventuels proxys n'expirent. Les keepalives sont envoyés dans tous les formats de stream, si bien que data peut valoir "" même dans les streams dont les payloads sont par ailleurs des objets.

Erreurs dans un stream #

Une fois le stream commencé, le statut HTTP est déjà 200. Un échec survenant après ce point est envoyé comme dernier chunk avec error défini, puis le stream se termine.

{"timestamp": 1759406402117, "data": null, "error": {"status": 422, "text": "Validation error", "detail": "not enough user credit"}}

Les erreurs du chat qui peuvent arriver de cette façon sont marquées pendant dans le tableau des erreurs du chat ; la plus fréquente est l'épuisement des crédits au milieu d'une réponse. Une réponse du chat interrompue par une erreur est conservée dans la conversation jusqu'au point où elle s'est arrêtée.

Fin du stream #

Le stream se termine lorsque le corps de la réponse HTTP se termine. Il n'y a pas de chunk final de « fin » :

• le corps s'est terminé après un chunk avec error défini : la requête a échoué ;
• le corps s'est terminé autrement : la requête a abouti.

Dans le stream d'événements du chat, un événement done marque le moment où le modèle a terminé sa réponse, mais considérez la fin du corps comme la fin du stream.

Si votre client ferme la connexion prématurément, le serveur arrête de générer la réponse du chat. La partie générée jusque-là est conservée dans la conversation et les appels au modèle déjà effectués sont facturés. (Une exécution de workflow continue sur le serveur après une déconnexion.)

Formats du stream de chat #

Le champ runner_version de la requête de chat détermine ce que contient data dans un stream de chat :

Les deux formats proviennent de la même génération et la réponse stockée est identique ; seul ce qui est transmis sur le réseau diffère.

Un modèle sans la capacité stream (voir Modèles et outils) peut quand même être utilisé en streaming : le texte de sa réponse arrive en un seul morceau (un fragment de texte, ou un événement text) lorsqu'il est complet, et il est stocké comme toute autre réponse.

Stream texte (version 1) #

Chaque data est un fragment de la réponse au format Markdown. Concaténez les fragments dans l'ordre pour obtenir la réponse complète ; les chunks keepalive ("") n'ajoutent rien.

Les appels d'outils font partie du texte, exactement comme dans le content d'une réponse non streamée : chaque appel d'outil est un bloc qui commence par le marqueur "\n\n### calling AI tool ...\n", se poursuit avec le texte de progression que rapporte l'outil et se termine par le marqueur "\n***\n". Voir Appels d'outils dans la réponse. Le raisonnement, les informations de statut et les étapes internes des sous-assistants ne sont pas envoyés dans ce format.

{"timestamp": 1759406400120, "data": "", "error": null}{"timestamp": 1759406400810, "data": "Let me check", "error": null}{"timestamp": 1759406400833, "data": " that.", "error": null}{"timestamp": 1759406401002, "data": "\n\n### calling AI tool ...\n", "error": null}{"timestamp": 1759406401004, "data": "### Scraping URL: https://example.com/rates\n", "error": null}{"timestamp": 1759406402950, "data": "\n***\n", "error": null}{"timestamp": 1759406403410, "data": "The current rate is 24.35 CZK per euro.", "error": null}

Stream d'événements (version 2) #

Chaque data (hors keepalives) est un objet événement. Tous les champs sont toujours présents ; ceux qui ne s'appliquent pas au type d'événement sont vides ("", null ou {}).

Un chunk complet du stream d'événements ressemble à ceci :

{"timestamp": 1759406400810, "data": {"type": "text", "delta": "Unit tests", "phase": null, "call_id": null, "tool_name": null, "tool_display_name": null, "tool_icon": null, "tool_status": null, "data": {}, "chunk": null}, "error": null}

Types d'événements #

Phases de statut #

De nouveaux types d'événements, phases et clés de data peuvent être ajoutés. Ignorez les valeurs que vous ne connaissez pas.

Ordre des événements #

Une réponse typique qui utilise un outil produit (keepalives omis, un data par ligne) :

{"type": "status", "phase": "context_building", ...}
{"type": "status", "phase": "model_selected", "data": {"model": "gpt-5-mini", "model_name": "GPT-5 mini"}, ...}
{"type": "status", "phase": "model_call", ...}
{"type": "text", "delta": "Let me check", ...}
{"type": "text", "delta": " that.", ...}
{"type": "status", "phase": "tool_call_pending", "call_id": "call_9f2c", "tool_name": "WebScraperFunctionTool", ...}
{"type": "tool_call_start", "call_id": "call_9f2c", "tool_name": "WebScraperFunctionTool", "tool_display_name": "Web Scraper", "tool_icon": "ayeto", ...}
{"type": "tool_call_output", "call_id": "call_9f2c", "delta": "### Scraping URL: https://example.com/rates\n", ...}
{"type": "tool_call_end", "call_id": "call_9f2c", "tool_status": "ok", ...}
{"type": "status", "phase": "model_call", ...}
{"type": "text", "delta": "The current rate is 24.35 CZK per euro.", ...}
{"type": "done", "data": {"stop_reason": "stop"}, ...}

Reconstituer le texte de la réponse #

Pour obtenir le même texte que celui que contient un stream texte ou le message stocké, ajoutez pour chaque événement de premier niveau :

Les fichiers générés (par exemple des images) apparaissent sous forme de liens Markdown dans tool_call_output. Une fois le stream terminé, vous pouvez lire la réponse stockée, y compris ses pièces jointes, via l'API Conversations.

Lire un stream #

Les exemples envoient un message de chat avec runner_version "2", affichent le texte de la réponse au fur et à mesure de son arrivée et s'arrêtent sur un chunk d'erreur. Tous deux découpent le corps en objets JSON à l'aide d'un petit tampon, si bien qu'ils fonctionnent quelle que soit la façon dont le réseau découpe les données.

Python #

import codecs
import json
import os
import uuid

import requests


def iter_chunks(response):
    """Yield the JSON chunks of a streamed response."""
    decoder = json.JSONDecoder()
    text = codecs.getincrementaldecoder("utf-8")()
    buffer = ""
    for raw in response.iter_content(chunk_size=None):
        buffer += text.decode(raw)
        while True:
            buffer = buffer.lstrip()
            if not buffer:
                break
            try:
                chunk, end = decoder.raw_decode(buffer)
            except json.JSONDecodeError:
                break  # incomplete object, wait for more data
            buffer = buffer[end:]
            yield chunk


response = requests.post(
    "https://ayeto.ai/api/v3/chat",
    headers={"uni-api-key": os.environ["AYETO_API_KEY"]},
    json={
        "conversation_id": str(uuid.uuid4()),
        "model": "gpt-5-mini",
        "message": "Explain recursion with a short example.",
        "stream": True,
        "runner_version": "2",
    },
    stream=True,
    timeout=(10, 600),
)
if response.status_code != 200:  # failed before the stream started
    raise RuntimeError(f"{response.status_code}: {response.json()['detail']}")

for chunk in iter_chunks(response):
    if chunk["error"]:
        error = chunk["error"]
        raise RuntimeError(f"{error['status']}: {error['detail']}")
    event = chunk["data"]
    if not isinstance(event, dict):
        continue  # keepalive
    if event["type"] == "text":
        print(event["delta"], end="", flush=True)
    elif event["type"] == "tool_call_start":
        print(f"\n[{event['tool_display_name']}]", flush=True)
    elif event["type"] == "status" and event["phase"] == "model_selected":
        print(f"[answering: {event['data']['model']}]", flush=True)
print()

Avec runner_version "1", chunk["data"] est une chaîne : affichez-la ou ajoutez-la telle quelle.

JavaScript #

// Yields the JSON chunks of a streamed response.
async function* readChunks(response) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  let pos = 0;
  let depth = 0;
  let inString = false;
  let escaped = false;
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    for (; pos < buffer.length; pos++) {
      const c = buffer[pos];
      if (inString) {
        if (escaped) escaped = false;
        else if (c === "\\") escaped = true;
        else if (c === '"') inString = false;
      } else if (c === '"') {
        inString = true;
      } else if (c === "{") {
        depth++;
      } else if (c === "}" && --depth === 0) {
        yield JSON.parse(buffer.slice(0, pos + 1));
        buffer = buffer.slice(pos + 1);
        pos = -1; // continue at the start of the remaining buffer
      }
    }
  }
}

const response = await fetch("https://ayeto.ai/api/v3/chat", {
  method: "POST",
  headers: {
    "uni-api-key": process.env.AYETO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversation_id: crypto.randomUUID(),
    model: "gpt-5-mini",
    message: "Explain recursion with a short example.",
    stream: true,
    runner_version: "2",
  }),
});
if (!response.ok) {
  // failed before the stream started
  const body = await response.json();
  throw new Error(`${response.status}: ${JSON.stringify(body.detail)}`);
}

let answer = "";
for await (const chunk of readChunks(response)) {
  if (chunk.error) {
    throw new Error(`${chunk.error.status}: ${chunk.error.detail}`);
  }
  const event = chunk.data;
  if (typeof event !== "object" || event === null) continue; // keepalive
  if (event.type === "text") {
    answer += event.delta;
    process.stdout.write(event.delta);
  }
}

Les mêmes fonctions lisent le stream d'une exécution de workflow ; seuls les payloads data diffèrent, voir Exécution en streaming.