ブラウザエージェント

ブラウザエージェントは、単純な HTTP リクエストではコードから実行できない Web 上のタスクをこなします。サイト内の検索、ページの移動、フォームの入力と送信、ログイン、ページに表示された内容の読み取りなどです。タスクは普段の言葉で説明するだけです。エージェントは実際の Chromium ブラウザで 1 操作ずつ作業を進め、テキストの answer と、指定した場合は data に JSON を返します。

API キーとプリペイド残高は Lovely Router の他のサービスと共通です。料金はステップ単位で $0.006 から、モデル料金も含まれています。実行料金はかかりません。

最初のタスクを実行する#

1. 1

   API キーを取得する

   API キーでキーを作成し、環境変数に設定します。X で Lovely Router を紹介すると $2 分の無料クレジットがもらえ、短い実行なら数十回試せます（受け取り方）。

   Shell

   export LOVELY_API_KEY="lr-..."

2. 2

   実行を開始する

   goal と start_url を POST /v1/browser/runs に送ります。レスポンスはステータス 202 と実行の id を含んですぐに返り、エージェントはバックグラウンドで作業を続けます。

   cURLPythonNode.js

   Shell

   curl https://lovelyrouter.com/v1/browser/runs \
     -H "Authorization: Bearer $LOVELY_API_KEY" \
     -H "content-type: application/json" \
     -d '{
       "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
       "start_url": "https://books.toscrape.com/"
     }'

3. 3

   結果を待つ

   ?wait=30 を付けて実行を取得します。リクエストは最大 30 秒（上限は 50 秒）待機し、ステータスが変わるとすぐに返ります。この呼び出しをループすれば、ビジーポーリングをせずに実行を追跡できます。

   各ステップやブラウザ画面をその場で見たい場合は、開始時に "stream": true を付けてください。ライブイベントと画面を参照してください。

   cURLPythonNode.js

   Shell

   curl "https://lovelyrouter.com/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d?wait=30" \
     -H "Authorization: Bearer $LOVELY_API_KEY"

4. 4

   結果を読む

   完了した実行には、status、エージェントの answer、そして費用を示す charge_usd が含まれます（一部省略）。

   JSON

   {
     "id": "brun_3f9a1c7e0b2d4e6f8a9b0c1d",
     "object": "browser_run",
     "status": "succeeded",
     "mode": "fast",
     "steps": 2,
     "max_steps": 50,
     "current_url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
     "answer": "\"A Light in the Attic\" costs £51.77 and is in stock (22 available).",
     "data": null,
     "error": null,
     "charge_usd": 0.012,
     "reserved_usd": 0
   }

   フィールドの全一覧は実行オブジェクトにあります。リクエストに &trace=1 を追加すると、エージェントが実行したすべてのステップを取得できます。

コンソールから実行を開始することもできます。例を選ぶかタスクを書き、ブラウザ画面と各ステップをリアルタイムで確認し、エージェントから質問されたら答え、対応する cURL、Python、JavaScript のコードをコピーできます。

実行の流れ#

実行は running で始まり、4 つの最終ステータスのいずれかで終わります。その間に waiting_for_human として一時停止し、あなたが返信すると再開することがあります。

エージェントは各ステップで現在のページを読み、操作を 1 つ選んで実行します。ゴールを達成したとき、人の対応が必要になったとき、または max_steps に達したときに停止します。フォームを送信するボタンをクリックする前には、すべての項目をゴールと照合し、合わない値を修正します。

succeeded はエージェントが作業を終えたことを意味し、Web サイトがその操作を受け付けたことを意味するわけではありません。何かを送信するタスクでは answer を確認してください。ページに入力エラーが表示された場合や確認画面が出なかった場合は、回答にその旨が書かれます。

実行が終了すると、開始時に仮押さえした金額のうち使わなかった分が残高に戻り、charge_usd に最終的な請求額が表示されます。それまでは charge_usd は null です。

ステップとして数えられるもの#

1 ステップは 1 回のブラウザ操作です。

• リンク、ボタン、チェックボックス、リストの選択肢をクリックする
• 入力欄に入力する、または入力して Enter キーを押す
• ドロップダウンで選択肢を選ぶ
• 保存済みのシークレットを入力する、またはファイルをアップロードする
• 前のページに戻る
• まだ読み込まれていないページを待つ、または再読み込みする
• 読み取り専用のコードを実行してページからデータを読む（高精度モードのみ）
• 最終回答を書く

人を待つ一時停止（質問、承認、引き渡し）はトレースに表示されますが、課金されません。失敗したステップ（要素が移動していた場合など）もカウントされます。実行の steps フィールドは、一時停止を含め、記録されたすべてのステップを数えます。

単純な調べものは 1〜3 ステップ、ログインは 4〜8 ステップ、複数ページにわたる長いフォームは 15〜25 ステップです。費用の例はモード、モデル、料金にあります。

うまくいくゴールの書き方#

ゴールはエージェントへの唯一の指示です。そのサイトを一度も見たことのない、注意深いアシスタントに依頼するつもりで書いてください。

• タスクに必要な値をすべて含める。 名前、メールアドレス、日付、数量、正確な商品などです。エージェントに推測させないでください。値が欠けていると、エージェントは停止してあなたに質問します（質問をオフにしている場合を除く）。
• 何を報告してほしいかを書く。 「本を確認して」よりも「価格と在庫の有無を教えて」のほうが良い回答が得られます。
• 操作を伴うタスクでは、何をもって成功とするかを書く。 「フォームを送信して、確認番号を教えて」。
• タスクに近いページから始める。 わかっている場合は、トップページではなく検索ページやフォームそのものを start_url にします。
• 見る場所を指定する。 サイト内に候補が複数ある場合は、「レビュータブで」「サイト内検索を使って」のように書きます。
• 1 回の実行に 1 つのタスク。 関係のないタスクは別々の実行に分けます。
• シークレットをゴールに書かない。 パスワードはゴールのテキストに書かず、必ずボールトシークレットとして渡してください。

制限#

同時実行数の上限に達すると、POST /v1/browser/runs は 429 を返します。残高が実行の仮押さえ額に満たない場合は 402 を返します。すべてのエラーはエラーに一覧があります。

AI エージェントから使う#

https://lovelyrouter.com/mcp の MCP サーバーは、ブラウザエージェントを browser_run、browser_status、browser_reply、browser_takeover の 4 つのツールとして公開しています。キー、制限、価格は REST API と同じです。MCP ツールが受け取るのはボールトシークレットの名前だけで、シークレットの値は受け取りません。先にシークレットをボールトに保存してください。

次のステップ#