Skip to content

docs: document first-class graph-state access for ToolNode tools#2511

Merged
Christian Bromann (christian-bromann) merged 10 commits into
mainfrom
cb/toolnode-state-access-docs-45f2
Jun 10, 2026
Merged

docs: document first-class graph-state access for ToolNode tools#2511
Christian Bromann (christian-bromann) merged 10 commits into
mainfrom
cb/toolnode-state-access-docs-45f2

Conversation

@christian-bromann

@christian-bromann Christian Bromann (christian-bromann) commented Jun 9, 2026

Copy link
Copy Markdown
Member

Tools running inside a ToolNode can already read the current graph state via getCurrentTaskInput(), but this was not documented as a first-class option and the browser-safe variant (passing config explicitly) was not surfaced.

This adds:

  • JSDoc on getCurrentTaskInput documenting the optional config arg and browser usage
  • A ToolNode JSDoc example showing how tools access graph state and runtime context
  • Browser-safe guidance in the agents context docs and the pass-run-time-values-to-tools how-to (getCurrentTaskInput(config))
  • A regression test verifying a ToolNode tool can read graph state via getCurrentTaskInput(config)

Closes #2506

@christian-bromann
docs: document first-class graph-state access for ToolNode tools
3277b82 
Tools running inside a ToolNode can already read the current graph state
via getCurrentTaskInput(), but this was not documented as a first-class
option and the browser-safe variant (passing config explicitly) was not
surfaced. This adds:

- JSDoc on getCurrentTaskInput documenting the optional config arg and
  browser usage
- A ToolNode JSDoc example showing how tools access graph state and
  runtime context
- Browser-safe guidance in the agents context docs and the
  pass-run-time-values-to-tools how-to (getCurrentTaskInput(config))
- A regression test verifying a ToolNode tool can read graph state via
  getCurrentTaskInput(config)

Closes #2506
@christian-bromann
docs: wire ToolNode state example into a StateGraph
4ede39a 
Show how the custom StateAnnotation is passed to StateGraph and run via a
ToolNode so getCurrentTaskInput actually returns the custom graph state.
@christian-bromann
docs: use modern Zod state schema in ToolNode state example
b738836 
Replace the legacy Annotation.Root state definition with the Zod-based
StateSchema (MessagesZodState + z.object) in the ToolNode JSDoc example
and the corresponding regression test.
@christian-bromann
test: prove getCurrentTaskInput(config) works without AsyncLocalStorage
b8db024 
Add a regression test that simulates a browser/web runtime (no async_hooks)
by forcing @langchain/core's MockAsyncLocalStorage. It verifies that the
implicit getCurrentTaskInput() lookup fails in that environment, while
getCurrentTaskInput(config) still reads the full graph state because
ToolNode threads config to the tool as an explicit argument.
@changeset-bot

changeset-bot Bot commented Jun 9, 2026 •
edited
Loading

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 617e770

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages
Name Type
@langchain/langgraph Minor
@example/ai-elements Patch
@examples/assistant-ui-claude Patch
@examples/ui-angular Patch
@examples/ui-multimodal Patch
@examples/ui-react Patch
langgraph Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@pkg-pr-new

pkg-pr-new Bot commented Jun 9, 2026 •
edited
Loading

Copy link
Copy Markdown

Open in StackBlitz

@langchain/langgraph-checkpoint

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint@2511

@langchain/langgraph-checkpoint-mongodb

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-mongodb@2511

@langchain/langgraph-checkpoint-postgres

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-postgres@2511

@langchain/langgraph-checkpoint-redis

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-redis@2511

@langchain/langgraph-checkpoint-sqlite

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-sqlite@2511

@langchain/langgraph-checkpoint-validation

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-checkpoint-validation@2511

create-langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/create-langgraph@2511

@langchain/langgraph-api

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-api@2511

@langchain/langgraph-cli

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cli@2511

@langchain/langgraph

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph@2511

@langchain/langgraph-cua

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-cua@2511

@langchain/langgraph-supervisor

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-supervisor@2511

@langchain/langgraph-swarm

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-swarm@2511

@langchain/langgraph-ui

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-ui@2511

@langchain/langgraph-sdk

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/langgraph-sdk@2511

@langchain/angular

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/angular@2511

@langchain/react

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/react@2511

@langchain/svelte

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/svelte@2511

@langchain/vue

npm i https://pkg.pr.new/langchain-ai/langgraphjs/@langchain/vue@2511

commit: 617e770

open-swe[bot]
open-swe Bot reviewed Jun 9, 2026
View reviewed changes

@open-swe open-swe Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Open SWE Review: No issues found

Open SWE reviewed this PR and found no potential bugs to report.

View Open SWE trace

@christian-bromann
Create metal-radios-cover.md
6cc3da4
@christian-bromann
feat(ToolNode): forward graph state to tools via config.state
fc3073e 
ToolNode now forwards its input (the current graph state when used as a
graph node, e.g. in createReactAgent) to each tool through the second
argument as `config.state`. Tools can type the second parameter as the new
`ToolRunnableConfig<StateType>` and read `config.state` directly.

This aligns ToolNode with how state is propagated elsewhere (the runtime
second parameter) and removes the need for `getCurrentTaskInput()`, which
relies on node:async_hooks/AsyncLocalStorage and therefore does not work in
web browsers. Reading from `config.state` works in every runtime.

- Add and export `ToolRunnableConfig` from @langchain/langgraph/prebuilt
- Strip the internal `lg_tool_call` routing key (v2 Send path) from state
- Keep `getCurrentTaskInput(config)` working for backwards compatibility
- Update ToolNode JSDoc, context docs, and the runtime-values how-to
- Tests: config.state in a graph node, on direct .invoke(), and in a
  simulated no-AsyncLocalStorage (browser) environment
@christian-bromann
chore: update changeset to minor for ToolNode config.state feature
9a745c2
@christian-bromann Christian Bromann (christian-bromann) merged commit ef04db3 into main Jun 10, 2026
48 of 49 checks passed
@christian-bromann Christian Bromann (christian-bromann) deleted the cb/toolnode-state-access-docs-45f2 branch June 10, 2026 22:18
This was referenced Jun 10, 2026
Merged
Open
Christian Bromann (christian-bromann) pushed a commit that referenced this pull request Jun 11, 2026
@github-actions
chore: version packages (#2524)
34a0125 
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @langchain/langgraph-supervisor@1.1.0

### Minor Changes

- [#2521](#2521)
[`56682a6`](56682a6)
Thanks [@open-swe](https://github.com/apps/open-swe)! -
feat(langgraph-supervisor): Add `addHandoffMessages` to
`createSupervisor` and `createHandoffTool`, allowing supervisor-to-agent
handoff bookkeeping messages to be omitted from the expert agent's
message history. When `addHandoffBackMessages` is not provided, it now
defaults to the same value as `addHandoffMessages`, matching the Python
package behavior.

`createHandoffTool` now also accepts `description` as the preferred
option name while continuing to support the existing `agentDescription`
option as deprecated for backwards compatibility.

### Patch Changes

- [#2407](#2407)
[`59d4765`](59d4765)
Thanks [@pragnyanramtha](https://github.com/pragnyanramtha)! - Normalize
all whitespace in supervisor handoff tool names.

## @langchain/langgraph@1.4.1

### Patch Changes

- [#2520](#2520)
[`2da5c33`](2da5c33)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
fix(state): validate Zod state updates from nodes

Validate node return values and Command updates against Zod state schema
    constraints before applying them to graph state.

Fixes [#2519](#2519)

- [#2511](#2511)
[`ef04db3`](ef04db3)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
feat(ToolNode): forward graph state to tools via `runtime.state`

`ToolNode` now forwards its input to each tool through the second
argument as `runtime.state`. When using `ToolNode` as a node in a
LangGraph graph, this gives tools access to the current graph state for
workflows that need tool-call support in LangGraph proper. Tools can
type the second parameter as `ToolRuntime<StateType>` from
`@langchain/core/tools` and read `runtime.state` directly. This works in
every runtime, including web browsers, and removes the need for
`getCurrentTaskInput()` (which relies on
`node:async_hooks`/`AsyncLocalStorage`). `getCurrentTaskInput(config)`
continues to work for backwards compatibility.

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21

## @langchain/langgraph-sdk@1.9.21

### Patch Changes

- [#2522](#2522)
[`3855985`](3855985)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
feat(stream): add per-event side-effect selector

Add `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`
(Angular), a side-effect counterpart to `useChannel` that invokes an
`onEvent` callback once per raw protocol event without re-rendering.
This is the idiomatic v1 replacement for the old `onLangChainEvent` /
`onCustomEvent` callbacks for analytics and logging. Backed by a new
framework-agnostic `acquireChannelEffect` helper in
`@langchain/langgraph-sdk/stream` that shares a ref-counted subscription
with matching `useChannel` consumers.

- [#2523](#2523)
[`7c3e9e9`](7c3e9e9)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
fix(sdk): stop re-streaming seeded messages on idle-thread submit

An idle (finished) thread defers its root SSE pump, so the first
`submit()` brings it up and the transport replays the finished run from
`seq=0`. The replayed `messages` channel carries no step (unlike
`values`, guarded by `maxStep`), so it rebuilt each already-complete
message from an empty `message-start` and re-streamed the whole turn
token-by-token — a visible "messages replay" of the existing
conversation. Seal the message ids seeded from the idle `getState()`
snapshot so replayed deltas can't downgrade the complete tail; the seal
lifts once a newer checkpoint advances the timeline or on thread rebind,
and ids from the next run are never sealed.

- [#2462](#2462)
[`17c44a3`](17c44a3)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
fix(sdk): reconnect v2 SSE and WebSocket thread streams after disconnect

Add automatic reconnect with resume (`since` for SSE) for protocol
transports,
wire `AsyncCaller` through `client.threads.stream`, and expose optional
reconnect tuning on `ThreadStreamOptions`. Includes integration tests
against
    an in-process mock langgraph-api server.

## @langchain/angular@1.0.22

### Patch Changes

- [#2522](#2522)
[`3855985`](3855985)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
feat(stream): add per-event side-effect selector

Add `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`
(Angular), a side-effect counterpart to `useChannel` that invokes an
`onEvent` callback once per raw protocol event without re-rendering.
This is the idiomatic v1 replacement for the old `onLangChainEvent` /
`onCustomEvent` callbacks for analytics and logging. Backed by a new
framework-agnostic `acquireChannelEffect` helper in
`@langchain/langgraph-sdk/stream` that shares a ref-counted subscription
with matching `useChannel` consumers.

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21

## @langchain/react@1.0.22

### Patch Changes

- [#2522](#2522)
[`3855985`](3855985)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
feat(stream): add per-event side-effect selector

Add `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`
(Angular), a side-effect counterpart to `useChannel` that invokes an
`onEvent` callback once per raw protocol event without re-rendering.
This is the idiomatic v1 replacement for the old `onLangChainEvent` /
`onCustomEvent` callbacks for analytics and logging. Backed by a new
framework-agnostic `acquireChannelEffect` helper in
`@langchain/langgraph-sdk/stream` that shares a ref-counted subscription
with matching `useChannel` consumers.

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21

## @langchain/svelte@1.0.22

### Patch Changes

- [#2522](#2522)
[`3855985`](3855985)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
feat(stream): add per-event side-effect selector

Add `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`
(Angular), a side-effect counterpart to `useChannel` that invokes an
`onEvent` callback once per raw protocol event without re-rendering.
This is the idiomatic v1 replacement for the old `onLangChainEvent` /
`onCustomEvent` callbacks for analytics and logging. Backed by a new
framework-agnostic `acquireChannelEffect` helper in
`@langchain/langgraph-sdk/stream` that shares a ref-counted subscription
with matching `useChannel` consumers.

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21

## @langchain/vue@1.0.22

### Patch Changes

- [#2522](#2522)
[`3855985`](3855985)
Thanks [@christian-bromann](https://github.com/christian-bromann)! -
feat(stream): add per-event side-effect selector

Add `useChannelEffect` (React/Svelte/Vue) / `injectChannelEffect`
(Angular), a side-effect counterpart to `useChannel` that invokes an
`onEvent` callback once per raw protocol event without re-rendering.
This is the idiomatic v1 replacement for the old `onLangChainEvent` /
`onCustomEvent` callbacks for analytics and logging. Backed by a new
framework-agnostic `acquireChannelEffect` helper in
`@langchain/langgraph-sdk/stream` that shares a ref-counted subscription
with matching `useChannel` consumers.

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21

## @example/ai-elements@0.1.37

### Patch Changes

- Updated dependencies
\[[`3855985`](3855985),
[`2da5c33`](2da5c33),
[`ef04db3`](ef04db3)]:
    -   @langchain/react@1.0.22
    -   @langchain/langgraph@1.4.1

## @examples/assistant-ui-claude@0.1.37

### Patch Changes

- Updated dependencies
\[[`3855985`](3855985),
[`2da5c33`](2da5c33),
[`ef04db3`](ef04db3)]:
    -   @langchain/react@1.0.22
    -   @langchain/langgraph@1.4.1

## @examples/ui-angular@0.0.47

### Patch Changes

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`2da5c33`](2da5c33),
[`ef04db3`](ef04db3),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21
    -   @langchain/angular@1.0.22
    -   @langchain/langgraph@1.4.1

## @examples/ui-multimodal@0.0.23

### Patch Changes

- Updated dependencies
\[[`3855985`](3855985),
[`2da5c33`](2da5c33),
[`ef04db3`](ef04db3)]:
    -   @langchain/react@1.0.22
    -   @langchain/langgraph@1.4.1

## @examples/ui-react@0.0.23

### Patch Changes

- Updated dependencies
\[[`3855985`](3855985),
[`7c3e9e9`](7c3e9e9),
[`2da5c33`](2da5c33),
[`ef04db3`](ef04db3),
[`17c44a3`](17c44a3)]:
    -   @langchain/langgraph-sdk@1.9.21
    -   @langchain/react@1.0.22
    -   @langchain/langgraph@1.4.1

## langgraph@1.0.41

### Patch Changes

- Updated dependencies
\[[`2da5c33`](2da5c33),
[`ef04db3`](ef04db3)]:
    -   @langchain/langgraph@1.4.1

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@open-swe open-swe[bot] open-swe[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

LangGraph.js ToolNode lacks a documented first-class way for tools to access current graph state

1 participant

@christian-bromann