Deployments.ai Docs
Platform

Web and browser tools

Search, scrape, crawl, and capture the public web from an agent with the built-in web and browser tools.

The web.* tools let an agent search, scrape, crawl, and parse public web content. The browser.* tools run headless Chromium inside the agent's sandbox to capture screenshots and drive short, approved browser sessions. These are tools an agent calls during a run, not REST endpoints. Declare them in the agent manifest like any other catalog tool. See Tools and tool policies.

Availability

An installation from the customer root runs web.* tools by default against its own private Firecrawl. browser.* tools also need the Lambda MicroVM sandbox provider, which is on by default, and a list of origins agents may open, agent_runtime_browser_allowed_origins, which is empty by default, so browser tools fail until the operator sets it or sets agent_runtime_browser_any_public_origin to true. When a family is off, the catalog still lists its tools but runs cannot use them, and POST /v1/tool-policies/evaluate does not reflect it.

Web tools

The web tools call a private, self-hosted Firecrawl service. All of them are platform catalog tools, so their default action decides each call.

ToolEffectDefault actionWhat it does
web.scrapereadallowScrape one page into Markdown, HTML, links, images, JSON, or metadata.
web.searchreadallowSearch the web, news, or image indexes and optionally scrape results.
web.mapreadallowDiscover and rank a site's URLs without scraping each page.
web.crawlexecuteallowStart a bounded crawl job.
web.crawl_params_previewreadallowTurn a natural-language objective into crawl parameters.
web.crawl_status, web.crawl_errorsreadallowRead crawl progress, results, and errors.
web.crawl_cancelexecuterequire_approvalCancel a crawl.
web.batch_scrapeexecuteallowStart a scrape of many URLs.
web.batch_scrape_status, web.batch_scrape_errorsreadallowRead batch results and errors.
web.batch_scrape_cancelexecuterequire_approvalCancel a batch scrape.
web.parsereadallowParse a document stored as an organization artifact.
web.extract, web.extract_statusexecute, readallowLegacy schema-guided extraction. Prefer web.scrape with a JSON format.
web.deep_research, web.deep_research_statusexecute, readallowDeprecated research job.
web.generate_llms_txt, web.llms_txt_statusexecute, readallowDeprecated llms.txt generation job.

Rules for web tool input

RuleLimit
URL scheme and porthttp or https on port 80 or 443, without credentials in the URL
URL targetsMust resolve to public addresses only. Private, loopback, and other reserved addresses are rejected.
URL length4,096 characters
URLs per call100 (10 for web.extract)
web.crawl limit1 to 100 pages
web.search limit1 to 100 results
Tool input size256 KiB
Response size25 MiB
web.parse fileUp to 50 MiB, read from an artifact in the caller's organization

Inputs are checked against a per-tool allowlist of fields. The tools reject Firecrawl actions and webhook callbacks.

Start tools such as web.crawl and web.batch_scrape return an encrypted job ticket instead of the upstream job ID. The ticket is bound to your organization and the job type. The status, errors, and cancel tools accept only that ticket. Crawl and batch status return a nextCursor for the next page of results.

Browser tools

browser.capture_screenshot, browser.screenshot.capture, and browser.session.execute run in the agent's sandbox MicroVM, the same boundary code.execute uses.

ToolEffectDefault actionNeeds
browser.capture_screenshotreadallowA target URL
browser.session.planwriterequire_approvalA target URL. Produces the plan a person approves.
browser.screenshot.capturereadallowAn approved plan (sessionPlanId) and its URL
browser.session.executewriterequire_approvalAn approved plan and 1 to 16 actions
browser.dom_snapshot.capturereadallowAn approved plan and its URL. Fetches HTML without a browser.
browser.session.audit_reportwriterequire_approvalAn approved plan. Records actions and evidence.

Releases that declare browser.capture_screenshot, browser.screenshot.capture, or browser.session.execute need a run-ephemeral or thread-persistent sandbox on the aws_lambda_microvm provider. Otherwise publishing fails with browser_tool_without_sandbox. See Code sandbox.

Targets

A target must use http or https, carry no credentials, and name a public host. Operators either restrict targets to an allowlist of origins, and a target outside it fails with Target origin <origin> is not allowed, or set agent_runtime_browser_any_public_origin so agents can open any public site.

With any public origin allowed, Chromium in the sandbox sends every request through a proxy in the sandbox. The proxy resolves each host and connects only when every address it resolves to is public. A page, redirect, frame, image, fetch, or WebSocket aimed at a private, loopback, link-local, or metadata address is refused, including a public name that resolves to one. A main-frame navigation that lands on a refused host fails with origin_not_allowed.

browser.capture_screenshot also accepts http://127.0.0.1:<port>/ when the agent's sandbox mode is thread-persistent. That lets an agent screenshot a dev server it started earlier in the same thread. The URL must use plain http, the literal host 127.0.0.1, and an explicit port other than the sandbox control port. localhost and other loopback or private addresses are rejected.

Screenshot options

OptionValues
viewportmobile (390×844), tablet (820×1180), desktop (1280×900), wide (1440×1000)
viewportSizewidth and height, each clamped to 100 to 4,000 px
formatpng, jpeg, or webp
fullPage, selector, waitForSelectorCapture the full page or one element. Selectors are at most 2,000 characters.
timeoutMsDefault 45,000. Maximum 60,000.
urlAt most 8,192 bytes after normalization

Images are limited to 25 MiB. Screenshots are saved as private run artifacts. See Artifacts.

Browser sessions

A browser session is an approval-gated sequence of actions on one target.

  1. The agent calls browser.session.plan for a target. The default policy pauses the run for approval. See Approvals and client tools.
  2. After approval, the agent calls browser.session.execute with the plan's ID, the same URL, and 1 to 16 actions: navigate, click, type, select, press, wait, or scroll. There is no action that runs arbitrary JavaScript. timeoutMs takes 1,000 to 60,000.
  3. The session returns a rendered DOM snapshot of at most 2 MiB and a viewport PNG as private artifacts.

browser.dom_snapshot.capture does not start a browser. It fetches the approved target over HTTPS, follows redirects only within the approved origin, accepts only HTML, and fails when the page is larger than 2 MiB.

When the browser fails

When a screenshot or session fails in the browser, the tool call still completes. Its result carries error with a code and a message, and the run continues so the agent can retry or move on. A target the tools refuse before the browser starts fails the same way: a non-public host, an origin outside the allowlist, or a host that resolves to a non-public address returns origin_not_allowed, and a host whose DNS lookup fails returns navigation_failed. Malformed input, such as a missing URL, still fails the run. Codes include selector_not_found, navigation_failed, origin_not_allowed, popup_not_allowed, dimensions_exceeded, timeout, and internal. A failed browser.session.execute is not run again when the run resumes. It returns the same error.

Use it

Declare the tools in the agent manifest and give the agent a MicroVM sandbox:

{
  "spec": {
    "capabilities": {
      "tools": [
        { "name": "web.search", "required": false, "requiredScopes": [] },
        { "name": "web.scrape", "required": false, "requiredScopes": [] },
        { "name": "browser.capture_screenshot", "required": false, "requiredScopes": [] }
      ]
    },
    "sandbox": { "mode": "run-ephemeral", "provider": "aws_lambda_microvm" }
  }
}

Check a tool's input schema before you write instructions that use it:

deployments tool get --name browser.capture_screenshot
deployments tool list --prefix web.

Reference

On this page