@b4run/langgraph

Use this whenCopy link to section: Use this when

Use this package when a B4.run runtime or framework extension must normalize graph and workflow route modules or execute those entries through B4.run's backend-adapter contract. Route authors normally use the SDK route contracts and let the CLI choose these adapters.

Install and importCopy link to section: Install and import

bash

npm install @b4run/langgraph

import { defineEntry, graphAdapter, normalizeRouteModule } from "@b4run/langgraph"
import type { RouteModule } from "@b4run/langgraph/route-module"

Use @b4run/langgraph/define-entry for the smallest entry-validation import and @b4run/langgraph/route-module for normalization contracts without the adapters.

Compatibility and audienceCopy link to section: Compatibility and audience

Surface	Runtime	Purity	Audience	Stability
`@b4run/langgraph`	edge-safe	dependency-free	integration	supported
`@b4run/langgraph/define-entry`	edge-safe	dependency-free	integration	supported
`@b4run/langgraph/route-module`	edge-safe	dependency-free	integration	supported

All three runtime surfaces bundle without third-party runtime dependencies or Node globals. That covers importing and running these adapters. It says nothing about a graph, workflow, or tool your application supplies.

Public exportsCopy link to section: Public exports

`@b4run/langgraph`Copy link to section: @b4run/langgraph

Export	Responsibility
`defineEntry`	Validate and return a graph-or-workflow route module unchanged.
`graphAdapter`	Execute callable graphs or objects with `invoke(input)`.
`workflowAdapter`	Execute callable workflow entries.
`GraphRouteModule`	Describe a module with a `graph` entry.
`NormalizedRouteModule`	Describe the normalized kind, entry, and config.
`normalizeRouteModule`	Validate and normalize either route-module form.
`RouteConfig`	Re-export the SDK-owned route configuration.
`RouteKind`	Re-export the SDK-owned `agent`, `chain`, `graph`, or `workflow` kind.
`RouteModule`	Unite graph and workflow route-module forms.
`WorkflowRouteModule`	Describe a module with a `workflow` entry.
`RuntimeContext`	Re-export the SDK-owned runtime context.
`RuntimeTool`	Re-export the SDK-owned callable tool contract.

ToolRegistry lives in a private implementation module and is not exported.

`@b4run/langgraph/define-entry`Copy link to section: @b4run/langgraph/define-entry

Export	Responsibility
`defineEntry`	Validate and preserve one route-module object.

`@b4run/langgraph/route-module`Copy link to section: @b4run/langgraph/route-module

Export	Responsibility
`GraphRouteModule`	Describe a module with a `graph` entry.
`NormalizedRouteModule`	Describe the normalized kind, entry, and config.
`normalizeRouteModule`	Produce a normalized route module.
`assertExactlyOneEntry`	Assert the runtime graph/workflow exclusivity rule.
`RouteConfig`	Re-export the SDK-owned route configuration.
`RouteKind`	Re-export the SDK-owned route kind.
`RouteModule`	Unite graph and workflow module forms.
`WorkflowRouteModule`	Describe a module with a `workflow` entry.

The route-module subpath exposes only its published normalization and route-module contracts.

Key contractsCopy link to section: Key contracts

export declare function defineEntry<TEntry, TModule extends RouteModule<TEntry>>(
  module: TModule,
): TModule

export interface GraphRouteModule<TEntry = unknown> {
  readonly graph: TEntry
  readonly workflow?: never
  readonly config?: RouteConfig
}

Fields: @b4run/langgraph#./route-module:GraphRouteModule

Field	Type	Required	Description
`readonly graph`	`TEntry`	yes	Supply the graph entry.
`readonly workflow`	`never`	no	Exclude the workflow alternative.
`readonly config`	`RouteConfig`	no	Configure the route; normalization defaults it to `{}`.

export interface WorkflowRouteModule<TEntry = unknown> {
  readonly workflow: TEntry
  readonly graph?: never
  readonly config?: RouteConfig
}

Fields: @b4run/langgraph#./route-module:WorkflowRouteModule

Field	Type	Required	Description
`readonly workflow`	`TEntry`	yes	Supply the workflow entry.
`readonly graph`	`never`	no	Exclude the graph alternative.
`readonly config`	`RouteConfig`	no	Configure the route; normalization defaults it to `{}`.

export type RouteModule<TEntry = unknown> = GraphRouteModule<TEntry>
  | WorkflowRouteModule<TEntry>

export interface NormalizedRouteModule<TEntry = unknown> {
  readonly kind: RouteKind
  readonly entry: TEntry
  readonly config: RouteConfig
}

Fields: @b4run/langgraph#./route-module:NormalizedRouteModule

Field	Type	Required	Description
`readonly kind`	`RouteKind`	yes	Identify the selected route entry kind.
`readonly entry`	`TEntry`	yes	Hold the selected graph or workflow.
`readonly config`	`RouteConfig`	yes	Hold the supplied config or `{}`.

export declare function normalizeRouteModule<TEntry>(
  module: RouteModule<TEntry> | (GraphRouteModule<TEntry> & WorkflowRouteModule<TEntry>),
): NormalizedRouteModule<TEntry>

export declare function assertExactlyOneEntry<TEntry>(
  module: RouteModule<TEntry> | (GraphRouteModule<TEntry> & WorkflowRouteModule<TEntry>),
): asserts module is RouteModule<TEntry>

Behavior contractsCopy link to section: Behavior contracts

Behavior contract `langgraph.entry.exclusive`

A route module must provide exactly one of graph or workflow.

Entry validation caveats

An explicitly undefined key counts as absent. defineEntry() returns the original object, while normalizeRouteModule() fills an omitted config with a new empty object. Invalid modules throw synchronously before an entry executes.

Behavior contract `langgraph.route-module.surface`

The route-module subpath exposes only its published normalization and route-module contracts.

Adapter lifecycle and failures

graphAdapter calls a function directly or calls an object's invoke. workflowAdapter accepts only a function. Both pass { signal }, await the result, and implement stream() as a single yielded execute result, with no native multi-chunk graph streaming. The runtime, streaming, and tags route-config fields are reserved, and these adapters ignore them.

import { defineEntry, normalizeRouteModule } from "@b4run/langgraph"
 
const route = defineEntry({
  workflow: async (input: { name: string }, { signal }: { signal: AbortSignal }) => {
    signal.throwIfAborted()
    return { greeting: `Hello, ${input.name}` }
  },
  config: { runtime: "node", streaming: false }, // reserved; no adapter runtime effect
})
 
const normalized = normalizeRouteModule(route)
console.log(normalized.kind) // workflow

Continue with Routes, SDK API, and CLI API.

@b4run/langgraph

Use this when#Copy link to section: Use this when

Install and import#Copy link to section: Install and import

Compatibility and audience#Copy link to section: Compatibility and audience

Public exports#Copy link to section: Public exports

@b4run/langgraph#Copy link to section: @b4run/langgraph

@b4run/langgraph/define-entry#Copy link to section: @b4run/langgraph/define-entry

@b4run/langgraph/route-module#Copy link to section: @b4run/langgraph/route-module

Key contracts#Copy link to section: Key contracts

Behavior contracts#Copy link to section: Behavior contracts

Behavior contract langgraph.entry.exclusive