Documentation menu

Known fixes and the circuit breaker

Wrap LangChain tools with memory.protect so known failures return the fix that worked and repeated failures stop instead of looping.

Updated

Warnings in the prompt help the model avoid known mistakes. memory.protect enforces them at the tool level: a tool call that hits a known failure returns the fix that worked, and a call that cannot succeed stops retrying.

Wrap your tools

memory = retrack.recall(task)
tools = memory.protect(tools)          # LangChain tools
agent = create_react_agent(llm, tools)

protect returns new tools with the same names, descriptions and argument schemas, so nothing else changes.

What a protected tool does

  • Known failure with a fix: if a call fails in a way Retrack has seen and a fix is known, the error your agent sees includes it. A raised error becomes a KnownFailureError whose message ends with Known fix from Retrack: ...; an error returned in the result gets a known_fix field.
  • Unrecoverable failure: if Retrack knows retrying will not help (5 or more occurrences and no fix ever recorded), the tool raises UnrecoverableToolError at once.
  • Repeated failure: if the very same failure happens 3 times in one run, the tool raises UnrecoverableToolError instead of letting the agent loop.

Change the limit with memory.protect(tools, max_same_failure=5).

Handling the stop

UnrecoverableToolError is meant to end the attempt so your code can hand off, escalate or report:

from retrack.recovery import UnrecoverableToolError
 
try:
    result = agent.invoke({"messages": [("system", memory.as_prompt()), ("user", task)]})
except UnrecoverableToolError as exc:
    result = escalate_to_human(task, reason=str(exc))

General-purpose tools

For a shell, SQL or HTTP tool, only the very same command failing again counts as a repeat, because different commands fail for different reasons. A command's failures are never marked unrecoverable automatically.

Overriding

If Retrack has marked a failure unrecoverable and you have since fixed the cause, clear it from the failure's page in the dashboard (Memory, then the failure signature). A recorded fix also clears it automatically.