Streaming Events

Stream tool calls, tool results, and text as structured events

Stream typed events (text, tool_call, tool_result, finish, error) instead of just token text, so a UI can show tool activity as it happens.

Quick Start

1. See tools happening live

   Iterate the event stream and switch on event.type to render text, tool calls, and results as they arrive.

   import { Agent } from 'praisonai';
   
   function getWeather(city: string): string {
     return `Weather in ${city}: 22°C, sunny`;
   }
   
   const agent = new Agent({
     instructions: 'You are a helpful assistant',
     tools: [getWeather],
   });
   
   for await (const event of agent.streamEvents('What is the weather in Paris?')) {
     if (event.type === 'text')        process.stdout.write(event.delta);
     else if (event.type === 'tool_call')   console.log(`\n[tool] ${event.name}(${JSON.stringify(event.args)})`);
     else if (event.type === 'tool_result') console.log(`[tool] ${event.name} -> ${event.ok ? 'ok' : 'fail'}: ${event.output}`);
     else if (event.type === 'finish')      console.log(`\n[done] ${event.text}`);
   }

2. Cancel a turn

   Pass an AbortController signal to stop generation mid-turn — or just break the for await loop, which aborts the upstream provider request automatically.

   import { Agent } from 'praisonai';
   
   const agent = new Agent({ instructions: 'You are a helpful assistant' });
   const controller = new AbortController();
   
   setTimeout(() => controller.abort(), 2000);  // Cancel after 2 seconds
   
   for await (const event of agent.streamEvents('Write a long essay', { signal: controller.signal })) {
     if (event.type === 'text') process.stdout.write(event.delta);
     if (event.type === 'finish') break;  // Breaking also aborts upstream generation
   }

How It Works

Structured events share the same internal queue as text deltas, so tool activity is reported in its true position in the response.

The Five Event Types

Every event is a member of the AgentEvent discriminated union — switch on type to narrow the fields.

Choosing a Streaming API

Pick the smallest API that gives you what you need.

Common Patterns

Chat UI that shows tools in progress

Track calls in a Map keyed by callId, then flip each card from running to ok or fail on the matching result.

import { Agent } from 'praisonai';

function getWeather(city: string): string {
  return `Weather in ${city}: 22°C, sunny`;
}

const agent = new Agent({ instructions: 'You are a helpful assistant', tools: [getWeather] });
const cards = new Map<string, { name: string; args: unknown; status: string }>();

for await (const event of agent.streamEvents('Weather in Paris and Tokyo?')) {
  if (event.type === 'tool_call') {
    cards.set(event.callId, { name: event.name, args: event.args, status: 'running' });
  } else if (event.type === 'tool_result') {
    const card = cards.get(event.callId);
    if (card) card.status = event.ok ? 'ok' : 'fail';
  }
  console.log([...cards.values()]);  // Render the tool cards
}

Progress spinner around a slow tool

Narrate tool_call.name in a status line, then clear it on the matching tool_result.

import { Agent } from 'praisonai';

function searchDocs(query: string): string {
  return `Found 3 results for ${query}`;
}

const agent = new Agent({ instructions: 'You are a research assistant', tools: [searchDocs] });

for await (const event of agent.streamEvents('Search the docs for streaming')) {
  if (event.type === 'tool_call')   process.stdout.write(`⏳ Running ${event.name}...`);
  if (event.type === 'tool_result') process.stdout.write(`\r✅ ${event.name} done       \n`);
}

Best Practices

Related