Add Subgraph Streaming Support to React useStream Hook

[xuxiankun]

Feature Request: Add Subgraph Streaming Support to React useStream Hook

Summary

Add support for subgraph streaming in the useStream React hook from @langchain/langgraph-sdk/react to enable streaming events from both main graphs and nested subgraphs.

Current Behavior

The React useStream hook currently only streams events from the main graph. While the underlying SDK supports subgraph streaming via the streamSubgraphs parameter in the client API, this functionality is not exposed through the React hook interface.

// Current useStream hook - no subgraph streaming support
const stream = useStream({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  // No way to enable subgraph streaming
});

// Must use underlying client for subgraph streaming
const client = new Client({ apiUrl, apiKey });
const stream = client.runs.stream(threadId, assistantId, {
  input: data,
  streamMode: ["values"],
  streamSubgraphs: true, // Only available at client level
});

Desired Behavior

Enable subgraph streaming directly through the useStream hook configuration:

const stream = useStream({
  apiUrl: "http://localhost:2024",
  assistantId: "agent",
  subgraphs: true, // Enable subgraph streaming
  // OR
  streamSubgraphs: true, // Alternative naming
});

// And/or support in submit options
stream.submit(data, {
  streamMode: ["values"],
  streamSubgraphs: true,
});

Use Case

When working with complex multi-agent systems that use nested subgraphs, developers need visibility into streaming events from all graph levels. This is particularly important for:

1. Multi-agent workflows where agents delegate tasks to specialized subgraphs
2. Hierarchical decision making with supervisor and worker agent patterns
3. Real-time debugging and monitoring of complex graph executions
4. UI components that need to display progress from nested graph operations

Current Workaround

Developers must abandon the convenient React hook and implement custom streaming logic using the underlying client API, which loses the benefits of:

• Automatic state management
• Built-in error handling
• React lifecycle integration
• Type safety from the hook interface

Technical Implementation Suggestions

Option 1: Add to UseStreamOptions interface

export interface UseStreamOptions<StateType, Bag> {
  // ... existing options
  /**
   * Enable streaming from subgraphs.
   * When true, events will include namespaced events from nested subgraphs.
   * @default false
   */
  subgraphs?: boolean;
}

Option 2: Add to SubmitOptions interface

interface SubmitOptions<StateType, ConfigurableType> {
  // ... existing options
  /**
   * Enable streaming from subgraphs for this submission.
   * @default false
   */
  streamSubgraphs?: boolean;
}

Option 3: Support both approaches

Allow configuration at both the hook level (default behavior) and submit level (per-request override).

Event Handling

When subgraph streaming is enabled, events should follow the existing pattern with namespaced event names:

// Main graph events
{ event: "values", data: {...} }

// Subgraph events  
{ event: "values|subgraph_namespace", data: {...} }

Related Documentation

• LangGraph Subgraph Streaming
• Stream API Documentation
• TypeScript Types

Environment

• Package: @langchain/langgraph-sdk
• Version: Latest (as of December 2024)
• Framework: React with TypeScript
• Use Case: Multi-agent chat interface with nested subgraph workflows

Additional Context

The underlying infrastructure already supports subgraph streaming as evidenced by:

• TypedAsyncGenerator<TStreamMode, TSubgraphs> type parameter
• SubgraphValuesStreamEvent, SubgraphUpdatesStreamEvent types
• AsSubgraph<TEvent> event transformation utilities
• Client-level streamSubgraphs parameter support

This feature request is to expose this existing functionality through the React hook interface for better developer experience and consistency.

Acceptance Criteria

• useStream hook accepts a subgraphs or streamSubgraphs boolean option
• When enabled, the hook receives events from both main graphs and subgraphs
• Event types are properly typed with subgraph namespace information
• Backward compatibility is maintained (default behavior unchanged)
• Documentation is updated with subgraph streaming examples
• TypeScript definitions are updated to reflect the new options