ブラウザエージェント

構造化出力

出力スキーマを渡すと、エージェントが訪れたページだけをもとにした検証済みの JSON が data に返ります。

すべての実行はテキストの answer を返します。output_schema を追加すると、それに一致する JSON も data に返ります。JSON はエージェントが訪れたページのテキストとリンク、そしてエージェントの回答から作られ、推測で埋めることはありません。そのため、リンク URL はページ上の実際のものです。構造化出力に追加料金はかかりません。

output_schema で JSON を取得する#

欲しい形を渡します。省略形では、各フィールドに型を対応させます。

Shell

curl https://lovelyrouter.com/v1/browser/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "goal": "Get the top 3 stories on the front page.",
    "start_url": "https://news.ycombinator.com/",
    "output_schema": {
      "stories": [{"title": "string", "url": "string", "points": "integer"}]
    }
  }'

完了した実行では、answer と並んで data に JSON が入ります。

JSON

{
  "id": "brun_8f3c2d1e0a9b8c7d6e5f4a3b",
  "object": "browser_run",
  "status": "succeeded",
  "steps": 1,
  "answer": "The top 3 stories are \"Bitwarden Dual License Model\" (95 points), \"Talorys – A self-hosted personal AI agent\" (57 points) and \"REA Reverse – Engineer Anything\" (498 points).",
  "data": {
    "stories": [
      { "title": "Bitwarden Dual License Model", "url": "https://community.bitwarden.com/…", "points": 95 },
      { "title": "Talorys – A self-hosted personal AI agent", "url": "https://github.com/rociiu/talorys", "points": 57 },
      { "title": "REA Reverse – Engineer Anything", "url": "https://rea.tools/", "points": 498 }
    ]
  },
  "charge_usd": 0.006
}

Python と Node.js のサンプルは、最初のタスクを実行するで定義した API、H、headers を使います。

省略形のスキーマ#

省略形は、各値がフィールドを表すプレーンな JSON です。

書き方	結果
`"string"`、`"number"`、`"integer"`、`"boolean"`、`"array"`、`"object"`、`"null"`	その型の値。ページに表示されていない場合は `null`
その他のテキスト（例：`"price as shown, with currency"`）	文字列または `null`。テキストで、そこに何を入れるかをエージェントに伝えます
`["string"]`、`[{...}]`	その要素のリスト。`[]` は任意の要素のリスト
`{"field": ...}`	ちょうどそれらのフィールドを持つオブジェクト。すべてのフィールドが含まれます

説明文を書いたフィールドは文字列になります。"price": "price in USD" は数値ではなく "$19.99" を返します。数値が欲しい場合は "number" を使ってください。

スキーマの最上位に type、properties、items、$schema という名前のキーがあると、省略形ではなく完全な JSON Schema として解釈されます。これらの名前のフィールドを返したい場合は、完全な JSON Schema で書いてください。

完全な JSON Schema#

列挙値、フォーマット、必須フィールド、型付きフィールドの説明が必要な場合は、JSON Schema（draft 2020-12）を渡します。

JSON

{
  "goal": "Find the 2026 Toyota Camry trims on the build page with their starting MSRP and engine.",
  "start_url": "https://www.toyota.com/camry/",
  "output_schema": {
    "type": "object",
    "properties": {
      "trims": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "msrp_usd": { "type": "number", "description": "Starting MSRP, without fees" },
            "engine": { "type": "string" },
            "hybrid": { "type": "boolean" }
          },
          "required": ["name", "msrp_usd"]
        }
      }
    },
    "required": ["trims"]
  }
}

結果はスキーマに対して検証されます。最初の試行が検証に通らなかった場合、エージェントは検証エラーを受け取り、1 回だけ修正します。スキーマのサイズは最大 20 KB です。有効な JSON Schema でないスキーマを渡すと、開始時に 400 と "output_schema" is not a usable JSON Schema: … が返ります。

data と data_error を読む#

フィールド	説明
`data`	実行終了後の JSON。実行中、構造を指定しなかった場合、抽出に失敗した場合は `null` です。
`data_error`	抽出に失敗した場合にのみ含まれ、理由を示します。例：`extracted data does not match the schema: …` に続けて、失敗したフィールドが示されます。

ページに表示されていない値は、作り上げられることなく null で返り、リストは空で返ります。シークレットの値が data に含まれることはなく、[secret:<name>] に置き換えられます。

data を使う前に data_error を確認してください。

Python

if run.get("data_error"):
    raise RuntimeError(f"no data: {run['data_error']}")
trims = run["data"]["trims"]

代わりにゴールで形式を指定する#

ゴールそのもので構造を指定することもできます。たとえば「募集中のポジションを、職種名、チーム、勤務地を含む JSON のリストで返して」のように書きます。ゴールが特定の形の構造化データ（JSON、名前付きのフィールド、列を指定したリストや表）を求めている場合、実行はその形で data も埋めます。スキーマがなければ検証の基準がないため、コードが正確な形に依存する場合は output_schema を使ってください。

実行が途中で終わった場合#

ステップ上限。 max_steps に達した実行は reached the step limit (N) で failed として終了します。それでも最後のページから answer を書き、それまでに見た内容から data を埋めます。
失敗またはタイムアウト。 data はそれまでに訪れたページから埋められるため、一部だけの場合があります。
停止。 停止した実行は data を返しません。

より良いデータを得るには#

フィールド名はページでの呼び方に合わせる。 フィールド名は抽出の手がかりになります。また、最上位の名前はエージェントへの指示に追加されるため、エージェントはそれらが表示されているページで作業を終えます。score や n より、points や comments のほうがうまくいきます。
スキーマの内容をすべてゴールでも依頼する。 スキーマだけを渡すより、「上位 5 件の記事をタイトル、リンク、ポイント付きで取得して」というゴールと、それに合ったスキーマを組み合わせるほうが効果的です。
ページ数を少なくする。 データは、エージェントが最後に訪れた 6 ページから取得されます。多くのページにまたがるデータは、1 ページごと、またはページのグループごとに 1 タスクずつ実行してください。
任意のフィールドは任意にする。 完全なスキーマでは、常に必要なフィールドだけを required に入れます。省略形のフィールドは常に null になりえます。
長い表には高精度モードを使う。 高精度モードは、表示されたテキストだけでなく、ページ上のコードで長い表やリストを読み取れます。モードを参照してください。

例#

フォーム送信後の注文確認：

JSON

{
  "goal": "Order one Blue Mug (size large) for Ada Lovelace, 12 Main St, Springfield, IL 62701, and tell me the order number and total.",
  "start_url": "https://shop.example.com/mugs/blue",
  "secrets": ["shop_user", "shop_password"],
  "output_schema": { "order_number": "string", "total": "number", "currency": "string" }
}

デフォルトの "approve": "risky" では、この実行は注文を確定する前に一時停止して、あなたの承認を待ちます。人による確認を参照してください。

ネストしたフィールドを持つ検索結果：

JSON

{
  "goal": "Search for 'noise cancelling headphones' and get the first 5 results with name, price, rating and number of reviews.",
  "start_url": "https://www.example-store.com/",
  "output_schema": {
    "results": [
      { "name": "string", "price": "number", "rating": "number", "reviews": "integer", "url": "string" }
    ]
  }
}