Skip to content

Developer tools

Claude’s SDKs run the click loop, but the browser is yours

8 min read

Written by an AI model from the linked sources and checked against them by a second model. How we work

Video: x.com

Anthropic’s Python and TypeScript SDKs now run the agent loop for the computer use and browser use tools, the company announced on October 7. Your job shrinks to subclassing one class and writing a method for each action Claude can take. The SDK routes each call, runs your checks, asks your approval callback and builds the tool_result. Anthropic’s documentation for the browser use SDK toolsets also makes clear how much is still left to you.

The API only says what Claude wants to click or type. Since computer use entered public beta in October 2024, turning that into real clicks and keystrokes meant writing your own loop and your own mapping to commands. That loop is now in the SDK. It ships with no browser, no desktop, no ready-made driver and no URL policy. The minimal example in the claude-quickstarts repository, in Python and TypeScript, controls Chromium through the Chrome DevTools Protocol (CDP), and Anthropic says it isn’t production code. Browser Use, Browserbase and E2B publish their own integrations with the toolsets, and the ClaudeDevs announcement on X also names Daytona among the compatible drivers.

What a driver looks like

A driver is your subclass of BetaAbstractBrowserToolset20260801, with a matching class for computer use. The date suffix is the same as on the browser and computer toolsets that left beta in August. The quick start implements navigate, screenshot and left_click, plus _browser_state, the state report every driver needs. Underneath sits your own wrapper around an automation library such as Playwright. You pass the driver instance itself as the tools entry.

Each member gets the call context and its input as a typed object, such as BetaBrowserNavigateInput from anthropic.types.beta. Any member you don’t implement is sent to the API as disabled. If Claude calls it anyway, the SDK returns an error and the run continues. A per-member configs setting switches members on or off, and the SDK refuses a call to a disabled member before your code runs. Enabling a member your class doesn’t implement is a configuration error.

TypeScript has two traps. Members must be written as methods rather than arrow-function fields, because the SDK finds them on the prototype. And the type member is spelled type_.

The runner never closes the toolset, so one instance can serve several runs, and closing it is up to you.

For logging or tracing you override execute and call the parent’s version. Code before that call runs after the URL policy, the file policy and confirm, and it can change the input, which the SDK doesn’t check again. Code after the call can rewrite the result. Raising ToolError refuses the call. Overriding execute also has a side effect: the SDK then treats every member as implemented and offers Claude every member that is on by default. The docs’ own TracedBrowser, built on a quick-start driver that serves three members, ends up offering Claude members it can’t serve, so those have to be switched off in configs.

What Claude reads back

What a member returns decides what Claude sees. A navigate result reaches it as Navigated to {url} — {title} (HTTP {status}). Screenshots and zooms become one image block. The page-reading members (read_page, get_page_text, find, read_console, read_network, javascript_exec) return a string, which Claude sees as (empty) when it’s empty. Actions such as left_click give a short confirmation like Clicked., followed by any line your driver returned.

Every successful result ends with a browser_state block built from your state report, and an error result has none. The SDK calls _browser_state after every call that returns a result, refused and failed ones included. The report lists every open tab and what changed since the last one: opened tabs, downloads, blocked navigations and dismissed native dialogs. When any tab is open, exactly one must be active. The SDK reports blocked navigations to Claude in a single line that names no URL. Dismissed dialogs get one line each for the first three, then a count of the rest.

Claude sees URLs exactly as your driver wrote them. The SDK doesn’t parse them. It turns line breaks and other control characters into spaces, trims the ends and cuts each URL at 4,096 characters. So the contents of a data: URL, the path in a file: URL and any user name or password in a URL all reach Claude. Local paths aren’t hidden either: they reach Claude in a member’s error text, in the line an action returns, in a failed download’s error and in a dismissed dialog’s message. A ToolError from your URL policy, file policy or confirm reaches Claude word for word.

The docs sort errors into three cases:

  • ToolError: Claude reads its message as an error result, and the run continues.
  • ToolsetUsageError: Claude reads nothing and the run stops. The SDK raises it for configuration errors, misuse of the SDK during a call, calls after close, and any exception from _browser_state, even a ToolError. Neither the tool runner nor tool_result catches it, so it reaches their caller.
  • Any other exception: Claude reads ClassName: message in Python or Error: message in TypeScript, and the run continues.

Anthropic’s advice is to catch exceptions inside your members and raise ToolError with text you wrote yourself.

Early start and its cost

By default the runner waits for Claude’s response to finish before it runs that turn’s calls. With stream=True and run_tools_eagerly=True, as in the quick start, a browser or computer call can start while the response is still streaming. Your loop then gets a stream on each pass instead of a message. The checks still run first, though confirm may now fire mid-stream. Calls still run one at a time in the order Claude wrote them, and a failed call still stops the toolset’s later calls in that turn.

The catch is that a started call can’t be taken back. If the response is cut off, at max_tokens for example, or your loop stops early, the click or navigation still happens and Claude never reads its result.

You can skip the runner entirely. You pass the instance in tools (browser.toJSON() in TypeScript) and answer each member call with a tool_result yourself. The browser use tool then requires you to stop at the first failed call. Each skipped call after it is answered with is_error, the call’s toolset_name and the exact text the API’s batch rules require, the same answer the runner would send.

Six safety steps, three of them yours

The docs explain the risk plainly: Claude’s next action depends on the pages it reads, and a page, or text injected into one, can try to reach internal services, pull files off the host or trigger actions with real effects. Before you point a driver at anything but a throwaway browser, Anthropic lists six steps:

  • a URL policy that refuses every navigate URL the task doesn’t need;
  • request interception in the driver, checked against the same rules;
  • egress policy on the container, so the network blocks what the driver can’t see;
  • confined uploads and downloads, or uploads left off;
  • confirm gating on consequential members;
  • a dedicated container or VM for the browser host in each session.

The SDK applies only the first, fourth and fifth, through the policies and the callable you pass. Interception, egress and isolation are up to your driver and your deployment, and even the URL policy is code you write and make production-ready yourself.

That policy is a narrow check. The SDK calls it with the URL as Claude wrote it, before navigate runs, and only for navigate: back, forward and reload skip it. Returning nothing allows the URL, and raising ToolError refuses it, with Claude reading your message. Claude may drop the scheme and write example.com, so the example policy adds https:// before reading the host. Your navigate receives the raw URL, so it has to add the scheme with the same test, or the browser opens something other than what the policy checked. Passing url_policy=None makes the SDK refuse every navigation, so a missing value in your config can’t leave URLs unchecked. In TypeScript, undefined counts as not setting the option.

The example policy allows about:blank plus two sites and their subdomains over http and https, and Anthropic says it isn’t production grade. A production policy has to deal with links Claude clicks, forms it submits, redirects and requests the page makes on its own, all of which only the driver sees. It also has to handle hostnames an attacker can plant in page content, parse URLs the way the browser does instead of splitting strings, and refuse every scheme the driver doesn’t mean to open, since the SDK checks none.

The request hook in the docs reuses the policy’s function, so the rules are written once. It still misses WebSocket handshakes, service-worker requests and redirect hops. Anthropic says to block service workers outright and check the rest with a hook that sees them, rewriting ws:// to http:// and wss:// to https:// first, because the example policy refuses WebSocket schemes.

The container’s network has to cover the rest, because interception can’t see every request the browser makes and the URL policy never sees where a hostname resolves. The first rule Anthropic gives there is to block link-local and private address ranges in both IPv4 and IPv6, cloud metadata addresses included.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.