Streaming

Jade uses Server-Sent Events (SSE) for real-time streaming, giving you instant feedback as AI processes your requests.

How Streaming Works

When you send a message, the SDK:

Opens an SSE connection to the server
Receives events as the AI generates responses
Updates the conversation in real-time
Closes the connection when complete

Client                    Server
  |                          |
  |-- POST /messages ------->|
  |                          |
  |<-- message_start --------|
  |<-- text_delta ----------|
  |<-- text_delta ----------|
  |<-- tool_use_start ------|
  |<-- tool_result ---------|
  |<-- message_complete -----|
  |                          |

Streaming State

The useJadeSession hook provides streaming state:

const {
  isStreaming,           // Whether AI is currently responding
  streamingText,         // Current streaming text
  streamingToolCall,     // Current tool being prepared (streaming inputs)
  showTinkering,         // Whether to show "thinking" indicator
  isExecutingTool,       // Whether a tool is executing on server (React Native only)
  executingToolName,     // Name of the executing tool (React Native only)
} = useJadeSession();

Displaying Streaming Text

function Message() {
  const { streamingText, isStreaming } = useJadeSession();

  return (
    <div>
      {streamingText && (
        <div className="streaming-message">
          {streamingText}
          {isStreaming && <span className="cursor">▋</span>}
        </div>
      )}
    </div>
  );
}

Tool Execution Indicator

React / Next.js
React Native

function ToolIndicator() {
  const { streamingToolCall, showTinkering } = useJadeSession();

  if (showTinkering) {
    return <div className="tool-indicator">Thinking...</div>;
  }

  if (streamingToolCall) {
    return (
      <div className="tool-indicator">
        Preparing: {streamingToolCall.tool_name}
      </div>
    );
  }

  return null;
}

function ToolIndicator() {
  const {
    streamingToolCall,
    showTinkering,
    isExecutingTool,
    executingToolName,
  } = useJadeSession();

  if (showTinkering) {
    return <Text>Thinking...</Text>;
  }

  if (streamingToolCall) {
    return <Text>Preparing: {streamingToolCall.tool_name}</Text>;
  }

  if (isExecutingTool) {
    return (
      <View style={styles.executing}>
        <ActivityIndicator />
        <Text>Running: {executingToolName}</Text>
      </View>
    );
  }

  return null;
}

Cancellation

Cancel an ongoing stream:

const { cancel, isStreaming } = useJadeSession();

<button onClick={cancel} disabled={!isStreaming}>
  Cancel
</button>

Cancellation:

Immediately stops receiving events
Sends a cancel signal to the server
Preserves partial conversation state

Reconnection

If a connection drops, you can reconnect to an existing session:

const { reconnect, sessionId, conversation } = useJadeSession();

// Reconnect to session with existing conversation
await reconnect(sessionId, conversation);

// Or reconnect with a new user prompt
await reconnect(sessionId, conversation, 'Continue where we left off');

The SDK automatically tracks event IDs internally to resume from the last received event.

Event Types

The SDK handles these SSE event types internally:

Event	Description
`message_start`	New message started
`text_delta`	Incremental text update
`tool_use_start`	Tool execution started
`tool_input_delta`	Tool input streaming
`tool_result`	Tool execution complete
`message_complete`	Full message complete
`error`	Error occurred

Media Generation Events

For media generation, watch for media URLs in tool results:

const { processedConversation } = useJadeSession();

// Find latest generated media
const latestMedia = processedConversation
  .filter(e => e.mediaUrls?.length)
  .flatMap(e => e.mediaUrls);

Or use the onMediaGenerated callback:

useJadeSession({
  onMediaGenerated: (urls, type) => {
    console.log(`Generated ${type}:`, urls);
    // Show notification, update gallery, etc.
  },
});

Error Handling

Handle streaming errors using the onError callback:

const { sendMessage, reconnect, sessionId } = useJadeSession({
  onError: (error) => {
    if (error.message.includes('network')) {
      // Network error - try reconnecting
      reconnect(sessionId);
    } else {
      // Display error to user
      showNotification(error.message);
    }
  },
});

Best Practices

Debounce UI Updates

For very fast streams, consider debouncing UI updates:

const [displayText, setDisplayText] = useState('');
const { streamingText } = useJadeSession();

useEffect(() => {
  const timer = setTimeout(() => {
    setDisplayText(streamingText || '');
  }, 50); // 50ms debounce

  return () => clearTimeout(timer);
}, [streamingText]);

Show Progress for Long Operations

Media generation can take time. Show progress:

React / Next.js
React Native

function GenerationProgress() {
  const { streamingToolCall } = useJadeSession();

  if (streamingToolCall?.tool_name.includes('video')) {
    return <div>Generating video... This may take a moment.</div>;
  }

  if (streamingToolCall?.tool_name.includes('image')) {
    return <div>Creating your image...</div>;
  }

  return null;
}

function GenerationProgress() {
  const { isExecutingTool, executingToolName } = useJadeSession();

  if (!isExecutingTool) return null;

  if (executingToolName?.includes('video')) {
    return <Text>Generating video... This may take a moment.</Text>;
  }

  if (executingToolName?.includes('image')) {
    return <Text>Creating your image...</Text>;
  }

  return <Text>Processing...</Text>;
}

Handle Background State (React Native)

On mobile, pause streaming when the app goes to background:

<JadeProvider
  config={config}
  storage={storage}
  pauseOnBackground={true}  // Default behavior
>

See App State for more details.

Getting Started

Guides

Integration

Examples

How Streaming Works

Streaming State

Displaying Streaming Text

Tool Execution Indicator

Cancellation

Reconnection

Event Types

Media Generation Events

Error Handling

Best Practices

Debounce UI Updates

Show Progress for Long Operations

Handle Background State (React Native)

​How Streaming Works

​Streaming State

​Displaying Streaming Text

​Tool Execution Indicator

​Cancellation

​Reconnection

​Event Types

​Media Generation Events

​Error Handling

​Best Practices

​Debounce UI Updates

​Show Progress for Long Operations

​Handle Background State (React Native)

How Streaming Works

Streaming State

Displaying Streaming Text

Tool Execution Indicator

Cancellation

Reconnection

Event Types

Media Generation Events

Error Handling

Best Practices

Debounce UI Updates

Show Progress for Long Operations

Handle Background State (React Native)