Migrate Cloud Agent docs and SDK examples to API V4

[gregpr07]

Summary

• migrate the Cloud quickstart and every Agent guide from the V3 session helper to the V4 run/session/workspace SDK
• document V4 model strings and pricing, implicit and explicit follow-ups, incremental events, turn-scoped attachments, manual reusable scripts, and live-browser handoff
• explain the intentional V4 differences: no server-side output schema, cacheScript, or useOwnKey request flags
• refresh the Cloud llms.txt/llms-full.txt context and point new agent integrations at V4
• sync the V4 OpenAPI copies and generated models with production
• make the API-defaulted model optional in the TypeScript request type
• expose the V4 ZDR session purge endpoint in both SDKs and their coverage maps

Production verification

Tested with the published/local V4 Python and TypeScript clients:

• run create, status polling, completion, results, events, and implicit session/workspace creation
• workspace creation, upload IDs, turn-scoped attachments, and file-backed agent work
• queued same-session follow-up, including the initial response with no run ID
• confirmed that V4 rejects the old outputSchema, cacheScript, and useOwnKey fields with HTTP 422

The supplied test API key was used only at runtime and is not stored in this branch.

Tests

• TypeScript: 151 passed; pnpm typecheck; pnpm build
• Python: 43 passed, 22 skipped; uv build
• both V4 OpenAPI documents pass mintlify openapi-check
• updated V4 OpenAPI canonical JSON matches the production spec
• git diff --check

Full Mintlify validation has the same two pre-existing failures on clean main:

• cloud/guides/x402.mdx
• open-source/supported-models.mdx

Python pyright also retains the existing missing-import errors for the optional eth_account x402 dependencies.

---

Summary by cubic

Migrated Cloud Agent docs and SDK examples to API V4 and aligned both SDKs with V4 runs, sessions, workspaces, and events. Adds session purge, makes run model optional, and syncs the V4 OpenAPI, model list, and pricing.

• New Features

  • browser-use-node: export RunCreateRequest; model is optional (defaults to minimax-m3); add Sessions.purge(sessionId); tests for model omission and purge.
  • browser-use-python: add Sessions.purge() (sync/async); sync model enum (kimi-k3, claude-opus-5, claude-fable-5); reduce workspace name max length to 100; tests updated.
  • OpenAPI/docs: sync V4 specs and snapshots (model additions, name length); update guides to V4 patterns (runs/events/follow-ups, turn-scoped attachments, BYOK behavior, models/pricing, live-browser handoff). Add /api-v4/* docs routing and refresh llms*.txt.

• Migration

  • Use runs.create() + runs.waitForCompletion() / wait_for_completion() (replace v3 run()).
  • Validate JSON client-side; V4 rejects output_schema/outputSchema.
  • Remove cacheScript/useOwnKey; BYOK is set in the dashboard and selected automatically.
  • Get the live browser URL from the browser.ready event; poll runs.events() with after for incremental updates.
  • Queue follow-ups with sessions.sendMessage() / send_message(); attach uploads per turn via attachedFileIds / attached_file_ids.

^{Written for commit 262a434. Summary will update on new commits.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
browser-use	🟢 Ready	View Preview	Jul 25, 2026, 11:16 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[cubic-dev-ai]

No issues found across 30 files

Not reviewed (too large): docs/cloud/llms-full.txt (~2,575 lines), docs/llms-full.txt (~2,575 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.

_{Re-trigger cubic}

[gregpr07]

Full production documentation matrix

Ran a second, exhaustive production pass against the code patterns underlying the updated Agent docs.

Results

• Python + REST/curl: 11/11 passed
• TypeScript: 9/9 passed
• Production model picker: 5/5 passed
  • claude-opus-5
  • grok-4.5
  • gpt-5.6
  • gemini-3.5-flash
  • minimax-m3

Verified live:

• default and explicit-model runs
• create/status/wait/get lifecycle and result
• Pydantic and Zod JSON validation
• implicit sessions, explicit follow-ups, and queued messages whose initial run_id can be null
• cursor-based events and browser.ready
• cancellation
• workspace creation and single/multi-file upload helpers
• turn-scoped attachment IDs
• agent-generated files, temporary URLs, and actual file download
• agent-authored/tested script plus a new-session rerun in the same workspace
• reachable live_view_url plus same-session continuation
• both documented curl request shapes
• HTTP 422 for V3-only outputSchema, cacheScript, and useOwnKey

Total test spend was approximately $0.523. The production API key was entered through a hidden prompt, was not written to disk, and a repository scan confirmed it is absent from the branch.

Intentional boundaries:

• No destructive sessions.purge() call was made; that ZDR-only endpoint is contract/unit tested.
• No physical human click was automated; the signed live URL was fetched successfully and the post-handoff same-session continuation was completed.
• Automatic BYOK selection needs a project with provider keys configured, so the no-flag behavior is documented from the production contract/backend and the obsolete flag was live-confirmed as rejected.

No additional docs or SDK failures were found, so this pass requires no follow-up commit.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
browser-use	🟡 Building	–	Jul 25, 2026, 11:15 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.