LangChain Reference home pageLangChain ReferenceLangChain Reference
  • GitHub
  • Main Docs
Deep Agents
LangChain
LangGraph
Integrations
LangSmith
LangGraph
  • Web
  • Channels
  • Pregel
  • Prebuilt
  • Remote
  • Stream
  • Overview
  • Getting started
  • useStream
  • Selectors
  • Interrupts & headless tools
  • Subagents & subgraphs
  • Fork & edit from a checkpoint
  • Submission queue
  • Multimodal media
  • Transports
  • provideStream & context
  • Type safety
  • Migrating to v1
LangGraph SDK
  • Client
  • Auth
  • React
  • Logging
  • React Ui
  • Server
LangGraph Checkpoint
LangGraph Checkpoint MongoDB
LangGraph Checkpoint Postgres
LangGraph Checkpoint Redis
  • Shallow
  • Store
LangGraph Checkpoint SQLite
LangGraph Checkpoint Validation
  • Cli
LangGraph API
LangGraph CLI
LangGraph CUA
  • Utils
LangGraph Supervisor
LangGraph Swarm
⌘I

Chat LangChain

What can I help with?

Enter to send·Shift+Enter new line

Menu

LangGraph
WebChannelsPregelPrebuiltRemoteStream
OverviewGetting starteduseStreamSelectorsInterrupts & headless toolsSubagents & subgraphsFork & edit from a checkpointSubmission queueMultimodal mediaTransportsprovideStream & contextType safetyMigrating to v1
LangGraph SDK
ClientAuthReactLoggingReact UiServer
LangGraph Checkpoint
LangGraph Checkpoint MongoDB
LangGraph Checkpoint Postgres
LangGraph Checkpoint Redis
ShallowStore
LangGraph Checkpoint SQLite
LangGraph Checkpoint Validation
Cli
LangGraph API
LangGraph CLI
LangGraph CUA
Utils
LangGraph Supervisor
LangGraph Swarm
Language
Theme
JavaScript@langchain/svelte

@langchain/svelte

Description

@langchain/svelte

Svelte 5 SDK for Deep Agents, LangChain and LangGraph.

useStream binds a LangGraph agent into a Svelte 5 component. Reactive fields are exposed as getters on a stable handle (stream.messages, stream.isLoading, …) so templates and $derived expressions track updates automatically — no stores, no $ prefix, no destructuring.

Installation

npm install @langchain/svelte @langchain/core

Peer dependencies: svelte ^5.0.0, @langchain/core ^1.0.1

Quick start

<script lang="ts">
  import { useStream } from "@langchain/svelte";

  const stream = useStream({
    assistantId: "agent",
    apiUrl: "http://localhost:2024",
  });
</script>

{#each stream.messages as msg (msg.id)}
  <div>{msg.content}</div>
{/each}

<button
  disabled={stream.isLoading}
  onclick={() =>
    stream.submit({ messages: [{ type: "human", content: "Hello!" }] })}
>
  Send
</button>

Note: Access fields through the live stream handle. Destructuring (const { messages } = stream) freezes the values at that moment — use stream.messages in templates instead.

Highlights

  • v2-native streaming protocol. Session-based transport with automatic re-attach on remount; no more reconnectOnMount / joinStream dance.
  • Always-on root projections. values, messages, toolCalls, and interrupts are reactive at the root with zero extra subscription cost.
  • Selector composables for scoped data. Per-subagent / per-subgraph messages, tool calls, and media stream only when a component actually mounts the matching composable, and release on unmount.
  • Discriminated option bag. The hosted Agent Server path and the custom-adapter path are two arms of a single typed union — mixing them is a compile-time error.
  • Reactive threadId. Pass threadId: () => active to drive in-place thread swaps without remounting.
  • Agent-brand type inference. useStream<typeof agent>() unwraps state, tool calls, and subagent state maps from an agent brand.
  • Multimodal media streams. Built-in assembly for audio, images, video, and files — plus opinionated playback helpers.
  • Headless tools. Register local tool implementations that auto-resolve server-emitted tool-call interrupts without a round-trip through the UI.

Documentation

In-depth guides live in docs/:

  • useStream — options, return shape, reactive threadId
  • Selector composables (useMessages, useToolCalls, useValues, …)
  • Interrupts, respond(), stop(), hydrationPromise
  • Submission queue
  • Stream context (provideStream / getStream)
  • Headless tools
  • Custom transport (AgentServerAdapter, HttpAgentServerAdapter)
  • Media (images, audio, video, files) & playback helpers
  • Type safety

Migrating from v0

@langchain/svelte v1 targets the v2 streaming protocol. The useStream import stays the same, but the option bag, return shape, and how you subscribe to scoped data all change. Most chat apps migrate in well under an hour — the full guide with line-by-line diffs lives in docs/v1-migration.md.

Playground

For full end-to-end examples, see the LangChain UI Playground.

License

MIT

Classes

Class

HttpAgentServerAdapter

Public v1 name for TransportAdapter plus optional high-level capabilities. Renamed to reflect that this interface now denotes the full agent-server protocol contract (not merely wire transport): any o

Class

MediaAssemblyError

Typed error thrown through media.stream / rejected from media.blob / media.objectURL when a handle fails before its message completes. Carries the bytes accumulated up to the failure point on `p

Functions

Function

executeHeadlessTool

Function

filterOutHeadlessToolInterrupts

Strip headless-tool interrupts from a user-facing interrupt list.

Function

findHeadlessTool

Function

flushPendingHeadlessToolInterrupts

Execute and resume all newly seen headless-tool interrupts from a values payload. Callers own handledIds and should clear it when the thread changes.

Function

getStream

Reads the shared stream handle exposed by the nearest ancestor provideStream call. Throws when no ancestor has provided one.

Function

handleHeadlessToolInterrupt

Function

headlessToolResumeCommand

Function

isHeadlessToolInterrupt

Function

parseHeadlessToolInterruptPayload

Parses a headless-tool interrupt value from the graph. Accepts both toolCall (LangChain JS) and tool_call (Python / JSON snake_case).

Function

provideStream

Creates a shared useStream handle and publishes it via Svelte's setContext. Descendant components read it via getStream.

Must be called during component initialisation (the top level of a `

Interface

AgentServerAdapter

Public v1 name for TransportAdapter plus optional high-level capabilities. Renamed to reflect that this interface now denotes the full agent-server protocol contract (not merely wire transport): any o

Interface

AssembledToolCall

Reactive tool handle for framework bindings (stream.toolCalls, useToolCalls, injectToolCalls).

status, error, and output are plain values that the assembler updates in place as tool events arri

Interface

AudioMedia

Shared surface across every media handle returned by MediaAssembler.

The handle is live while its parent message is active:

  • partialBytes is a snapshot of all bytes received so far.
  • stream i
Interface

AudioPlayerHandle

Player controls + live state returned by useAudioPlayer.

Live state is exposed via getters on a stable object so templates can read player.status / player.currentTime without a .value hop. Impe

Interface

FileMedia

Shared surface across every media handle returned by MediaAssembler.

The handle is live while its parent message is active:

  • partialBytes is a snapshot of all bytes received so far.
  • stream i
Interface

FlushPendingHeadlessToolInterruptsOptions

Interface

HeadlessToolImplementation

Client-side implementation returned by headlessTool.implement(...).

Interface

HeadlessToolInterrupt

Represents a headless tool interrupt payload emitted by LangChain's schema-only tool({ ... }) overload.

Servers may serialize the nested tool call as toolCall (JS) or tool_call (Python). Use pa

Interface

HttpAgentServerAdapterOptions

Interface

ImageMedia

Shared surface across every media handle returned by MediaAssembler.

The handle is live while its parent message is active:

  • partialBytes is a snapshot of all bytes received so far.
  • stream i
Interface

MediaBase

Shared surface across every media handle returned by MediaAssembler.

The handle is live while its parent message is active:

  • partialBytes is a snapshot of all bytes received so far.
  • stream i
Interface

MessageMetadata

Metadata tracked per message id. Surfaced to applications via useMessageMetadata(stream, messageId).

Interface

StreamStopOptions

Options for StreamController.stop / framework stop().

Interface

StreamSubmitOptions

Interface

SubagentDiscoverySnapshot

Lightweight discovery record for a subagent running inside the thread.

Populated eagerly from the root subscription (tools + lifecycle channels). Content projections (messages, toolCalls, cus

Interface

SubgraphDiscoverySnapshot

Lightweight discovery record for a subgraph running inside the thread.

Interface

SubmissionQueueEntry

A single queued submission.

Interface

ThreadStream

High-level wrapper around a protocol connection to a specific thread.

In the thread-centric protocol, threads are durable (backed by checkpoints) and connections are ephemeral. A ThreadStream is th

Interface

ToolEvent

Interface

UseAgentStream

Stream interface for ReactAgent instances created with createAgent.

Extends UseGraphStream with tool calling capabilities. Tool calls are automatically typed based on the agent's tools configuratio

Interface

UseAgentStreamOptions

Options for configuring an agent stream.

Use this options interface when calling useStream with a ReactAgent created via createAgent.

This interface is subject to change.

Interface

UseAudioPlayerOptions

Options for useAudioPlayer.

Interface

UseChannelEffectOptions

Options for useChannelEffect. Extends the projection options (bufferSize, replay) with the per-event callback, an optional error sink, a reactive target scope, and a reactive enabled gate.

Interface

UseDeepAgentStream

Stream interface for DeepAgent instances created with createDeepAgent.

Extends UseAgentStream with subagent streaming capabilities. Subagent streams are automatically typed based on the agent's sub

Interface

UseDeepAgentStreamOptions

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 conf

Interface

UseStreamReturn

Svelte binding return type for useStream. Reactive projections are exposed as getters on a stable object so templates can read stream.messages directly without a .value / .current hop and `$deri

Interface

UseSubmissionQueueReturn

Reactive handle on the server-side submission queue.

Populated when submit() is invoked with multitaskStrategy: "enqueue" while another run is in flight. The returned getters are stable — safe to

Interface

UseVideoPlayerOptions

Options for useVideoPlayer.

Interface

VideoMedia

Shared surface across every media handle returned by MediaAssembler.

The handle is live while its parent message is active:

  • partialBytes is a snapshot of all bytes received so far.
  • stream i
Interface

VideoPlayerHandle

Controls + live state returned by useVideoPlayer. Mirrors AudioPlayerHandle on the shared subset so callers only ever learn one shape.

Type

AcceptBaseMessages

Widens an update type so that its messages field also accepts @langchain/core BaseMessage class instances (single or array).

Framework SDKs apply this to submit so callers can write:

stre
Type

AgentServerOptions

Type

AnyHeadlessToolImplementation

Type

AnyMediaHandle

Type

AnyStream

Erased handle useful as a parameter type for helpers and wrapper components that pass a stream through to selector composables without reading values directly. Mirrors the React AnyStream alias.

Type

CustomAdapterOptions

Type

DefaultToolCall

Default tool call type when no specific tool definitions are provided.

Type

GetToolCallsType

Extract the tool call type from a StateType's messages property. This is the canonical way to get typed tool calls in useStream.

Tool call types are now extracted from the messages property of StateT

Type

InferStateType

Unwrap the state shape from a compiled graph, a create-agent brand, or a plain type. Used by useStream<T>() to resolve T = typeof agent into the state the values/messages projections observe.

Type

InferSubagentStates

Infer the subagent → state map from a DeepAgent brand. Non-brands collapse to DefaultSubagentStates.

Type

InferToolCalls

Infer the discriminated union of AssembledToolCall handles from an agent brand, an array of LangChain tools, or fall back to the untyped default handle.

Pass typeof agent or typeof tools and narr

Type

InferToolOutput

Infer the successful return type of a LangChain tool.

Resolution order mirrors InferToolInput: func, then invoke, then _call, so inference survives cross-package boundaries where _call is `pr

Type

MediaAssemblyErrorKind

Kinds of failure that can terminate a media handle prematurely.

  • "message-error" — the upstream message emitted an error event before completion.
  • "stream-closed" — the transport stream clo
Type

MediaBlockType

Block types this assembler knows how to reassemble into media handles.

Type

MessageMetadataMap

Read-only map exposed via MessageMetadataTracker.store.

Type

OnToolCallback

Type

PlayerStatus

Lifecycle state of an audio or video player returned by useAudioPlayer and useVideoPlayer.

Type

ProvideStreamCustomProps

Props for provideStream when wiring a custom AgentServerAdapter.

Type

ProvideStreamProps

Props for provideStream when talking to the default LangGraph-Platform agent server.

Type

ResolveStreamInterface

Resolves the appropriate stream interface based on the agent/graph type.

This type automatically selects the correct stream interface based on the type of agent or graph passed to useStream:

  1. **
Type

ResolveStreamOptions

Resolves the appropriate options interface based on the agent/graph type.

This type automatically selects the correct options interface based on the type of agent or graph:

  1. DeepAgent → UseDee
Type

SelectorTarget

What a selector composable targets. Callers can pass:

  • undefined / null — root namespace (served by the always-on root store; no extra subscription opens);
  • a SubagentDiscoverySnapshot (`st
Type

SubmissionQueueSnapshot

Read-only snapshot of the queue. The queue store hands this out directly; consumers must not mutate the array.

Type

ToolCallFromTool

Infer the streaming AssembledToolCall handle for a single LangChain tool.

Parallel to ToolCallFromTool for message-level tool calls — use this when a component receives one entry from `stream.toolCal

Type

ToolCallsFromTools

Infer a union of tool call types from an array of tools. Works with tools created via tool() from @langchain/core/tools.

Type

ToolCallState

The lifecycle state of a tool call.

  • pending: Tool call received, awaiting result
  • completed: Tool execution finished successfully
  • error: Tool execution failed (result.status === "error")
Type

ToolCallStatus

High-level outcome of a single tool call.

Type

UseStreamOptions

Type

UseStreamResult

Convenience alias for the fully-resolved stream handle type.

Type

WidenUpdateMessages

Widen an update type so its messages field also accepts @langchain/core BaseMessage class instances (single or array). Framework bindings apply this to submit() so callers can write `stream.subm