langchain.js
    Preparing search index...

    Interface UseDeepAgentStreamOptions<StateType, Bag>

    Options for configuring a deep agent stream.

    Use this options interface when calling useStream with a DeepAgent created via createDeepAgent. Includes all agent options plus subagent-specific configuration.

    const stream = useStream<typeof agent>({
      assistantId: "deep-agent",
      apiUrl: "http://localhost:2024",

      // DeepAgent-specific options
      subagentToolNames: ["task", "delegate"],
      filterSubagentMessages: true,

      onError: (error) => console.error(error),
    });
    interface UseDeepAgentStreamOptions<
        StateType extends Record<string, unknown> = Record<string, unknown>,
        Bag extends BagTemplate = BagTemplate,
    > {
        apiKey?: null | string;
        apiUrl?: string;
        assistantId: string;
        callerOptions?: AsyncCallerParams;
        client?: Client<DefaultValues, DefaultValues, unknown>;
        defaultHeaders?: Record<string, HeaderValue>;
        fetchStateHistory?: boolean | { limit: number };
        filterSubagentMessages?: boolean;
        initialValues?: null | StateType;
        messagesKey?: string;
        onCheckpointEvent?: (
            data: {
                config: Config;
                metadata: Metadata;
                next: string[];
                tasks: ThreadTask<DefaultValues, unknown>[];
                values: StateType;
            },
            options: { namespace: undefined | string[] },
        ) => void;
        onCreated?: (run: RunCallbackMeta) => void;
        onCustomEvent?: (
            data: GetCustomEventType<Bag>,
            options: {
                mutate: (
                    update:
                        | Partial<StateType>
                        | ((prev: StateType) => Partial<StateType>),
                ) => void;
                namespace: undefined | string[];
            },
        ) => void;
        onError?: (error: unknown, run: undefined | RunCallbackMeta) => void;
        onFinish?: (
            state: ThreadState<StateType>,
            run: undefined | RunCallbackMeta,
        ) => void;
        onLangChainEvent?: (
            data: {
                data: unknown;
                event:
                    | string & {}
                    | "on_tool_start"
                    | "on_tool_stream"
                    | "on_tool_end"
                    | "on_chat_model_start"
                    | "on_chat_model_stream"
                    | "on_chat_model_end"
                    | "on_llm_start"
                    | "on_llm_stream"
                    | "on_llm_end"
                    | "on_chain_start"
                    | "on_chain_stream"
                    | "on_chain_end"
                    | "on_retriever_start"
                    | "on_retriever_stream"
                    | "on_retriever_end"
                    | "on_prompt_start"
                    | "on_prompt_stream"
                    | "on_prompt_end";
                metadata: Record<string, unknown>;
                name: string;
                parent_ids: string[];
                run_id: string;
                tags: string[];
            },
        ) => void;
        onMetadataEvent?: (data: { run_id: string; thread_id: string }) => void;
        onStop?: (
            options: {
                mutate: (
                    update:
                        | Partial<StateType>
                        | ((prev: StateType) => Partial<StateType>),
                ) => void;
            },
        ) => void;
        onTaskEvent?: (
            data:
                | {
                    error: string;
                    id: string;
                    interrupts: Interrupt<unknown>[];
                    name: string;
                }
                | {
                    id: string;
                    input: StateType;
                    interrupts: Interrupt<unknown>[];
                    name: string;
                    triggers: string[];
                }
                | {
                    id: string;
                    interrupts: Interrupt<unknown>[];
                    name: string;
                    result: [string, GetUpdateType<Bag, StateType>][];
                },
            options: { namespace: undefined | string[] },
        ) => void;
        onThreadId?: (threadId: string) => void;
        onUpdateEvent?: (
            data: { [node: string]: GetUpdateType<Bag, StateType> },
            options: {
                mutate: (
                    update:
                        | Partial<StateType>
                        | ((prev: StateType) => Partial<StateType>),
                ) => void;
                namespace: undefined | string[];
            },
        ) => void;
        reconnectOnMount?: boolean
        | (() => RunMetadataStorage);
        subagentToolNames?: string[];
        thread?: UseStreamThread<StateType>;
        threadId?: null | string;
        throttle?: number | boolean;
    }

    Type Parameters

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

      The agent's state type

    • Bag extends BagTemplate = BagTemplate

      Type configuration bag

    Hierarchy (View Summary)

    Index

    Properties

    apiKey? apiUrl? assistantId callerOptions? client? defaultHeaders? fetchStateHistory? filterSubagentMessages? initialValues? messagesKey? onCheckpointEvent? onCreated? onCustomEvent? onError? onFinish? onLangChainEvent? onMetadataEvent? onStop? onTaskEvent? onThreadId? onUpdateEvent? reconnectOnMount? subagentToolNames? thread? threadId? throttle?

    Properties

    apiKey?: null | string

    The API key to use.

    apiUrl?: string

    The URL of the API to use.

    assistantId: string

    The ID of the assistant to use.

    callerOptions?: AsyncCallerParams

    Custom call options, such as custom fetch implementation.

    client?: Client<DefaultValues, DefaultValues, unknown>

    Client used to send requests.

    defaultHeaders?: Record<string, HeaderValue>

    Default headers to send with requests.

    fetchStateHistory?: boolean | { limit: number }

    Whether to fetch the history of the thread. If true, the history will be fetched from the server. Defaults to 10 entries. If false, only the last state will be fetched from the server.

    true
    filterSubagentMessages?: boolean

    Whether to filter out messages from subagent namespaces.

    When true, only messages from the main agent are included in the messages array. Subagent messages are still accessible via the subagents map and individual subagent streams.

    This is useful when you want to display subagent progress separately from the main conversation, or when subagent messages would be too verbose in the main message list.

    false

    const stream = useStream<typeof agent>({
      assistantId: "deep-agent",
      filterSubagentMessages: true,
    });

    // stream.messages only contains main agent messages
    // Subagent messages are in stream.getSubagentsByType("researcher")[0].messages
    initialValues?: null | StateType

    Initial values to display immediately when loading a thread. Useful for displaying cached thread data while official history loads. These values will be replaced when official thread data is fetched.

    Note: UI components from initialValues will render immediately if they're predefined in LoadExternalComponent's components prop, providing instant cached UI display without server fetches.

    messagesKey?: string

    Specify the key within the state that contains messages. Defaults to "messages".

    "messages"
    onCheckpointEvent?: (
        data: {
            config: Config;
            metadata: Metadata;
            next: string[];
            tasks: ThreadTask<DefaultValues, unknown>[];
            values: StateType;
        },
        options: { namespace: undefined | string[] },
    ) => void

    Callback that is called when a checkpoints event is received.

    onCreated?: (run: RunCallbackMeta) => void

    Callback that is called when a new stream is created.

    onCustomEvent?: (
        data: GetCustomEventType<Bag>,
        options: {
            mutate: (
                update: Partial<StateType> | ((prev: StateType) => Partial<StateType>),
            ) => void;
            namespace: undefined | string[];
        },
    ) => void

    Callback that is called when a custom event is received.

    onError?: (error: unknown, run: undefined | RunCallbackMeta) => void

    Callback that is called when an error occurs.

    onFinish?: (
        state: ThreadState<StateType>,
        run: undefined | RunCallbackMeta,
    ) => void

    Callback that is called when the stream is finished.

    onLangChainEvent?: (
        data: {
            data: unknown;
            event:
                | string & {}
                | "on_tool_start"
                | "on_tool_stream"
                | "on_tool_end"
                | "on_chat_model_start"
                | "on_chat_model_stream"
                | "on_chat_model_end"
                | "on_llm_start"
                | "on_llm_stream"
                | "on_llm_end"
                | "on_chain_start"
                | "on_chain_stream"
                | "on_chain_end"
                | "on_retriever_start"
                | "on_retriever_stream"
                | "on_retriever_end"
                | "on_prompt_start"
                | "on_prompt_stream"
                | "on_prompt_end";
            metadata: Record<string, unknown>;
            name: string;
            parent_ids: string[];
            run_id: string;
            tags: string[];
        },
    ) => void

    Callback that is called when a LangChain event is received.

    https://langchain-ai.github.io/langgraph/cloud/how-tos/stream_events/#stream-graph-in-events-mode for more details.

    onMetadataEvent?: (data: { run_id: string; thread_id: string }) => void

    Callback that is called when a metadata event is received.

    onStop?: (
        options: {
            mutate: (
                update: Partial<StateType> | ((prev: StateType) => Partial<StateType>),
            ) => void;
        },
    ) => void

    Callback that is called when the stream is stopped by the user. Provides a mutate function to update the stream state immediately without requiring a server roundtrip.

    onStop: ({ mutate }) => {
      mutate((prev) => ({
        ...prev,
        ui: prev.ui?.map(component =>
          component.props.isLoading
            ? { ...component, props: { ...component.props, stopped: true, isLoading: false }}
            : component
        )
      }));
    }
    onTaskEvent?: (
        data:
            | {
                error: string;
                id: string;
                interrupts: Interrupt<unknown>[];
                name: string;
            }
            | {
                id: string;
                input: StateType;
                interrupts: Interrupt<unknown>[];
                name: string;
                triggers: string[];
            }
            | {
                id: string;
                interrupts: Interrupt<unknown>[];
                name: string;
                result: [string, GetUpdateType<Bag, StateType>][];
            },
        options: { namespace: undefined | string[] },
    ) => void

    Callback that is called when a tasks event is received.

    onThreadId?: (threadId: string) => void

    Callback that is called when the thread ID is updated (ie when a new thread is created).

    onUpdateEvent?: (
        data: { [node: string]: GetUpdateType<Bag, StateType> },
        options: {
            mutate: (
                update: Partial<StateType> | ((prev: StateType) => Partial<StateType>),
            ) => void;
            namespace: undefined | string[];
        },
    ) => void

    Callback that is called when an update event is received.

    reconnectOnMount?: boolean | (() => RunMetadataStorage)

    Will reconnect the stream on mount

    subagentToolNames?: string[]

    Tool names that indicate subagent invocation.

    When an AI message contains tool calls with these names, they are automatically tracked as subagent executions. This enables the subagents, activeSubagents, getSubagent(), getSubagentsByType(), and getSubagentsByMessage() properties on the stream.

    ["task"]

    const stream = useStream<typeof agent>({
      assistantId: "deep-agent",
      // Track both "task" and "delegate" as subagent tools
      subagentToolNames: ["task", "delegate", "spawn_agent"],
    });

    // Now stream.subagents will include executions from any of these tools
    thread?: UseStreamThread<StateType>

    Manage the thread state externally.

    threadId?: null | string

    The ID of the thread to fetch history and current values from.

    throttle?: number | boolean

    Throttle the stream. If a number is provided, the stream will be throttled to the given number of milliseconds. If true, updates are batched in a single macrotask. If false, updates are not throttled or batched.

    true

    Settings

    Member Visibility

    On This Page

    Properties