langchain-tool-recover 0.1.0

Tiny LangChain middleware for better tool-call recovery, loop detection, and structured failure messages.

langchain-tool-recover

A tiny LangChain middleware that stops agents from looping, failing silently, or retrying tools stupidly.

langchain-tool-recover is not another retry library. LangChain already has ToolRetryMiddleware, ToolCallLimitMiddleware, and create_agent middleware. This package fills the smaller wedge around tool-call recovery UX: duplicate-call loop detection, structured failure messages, empty-result recovery, and sane LangChain tool defaults.

Install

pip install langchain-tool-recover

For local development:

pip install -e ".[dev]"

Use With create_agent

from langchain.agents import create_agent
from langchain_tool_recover import ToolRecoverMiddleware

agent = create_agent(
    model=model,
    tools=tools,
    middleware=[
        ToolRecoverMiddleware(),
    ],
)

When a tool fails or returns an empty result, the agent receives compact JSON it can reason over:

{"status":"needs_replan","tool":"search_docs","failure_class":"empty_result","message":"The tool returned no results.","suggestion":"Try broadening the query or removing exact-match terms.","action":"return_to_agent","attempt":1}

Use As A Tool Wrapper

from langchain_tool_recover import recover_tool

safe_search = recover_tool(search_tool)

The wrapper preserves the tool name, description, argument schema, and async support where LangChain exposes it.

Before And After

Without this library:

Agent calls search_docs("foo")
No results.
Agent calls search_docs("foo")
No results.
Agent calls search_docs("foo")
No results.

With this library:

Agent calls search_docs("foo")
No results.
[tool-recover] search_docs attempt=1 status=empty_result
[tool-recover] suggestion=Try broadening the query or removing exact-match terms.
[tool-recover] action=returned_recovery_message
Suggestion sent to agent: broaden the query or try another tool.

Duplicate calls are tracked per run. The first duplicate logs a warning and executes. The second duplicate returns a needs_replan message. The third and later duplicates are blocked for that run.

Default Policy

Failure class	Default action
timeout	retry_with_backoff
rate_limit	retry_with_backoff
validation_error	return_to_agent
auth_error	fail_fast
empty_result	return_to_agent
duplicate_call	block after duplicate limit
unsafe_command	block
unknown_error	fail_fast

Override policies by passing a mapping:

from langchain_tool_recover import FailureClass, RecoveryAction, ToolRecoverMiddleware

middleware = ToolRecoverMiddleware(
    policies={
        FailureClass.UNKNOWN_ERROR: RecoveryAction.RETURN_TO_AGENT,
    }
)

What It Classifies

The classifier is deterministic and conservative:

• Exceptions: timeout, rate limit, validation error, auth error, unsafe command, unknown error.
• Empty results: None, blank strings, empty collections, and explicit empty sentinels such as {"empty": true} or {"results": []}.
• LangChain ToolMessage(status="error") content is reclassified when the tool node converts invocation errors into messages.

It intentionally does not try to infer complex semantic failure from arbitrary prose in v1.

Examples

• examples/basic_agent.py
• examples/duplicate_tool_loop.py
• examples/empty_search_recovery.py

Development

pip install -e ".[dev]"
pytest
python -m build
ruff check .

License

MIT