The 400 status chosen for truncation errors (deliberately outside provider
retry lists — an identical retry truncates identically) also fell outside
Agent._try_switch_to_fallback_llm's allowlist, so a configured fallback_llm
could no longer rescue a truncated run. Before this PR the downstream parse
failure was wrapped as a 502 ModelProviderError, which did allow the switch.
Introduce ModelOutputTruncatedError(ModelProviderError, status 400): the
three providers raise it, provider retry loops still skip it, and the
agent's fallback check treats it as switchable explicitly — a fallback with
a different output cap can succeed where the primary truncated.
ChatBrowserUse now accepts provider-prefixed model ids (anthropic/*,
openai/*, google/*) alongside the bu-* aliases and browser-use/* models,
so a single BROWSER_USE_API_KEY can reach them. bu-* aliases and the
bu-latest -> bu-2-0 normalization are unchanged; bare ids are rejected
with guidance toward the provider/model form.
Also matches provider-prefixed Claude Sonnet ids in the Agent
llm_screenshot_size auto-config, so the screenshot optimization isn't
lost when Claude is reached via ChatBrowserUse.
Adds an example, a README FAQ entry, and tests.
ENG-5060
- fable for coord clicks
- explicit support
- model refusal response
- fable pricing with 5m/1h cache writes and inference geo multiplier
- anthropic fallback, thinking, output config, and inference geo request support
The step counter (Step N maximum:M) and datetime.now() were rendered
inside <agent_state>, ahead of <browser_state> in the user message.
The cache miss already happens at the <agent_state> boundary today, so
this isn't a live cache regression — but the layout meant that any
future move of more-stable agent_state fields into the system prompt
would still leave per-step varying bytes in the middle of the prefix,
silently capping how far the cache could extend.
Pull both fields into a new _get_step_meta_description() and append it
at the very end of get_user_message(), after <agent_state>,
<browser_state>, <read_state>, <page_specific_actions>, and unavailable-
skills info. Everything above this tail block is now eligible to be
treated as the cacheable region.
Adds regression tests that lock the layout:
- <step_info> must appear after <agent_state> and <browser_state>
- <step_info> must not leak back into <agent_state>
- bytes before <step_info> must be identical across two different step
numbers (the step counter must not be in the prefix)
For Gemini's implicit cache (and similar provider caches) to actually
hit step over step, the rendered transcript for steps 1..N-1 must be
byte-identical at step N and at step N+1. The agent already appends
HistoryItems immutably in practice, but nothing in the type prevented
a future caller from mutating one in place — which would silently kill
the cache from that byte onward.
Mark HistoryItem frozen so any mutation now fails loud at runtime
rather than slowly burning input tokens. Add a regression test set
that asserts the cache property directly:
- render(items[:N]) must be a strict byte-prefix of render(items[:N+1])
- to_string() is deterministic for identical inputs
- the prefix property holds across mixed entry shapes (normal steps,
errors, system messages, follow-up tasks)
- conditional field inclusion doesn't collapse to ambiguous output
Known limitation, not addressed here: max_history_items compaction in
MessageManager.agent_history_description rewrites earlier bytes once
the cap is exceeded (the omitted-count message changes). That's a
larger redesign and deserves its own PR.
- Re-indent the except block to match the inner try (was a SyntaxError)
- Drop asyncio.CancelledError from the isinstance check (it's BaseException,
never reaches except Exception)
- Re-raise on _is_connection_like_error so _handle_step_error can run its
reconnect / browser-closed shutdown logic
- Include exception class name in the preserved ActionResult error
PHclaw pointed out that _check_stop_or_pause() raises InterruptedError
inside the multi_act loop. Converting it to an ActionResult would prevent
the agent from properly stopping/pausing between batched actions.
Re-raise InterruptedError and asyncio.CancelledError before wrapping
other exceptions as ActionResult with partial results.
When multi_act() executes a batch of actions and one fails mid-way,
the partial results from successfully executed earlier actions were
discarded by re-raising the exception. The agent lost visibility into
which actions completed before the failure.
Return the accumulated results with an error ActionResult appended,
which aligns with the existing post_process logic that explicitly
handles multi-action errors via loop detection and replan nudges
(lines 1221-1222).
The main execution loop already wraps _execute_step with asyncio.wait_for
using settings.step_timeout (default 180s). But _execute_initial_actions,
which runs before the main loop, is unwrapped — if it hangs (e.g. the
first navigate stalls on a silent CDP WebSocket before the per-action
timeout can catch it), the agent blocks indefinitely without ever
entering the main loop. No step gets recorded, history stays empty, and
any outer watchdog eventually kills the run with zero diagnostic data.
Wrap _execute_initial_actions with the same step_timeout. On timeout,
record the failure in state.last_result / consecutive_failures and fall
through to the main execution loop so the agent can still attempt to
recover. InterruptedError (from an interrupting callback) is still
swallowed silently — same contract as before.
Paired with the per-action asyncio.wait_for added in tools/service.py,
this closes the last unprotected path in the pre-main-loop flow.
- Add UTM params to all cloud-bound links across README, CLI, and error messages
- Rewrite README Open Source vs Cloud section: position cloud browsers as
recommended pairing for OSS users, remove separate Use Both section
- Rewrite error messages for use_cloud=True and ChatBrowserUse() to clearly
state what is wrong and what to do next
- Add missing URLs: invalid API key now links to key page, insufficient
credits now links to billing page
- Add cloud browser nudge on captcha detection (logger.warning)
- Add cloud browser nudge on local browser launch failure
_prepare_context passes last_model_output/last_result to the message
manager for the "previous action result" prompt section. Clearing
them before context preparation drops this context.
Move the clear to after _prepare_context but before _get_next_action,
so prompt assembly still sees the previous step's output while
preventing stale data on timeout during the LLM call or action phase.
Two related bugs when step() is cancelled by timeout:
1. step() does not clear last_model_output/last_result at the start,
so if timeout occurs before _get_next_action, _finalize() sees
stale values from the previous step and records a duplicate history
entry with wrong step numbers.
2. _finalize() early-returns when last_result is falsy, skipping the
n_steps increment. On timeout, this means the while loop retries
the same step number repeatedly.
Fix: clear last_model_output and last_result at step() entry, and
ensure _execute_step increments n_steps after a timeout if _finalize
did not already do so.
- load_from_dict: use data.get('history', []) and h.get() for safe access
to avoid KeyError when history dict is missing keys (e.g. legacy/partial
history files saved before a schema change)
- final_result: add len() check before accessing result[-1] to prevent
IndexError when the result list is empty, consistent with is_done(),
is_successful(), judgement() and other methods in the same class
Add disabled parameter to SignalHandler class to allow opting out of
signal handling. This enables browser-use to be embedded in applications
like uvicorn/FastAPI that need to manage their own signal lifecycle.
Add enable_signal_handler parameter to Agent class (default True for
backward compatibility). When set to False, the Agent will not register
signal handlers, allowing the host application to control graceful
shutdown and signal handling.
Fixes#4385
Saurav Panda