A task is the core primitive. Describe what you want in plain text, the agent browses the web and returns the result.
run()
Runs the task and returns a TaskResult with typed output.
from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
result = await client.run("What is the current price of Bitcoin?")
print(result.output) # "Bitcoin is currently $67,432..."
print(result.id) # task ID
print(result.status) # TaskStatus.FINISHED
print(result.steps) # list of TaskStepView
Structured output
Pass a schema to get validated, typed data back.
from browser_use_sdk import AsyncBrowserUse
from pydantic import BaseModel
class Stock(BaseModel):
ticker: str
price: float
change_pct: float
client = AsyncBrowserUse()
result = await client.run(
"Get the current stock price of NVDA from Yahoo Finance",
output_schema=Stock,
)
print(result.output) # Stock(ticker='NVDA', price=135.40, change_pct=2.3)
Streaming steps
Use async for to yield steps as the agent works.
from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
run = client.run("Find the cheapest flight from NYC to London on Google Flights")
async for step in run:
print(f"Step {step.number}: {step.next_goal}")
print(f" URL: {step.url}")
print(run.result.output) # final result after iteration
Message streaming (v3)
In the BU Agent API, use sessions.messages() to poll the agent’s message history while a task runs. This gives you the full conversation — user messages, assistant reasoning, and tool calls.
import asyncio
from browser_use_sdk.v3 import AsyncBrowserUse
client = AsyncBrowserUse()
session = await client.sessions.create("Find the top story on Hacker News")
session_id = str(session.id)
seen = set()
while True:
s = await client.sessions.get(session_id)
msgs = await client.sessions.messages(session_id, limit=100)
for m in msgs.messages:
if str(m.id) not in seen:
seen.add(str(m.id))
print(f"[{m.role}] {m.data[:200]}")
if s.status.value in ("idle", "stopped", "error", "timed_out"):
print(f"\nDone — {s.output}")
break
await asyncio.sleep(2)
after and before cursors for pagination through large message histories.
Files
Upload images, PDFs, documents, and text files (10 MB max) to sessions, and download output files from completed tasks.
Upload a file
Get a presigned URL, then upload via PUT.
import httpx
from browser_use_sdk import AsyncBrowserUse
client = AsyncBrowserUse()
session = await client.sessions.create()
upload = await client.files.session_url(
session.id,
file_name="input.pdf",
content_type="application/pdf",
size_bytes=1024,
)
with open("input.pdf", "rb") as f:
async with httpx.AsyncClient() as http:
await http.put(upload.presigned_url, content=f.read(), headers={"Content-Type": "application/pdf"})
result = await client.run("Summarize the uploaded PDF", session_id=session.id)
Presigned URLs expire after 120 seconds. Max file size: 10 MB.
Download task output files
result = await client.tasks.get(task_id)
for file in result.output_files:
output = await client.files.task_output(task_id, file.id)
print(output.presigned_url) # download URL
Key parameters
| Parameter | Type | Description |
|---|
task | str | What you want the agent to do. 1-50,000 characters. |
llm | str | Model override. Default: Browser Use 2.0. See Models & Pricing. |
output_schema / schema | Pydantic / Zod | Schema for structured output. |
session_id | str | Reuse an existing session. Omit for auto-session. |
start_url | str | Initial page URL. Saves steps — send the agent directly there. |
secrets | dict | Domain-specific credentials. See Authentication. |
allowed_domains | list[str] | Restrict agent to these domains only. |
session_settings | SessionSettings | Proxy, profile, browser config. See Sessions. |
flash_mode | bool | Faster but less careful navigation. |
thinking | bool | Enable extended reasoning. |
vision | bool | str | Enable screenshots for the agent. |
highlight_elements | bool | Highlight interactive elements on the page. |
system_prompt_extension | str | Append custom instructions to the system prompt. |
judge | bool | Enable quality judge to verify output. |
skill_ids | list[str] | Skills the agent can use during the task. |
op_vault_id | str | 1Password vault ID for auto-fill credentials and 2FA. See Authentication. |
metadata | dict[str, str] | Custom metadata attached to the task. |
