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
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. |