opensteer

Opensteer

Opensteer は、グローバルなブラウザー制御ランタイムです。エージェントとハーネスパックに、小さな CDP プリミティブを公開します。

使用方法

opensteer -c "open_browser(profile='fresh'); new_tab('https://example.com'); print(page_info())"

Python スニペットでは、ヘルパーがあらかじめインポートされています。

opensteer -c "new_tab('https://docs.opensteer.com'); wait_for_load(); print(page_info())"

ハーネスコードでは、インストール済みパッケージからヘルパーをインポートします。

from opensteer.helpers import goto_url, js, click_at_xy, type_text, wait_for_load

明示的なブラウザーセッション

ブラウザーを操作する際は、ブラウザープロファイルと再利用モードを明示的に選択してください。返されるハンドルは、特定のプラットフォームセッション 1 つだけに紐づいています。また、その安定した ID によって、後続の CLI 呼び出しやエージェントの実行でもブラウザーを再利用できます。

opensteer -c "browser = open_browser(label='research', profile='fresh'); browser.new_tab('https://example.com')"
opensteer -c "browser = open_browser(label='work', profileId='bp_...'); print(browser.page_info())"
opensteer -c "browser = open_browser(profileId='bp_...'); print(browser.page_info())"

プラットフォームに、許可された唯一のプロファイル（または許可がない場合はプロファイル未設定のブラウザー）を意図的に選ばせたい場合に限り、profile='auto' を使用してください。mode='reuse' がデフォルトです。このエージェント、場所、プロファイルに対応する安定したプライマリブラウザーを選択します。label は省略可能な変更可能な表示メタデータです。明示的に異なるラベルを指定すると、同じブラウザーの UI 上の名前が変更されます。省略すると、現在のラベルが維持されます。別のブラウザーを選択したり作成したりすることはありません。別個の論理ブラウザーが意図的に必要な場合に限り、mode='new' を使用してください。

profile='fresh' は、保存済みプロファイルが紐づかないことを意味します。新規またはクリーンな状態、あるいはサインアウト済みのブラウザーが保証されるわけではありません。mode='reuse' では、以前の実行で使われたものを含め、プロファイル未設定の既存ブラウザーが返される場合があります。別個のクリーンな状態が必要な場合は、profile='fresh', mode='new' を使用してください。

読み取りヘルパーがクラウドブラウザーを作成することはありません。アクティブなブラウザーがない場合は、まず open_browser(...) を呼び出してください。

ブラウザーを作成せずに、稼働中のブラウザーを一覧表示して明示的に選択します。

opensteer -c "print(list_browsers())"
opensteer -c "browser = use_browser('linkedin'); print(browser.page_info())"

list_browsers() は読み取り専用です。use_browser(...) には、一意のラベル、または一覧から返された正確な sessionId を指定できます。

ブラウザーは、単一のエージェントコマンドや実行が終了した後も存続します。通常のプロセスや実行の終了時には、コントローラーリレーのみが切り離されます。ブラウザー自体を破棄する場合に限り、browser.close()（または対応する close API）を呼び出してください。

ブラウザーのトランスポートは、エージェントの実行場所とは独立しています。ローカルで実行されるエージェントに分離されたクラウドブラウザーが必要な場合は location='cloud'、デスクトップアプリの組み込みブラウザーを使う場合は location='inapp'、別のマシンの Chromium ウィンドウを使う場合は location='local' を指定してください。通常の自動ルーティングでは、省略するか location='auto' を使用してください。クラウド実行でサポートされるのは auto と cloud のみです。デバイス専用の場所は拒否されます。

opensteer -c "open_browser(label='research', profile='fresh', location='cloud')"

ブラウザープロファイル

ブラウザープロファイルとは、クラウドブラウザーが起動時に使用できる、ログイン済みのブラウザー ID（Cookie、認証状態）を保存したものです。プロファイルへのアクセスは許可ベースです。サーバーは、このエージェントが使用できるプロファイルを管理し、エージェントごとのデフォルトプロファイルはありません。

• list_cloud_profiles() は表示可能なプロファイルを一覧表示します。各エントリーには、このエージェントがそのプロファイルを使用できるかを示す granted フラグが含まれます。
• open_browser(label=name, profile='auto') を使うと、サーバーがプロファイルを解決します。許可されたプロファイルが1つだけの場合は自動的に割り当てられ、許可されたプロファイルがない場合はプロファイルなしのセッションが起動します。許可されたプロファイルが複数ある場合は、profileName または profileId を渡すよう指示するエラーが返されます。
• 複数のプロファイルが許可されている場合は、明示的に選択します。 open_browser(label='linkedin', profileName='LinkedIn work') または open_browser(label='linkedin', profileId='bp_...') を使います。長期運用するスクリプトでは profileId を指定してください。プロファイル名が変更されても影響を受けません。
• このエージェントに許可されていないプロファイルを渡すと、次の手順（許可済みプロファイルの一覧表示またはアクセス権のリクエスト）を示すメッセージを含む403エラーが発生します。
• 許可されたプロファイルは、location='inapp' と location='cloud' のどちらでも使用できます。要求されたプロファイルまたは場所に対応できないプロバイダーは、どちらも変更せずに失敗します。

プラットフォームのプロファイルツールでは、アクセス権のリクエストと、実行中の状態の保存は別々に行います。

• request_browser_profile は、既存のプロファイルをユーザーに選択または許可してもらいます。許可済みのプロファイルからサインアウトされている場合は、そのプロファイルを正確に開き、ユーザーに操作を引き継いでサインインしてもらってから続行します。修復モードはありません。通常のブラウザー終了時の永続化処理で、更新されたログイン状態が保存されます。
• request_save_browser_profile は、すでに開いている、プロファイルが割り当てられていないブラウザーを保存します。今後の再利用が役立つ可能性が高い場合に限って提案し、自動で保存したり、断られた後も繰り返し尋ねたりしないでください。保存を直接依頼された場合は承認とみなします。それ以外の場合は、まず request_user_input で明示的な承認を得てください。open_browser(...) が返したハンドル（または use_browser(...) で取得したハンドル）を保持し、その正確な browser.browser_ref を渡してください。ラベルや、現在のブラウザーだと推測したものは絶対に渡さないでください。特殊化されたエージェントは cloudAgentId を省略し、自身が許可を受け取ります。Chat では対象となる特殊化されたエージェントを指定することも、対象を省略して未割り当てで保存することもできます。Chat 自体は許可を受け取りません。保存されるのは、Cookie を使った永続的な認証状態のスナップショットです。元のブラウザーを閉じたり、再割り当てしたり、同期し続けたりすることはありません。

インタラクションスキル

一般的なブラウザー操作は interaction-skills/ にあります。

• connection.md
• cookies.md
• cross-origin-iframes.md
• dialogs.md
• downloads.md
• drag-and-drop.md
• dropdowns.md
• iframes.md
• network-requests.md
• print-as-pdf.md
• screenshots.md
• scrolling.md
• shadow-dom.md
• tabs.md
• uploads.md
• viewport.md

ページの操作が複雑な場合は、これらを活用してください。ドメイン固有のセレクター、ワークフロー、API、ローカルデータベース、タスクツールはハーネスパックに含めてください。

うまく機能する使い方

• 表示状態を確認するには、まずスクリーンショットを取得します：capture_screenshot()。
• 表示されている対象のクリックには、座標を使う方法を優先します：click_at_xy(x, y)。
• DOM の調査、情報の抽出、ページ API の確認には js(...) を使います。
• ヘルパーで対応できない生の CDP 操作には cdp("Domain.method", ...) を使います。
• ページ遷移後は wait_for_load() を呼び出します。
• デフォルトでは、現在の Opensteer 所有タブを操作します。既存の特定のタブを指定するようユーザーから明示的に依頼された場合に限り、list_tabs() と switch_tab(target_id) を使います。
• ページがログイン画面にリダイレクトされた場合は停止し、ユーザーに確認してください。スクリーンショットに写った認証情報を入力してはいけません。

境界

Opensteer は、一般的なブラウザープリミティブ、ローカルアタッチ、リモートアタッチ、クラウドブラウザーへのアタッチ、一般的なインタラクションスキルを管理します。

ハーネスパックは、ドメイン固有のツール、セレクター、ワークフロー、ストレージ、セットアップドキュメント、エージェントスキルを管理します。