smooth-browser

Smooth Browser

Smooth CLI は、AI エージェントが自然言語を使ってウェブサイトとやり取りし、認証を行い、データをスクレイピングし、複雑なウェブベースのタスクを実行するためのブラウザーです。

前提条件

Smooth CLI はすでにインストールされているものとします。インストールされていない場合は、次を実行してインストールできます。

pip install smooth-py

API キーはすでに設定されているものとします。認証エラーが発生した場合は、次のコマンドで設定してください。

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

設定を確認するには、次を実行します。

smooth config --show

API キーは https://app.smooth.sh で取得できます。

アカウントのクレジットが不足している場合は、https://app.smooth.sh でプランをアップグレードするようユーザーに案内してください。

基本的なワークフロー

1. プロファイルを作成する（任意）

プロファイルを使うと、セッション間で Cookie、ログインセッション、ブラウザーの状態を保持できます。

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

既存のプロファイルを一覧表示します。

smooth list-profiles

2. ブラウザーセッションを開始する

smooth start-session --profile-id "my-profile"

オプション：

• --profile-id - 特定のプロファイルを使用します（任意。指定しない場合は匿名セッションが作成されます）
• --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. セッションでタスクを実行する

自然言語を使ってタスクを実行します。

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

構造化出力を使う場合（操作を伴うタスク向け）：

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"]}}'

メタデータを使う場合（エージェントに渡す情報）：

smooth run <session-id> "Fill out the form with user information" \
  --metadata '{"email":"[email protected]","name":"John Doe"}'

オプション：

• --url - タスクを実行する前に、この URL に移動します
• --metadata - タスク用の変数を含む JSON オブジェクト
• --response-model - 構造化出力用の JSON スキーマ
• --max-steps - エージェントの最大ステップ数（デフォルト：32）
• --json - 結果を JSON 形式で出力します

注： タスクは適切な抽象度で指定することが重要です。細かすぎる指示（例：単一ステップの操作）も、広すぎたり曖昧すぎたりする指示も避けてください。

適切なタスク：

• 「LinkedIn で Amazon に SDE として勤務する人を検索し、プロフィール URL を 5 件返してください」
• 「Amazon での iPhone 17 の価格を調べてください」

不適切なタスク：

• 「検索をクリックする」→ 細かすぎます！
• 「google.com を開き、『近くのレストラン』と入力して検索をクリックし、ページの読み込みを待ち、上位 5 件の結果を抽出して返してください。」→ 細かすぎます！「Google で近くのレストランを検索し、上位 5 件の結果を返してください」と指定できます。
• 「当社に適したソフトウェアエンジニアを探してください」→ 広すぎます！目標達成の方法を計画し、目標を構成する明確に定義されたタスクを実行する必要があります。

重要：Smooth はインテリジェントなエージェントを搭載しています。過度に細かく指示せず、手順ではなく、目標が明確に定義されたタスクを与えてください。

4. セッションを閉じる

完了したら、必ずセッションを閉じてください。

smooth close-session <session-id>

重要： 別のセッションでもプロファイルを使用する必要がある場合は、Cookie と状態がプロファイルに保存されるよう、セッションを閉じた後 5 秒待ってください。

---

よくあるユースケース

認証と永続セッション

特定のウェブサイト用のプロファイルを作成する：

# 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

認証済みプロファイルを再利用する：

# 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'"

プロファイルを整理して管理する： どのプロファイルがどのサービスで認証されているかをメモリに保存しておくと、今後効率よく再利用できます。

---

同じブラウザーでの連続タスク

セッションを終了せずに、複数のタスクを順番に実行します。

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

重要： run はブラウザーの状態（Cookie、URL、ページの内容）を保持しますが、ブラウザーエージェントのメモリは保持しません。あるタスクから次のタスクへ情報を引き継ぐ必要がある場合は、プロンプトで明示的に渡してください。

例 - タスク間でコンテキストを引き継ぐ：

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

注意：

• run コマンドはブロッキング処理です。複数のタスクを同時に実行する必要がある場合は、サブエージェント（Task ツール）を使用する必要があります。
• すべてのタスクは現在のタブを使用します。新しいタブでタスクを実行するよう指定することはできません。現在のタブの状態を保持する必要がある場合は、新しいセッションを開いてください。
• 各セッションで実行できるタスクは一度に1つだけです。タスクを同時に実行するには、セッションを1つずつ割り当ててサブエージェントを使用してください。
• 同時に実行できるセッションの最大数は、ユーザープランによって異なります。
• 必要に応じて、プランをアップグレードすると同時に実行できるセッション数を増やせることをユーザーに伝えてください。

---

構造化出力を使用したウェブスクレイピング

オプション1：構造化出力を指定して run を使用する：

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"}
          }
        }
      }
    }
  }'

オプション2：直接データを抽出する extract を使用する：

extract コマンドはエージェントのステップを使用しないため、純粋なデータ抽出により効率的です。

動的にレンダリングされるウェブサイトから構造化データを抽出できる、スマートな fetch のような機能です。

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"

使い分け：

• 適切なページを開いている場合や、目的の URL がわかっていて、構造化データを取得するだけの場合は extract を使用します
• 抽出前にエージェントによる移動、操作、複雑なアクションが必要な場合は run を使用します

---

ファイルの操作

セッションで使用するファイルをアップロードする：

セッションを開始する前にファイルをアップロードし、ファイル ID を使ってセッションに渡す必要があります。

# 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 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"

セッションからファイルをダウンロードする：

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

---

ライブビューと手動操作

自動化で人間による入力が必要な場合（CAPTCHA、2FA、複雑な認証）：

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"

---

ブラウザーの直接操作

現在のページからデータを抽出する：

smooth extract <session-id> \
  --schema '{"type":"object","properties":{"products":{"type":"array"}}}' \
  --prompt "Extract all product names and prices"

URL に移動してから抽出する：

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

ブラウザーで JavaScript を実行する：

# 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"

---

プロファイル管理

すべてのプロファイルを一覧表示する：

smooth list-profiles

プロファイルを削除する：

smooth delete-profile <profile-id>

プロファイルを使用する場合：

• ✅ 認証が必要なウェブサイト
• ✅ 複数のタスク実行にわたってセッションの状態を維持する場合
• ✅ ログインの繰り返しを避ける場合
• ✅ Cookie とローカルストレージを保持する場合

プロファイルを使用しない場合：

• 認証が不要な公開ウェブサイト
• 1回限りのスクレイピングタスク
• テストシナリオ

---

ファイル管理

ファイルをアップロードする：

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

ファイルを削除する：

smooth delete-file <file-id>

---

ベストプラクティス

1. セッション ID は必ず保存する - 後続のコマンドで必要になります
2. 認証済みセッションにはプロファイルを使用する - どのプロファイルがどのウェブサイト用かを記録します
3. セッションを終了した後は5秒待つ - 状態が確実に保存されます
4. わかりやすいプロファイル ID を使用する - 例：「linkedin-personal」、「twitter-company」
5. 作業が終わったらセッションを終了する - 正常に終了すると（デフォルト）、適切にクリーンアップされます
6. データ抽出には構造化出力を使用する - 整然とした型付きの結果が得られます
7. 連続するタスクは同じセッションで実行する - 手順が前の作業に依存する場合は、セッションを継続してください。
8. 独立したタスクには、セッションを1つずつ割り当ててサブエージェントを使用する - タスクを並列実行して作業を高速化します。
9. リソースを調整する - サブエージェントを使用する場合は、各サブエージェントにセクションを1つずつ作成して割り当て、サブエージェント自身には作成させないでください。
10. URL にクエリパラメーターを追加しない - たとえば、?filter=xyz は使用しないでください。ベース URL から始め、エージェントに UI を操作させてフィルターを適用します。
11. Smooth はインテリジェントエージェントを搭載しています - 個々の手順ではなく、タスクを指示してください。

---

トラブルシューティング

「Session not found」 - セッションがタイムアウトしたか、終了している可能性があります。新しいセッションを開始してください。

「Profile not found」 - smooth list-profiles を実行して、利用可能なプロファイルを確認してください。

CAPTCHA または認証に関する問題 - smooth live-view <session-id> を使用して、ユーザーが手動で操作できるようにしてください。

タスクのタイムアウト - --max-steps を増やすか、タスクを小さなステップに分割してください。

既知の問題

-（ハイフン）で始まるセッション ID の扱い - セッション ID がハイフンで始まる場合があります。その場合は、--（ダブルハイフン）セパレーターを使ってください。

---

コマンドリファレンス

プロファイルコマンド

• smooth create-profile [--profile-id ID] - 新しいプロファイルを作成します
• smooth list-profiles - すべてのプロファイルを一覧表示します
• smooth delete-profile <profile-id> - プロファイルを削除します

ファイルコマンド

• smooth upload-file <path> [--name NAME] [--purpose PURPOSE] - ファイルをアップロードします
• smooth delete-file <file-id> - アップロードしたファイルを削除します

セッションコマンド

• 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 フラグを使用できます。