
smooth-browser
Browser automation skill with persistent page state for developers and AI agents
- GitHub stars
- 19
Install
/plugin install smooth-browser@smooth-browser-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add circlemind-ai/smooth-sdk.
Contents
Discovered from sourceSkills 2
Smooth Browser
Smooth CLI is a browser for AI agents to interact with websites, authenticate, scrape data, and perform complex web-based tasks using natural language.
Prerequisites
Assume the Smooth CLI is already installed. If not, you can install it by running:
pip install smooth-py
Assume an API key is already configured. If you encounter authentication errors, configure it with:
smooth config --api-key <api-key>
To verify the configuration:
smooth config --show
Get an API key at https://app.smooth.sh
If the account is out of credits, ask the user to upgrade their plan at https://app.smooth.sh
Basic Workflow
1. Create a Profile (Optional)
Profiles are useful to persist cookies, login sessions, and browser state between sessions.
smooth create-profile --profile-id "my-profile"
List existing profiles:
smooth list-profiles
2. Start a Browser Session
smooth start-session --profile-id "my-profile"
Options:
--profile-id- Use a specific profile (optional, creates anonymous session if not provided)--files- Comma-separated file IDs to make available in the session (optional)--device mobile|desktop- Device type (default: mobile)--profile-read-only- Load profile without saving changes--allowed-urls- Comma-separated URL patterns to restrict access to certain URLs only (e.g., "https://example.com/,https://api.example.com/")--no-proxy- Disable the default proxy (see note below)
Important: Save the session ID from the output - you'll need it for all subsequent commands.
Proxy behavior: By default, the CLI automatically configures a built-in proxy for the browser session. If a website blocks the proxy or you need direct connections, disable it with --no-proxy.
3. Run Tasks in the Session
Execute tasks using natural language:
smooth run <session-id> "Go to the LocalLLM subreddit and find the top 3 posts"
With structured output (for tasks requiring interaction):
smooth run <session-id> "Search for 'wireless headphones', filter by 4+ stars, sort by price, and extract the top 3 results" \
--url "https://shop.example.com" \
--response-model '{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","description":"Thenameoftheproductbeingdescribed."},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"description":"The overall sentiment about the product."}},"required":["product","sentiment"]}}'
With metadata (the agent will be):
smooth run <session-id> "Fill out the form with user information" \
--metadata '{"email":"user@example.com","name":"John Doe"}'
Options:
--url- Navigate to this URL before running the task--metadata- JSON object with variables for the task--response-model- JSON schema for structured output--max-steps- Maximum agent steps (default: 32)--json- Output results as JSON
Notes: It's important that you give tasks at the right level of abstraction. Not too prescriptive - e.g. single-step actions - and not too broad or vague.
Good tasks:
- "Search on Linkedin for people working as SDEs at Amazon, and return 5 profile urls"
- "Find the price of an iPhone 17 on Amazon"
Bad tasks:
- "Click search" -> too prescriptive!
- "Load google.com, write 'restaurants near me', click search, wait for the page to load, extract the top 5 results, and return them." -> too prescriptive! you can say "search restaurants near me on google and return the top 5 results"
- "Find software engineers that would be a good fit for our company" -> too broad! YOU need to plan how to achieve the goal and run well-defined tasks that compose into the given goal
IMPORTANT: Smooth is powered by an intelligent agent, DO NOT over-controll it, and give it well-defined goal-oriented tasks instead of steps.
4. Close the Session
You must close the session when you're done.
smooth close-session <session-id>
Important: Wait 5 seconds after closing to ensure cookies and state are saved to the profile if you need it for another session.
Common Use Cases
Authentication & Persistent Sessions
Create a profile for a specific website:
# Create profile
smooth create-profile --profile-id "github-account"
# Start session
smooth start-session --profile-id "github-account"
# Load url
smooth goto <session-id> "https://github.com/login"
# Get live view to authenticate manually
smooth live-view <session-id>
# Give the URL to the user so it can open it in the browser and log in
# When the user confirms the login you can then close the session to save the profile data
smooth close-session <session-id>
# Save the profile-id somewhere to later reuse it
Reuse authenticated profile:
# Next time, just start a session with the same profile
smooth start-session --profile-id "github-account"
smooth run <session-id> "Create a new issue in my repo 'my-project'"
Keep profiles organized: Save to memory which profiles authenticate to which services so you can reuse them efficiently in the future.
Sequential Tasks on Same Browser
Execute multiple tasks in sequence without closing the session:
SESSION_ID=$(smooth start-session --profile-id "my-profile" --json | jq -r .session_id)
# Task 1: Login
smooth run $SESSION_ID "Log into the website with the given credentials"
# Task 2: First action
smooth run $SESSION_ID "Find the settings and change the notifications preferences to email only"
# Task 3: Second action
smooth run $SESSION_ID "Find the billing section and give me the url of the latest invoice"
smooth close-session $SESSION_ID
Important: run preserves the browser state (cookies, URL, page content) but not the browser agent's memory. If you need to carry information from one task to the next, you should pass it explicitly in the prompt.
Example - Passing context between tasks:
# Task 1: Get information
RESULT=$(smooth run $SESSION_ID "Find the product name on this page" --json | jq -r .output)
# Task 2: Use information from Task 1
smooth run $SESSION_ID "Consider the product with name '$RESULT'. Now find 3 similar products offered by this online store."
Notes:
- The run command is blocking. If you need to carry out multiple tasks at the same time, you MUST use subagents (Task tool).
- All tasks will use the current tab, you cannot request to run tasks in a new tab. If you need to preserve the current tab’s state, you can open a new session.
- Each session can run only one task at a time. To run tasks simultaneously, use subagents with one session each.
- The maximum number of concurrent sessions depends on the user plan.
- If useful, remind the user that they can upgrade the plan to give you more concurrent sessions.
Web Scraping with Structured Output
Option 1: Using run with structured output:
smooth start-session
smooth run <session-id> "Extract the top 10 posts" \
--url "https://news.ycombinator.com" \
--response-model '{
"type": "object",
"properties": {
"posts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {"type": "string"},
"url": {"type": "string"},
"points": {"type": "number"}
}
}
}
}
}'
Option 2: Using extract for direct data extraction:
The extract command is more efficient for pure data extraction as it doesn't use agent steps.
It's like a smart fetch that can extract structured data from dynamically rendered websites:
smooth start-session
smooth extract <session-id> \
--url "https://news.ycombinator.com" \
--schema '{
"type": "object",
"properties": {
"posts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {"type": "string"},
"url": {"type": "string"},
"points": {"type": "number"}
}
}
}
}
}' \
--prompt "Extract the top 10 posts"
When to use each:
- Use
extractwhen you're on the right page or know the right url and just need to pull structured data - Use
runwhen you need the agent to navigate, interact, or perform complex actions before extracting
Working with Files
Upload files for use in sessions:
Files must be uploaded before starting a session, then passed to the session via file IDs:
# Step 1: Upload files
FILE_ID=$(smooth upload-file /path/to/document.pdf --purpose "Contract to analyze" --json | jq -r .file_id)
# Step 2: Start session with the file
smooth start-session --files "$FILE_ID"
# Step 3: The agent can now access the file in tasks
smooth run <session-id> "Analyze the contract document and extract key terms" --url "https://example.com"
Upload multiple files:
# Upload files
FILE_ID_1=$(smooth upload-file /path/to/invoice.pdf --json | jq -r .file_id)
FILE_ID_2=$(smooth upload-file /path/to/screenshot.png --json | jq -r .file_id)
# Start session with multiple files
smooth start-session --files "$FILE_ID_1,$FILE_ID_2"
Download files from session:
smooth run <session-id> "Download the monthly report PDF"
smooth close-session <session-id>
# After session closes, get download URL
smooth downloads <session-id>
# curl the URL to download files
Live View & Manual Intervention
When automation needs human input (CAPTCHA, 2FA, complex authentication):
smooth start-session --profile-id "my-profile"
smooth run <session-id> "Go to secure-site.com and log in"
# If task encounters CAPTCHA or requires manual action:
smooth live-view <session-id>
# Open the URL and complete the manual steps
# Continue automation after manual intervention:
smooth run <session-id> "Now navigate to the dashboard and export data"
Direct Browser Actions
Extract data from current page:
smooth extract <session-id> \
--schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
--prompt "Extract all product names and prices"
Navigate to URL then extract:
smooth extract <session-id> \
--url "https://example.com/products" \
--schema '{"type":"object","properties":{"products":{"type":"array"}}}'
Execute JavaScript in the browser:
# Simple JavaScript
smooth evaluate-js <session-id> "document.title"
# With arguments
smooth evaluate-js <session-id> "(args) => {return args.x + args.y;}" --args '{"x": 5, "y": 10}'
# Complex DOM manipulation
smooth evaluate-js <session-id> \
"document.querySelectorAll('a').length"
Profile Management
List all profiles:
smooth list-profiles
Delete a profile:
smooth delete-profile <profile-id>
When to use profiles:
- ✅ Websites requiring authentication
- ✅ Maintaining session state across multiple task runs
- ✅ Avoiding repeated logins
- ✅ Preserving cookies and local storage
When to skip profiles:
- Public websites that don't require authentication
- One-off scraping tasks
- Testing scenarios
File Management
Upload files:
smooth upload-file /path/to/file.pdf --name "document.pdf" --purpose "Contract for review"
Delete files:
smooth delete-file <file-id>
Best Practices
- Always save session IDs - You'll need them for subsequent commands
- Use profiles for authenticated sessions - Track which profile is for which website
- Wait 5 seconds after closing sessions - Ensures state is properly saved
- Use descriptive profile IDs - e.g., "linkedin-personal", "twitter-company"
- Close sessions when done - Graceful close (default) ensures proper cleanup
- Use structured output for data extraction - Provides clean, typed results
- Run sequential tasks in the same session - Keep the session continuous when steps rely on previous work.
- Use subagents with one session each for independent tasks - Run tasks in parallel to speed up work.
- Coordinate resources - When working with subagents, you must create and assign ONE section to each subagent without having them creating them.
- Do not add url query parameters to urls, e.g. avoid
?filter=xyz- Start at the base URL and let the agent navigate the UI to apply filters. - Smooth is powered by an intelligent agent - Give it tasks, not individual steps.
Troubleshooting
"Session not found" - The session may have timed out or been closed. Start a new one.
"Profile not found" - Check smooth list-profiles to see available profiles.
CAPTCHA or authentication issues - Use smooth live-view <session-id> to let the user manually intervene.
Task timeout - Increase --max-steps or break the task into smaller steps.
Known issues
Dealing with session ids starting with a - (dash) sign - Session ids might start with a dash sign. In those situations, deal with them using the -- (double-dash) separator
Command Reference
Profile Commands
smooth create-profile [--profile-id ID]- Create a new profilesmooth list-profiles- List all profilessmooth delete-profile <profile-id>- Delete a profile
File Commands
smooth upload-file <path> [--name NAME] [--purpose PURPOSE]- Upload a filesmooth delete-file <file-id>- Delete an uploaded file
Session Commands
smooth start-session [OPTIONS]- Start a browser sessionsmooth close-session <session-id> [--force]- Close a sessionsmooth run <session-id> "<task>" [OPTIONS]- Run a tasksmooth extract <session-id> --schema SCHEMA [OPTIONS]- Extract structured datasmooth evaluate-js <session-id> "code" [--args JSON]- Execute JavaScriptsmooth live-view <session-id>- Get interactive live URLsmooth recording-url <session-id>- Get recording URLsmooth downloads <session-id>- Get downloads URL
All commands support --json flag for JSON output.
Smooth Python SDK
Smooth offers serverless browsers infra and autonomous browser agents in cloud sandboxes.
The agents take tasks in natural language and drive the browser autonomously to complete them.
You orchestrate automation and resources from Python via smooth.
pip install smooth-py
from smooth import SmoothClient
client = SmoothClient(api_key="cmzr-...") # or set env SMOOTH_API_KEY
task = client.run("Find the cheapest flight from London to Paris today on Google Flights")
print(task.live_url()) # watch it live
print(task.result().output) # blocks until done
Auth: pass api_key=, or set SMOOTH_API_KEY. Get a key at https://app.smooth.sh.
A TypeScript SDK (@circlemind-ai/smooth-ts) mirrors this same API.
Operating mode: act as a Smooth automation consultant
When an engineer asks you to build a Smooth automation, act as a consultant, not a code dispenser. Work in this order:
- Understand & scope. Pin down: the goal; target site(s); whether the flow is stable and
recurring or novel each run; the exact input/output shape (→
response_model); auth needs; volume/concurrency; where and how it runs (one-off, service, schedule); data sensitivity. - Ask only where a decision needs the engineer. Resolve what you can from context and sensible defaults — don't interrogate. Do ask when a choice materially changes the design or carries a trade-off the engineer must own (see Authentication below).
- Always confirm a plan before writing code. Lay out the intended design — primitives
(default: one session with the goal split into
run_tasksubtasks), task altitude (goal vs. step-hints), schemas, auth path, anti-bot/proxy posture — and get agreement first. - Implement per the reference below, best-practices by default: structured output on every
task, least-privilege
allowed_urls, secrets over hard-coded credentials, subtask decomposition for reliability. - Validate and iterate — never declare done from a single happy-path run. Run a small sample, inspect the run artifacts (see Inspecting results) to find where it broke, adjust, re-run. Use a profile during iteration to avoid re-authenticating each run.
Authentication — explain the trade-off, let the engineer choose:
- Secrets are usually the best default. Credentials are injected into the page at runtime, URL-scoped, and never exposed to the agent, logs, or traces. Proactively reassure the engineer of these guarantees — the real concern is usually "will the model see my password?", and it won't.
- Profiles suit durable logins (authenticate once, reuse) — but plan a path for the agent to
request a human to re-authenticate (surface
live_url()) when cookies expire. - For OTP / 2FA / SSO, add a custom tool that fetches the code or drives the step.
Writing tasks: goals vs. workflows
Smooth is a smart agent — how much you spell out depends on the job:
-
Novel / varying sites each run → give a goal. Let the agent figure out the flow.
- ✅
"Search Amazon for 'wireless headphones', filter to 4+ stars, return the top 3 with prices" - ❌
"Click search box, type headphones, click submit, scroll 500px, click first result"(too granular) - ❌
"Find engineers who'd be a good fit for us"(too vague — you decompose big goals into concrete tasks)
- ✅
-
Same recurring flow every time → you may add high-level step hints (a workflow), never granular clicks, and always tell the agent the site may have changed so it adapts rather than follows blindly:
Goal: buy an iPhone 17 128GB on Amazon Here are high-level notes on how to do it. The website may have changed and the flow could differ: - go to amazon - search "iphone 17 128gb" - locate the right item and open its page - add it to cart - go to the basket - check out -
When writing tasks, DO NOT guess steps that weren't given by the user. — it only follows steps when you supply them.
-
Start at a base URL; let the agent apply filters through the UI. Avoid
?filter=xyzquery params.
Choosing the right primitive
| You need… | Use | Notes |
|---|---|---|
| One autonomous task, done | client.run(task) | Fire-and-forget; returns a TaskHandle. |
| Do several sequential things on one browser | client.session() | Run many actions/tasks, then close. Cross-run state → use a profile. |
| An agentic step inside a session | session.run_task(task) | LLM-driven; navigates/interacts/reasons. |
| Deterministic data pull (no agent steps, cheap) | session.extract(schema, prompt) | "Smart fetch" from the current/target page. |
| Deterministic navigation | session.goto(url) | Just loads the URL. |
| Raw JS in the page | session.evaluate_js(code, args) | Full control; returns the JS value. |
| Run tasks in parallel | separate sessions, async client | One browser = one task at a time; parallelize across sessions. |
run vs session: prefer sessions. client.run(task) is essentially syntactic sugar for a
session that does one run_task and auto-closes. A session lets you drive one browser across many
sequential steps (goto/extract/run_task/evaluate_js), and — most importantly — lets you
split a big task into smaller subtasks, each its own run_task. That decomposition is a good
reliability pattern for long-horizon or highly repetitive tasks: smaller, well-scoped tasks succeed far more often than one sprawling goal.
The browser's state (cookies, URL, open page) persists across steps, but the agent's memory does
not carry between run_task calls — pass needed context in each prompt. For state that must
survive across sessions (logins), use a profile.
Core API
client.run(...) -> TaskHandle
handle = client.run(
task="...", # the goal (natural language)
response_model=MyModel, # Pydantic class OR JSON-schema dict -> structured output
url="https://...", # optional starting URL (else agent infers)
metadata={"city": "SF"}, # plain variables visible to the agent (referenced by name in task)
max_steps=32, # agent step budget, 2..128
device="desktop", # "desktop" (default) | "mobile"
profile_id="my-login", # reuse a saved profile (cookies/logins)
allowed_urls=["https://**.example.com/**"], # glob allowlist; None = all
files=[file_id], # uploaded file ids the agent can use
custom_tools=[my_tool], # functions the agent can call
additional_tools={"screenshot": None}, # enable built-in tools
extensions=[ext_id], # browser extensions to load
)
resp = handle.result(timeout=300) # blocks; raises TimeoutError if exceeded
resp.output # the result (str, or an instance/dict of response_model)
resp.status # "done" | "failed" | "cancelled" | ...
resp.credits_used
handle.live_url() # interactive live-view URL (while running)
handle.recording_url() # video (needs enable_recording=True, default True) — call after completion
handle.downloads_url() # zip of files the task downloaded — call after completion
Almost always pass response_model (a Pydantic class or JSON-schema dict). Free-text output
is rarely the right shape to consume in code — the same reason you use structured outputs when
coding against any LLM. Without it, output is a plain string.
client.session(...) -> SessionHandle
with client.session(device="desktop", profile_id="my-login") as session:
session.goto("https://books.toscrape.com")
books = session.extract(Books.model_json_schema(), prompt="Extract all books with prices")
# books.output -> data matching the schema
r = session.run_task("Open the first Mystery book's detail page")
title = session.evaluate_js("document.querySelector('h1').textContent")
# leaving the block closes the session (persists state only if a profile_id was set)
session(**kwargs)accepts the same config asrun(excepttask), plusproxy_server="self".session.extract(schema, prompt=None)—schemais a JSON-schema dict; returns.output.session.run_task(task, max_steps=32, response_model=None, url=None, metadata=None, secrets=None).session.evaluate_js(code, args=None)—coderuns as-is, or as an arrow fn(args) => ...when you passargs(a dict). Returns.output.session.close(force=True);session.result()returns the final trace — only after close.- Call
recording_url()/downloads_url()after the session closes (or the task completes); calling them mid-run can deadlock.
Async
Everything mirrors under SmoothAsyncClient; await every call. Sessions support both forms:
from smooth import SmoothAsyncClient
async with SmoothAsyncClient() as client:
handle = await client.run("...")
resp = await handle.result(timeout=120)
async with client.session() as session: # or: session = await client.session()
await session.goto("https://example.com")
r = await session.evaluate_js("document.title")
For parallelism, open several independent sessions and drive them concurrently with
asyncio.gather — a single session/browser still runs only one task at a time.
Features
Structured output
Pass response_model (Pydantic class or JSON schema) on nearly every task — the agent returns data matching it, ready to consume in code.
from pydantic import BaseModel, Field
class Product(BaseModel):
name: str; price: float | None = Field(None); url: str
class Products(BaseModel):
products: list[Product]
out = client.run("Extract page-1 Amazon results for 'playstation'",
url="https://www.amazon.com", response_model=Products).result().output
Profiles (persistent auth)
A profile stores cookies/localStorage/logins. Reuse it to stay logged in.
client.create_profile(profile_id="github") # create a named profile
# Log in once (headful): open session, goto login, hand user the live_url to authenticate,
# then close to persist. Later just reuse:
client.run("Create an issue in my repo", profile_id="github")
profile_read_only=Trueloads a profile without saving changes back.- Manage:
create_profile,list_profiles,delete_profile. Track which profile ↔ which site.
Files (upload / download)
with open("doc.pdf", "rb") as f:
fid = client.upload_file(f, purpose="contract to analyze").id
client.run("Analyze the uploaded contract", files=[fid])
# Downloads the task made -> handle.downloads_url() returns a zip; also delete_file(fid).
Secrets (values the LLM must never see)
Unlike metadata (plain visible variables), secrets are injected into the page but redacted
from the agent, logs, and traces, and video recording. URL-scoped using glob-like syntax.
from smooth import Secret
from pydantic import SecretStr
with client.session() as s:
s.run_task(
"Log in using the `password` value",
url="https://example.com/login",
secrets={"password": Secret(value=SecretStr("hunter2"),
allowed_urls=["**.example.com/**"])},
)
Reference a secret in the task by its key name. Only available on session.run_task.
Authentication (two paths)
When a task needs a logged-in session, pick one:
- Profiles — authenticate once, reuse the profile on later runs while its cookies stay valid.
Best for durable logins. Build in a way for the agent to request a human to re-authenticate
(surface
live_url()so a person can log in) when cookies expire. - Secrets — inject credentials per-run with no persistence (see above). Best for one-offs or when you don't want to store a profile. Pair with a custom tool to handle OTP / 2FA.
Custom tools
Expose Python functions the agent can call (APIs, DBs, computed values).
@client.tool(
name="get_quote", description="Fetch a shipping quote",
inputs={"zip": {"type": "string", "description": "destination ZIP"}},
output="quote in USD",
essential=True, # essential error -> fails task; non-essential -> agent sees error, continues
)
def get_quote(zip: str): # first param named `task` (optional) receives the handle
if not zip.isdigit():
raise ToolCallError("ZIP must be numeric") # user-facing 400 back to the agent
return {"usd": 12.5}
client.run("Quote shipping to 94107 using get_quote", custom_tools=[get_quote])
- Sync fn with
SmoothClient;async defwithSmoothAsyncClient. - A
task-named first arg gives the tool the handle →task.evaluate_js(...), ortask.run_task(...)to spawn a sub-agent sharing the browser (max nesting depth 2; no two concurrentrun_taskin one session). Tool return must be JSON-serializable and <~64KB (return summaries for big data).
Custom tools are the main extensibility lever. A tool is just arbitrary code running in your own environment — it can do literally anything you can do in Python:
- Integrate anything: call MCP servers, external services, internal APIs, databases.
ask_human: give the agent an escape hatch to reach a person — send a Slack message, page someone, open a ticket — and return their answer to the agent.- OTP / 2FA: fetch the code from your inbox/API and hand it back to the agent.
- Arbitrary browser ops via
task.evaluate_js(...)(raw CDP coming soon). - Context hygiene for auth/payments: wrap a sensitive flow in a tool that runs a subtask
(
task.run_task(...)) to verify it's safe to authenticate/pay before proceeding, keeping that reasoning out of the main agent's context. (See the nested-run_taske2e test for the pattern.)
Built-in extra tools (additional_tools)
Map tool name → config dict (or None for defaults):
additional_tools={
"screenshot": {"full_page": True},
"hover": None,
"drag_drop": None,
"print_page": {"print_and_screenshot": True, "print_background": True}, # -> PDF in downloads zip
}
Browser extensions
with open("ext.zip", "rb") as f:
eid = client.upload_extension(f).id
client.run("...", extensions=[eid]) # list_extensions(), delete_extension(eid)
Proxies
- External:
proxy_server=..., proxy_username=..., proxy_password=...(e.g. residential/geo-routed). proxy_server="self"(sessions only): routes the sandbox browser through your machine via a P2P tunnel — useful to appear from your own IP / reach intranet.
with client.session(proxy_server="self") as s:
s.run_task("What's my IP?", url="https://whatismyipaddress.com/")
Anti-bot / detection
For sites with bot detection:
- Keep
use_stealth=True(default) and addexperimental_features={"humanize": True}for human-like interaction timing. - If still blocked, escalate proxies in order: no proxy → ISP → residential.
Other options
device:"mobile"/"desktop"(default)use_stealth=True(default) anti-bot stealth;use_adblock=True;use_captcha_solver=True.allowed_urls: glob allowlist on domain+path, e.g.["https://**.example.com/**"]. None = all.enable_recording=True→recording_url().show_cursor=False.certificates=[{"file": open("c.p12","rb"), "password": "..."}]for mTLS sites.experimental_features={"enhanced_vision": None}— opt-in experimental behaviors (see Anti-bot forhumanize).metadatavalues arestr|int|float|bool, referenced by name in the task text.
Inspecting results (for debugging & iteration)
A completed task/session carries more than output. Use these to see what happened and iterate
(all work on TaskHandle and SessionHandle; for sessions, read them after close()):
handle.session_log()— timestamped steps the agent took (where it went wrong).handle.recording_url()— video of the run.handle.har_url()— network HAR (blocked requests, CORS, proxy, API calls).handle.console_log_url()— browser console (page JS errors).handle.live_url()— watch live / intervene while running.
Artifacts are written on completion — poll briefly if not yet ready.
Errors & gotchas
- Exceptions:
ApiError,BadRequestError,ToolCallError,TimeoutError(all fromsmooth). result(timeout=...)raisesTimeoutErrorpast the deadline;timeout=Nonewaits indefinitely.- One task per session at a time; parallelism = many sessions (async +
gatherpattern). session.result()works only after the session is closed (useclient.runfor one-shots).- Closing a session persists profile state; give it a moment before reusing the profile elsewhere.
- Deprecated (avoid):
session_id→profile_id,stealth_mode→use_stealth,exec_js→evaluate_js,open_session/close_session/list_sessions/delete_session(usesession()/profile methods),TaskHandle.stop()/update(). - Out of credits → the API errors; upgrade at https://app.smooth.sh.
Docs: https://docs.smooth.sh · Quickstart: https://docs.smooth.sh/quickstart
Sponsors
Details
- Marketplace
- circlemind-ai/smooth-sdk
- Category
- Community
- Keywords
- browser, browser navigation, automation, scrape, debugging