smooth-browser

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

Smooth CLI是一款供AI Agent与网站交互、完成身份认证、爬取数据并使用自然语言执行复杂网页任务的浏览器。

Prerequisites

前提条件

Assume the Smooth CLI is already installed. If not, you can install it by running:

bash

pip install smooth-py

Assume an API key is already configured. If you encounter authentication errors, configure it with:

bash

smooth config --api-key <api-key>

To verify the configuration:

bash

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

假设Smooth CLI已安装。若未安装，可运行以下命令进行安装：

bash

pip install smooth-py

假设API密钥已配置。若遇到认证错误，可通过以下命令配置：

bash

smooth config --api-key <api-key>

验证配置：

bash

smooth config --show

可在https://app.smooth.sh获取API密钥。

若账户余额不足，请提示用户前往https://app.smooth.sh升级套餐。

Basic Workflow

基本工作流

1. Create a Profile (Optional)

1. 创建配置文件（可选）

Profiles are useful to persist cookies, login sessions, and browser state between sessions.

bash

smooth create-profile --profile-id "my-profile"

List existing profiles:

bash

smooth list-profiles

配置文件可用于在会话之间持久化Cookie、登录会话和浏览器状态。

bash

smooth create-profile --profile-id "my-profile"

列出现有配置文件：

bash

smooth list-profiles

2. Start a Browser Session

2. 启动浏览器会话

bash

smooth start-session --profile-id "my-profile" --url "https://example.com"

Options:

```
--profile-id
```
- Use a specific profile (optional, creates anonymous session if not provided)
```
--url
```
- Initial URL to navigate to (optional)
```
--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

bash

smooth start-session --profile-id "my-profile" --url "https://example.com"

可选参数：

```
--profile-id
```
- 使用指定配置文件（可选，若未提供则创建匿名会话）
```
--url
```
- 初始导航URL（可选）
```
--files
```
- 会话中可用的逗号分隔文件ID（可选）
```
--device mobile|desktop
```
- 设备类型（默认：mobile）
```
--profile-read-only
```
- 加载配置文件但不保存更改
```
--allowed-urls
```
- 逗号分隔的URL模式，仅允许访问特定URL（例如："https://example.com/,https://api.example.com/"）
```
--no-proxy
```
- 禁用默认代理（见下方说明）

重要提示： 保存输出中的会话ID - 后续所有命令都需要用到它。

代理行为： 默认情况下，CLI会自动为浏览器会话配置内置代理。若网站阻止代理或需要直接连接，可使用

--no-proxy

禁用代理。

3. Run Tasks in the Session

3. 在会话中执行任务

Execute tasks using natural language:

bash

smooth run <session-id> "Go to the LocalLLM subreddit and find the top 3 posts"

With structured output (for tasks requiring interaction):

bash

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):

bash

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.

使用自然语言执行任务：

bash

smooth run <session-id> "访问LocalLLM子版块并找出排名前三的帖子"

带结构化输出（适用于需要交互的任务）：

bash

smooth run <session-id> "搜索'无线耳机'，筛选4星及以上评分，按价格排序，并提取排名前三的结果" \
  --url "https://shop.example.com" \
  --response-model '{"type":"array","items":{"type":"object","properties":{"product":{"type":"string","description":"产品名称。"},"sentiment":{"type":"string","enum":["positive","negative","neutral"],"description":"产品整体情感倾向。"}},"required":["product","sentiment"]}}'

带元数据（Agent将使用该数据）：

bash

smooth run <session-id> "使用用户信息填写表单" \
  --metadata '{"email":"user@example.com","name":"John Doe"}'

可选参数：

```
--url
```
- 执行任务前导航至该URL
```
--metadata
```
- 任务所需变量的JSON对象
```
--response-model
```
- 结构化输出的JSON schema
```
--max-steps
```
- Agent最大执行步骤数（默认：32）
```
--json
```
- 以JSON格式输出结果

注意事项： 任务的抽象层级要合适。既不要过于具体（例如单步操作），也不要过于宽泛模糊。

合适的任务示例：

"在领英上搜索亚马逊的SDE岗位从业者，返回5个个人资料链接"
"查询亚马逊上iPhone 17的价格"

不合适的任务示例：

"点击搜索按钮" -> 过于具体！
"打开google.com，输入'附近餐厅'，点击搜索，等待页面加载，提取排名前五的结果并返回。" -> 过于具体！可以简化为"在谷歌上搜索附近餐厅并返回排名前五的结果"
"寻找适合我们公司的软件工程师" -> 过于宽泛！你需要规划实现目标的步骤，拆分出清晰明确的任务来完成最终目标

重要提示：Smooth由智能Agent驱动，请勿过度控制它，应提供清晰的目标导向任务而非具体步骤。

4. Close the Session

4. 关闭会话

You must close the session when you're done.

bash

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.

任务完成后必须关闭会话。

bash

smooth close-session <session-id>

重要提示： 关闭会话后等待5秒，确保Cookie和状态已保存到配置文件（若后续会话需要使用）。

Common Use Cases

常见使用场景

Authentication & Persistent Sessions

身份认证与持久会话

Create a profile for a specific website:

bash

undefined

为特定网站创建配置文件：

bash

undefined

Create profile

创建配置文件

smooth create-profile --profile-id "github-account"

Start session

启动会话

smooth start-session --profile-id "github-account" --url "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

将URL提供给用户，让其在浏览器中打开并登录

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

保存profile-id以便后续复用


**Reuse authenticated profile:**
```bash


**复用已认证的配置文件：**
```bash

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.

---

smooth start-session --profile-id "github-account" smooth run <session-id> "在我的仓库'my-project'中创建一个新的Issue"


**有序管理配置文件：** 记录每个配置文件对应的服务，以便后续高效复用。

---

Sequential Tasks on Same Browser

同一浏览器中的连续任务

Execute multiple tasks in sequence without closing the session:

bash

SESSION_ID=$(smooth start-session --profile-id "my-profile" --json | jq -r .session_id)

在不关闭会话的情况下依次执行多个任务：

bash

SESSION_ID=$(smooth start-session --profile-id "my-profile" --json | jq -r .session_id)

Task 1: Login

任务1：登录

smooth run $SESSION_ID "Log into the website with the given credentials"

smooth run $SESSION_ID "使用提供的凭据登录网站"

Task 2: First action

任务2：第一个操作

smooth run $SESSION_ID "Find the settings and change the notifications preferences to email only"

smooth run $SESSION_ID "找到设置页面，将通知偏好修改为仅邮件通知"

Task 3: Second action

任务3：第二个操作

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:**
```bash

smooth run $SESSION_ID "找到账单板块，提供最新发票的URL"

smooth close-session $SESSION_ID


**重要提示：** `run`命令会保留浏览器状态（Cookie、URL、页面内容），但**不会**保留浏览器Agent的记忆。若需要将信息从一个任务传递到下一个任务，需在提示语中明确传递。

**示例 - 在任务间传递上下文：**
```bash

Task 1: Get information

任务1：获取信息

RESULT=$(smooth run $SESSION_ID "Find the product name on this page" --json | jq -r .output)

RESULT=$(smooth run $SESSION_ID "查找当前页面的产品名称" --json | jq -r .output)

Task 2: Use information from Task 1

任务2：使用任务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.

---

smooth run $SESSION_ID "考虑名为'$RESULT'的产品，现在找出该电商平台上的3款同类产品。"


**注意事项：** 
- `run`命令是阻塞式的。若需要同时执行多个任务，必须使用子Agent（任务工具）。
- 所有任务将在当前标签页执行，无法在新标签页运行任务。若需要保留当前标签页状态，可打开新会话。
- 每个会话一次只能运行一个任务。若需要同时执行任务，需为每个子Agent分配一个独立会话。
- 最大并发会话数取决于用户的套餐。
- 必要时可提醒用户升级套餐以获得更多并发会话数。

---

Web Scraping with Structured Output

带结构化输出的网页爬取

Option 1: Using
run
with structured output:

bash

smooth start-session --url "https://news.ycombinator.com"
smooth run <session-id> "Extract the top 10 posts" \
  --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:

bash

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
```
extract
```
when you're on the right page or know the right url and just need to pull structured data
Use
```
run
```
when you need the agent to navigate, interact, or perform complex actions before extracting

选项1：使用带结构化输出的
run
命令：

bash

smooth start-session --url "https://news.ycombinator.com"
smooth run <session-id> "提取排名前十的帖子" \
  --response-model '{
    "type": "object",
    "properties": {
      "posts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "points": {"type": "number"}
          }
        }
      }
    }
  }'

选项2：使用
extract
命令直接提取数据：

extract

命令更适合纯数据提取场景，因为它不使用Agent步骤，效率更高。

它就像一个智能抓取工具，可以从动态渲染的网站中提取结构化数据：

bash

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 "提取排名前十的帖子"

使用场景区分：

当你已在目标页面或知道目标URL，仅需提取结构化数据时，使用
```
extract
```
当你需要Agent先完成导航、交互或复杂操作再提取数据时，使用
```
run
```

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:

bash

undefined

上传文件以供会话使用：

文件必须在启动会话前上传，然后通过文件ID传递给会话：

bash

undefined

Step 1: Upload files

步骤1：上传文件

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

步骤2：启动会话并加载文件

smooth start-session --files "$FILE_ID" --url "https://example.com"

Step 3: The agent can now access the file in tasks

步骤3：Agent可在任务中访问该文件

smooth run <session-id> "Analyze the contract document and extract key terms"


**Upload multiple files:**
```bash

smooth run <session-id> "分析合同文档并提取关键条款"


**上传多个文件：**
```bash

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:**
```bash
smooth run <session-id> "Download the monthly report PDF" --url
smooth close-session <session-id>

smooth start-session --files "$FILE_ID_1,$FILE_ID_2"


**从会话中下载文件：**
```bash
smooth run <session-id> "下载月度报告PDF" --url
smooth close-session <session-id>

After session closes, get download URL

会话关闭后，获取下载URL

smooth downloads <session-id>

Visit the URL to download files

访问该URL以下载文件

---

---

Live View & Manual Intervention

实时视图与人工干预

When automation needs human input (CAPTCHA, 2FA, complex authentication):

bash

smooth start-session --profile-id "my-profile"
smooth run <session-id> "Go to secure-site.com and log in"

当自动化需要人工输入（验证码、双因素认证、复杂身份认证）时：

bash

smooth start-session --profile-id "my-profile"
smooth run <session-id> "访问secure-site.com并登录"

If task encounters CAPTCHA or requires manual action:

若任务遇到验证码或需要人工操作：

smooth live-view <session-id>

Open the URL and complete the manual steps

打开该URL并完成手动步骤

Continue automation after manual intervention:

人工干预后继续自动化：

smooth run <session-id> "Now navigate to the dashboard and export data"

---

smooth run <session-id> "现在导航至仪表板并导出数据"

---

Direct Browser Actions

直接浏览器操作

Extract data from current page:

bash

smooth start-session --url "https://example.com/products"
smooth extract <session-id> \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
  --prompt "Extract all product names and prices"

Navigate to URL then extract:

bash

smooth extract <session-id> \
  --url "https://example.com/products" \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}'

Execute JavaScript in the browser:

bash

undefined

从当前页面提取数据：

bash

smooth start-session --url "https://example.com/products"
smooth extract <session-id> \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
  --prompt "提取所有产品名称和价格"

导航至URL后提取数据：

bash

smooth extract <session-id> \
  --url "https://example.com/products" \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}'

在浏览器中执行JavaScript：

bash

undefined

Simple JavaScript

简单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

复杂DOM操作

smooth evaluate-js <session-id>
"document.querySelectorAll('a').length"

---

smooth evaluate-js <session-id>
"document.querySelectorAll('a').length"

---

Profile Management

配置文件管理

List all profiles:

bash

smooth list-profiles

Delete a profile:

bash

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

列出所有配置文件：

bash

smooth list-profiles

删除配置文件：

bash

smooth delete-profile <profile-id>

配置文件适用场景：

✅ 需要身份认证的网站
✅ 在多个任务执行之间保持会话状态
✅ 避免重复登录
✅ 保留Cookie和本地存储

无需使用配置文件的场景：

无需身份认证的公共网站
一次性爬取任务
测试场景

File Management

文件管理

Upload files:

bash

smooth upload-file /path/to/file.pdf --name "document.pdf" --purpose "Contract for review"

Delete files:

bash

smooth delete-file <file-id>

上传文件：

bash

smooth upload-file /path/to/file.pdf --name "document.pdf" --purpose "Contract for review"

删除文件：

bash

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.

务必保存会话ID - 后续命令都需要用到它
对已认证会话使用配置文件 - 记录每个配置文件对应的网站
关闭会话后等待5秒 - 确保状态已正确保存
使用描述性的配置文件ID - 例如："linkedin-personal"、"twitter-company"
任务完成后关闭会话 - 正常关闭（默认）可确保资源正确清理
数据提取时使用结构化输出 - 提供清晰、类型明确的结果
在同一会话中执行连续任务 - 当步骤依赖于之前的操作时，保持会话连续
为独立任务使用带单独会话的子Agent - 并行执行任务以提高效率
协调资源 - 与子Agent协作时，必须为每个子Agent创建并分配一个独立会话，避免重复创建
不要在URL中添加查询参数，例如避免
?filter=xyz
- 从基础URL开始，让Agent通过UI导航来应用筛选条件
Smooth由智能Agent驱动 - 提供任务目标，而非单个步骤

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.

“Session not found” - 会话可能已超时或被关闭。请启动新会话。

“Profile not found” - 运行

smooth list-profiles

查看可用配置文件。

验证码或身份认证问题 - 使用

smooth live-view <session-id>

让用户手动干预。

任务超时 - 增加

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

处理以“-”（短横线）开头的会话ID - 会话ID可能以短横线开头。这种情况下，使用“--”（双短横线）分隔符来处理

Command Reference

命令参考

Profile Commands

配置文件命令

```
smooth create-profile [--profile-id ID]
```
- Create a new profile
```
smooth list-profiles
```
- List all profiles
```
smooth delete-profile <profile-id>
```
- Delete a profile

```
smooth create-profile [--profile-id ID]
```
- 创建新配置文件
```
smooth list-profiles
```
- 列出所有配置文件
```
smooth delete-profile <profile-id>
```
- 删除配置文件

File Commands

文件命令

smooth upload-file <path> [--name NAME] [--purpose PURPOSE]

- Upload a file

```
smooth delete-file <file-id>
```
- Delete an uploaded file

smooth upload-file <path> [--name NAME] [--purpose PURPOSE]

- 上传文件

```
smooth delete-file <file-id>
```
- 删除已上传文件

Session Commands

会话命令

```
smooth start-session [OPTIONS]
```
- Start a browser session

smooth close-session <session-id> [--force]

- Close a session

smooth run <session-id> "<task>" [OPTIONS]

- Run a task

smooth extract <session-id> --schema SCHEMA [OPTIONS]

- Extract structured data

smooth evaluate-js <session-id> "code" [--args JSON]

- Execute JavaScript

```
smooth live-view <session-id>
```
- Get interactive live URL
```
smooth recording-url <session-id>
```
- Get recording URL
```
smooth downloads <session-id>
```
- Get downloads URL

All commands support

--json

flag for JSON output.

```
smooth start-session [OPTIONS]
```
- 启动浏览器会话

smooth close-session <session-id> [--force]

- 关闭会话

smooth run <session-id> "<task>" [OPTIONS]

- 执行任务

smooth extract <session-id> --schema SCHEMA [OPTIONS]

- 提取结构化数据

smooth evaluate-js <session-id> "code" [--args JSON]

- 执行JavaScript代码

```
smooth live-view <session-id>
```
- 获取交互式实时URL
```
smooth recording-url <session-id>
```
- 获取录制URL
```
smooth downloads <session-id>
```
- 获取下载URL

所有命令均支持

--json

参数以输出JSON格式结果。