Skip to main content

Basic Streaming

final agent = Agent('openai');

// Like watching a typist with 200 WPM
await for (final chunk in agent.sendStream('Tell me your best joke')) {
  stdout.write(chunk.output); 
}
// "Why don't scientists trust atoms?"
// (dramatic pause as it streams...)
// "Because they make up everything!"

With Messages

final agent = Agent('openai');

final history = [ChatMessage.system('You are a comedian.')];

await for (final chunk in agent.sendStream(
  'Tell me your best joke',
  history: history,
)) {
  // Stream the output
  stdout.write(chunk.output); 

  // Add new messages to the history
  history.addAll(chunk.messages);
}

With Tools

// Tool calls stream alongside text
await for (final chunk in agent.sendStream(
  'Weather in NYC?',
  tools: [weatherTool],
)) {
  // Tool results integrated into stream
  stdout.write(chunk.output);
}

Thinking Metadata

final agent = Agent(
  'openai-responses:gpt-5',
  chatModelOptions: const OpenAIResponsesChatModelOptions(
    reasoningSummary: OpenAIReasoningSummary.concise,
  ),
);

final result = await agent.send('Explain quicksort.');
final thinking = result.metadata['thinking'] as String?;
if (thinking != null && thinking.isNotEmpty) {
  stdout.write('[[${thinking.trim()}]]');
}
stdout.write(result.output);
Thinking stays in ChatResult.metadata so you can show a live “thought bubble” without polluting the message stream. See Thinking Metadata for more options.

With Typed Output

// Stream structured JSON
await for (final chunk in agent.sendStream(
  'List 3 facts',
  outputSchema: factsSchema,
)) {
  stdout.write(chunk.output); // Streams JSON chunks
}

Usage Tracking & Tool Metadata

var usage = const LanguageModelUsage();

await for (final chunk in agent.sendStream('Story time')) {
  stdout.write(chunk.output);
  if (chunk.usage.totalTokens != null) {
    usage = chunk.usage; // Final chunk contains usage
  }

  // Inspect server-side tool events (OpenAI Responses)
  final web = chunk.metadata['web_search'] as List?;
  if (web != null) {
    stdout.writeln('\nSearch stage: ${web.last['type']}');
  }
}

print('\nTokens used: ${usage.totalTokens}');

Examples

Next Steps