Streaming

Display AI responses in real-time as they are generated

Stream agent responses token-by-token — print to the terminal, or iterate tokens yourself to render them in a browser, webview, mobile app, or server.

To stop a stream mid-flight, pass an AbortSignal — see Cancellation.

Which Mode Do I Want?

Pick the surface that matches where the answer renders.

Quick Start

1. Iterate tokens with stream()

   Render tokens live anywhere — the for await loop pulls them at its own pace.

   import { Agent } from 'praisonai';
   
   const agent = new Agent({
     instructions: 'You are a storyteller'
   });
   
   for await (const token of agent.stream('Tell me a short story about a robot')) {
     process.stdout.write(token);  // or send to a WebSocket, React state, etc.
   }

2. Terminal default (start / chat)

   On the CLI, streaming is already on — tokens print to the terminal.

   import { Agent } from 'praisonai';
   
   const agent = new Agent({
     instructions: 'You are a helpful assistant'
   });
   
   await agent.chat('Tell me a story about a robot');
   // Response streams to the console word by word

3. Structured events with streamEvents()

   Same agent, structured events — handle text, finish, and error.

   import { Agent } from 'praisonai';
   
   const agent = new Agent({ instructions: 'You are helpful' });
   
   for await (const event of agent.streamEvents('Hi')) {
     if (event.type === 'text') {
       process.stdout.write(event.delta);
     } else if (event.type === 'finish') {
       console.log('\n\nDone. Full text:', event.text);
     } else if (event.type === 'error') {
       console.error('Stream failed:', event.error);
     }
   }

4. Streaming with Tools

   Tool calls are woven into the same stream — text the model speaks before the tool ("Let me check."), the tool call itself, and the answer after it all arrive as they happen. This holds on every provider: OpenAI, Anthropic, Google, xAI, Groq, and any AI-SDK backend. Pre-tool commentary is delivered as tokens, not held back until the tool finishes.

   import { Agent } from 'praisonai';
   
   function getWeather(city: string): string {
     return `Weather in ${city}: 22°C, sunny`;
   }
   
   const agent = new Agent({
     instructions: 'You are a weather assistant',
     llm: 'anthropic/claude-3-5-sonnet-latest',  // non-OpenAI provider
     stream: true,
     tools: [getWeather]
   });
   
   await agent.chat('What is the weather in Paris?');
   // Console:
   //   Let me check the weather.     <-- streamed reasoning
   //   [getWeather("Paris") runs]     <-- tool executes
   //   It is 22°C in Paris.           <-- streamed final answer

   Iterate agent.stream() to observe the pre-tool text in a non-console caller — each chunk is a token string.

   for await (const chunk of agent.stream('What is the weather in Paris?')) {
     process.stdout.write(chunk);
   }

5. Consume Tokens Yourself

   Consume tokens yourself with agent.stream() — an async iterator over chunks.

   import { Agent } from 'praisonai';
   
   const agent = new Agent({ instructions: 'You are a helpful assistant' });
   
   for await (const chunk of agent.stream('Tell me a story about a robot')) {
     process.stdout.write(chunk);
   }

6. Stop a Stream

   Break the loop to stop the request — the provider stops generating and billing immediately.

   import { Agent } from 'praisonai';
   
   const agent = new Agent({ instructions: 'You are a helpful assistant' });
   
   let tokens = 0;
   for await (const chunk of agent.stream('Write a very long essay')) {
     process.stdout.write(chunk);
     if (++tokens === 50) break;  // Auto-aborts the underlying request
   }
   
   console.log(agent.lastStopReason);  // 'cancelled'

   For a UI Stop button, pass an AbortSignal:

   const controller = new AbortController();
   document.getElementById('stop')!.onclick = () => controller.abort();
   
   try {
     for await (const chunk of agent.stream('Write a long essay', { signal: controller.signal })) {
       process.stdout.write(chunk);
     }
   } catch (err) {
     if (agent.lastStopReason === 'cancelled') {
       console.log('User stopped the stream');
     } else {
       throw err;  // Real error
     }
   }

Cancellation

Break out of the loop to stop the stream cleanly — no more tokens are queued and the in-flight provider request is aborted.

let received = '';
for await (const token of agent.stream('Write a very long essay')) {
  received += token;
  if (received.length > 500) break;  // stops the stream cleanly
}

You can also pass an AbortSignal to cancel a turn from outside the loop.

const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);  // stop after 2s

for await (const token of agent.stream('Long essay', { signal: controller.signal })) {
  process.stdout.write(token);
}

How It Works

When tools are configured, the round routes through streamText on every provider — text spoken before the tool call streams as tokens, then the tool runs, then the answer after it streams too.

Streaming with Tools

Text deltas, tool calls, and tool results interleave on a single loop — the stream never stops just because the agent needs a tool.

Bounding the loop

Two knobs bound the run when the model chains many tools.

const agent = new Agent({
  instructions: 'Research assistant',
  stream: true,
  tools: [search, fetchUrl, summarise],
  maxIterations: 30,          // more room for long research chains
  maxToolCallsPerTurn: 5,     // but at most 5 parallel tools per turn
});

Stop a stream

Two ways to cancel a streaming turn — both stop the upstream provider request so no further tokens are generated or billed.

Which one should I use?

Tell a Stop from a real error

agent.lastStopReason reports why the last run ended:

try {
  for await (const chunk of agent.stream('...', { signal })) { /* ... */ }
} catch (err) {
  if (agent.lastStopReason === 'cancelled') {
    // Silent — user asked for it
  } else {
    reportError(err);  // Real failure
  }
}

AgentEvent Reference

streamEvents() yields a discriminated union. Switch on event.type.

AgentStreamOptions Reference

Both stream() and streamEvents() accept an optional second argument.

Configuration Options

The stream config option controls the terminal default and whether token deltas are produced.

Common Patterns

Stream to a Server-Sent Events endpoint

import { Agent } from 'praisonai';
import express from 'express';

const agent = new Agent({ instructions: 'You are helpful' });
const app = express();

app.get('/chat', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  for await (const token of agent.stream(String(req.query.q))) {
    res.write(`data: ${token}\n\n`);
  }
  res.end();
});

app.listen(3000);

Log the full text once with streamEvents()

import { Agent } from 'praisonai';

const agent = new Agent({ instructions: 'You are helpful' });

for await (const event of agent.streamEvents('Explain streaming in one line')) {
  if (event.type === 'text') process.stdout.write(event.delta);
  if (event.type === 'finish') console.log('\n[full]', event.text);
}

Terminal default (unchanged)

import { Agent } from 'praisonai';

const writer = new Agent({
  instructions: 'You are a creative writer',
  stream: true
});

// See the story unfold in the terminal as it is written
await writer.chat('Write a 500-word story about a time-traveling chef');

Seeing Tool Activity

If your UI needs to render tool calls and their results — not just the streamed text — use agent.streamEvents() instead of agent.chat(). It yields a typed union (text, tool_call, tool_result, finish, error) in the order the agent produced them, so a call is announced before it runs and its result carries an explicit ok field.

Best Practices

Beyond Text: Structured Events

For UIs that need to show tool activity live, use streamEvents() — it yields typed AgentEvents instead of just tokens.

import { Agent } from 'praisonai';

const agent = new Agent({ instructions: 'You are a helpful assistant' });

for await (const event of agent.streamEvents('What is the weather in Paris?')) {
  switch (event.type) {
    case 'text':        process.stdout.write(event.delta); break;
    case 'tool_call':   console.log(`\n[tool] ${event.name}`); break;
    case 'tool_result': console.log(`[tool] ${event.ok ? 'ok' : 'fail'}`); break;
    case 'finish':      console.log(`\n[done]`); break;
  }
}

Related