Skip to main content

crewai-browsa

CrewAI tools for Browsa, cloud browsers for AI agents. Your crew gets Phantom, Browsa's cloud browser, to run browser tasks in plain language and to scrape, extract and screenshot pages.

Tool What the agent gets Credits
BrowsaTaskTool A browser agent that opens sites, clicks, types and returns the answer (text, or JSON from an output_schema) browser + 1 + 1 per 5 steps, + 5 on a hosted tier
BrowsaScrapeTool One rendered page as Markdown and links 1 per page
BrowsaExtractTool Fields you describe from one page, as JSON 1 per page
BrowsaScreenshotTool A PNG of a page, saved to a file 1 per page

Install

pip install crewai-browsa

Python 3.10 to 3.13. It installs the official browsa SDK (0.3.1 or later) and crewai.

Set your key

Create an API key at https://app.browsa.io/dashboard/keys and set it:

export BROWSA_API_KEY=agt_live_...

or pass it to any tool: BrowsaScrapeTool(api_key="agt_live_..."). New accounts get 100 free credits after email verification, with no card.

Quick start

from crewai import Agent, Crew, Task
from crewai_browsa import BrowsaScrapeTool, BrowsaTaskTool

researcher = Agent(
    role="Web researcher",
    goal="Find facts on live websites",
    backstory="You read pages in a cloud browser and cite URLs.",
    tools=[BrowsaScrapeTool(), BrowsaTaskTool()],
)

task = Task(
    description="Return the titles of the top 3 stories on news.ycombinator.com.",
    expected_output="Three titles with their links.",
    agent=researcher,
)

print(Crew(agents=[researcher], tasks=[task]).kickoff())

Your crew's own model is configured as usual in CrewAI. BrowsaTaskTool runs a separate browser agent on Browsa, by default on the hosted tier browsa, so no model key is needed for it.

Example: a research crew

A researcher reads live pages and a writer turns the notes into a brief. The researcher reads known URLs with the scrape tool (1 credit) and uses a browser task only when it must click or search. Full file: examples/research_crew.py.

from crewai import Agent, Crew, Process, Task
from crewai_browsa import BrowsaExtractTool, BrowsaScrapeTool, BrowsaTaskTool

researcher = Agent(
    role="Web researcher",
    goal="Collect accurate, current facts from the live web, with their source URLs",
    backstory=(
        "You read pages in a cloud browser. Read a known URL with the scrape tool; "
        "use the browser task tool only when you must click, search or page through a site."
    ),
    tools=[BrowsaScrapeTool(), BrowsaExtractTool(), BrowsaTaskTool(max_steps=25)],
)
writer = Agent(
    role="Analyst",
    goal="Turn the researcher's notes into a short, sourced brief",
    backstory="You write plainly and cite every fact with its URL.",
)

research = Task(
    description=(
        "Find the top 5 stories on the front page of Hacker News (title, points, link). "
        "Then open the top story's link and summarise it in three sentences."
    ),
    expected_output="5 stories and a 3-sentence summary of the first.",
    agent=researcher,
)
brief = Task(
    description="Write a brief from the research: one line per story, then the summary.",
    expected_output="A Markdown brief with sources.",
    agent=writer,
    context=[research],
)

Crew(agents=[researcher, writer], tasks=[research, brief], process=Process.sequential).kickoff()

Example: a shopping assistant that compares stores

The shopper runs one browser task per store. Each task returns the same JSON shape through an output_schema, and an advisor compares the offers. Full file: examples/shopping_crew.py.

from crewai import Agent, Crew, Process, Task
from crewai_browsa import BrowsaTaskTool

OFFER_SCHEMA = {
    "type": "object",
    "properties": {
        "store": {"type": "string"},
        "product_title": {"type": "string"},
        "price": {"type": "number"},
        "currency": {"type": "string"},
        "in_stock": {"type": "boolean"},
        "url": {"type": "string"},
    },
    "required": ["store", "product_title", "price", "currency", "in_stock", "url"],
}

shopper = Agent(
    role="Shopping assistant",
    goal="Find the current price and stock of one exact product at each store",
    backstory="You check one store per browser task and skip accessories and bundles.",
    tools=[BrowsaTaskTool(output_schema=OFFER_SCHEMA, max_steps=30, max_credits=20)],
)
advisor = Agent(
    role="Buying advisor",
    goal="Recommend where to buy, based only on the offers that were found",
    backstory="You compare like for like and never invent a price.",
)

find_offers = Task(
    description=(
        "Product: Sony WH-1000XM5 headphones, black. For each of bestbuy.com, target.com "
        "and walmart.com, run one browser task: search the store, open the exact listing "
        "and return the offer. Note any store that failed and why."
    ),
    expected_output="One JSON offer per store, plus a note for stores with no offer.",
    agent=shopper,
)
recommend = Task(
    description="Compare the offers: cheapest in-stock offer first, then the rest.",
    expected_output="A table (store, price, in stock, link) and a one-line recommendation.",
    agent=advisor,
    context=[find_offers],
)

Crew(agents=[shopper, advisor], tasks=[find_offers, recommend], process=Process.sequential).kickoff()

Browsa's task agent does not press order, payment or subscription buttons unless the task sets allow_purchase (it is off by default), so this crew only reads. One task per store keeps each answer separate: when a task about several named stores has no answer for one of them, the whole task's outcome is failed.

What BrowsaTaskTool returns

On success the agent gets JSON:

{
  "result": {"store": "...", "price": 279.99, "...": "..."},
  "status": "completed",
  "outcome": "completed",
  "partial": false,
  "job_id": "252e8eac-...",
  "live_url": "https://...",
  "credits_charged": 11
}
  • result is structured_output when an output_schema was given, otherwise the agent's text answer.
  • The tool reads outcome, not only status. status: "completed" with outcome: "failed" means the agent finished but could not do the task; the tool reports that as a failure, with outcome_message saying what stopped it.
  • A task a limit stopped (step_limit_reached, budget_reached, timed_out) that still returned a partial result comes back with "partial": true.
  • live_url is a Phantom Live link to watch the browser. It exists only while the task runs, and each link opens once.

Failures (a failed outcome, an HTTP error such as 402 INSUFFICIENT_CREDIT, no free browser slot) are returned as CrewAI ToolFailure objects, so CrewAI records the call as failed and your crew's tool failure policy applies. The agent still reads the message, the error code and the details. On crewai versions without ToolFailure the tool returns the same text.

If a task is still running at timeout (600 seconds by default), or stops to ask a question the tool cannot answer, the tool cancels it so it does not keep its browser. Pass cancel_unfinished=False to leave it running.

Options

All tools take api_key (default BROWSA_API_KEY), base_url (default BROWSA_BASE_URL or https://browsa.io) and client (an existing browsa.Client).

BrowsaTaskTool

Option Default Meaning
llm "browsa" A hosted tier ("browsa", "browsa-fast", "browsa-smart") or your own model, e.g. "anthropic:claude-sonnet-5-5"
llm_api_key none Your Anthropic, OpenAI or Google key, for this task only
llm_key_id none A model key saved in your Browsa workspace
reasoning none "low", "medium" or "high"
max_steps Browsa's 20 Most agent steps, up to 100
max_credits none Most credits one task may charge
output_schema none Default JSON Schema for the answer; the agent can pass its own
timeout 600 Seconds to wait
cancel_unfinished True Cancel on timeout or on a question
task_options {} Any other POST /v1/tasks field, e.g. {"allowed_domains": ["example.com"]}

The agent passes task, and optionally start_url and output_schema.

To use your own model key instead of a hosted tier:

import os
BrowsaTaskTool(llm="anthropic:claude-sonnet-5-5", llm_api_key=os.environ["ANTHROPIC_API_KEY"])

BrowsaScrapeTool: formats (any of markdown, html, text, links; default ["markdown", "links"]), max_chars (30000 here; Browsa's default is 100000), wait_ms, country, block, max_links.

BrowsaExtractTool: the agent passes url and a prompt or an extraction_schema. With llm_api_key (an Anthropic or Anthropic-compatible key) or a saved llm_key_id, Browsa runs the extraction and the tool returns data as JSON. Without a key, Browsa returns the page's clean text and the schema, and your crew's model reads the fields from it.

BrowsaScreenshotTool: the agent passes url and full_page; the PNG is written to output_dir (default browsa_screenshots) and the tool returns its path.

All tools also have _arun, so they work in async crews.

Costs

From https://browsa.io/pricing:

What you run Credits
Cloud browser 1 per started 12 minutes it runs, 5 for a full hour
Quick scrape, extract or screenshot 1 per page
Agent task, your own LLM key browser + 1 + 1 per 5 steps
Agent task on a hosted tier ("llm": "browsa", "browsa-fast" or "browsa-smart") browser + 1 + 1 per 5 steps + 5
  • A 10-step agent task that finishes inside 12 minutes costs 4 credits with your own key, 9 on a hosted tier. A 20-step task costs 6 or 11.
  • A task that fails gets its whole browser charge back and is not charged for steps or the hosted surcharge. With your own model key, Browsa adds no LLM markup; your provider bills you for tokens.
  • Credit packs: Starter $20 for 200 credits, Growth $100 for 1,200, Pro $500 for 7,500. Credits never expire. No subscription.
  • A workspace has 6 browser slots; a request with every slot in use gets 429 TOO_MANY_REQUESTS and is not charged. The tool reports it as a retryable failure.

Set max_credits on BrowsaTaskTool to cap what one task may charge.

Development

pip install -e ".[dev]"
pytest

The tests fake the HTTP layer under the browsa SDK and block real sockets, so they need no key and no network.

MIT licensed.

Metadata

Release files for crewai-browsa 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for crewai-browsa 0.1.0
File Size Uploaded Provenance Actions
crewai_browsa-0.1.0.tar.gz 20.1 kB Without provenance Details for crewai_browsa-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for crewai-browsa 0.1.0
File Interpreter ABI Platform Actions
crewai_browsa-0.1.0-py3-none-any.whl Python 3 none any Details for crewai_browsa-0.1.0-py3-none-any.whl

Total release size: 35.8 kB

Release files / crewai_browsa-0.1.0.tar.gz

Download URL crewai_browsa-0.1.0.tar.gz
Size 20.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6fe24f268b33db4ad6ab75a2e0fc5d9b784b681058c00b143a46765640e5970a
BLAKE2b-256 checksum
How to use checksums
75427353bd2678ffc2f6bcdd98fd866be99bdf3bb6dbf89615b5b48b9c4b6574
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Release files / crewai_browsa-0.1.0-py3-none-any.whl

Download URL crewai_browsa-0.1.0-py3-none-any.whl
Size 15.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
60e7481bc3c3828bc56cd60756f8a10ab3c6b8190b5f2d09dc250a1748703471
BLAKE2b-256 checksum
How to use checksums
013c3e090d86b3d2b8f4445dc5250073824c74c1d1fb399b917e3230494e1ac3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.2

Security for crewai-browsa 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page