langchain.js
    Preparing search index...

    Interface UseDeepAgentStream<StateType, ToolCall, SubagentStates, Bag>Experimental

    Stream interface for DeepAgent instances created with createDeepAgent.

    Extends UseAgentStream with subagent streaming capabilities. Subagent streams are automatically typed based on the agent's subagent configuration, enabling type-safe access to subagent state and messages.

    Use this interface when streaming from an agent created with createDeepAgent that orchestrates multiple specialized subagents.

    This interface is subject to change.

    import { createDeepAgent } from "deepagents";
    import { useStream } from "@langchain/langgraph-sdk/react";

    // Define subagents with typed middleware
    const agent = createDeepAgent({
      subagents: [
        {
          name: "researcher",
          description: "Research specialist",
          middleware: [ResearchMiddleware],
        },
        {
          name: "writer",
          description: "Content writer",
          middleware: [WriterMiddleware],
        },
      ] as const, // Important: use 'as const' for type inference
    });

    // In React component:
    function Chat() {
      const stream = useStream<typeof agent>({
        assistantId: "deep-agent",
        apiUrl: "http://localhost:2024",
        filterSubagentMessages: true, // Only show main agent messages
      });

      // Subagent streams are typed!
      const researchers = stream.getSubagentsByType("researcher");
      researchers.forEach(subagent => {
        // subagent.values.messages is typed as Message<ToolCall>[]
        // subagent.status is "pending" | "running" | "complete" | "error"
        console.log("Researcher status:", subagent.status);
      });

      // Track all active subagents
      stream.activeSubagents.forEach(subagent => {
        console.log(`${subagent.toolCall.args.subagent_type} is running...`);
      });
    }

    This interface adds subagent streaming on top of UseAgentStream:

    • subagents - Map of all subagent streams by tool call ID
    • activeSubagents - Array of currently running subagents
    • getSubagent(id) - Get a specific subagent by tool call ID
    • getSubagentsByType(type) - Get all subagents of a specific type with typed state
    • getSubagentsByMessage(messageId) - Get all subagents triggered by a specific AI message

    It also enables the filterSubagentMessages option to exclude subagent messages from the main messages array.

    interface UseDeepAgentStream<
        StateType extends Record<string, unknown> = Record<string, unknown>,
        ToolCall = DefaultToolCall,
        SubagentStates extends Record<string, unknown> = DefaultSubagentStates,
        Bag extends BagTemplate = BagTemplate,
    > {
        activeSubagents: SubagentStreamInterface<
            SubagentStates[keyof SubagentStates],
            ToolCall,
            keyof SubagentStates & string,
        >[];
        assistantId: string;
        branch: string;
        client: Client;
        error: unknown;
        experimental_branchTree: Sequence<StateType>;
        getMessagesMetadata: (
            message: Message<ToolCall>,
            index?: number,
        ) => undefined | MessageMetadata<StateType>;
        getSubagent: (
            toolCallId: string,
        ) =>
            | undefined
            | SubagentStreamInterface<
                SubagentStates[keyof SubagentStates],
                ToolCall,
                keyof SubagentStates & string,
            >;
        getSubagentsByMessage: (
            messageId: string,
        ) => SubagentStreamInterface<
            SubagentStates[keyof SubagentStates],
            ToolCall,
            keyof SubagentStates & string,
        >[];
        getSubagentsByType: {
            <TName extends string>(
                type: TName,
            ): SubagentStreamInterface<SubagentStates[TName], ToolCall, TName>[];
            (
                type: string,
            ): SubagentStreamInterface<Record<string, unknown>, ToolCall, string>[];
        };
        getToolCalls: (
            message: AIMessage<ToolCall>,
        ) => ToolCallWithResult<ToolCall>[];
        history: ThreadState<StateType>[];
        interrupt: undefined | Interrupt<GetInterruptType<Bag>>;
        interrupts: Interrupt<GetInterruptType<Bag>>[];
        isLoading: boolean;
        isThreadLoading: boolean;
        joinStream: (
            runId: string,
            lastEventId?: string,
            options?: {
                filter?: (
                    event: { data: unknown; event: StreamEvent; id?: string },
                ) => boolean;
                streamMode?: StreamMode | StreamMode[];
            },
        ) => Promise<void>;
        messages: Message<ToolCall>[];
        setBranch: (branch: string) => void;
        stop: () => Promise<void>;
        subagents: Map<
            string,
            SubagentStreamInterface<
                SubagentStates[keyof SubagentStates],
                ToolCall,
                keyof SubagentStates & string,
            >,
        >;
        submit: (
            values: undefined | null | GetUpdateType<Bag, StateType>,
            options?: SubmitOptions<StateType, GetConfigurableType<Bag>>,
        ) => Promise<void>;
        toolCalls: ToolCallWithResult<ToolCall>[];
        values: StateType;
    }

    Type Parameters

    • StateType extends Record<string, unknown> = Record<string, unknown>

      The agent's state type

    • ToolCall = DefaultToolCall

      Tool call type from agent's tools

    • SubagentStates extends Record<string, unknown> = DefaultSubagentStates

      Map of subagent names to their state types

    • Bag extends BagTemplate = BagTemplate

      Type configuration bag

    Hierarchy (View Summary)

    Index

    Properties

    activeSubagents assistantId branch client error experimental_branchTree getMessagesMetadata getSubagent getSubagentsByMessage getSubagentsByType getToolCalls history interrupt interrupts isLoading isThreadLoading joinStream messages setBranch stop subagents submit toolCalls values

    Properties

    activeSubagents: SubagentStreamInterface<
        SubagentStates[keyof SubagentStates],
        ToolCall,
        keyof SubagentStates & string,
    >[]

    Currently active subagents (where status === "running").

    Use this to track and display subagents that are actively executing. Completed or errored subagents are not included.

    // Show loading indicators for active subagents
    stream.activeSubagents.map(subagent => (
      <SubagentCard
        key={subagent.id}
        type={subagent.toolCall.args.subagent_type}
        isLoading={true}
      />
    ));
    assistantId: string

    The ID of the assistant to use.

    branch: string

    The current branch of the thread. Used for navigating between different conversation branches.

    client: Client

    LangGraph SDK client used to send requests and receive responses.

    error: unknown

    Last seen error from the stream, if any. Reset to undefined when a new stream starts.

    experimental_branchTree: Sequence<StateType>

    Tree of all branches for the thread. This API is experimental and subject to change.

    getMessagesMetadata: (
        message: Message<ToolCall>,
        index?: number,
    ) => undefined | MessageMetadata<StateType>

    Get the metadata for a message, such as first thread state the message was seen in and branch information.

    Type Declaration

    getSubagent: (
        toolCallId: string,
    ) =>
        | undefined
        | SubagentStreamInterface<
            SubagentStates[keyof SubagentStates],
            ToolCall,
            keyof SubagentStates & string,
        >

    Get subagent stream by tool call ID.

    Use this when you have a specific tool call ID and need to access its corresponding subagent stream.

    Type Declaration

    // In a tool call component
    const subagent = stream.getSubagent(toolCall.id);
    if (subagent) {
      return <SubagentProgress subagent={subagent} />;
    }
    getSubagentsByMessage: (
        messageId: string,
    ) => SubagentStreamInterface<
        SubagentStates[keyof SubagentStates],
        ToolCall,
        keyof SubagentStates & string,
    >[]

    Get all subagents triggered by a specific AI message.

    Useful for rendering subagent activities grouped by conversation turn. Each AI message that contains subagent tool calls will have its triggered subagents returned by this method.

    Type Declaration

    // Render subagents inline after the AI message that triggered them
    {stream.messages.map((msg) => (
      <div key={msg.id}>
        <MessageBubble message={msg} />
        {msg.type === "ai" && "tool_calls" in msg && (
          <SubagentPipeline
            subagents={stream.getSubagentsByMessage(msg.id)}
          />
        )}
      </div>
    ))}
    getSubagentsByType: {
        <TName extends string>(
            type: TName,
        ): SubagentStreamInterface<SubagentStates[TName], ToolCall, TName>[];
        (
            type: string,
        ): SubagentStreamInterface<Record<string, unknown>, ToolCall, string>[];
    }

    Get all subagents of a specific type.

    Returns streams with properly inferred state types based on subagent name. When called with a literal string that matches a subagent name, TypeScript will infer the correct state type for that subagent.

    Type Declaration

    The subagent_type to filter by

    Array of matching subagent streams with inferred state types

    // Get all researcher subagents with typed state
    const researchers = stream.getSubagentsByType("researcher");

    researchers.forEach(researcher => {
      // researcher.values is typed based on ResearchMiddleware
      console.log("Research messages:", researcher.values.messages.length);
      console.log("Status:", researcher.status);
    });

    // Get all writer subagents
    const writers = stream.getSubagentsByType("writer");
    // writers have different state type based on WriterMiddleware
    getToolCalls: (message: AIMessage<ToolCall>) => ToolCallWithResult<ToolCall>[]

    Get tool calls for a specific AI message.

    Use this to find which tool calls were initiated by a particular assistant message, useful for rendering tool calls inline with messages.

    Type Declaration

    messages.map(message => {
      if (message.type === "ai") {
        const calls = stream.getToolCalls(message);
        return (
          <>
            <MessageBubble message={message} />
            {calls.map(tc => <ToolCallCard key={tc.call.id} {...tc} />)}
          </>
        );
      }
      return <MessageBubble message={message} />;
    });
    history: ThreadState<StateType>[]

    Flattened history of thread states of a thread. Contains all states in the current branch's history.

    interrupt: undefined | Interrupt<GetInterruptType<Bag>>

    Current interrupt, if the stream is interrupted. Convenience alias for interrupts[0]. For workflows with multiple concurrent interrupts, use interrupts instead.

    interrupts: Interrupt<GetInterruptType<Bag>>[]

    All current interrupts from the stream. When using Send() fan-out with per-task interrupt() calls, multiple interrupts may be pending simultaneously.

    isLoading: boolean

    Whether the stream is currently running. true while streaming, false when idle or completed.

    isThreadLoading: boolean

    Whether the thread is currently being loaded. true during initial thread data fetch.

    joinStream: (
        runId: string,
        lastEventId?: string,
        options?: {
            filter?: (
                event: { data: unknown; event: StreamEvent; id?: string },
            ) => boolean;
            streamMode?: StreamMode | StreamMode[];
        },
    ) => Promise<void>

    Join an active stream that's already running.

    Type Declaration

      • (
            runId: string,
            lastEventId?: string,
            options?: {
                filter?: (
                    event: { data: unknown; event: StreamEvent; id?: string },
                ) => boolean;
                streamMode?: StreamMode | StreamMode[];
            },
        ): Promise<void>

      • Parameters

        • runId: string

          The ID of the run to join

        • OptionallastEventId: string

          Optional last event ID for resuming from a specific point

        • Optionaloptions: {
              filter?: (
                  event: { data: unknown; event: StreamEvent; id?: string },
              ) => boolean;
              streamMode?: StreamMode | StreamMode[];
          }

          Optional configuration for the stream

        Returns Promise<void>

    messages: Message<ToolCall>[]

    Messages accumulated during the stream. Includes both human and AI messages. AI messages include typed tool calls based on the agent's tools.

    setBranch: (branch: string) => void

    Set the branch of the thread.

    Type Declaration

      • (branch: string): void

      • Parameters

        • branch: string

          The branch identifier to switch to

        Returns void

    stop: () => Promise<void>

    Stops the currently running stream.

    Type Declaration

      • (): Promise<void>

      • Returns Promise<void>

        A promise that resolves when the stream is stopped.

    subagents: Map<
        string,
        SubagentStreamInterface<
            SubagentStates[keyof SubagentStates],
            ToolCall,
            keyof SubagentStates & string,
        >,
    >

    All currently active and completed subagent streams.

    Keyed by tool call ID for easy lookup. Includes subagents in all states: pending, running, complete, and error.

    // Iterate over all subagents
    stream.subagents.forEach((subagent, toolCallId) => {
      console.log(`Subagent ${toolCallId}: ${subagent.status}`);
    });

    // Get a specific subagent
    const specific = stream.subagents.get("call_abc123");
    submit: (
        values: undefined | null | GetUpdateType<Bag, StateType>,
        options?: SubmitOptions<StateType, GetConfigurableType<Bag>>,
    ) => Promise<void>

    Create and stream a run to the thread.

    Type Declaration

      • (
            values: undefined | null | GetUpdateType<Bag, StateType>,
            options?: SubmitOptions<StateType, GetConfigurableType<Bag>>,
        ): Promise<void>

      • Parameters

        • values: undefined | null | GetUpdateType<Bag, StateType>

          The input values to send, or null/undefined for empty input

        • Optionaloptions: SubmitOptions<StateType, GetConfigurableType<Bag>>

          Optional configuration for the submission

        Returns Promise<void>

        A promise that resolves when the stream completes

    toolCalls: ToolCallWithResult<ToolCall>[]

    Tool calls paired with their results.

    Each entry contains the tool call request and its corresponding result. Useful for rendering tool invocations and their outputs together.

    stream.toolCalls.map(({ call, result }) => (
      <ToolCallCard
        name={call.name}
        args={call.args}
        result={result}
      />
    ));
    values: StateType

    The current state values of the stream. Updated as streaming events are received.

    Settings

    Member Visibility

    On This Page

    Properties