Repository navigation
docs(tools): a failed returnDirect call ends the run too - #811
Merged
Merged
Conversation
LangGraph's prebuilt agent routes a returnDirect tool's result to END by tool name without checking the ToolMessage status, so an error result (the tool threw, or the model's arguments failed the schema) also ends the run and the model never gets to retry. Say so in the Tools docs and the B4ToolDefinition JSDoc, and replace the example, which validated its input and so was exactly the tool that should not use returnDirect. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
blove
temporarily deployed
to
vercel-preview
September 23, 2026 15:45 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
5 of 6 tasks
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
returnDirect(shipped in #800) ends the run on any result from the tool, including an error. LangGraph's prebuilt agent routes toENDby matching the trailingToolMessage'snameagainst thereturnDirectset and never checksstatus, so when areturnDirecttool throws, or the model's arguments fail the tool's schema, the errorToolMessageends the run and the model never gets to correct the call.This PR corrects the docs until that changes upstream:
apps/web/content/docs/tools.mdx("Ending the run from a tool"): adds a paragraph saying a failed call ends the run too, soreturnDirectis only for tools that cannot usefully fail. A validating renderer that expects the model to fix a rejected call should stay a normal tool. The example is replaced: it awaitedvalidateUi(input), which made it exactly the kind of tool that should not usereturnDirect.packages/core/src/capabilities/types.ts: theB4ToolDefinition.returnDirectJSDoc says the same thing.@b4run/cli(the docs ship in its bundleddocs/) and@b4run/core(JSDoc).Reproduced against the latest published
@langchain/langgraph1.4.17 (createReactAgent, what B4 uses) andlangchain1.5.12 (createAgent): a scripted model calls areturnDirecttool that fails, then retries. Both runs end after 1 model call on the errorToolMessage. A fix that skipsstatus: "error"messages is being proposed upstream, and it gives 2 calls and ends on the successful retry. The Python version of this bug is langchain-ai/langchain#36411.Test plan
node scripts/check-docs.mjspassesvalidate🤖 Generated with Claude Code