docs: warn that try/catch swallows handoff Command.PARENT signals

[WALTER BRUNO PRADO VIEIRA (wbrunovieira)]

Summary

Adds a warning to the "Handoffs" section of the multi-agent guide about a subtle footgun: returning a Command with graph: Command.PARENT from a tool relies on an internal GraphBubbleUp control-flow signal (thrown, then caught by the Pregel loop to route to the parent graph). Wrapping the agent/subgraph invocation in a try/catch silently swallows that signal, so handoffs — and interrupt(), which uses the same mechanism — stop working with no error surfaced.

The admonition shows the correct pattern: re-throw GraphBubbleUp errors using the public isGraphBubbleUp guard.

Context

Reported in #1885: a Command.PARENT handoff from a tool inside createAgent breaks only when the invoke() call is wrapped in try/catch.

Notes

• Docs-only; no code changes.
• isGraphBubbleUp is publicly exported from @langchain/langgraph.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 624cd06

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[pkg-pr-new]

Open in StackBlitz

@langchain/langgraph-checkpoint

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

@langchain/langgraph-checkpoint-mongodb

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

@langchain/langgraph-checkpoint-postgres

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

@langchain/langgraph-checkpoint-redis

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

@langchain/langgraph-checkpoint-sqlite

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

@langchain/langgraph-checkpoint-validation

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

create-langgraph

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

@langchain/langgraph-api

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

@langchain/langgraph-cli

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

@langchain/langgraph

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

@langchain/langgraph-cua

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

@langchain/langgraph-supervisor

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

@langchain/langgraph-swarm

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

@langchain/langgraph-ui

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

@langchain/langgraph-sdk

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

@langchain/angular

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

@langchain/react

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

@langchain/svelte

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

@langchain/vue

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

commit: 624cd06