Streaming

Streaming permite que seu agente envie respostas token por token conforme o LLM as gera. Usuarios veem o texto aparecer em tempo real em vez de esperar pela resposta completa.

API StreamSession

Inicie um stream com agent.stream():

interface StreamSession {
  delta(chunk: string): Promise<void>;  // Envia um fragmento
  done(finalPayload: SendPayload): Promise<void>;  // Completa o stream
  abort(): void;  // Cancela o stream
}

Uso Basico

const session = agent.stream(conversationId);
// SDK envia um frame stream.start com uma chave de idempotencia

for await (const chunk of llmStream) {
  await session.delta(chunk);
  // Cada delta e independentemente criptografado e enviado
}

await session.done({
  type: "text",
  content: fullText,
});
// SDK envia stream.done com o payload criptografado completo para persistencia

Com OpenAI

agent.onMessage(async (msg) => {
  const session = agent.stream(msg.conversation_id);

  const stream = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: msg.content }],
    stream: true,
  });

  let fullText = "";

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta?.content ?? "";
    if (delta) {
      fullText += delta;
      await session.delta(delta);
    }
  }

  await session.done({
    type: "text",
    content: fullText,
  });
});

Abortando um Stream

Cancele um stream se o usuario enviar uma nova mensagem ou ocorrer um erro:

session.abort();
// SDK envia um frame stream.abort; o cliente descarta o conteudo parcial

Criptografia

Cada frame delta e independentemente criptografado. Isso significa que cada fragmento e um payload criptografado autonomo. O frame final done carrega a mensagem criptografada completa para persistencia no servidor.

Limites

Restricao	Valor
Duracao maxima do stream	5 minutos
Timeout de deteccao de orfao	30 segundos (sem delta)
Grupos grandes (201-500 membros)	Streaming desabilitado

Se o servidor detectar timeout de stream, envia um frame stream.error. O SDK aborta a sessao e emite o erro via onEvent. O agente decide se reinicia.

Proximos Passos

• Artifacts — Envie interacoes estruturadas
• Enviando Mensagens — Tipos de mensagem sem streaming
• Eventos WebSocket — Referencia de frames de eventos de stream