ログイン、シークレット、プロファイル

エージェントは、モデルにパスワードを一切見せずに Web サイトへサインインできます。各認証情報を一度だけボールトに保存して使用できるサイトに紐付け、その名前を実行に渡します。どこに値を入力するかはエージェントが決めます。値そのものは入力の瞬間にだけ復号され、そのページが許可したサイト上にある場合にのみ入力されます。

ボールトにシークレットを保存する#

PUT /v1/browser/vault/{name} でシークレットを保存します。同じ名前で再度送ると置き換えられます。

curl -X PUT https://lovelyrouter.com/v1/browser/vault/shop_password \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "value": "correct-horse-battery-staple",
    "kind": "password",
    "origins": ["https://shop.example.com"]
  }'

レスポンスでは、値を除いた保存内容が返ります。

{ "name": "shop_password", "kind": "password", "origins": ["https://shop.example.com"], "stored": true }

シークレットは書き込み専用で、値を返すエンドポイントはありません。コンソールの シークレットとファイル でも管理できます。Python と Node.js のサンプルは、最初のタスクを実行するで定義した API、H、headers を使います。

オリジン#

エージェントがシークレットを入力できるのは、現在のページ（ブラウザが報告するもの）がシークレットのオリジンのいずれかに一致する場合だけです。

• https://shop.example.com は、そのサイトにのみ、https の場合に限って一致します。
• https://*.example.com は、example.com と、login.example.com などのすべてのサブドメインに一致します。

それ以外のサイトでは、シークレットはエージェントに提示すらされません。そっくりに作られたフィッシングページがログインを求めてきても、エージェントがそこに値を入力する手段はありません。

実行でシークレットを使う#

secrets に名前を渡します。実行で使えるのは、指定したシークレットだけです。

curl https://lovelyrouter.com/v1/browser/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "goal": "Sign in and tell me the status of my latest order.",
    "start_url": "https://shop.example.com/login",
    "secrets": ["shop_user", "shop_password"]
  }'

トレースには、どのシークレットがどこに入力されたかが表示されますが、値は表示されません。ステップの action は secret:e4:shop_password のようになります。ボールトにない名前を指定すると、400 と Unknown vault secret(s): shop_pw. Store them with PUT /v1/browser/vault/{name}. が返ります。

二要素認証のコード#

認証アプリを使うサイトでは、TOTP シードを totp シークレットとして保存します。シードとは、二要素認証を有効にするときにスキャンする QR コードの元になっているテキストです（多くの場合「コードをスキャンできない場合」などの表示から確認できます）。A〜Z と 2〜7 からなる 16 文字以上の文字列で、スペースとハイフンは無視されます。

curl -X PUT https://lovelyrouter.com/v1/browser/vault/github_totp \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"value": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "kind": "totp", "origins": ["https://github.com"]}'

サイトがコードを求めると、エージェントは現在のコード（標準的な 6 桁、30 秒ごとのコード）を入力します。シードの名前は、ユーザー名とパスワードとあわせて secrets に渡してください。

SMS やメールで届くコードの場合は、エージェントに質問させます。エージェントが質問で一時停止したら、{"secret": "481923"} で返信します。質問に答えるを参照してください。

実行ごとのシークレット#

保存したくない認証情報（たとえば、自社のユーザーから 1 つのタスクのために預かったもの）は、ephemeral_secrets で渡します。ボールトシークレットと同じように機能しますが、その実行の間だけ存在します。実行中は暗号化して保存され、終了時に削除されます。

{
  "goal": "Sign in and tell me the account's plan name.",
  "start_url": "https://app.example.com/login",
  "ephemeral_secrets": {
    "customer_email": { "value": "ada@example.com", "kind": "username", "origins": ["https://app.example.com"] },
    "customer_password": { "value": "s3cret-pa55word", "kind": "password", "origins": ["https://app.example.com"] }
  }
}

名前はボールトと同じ規則に従い、secrets にも渡す名前と重複してはいけません。kind のデフォルトは password で、origins は必須です。

ゴールに書いた認証情報#

ゴール自体にパスワードが含まれている場合（「demo / demo1234 でログインして」など）、エージェントはそれをパスワード欄に入力できます。これでも動作しますが、ゴールはモデルに送られ、実行オブジェクトで返され、実行履歴にも残ります。使い捨てのテストアカウントにだけ使ってください。実際のアカウントには、ボールトシークレットか実行ごとのシークレットを使ってください。

セッションを保存して再利用する#

プロファイルは保存されたブラウザセッションで、実行が訪れたサイトの Cookie とローカルストレージからなります。ログイン後に保存しておけば、以後の実行はシークレットも二要素認証の入力もなしに、サインイン済みの状態で始まります。

save_profile（最大 64 文字の名前）でプロファイルを保存します。

{
  "goal": "Sign in to the shop and tell me my name as shown on the account page.",
  "start_url": "https://shop.example.com/login",
  "secrets": ["shop_user", "shop_password", "shop_totp"],
  "save_profile": "shop-login"
}

実行が終了すると、実行オブジェクトの profile_saved に保存内容が表示されます。

{ "profile_saved": { "id": "prof_4c1e9a7b2d0f3e5a8b6c", "name": "shop-login", "cookies": 14 } }

以後の実行では、profile（名前または ID）を指定してそのプロファイルから開始します。

{
  "goal": "Open my orders and tell me the status of the latest one.",
  "start_url": "https://shop.example.com/account/orders",
  "profile": "shop-login"
}

• 既存の名前で保存すると、そのプロファイルが更新されます。セッションを新しく保つには、profile と save_profile の両方に同じ名前を指定します。
• プロファイルは、実行の最終ステータスにかかわらず保存されます。
• セッションは Web サイト側の都合で期限切れになります。プロファイルが使えなくなったら、save_profile を付けてもう一度ログインを実行してください。profile と一緒に secrets を渡しておけば、セッションが期限切れでもエージェントが自分でサインインし直せます。
• 存在しないプロファイルを指定すると、400 と Unknown profile "shop-login" (GET /v1/browser/profiles) が返ります。
• プロファイルには有効なセッション Cookie が含まれます。パスワードと同じように扱い、不要になったものは削除してください。

シークレットとプロファイルを管理する#

# List secrets: names, kinds, origins and dates, never values
curl https://lovelyrouter.com/v1/browser/vault -H "Authorization: Bearer $LOVELY_API_KEY"

# Delete a secret
curl -X DELETE https://lovelyrouter.com/v1/browser/vault/shop_password -H "Authorization: Bearer $LOVELY_API_KEY"

# List profiles
curl https://lovelyrouter.com/v1/browser/profiles -H "Authorization: Bearer $LOVELY_API_KEY"

# Delete a profile by name or id
curl -X DELETE https://lovelyrouter.com/v1/browser/profiles/shop-login -H "Authorization: Bearer $LOVELY_API_KEY"

一覧の各シークレットには last_used_at が含まれ、最後に実行で入力された日時がわかります。レスポンスの完全な形式は API リファレンスにあります。

シークレットの保護方法#

• 保存時に暗号化。 シークレット、実行ごとのシークレット、プロファイル、アップロードしたファイルは、アカウントごと、実行ごとに個別に導出した鍵を使って AES-256-GCM で暗号化されます。各値は所有者と名前に紐付けられているため、他人の値として、あるいは別の名前で復号することはできません。
• 書き込み専用。 API がシークレットの値を返すことはありません。あなたにも、あなたのキーを持つ誰にも返しません。
• モデルには送られない。 エージェントは shop_password のような名前で作業します。値が復号されるのは入力の瞬間だけで、その前にページのサイトと入力欄の種類が確認されます。
• 出力から除去。 ページのテキスト、回答、data、ステップのトレースに現れた 6 文字以上のシークレットの値は、[secret:<name>] に置き換えられます。高精度モードでは、シークレットを入力した後はスクリーンショットを撮りません。
• 必要に応じて短期間だけ保持。 実行ごとのシークレットとシークレットでの返信は、実行の終了時に削除されます。

API キーはボールトを使えるため、シークレットそのものと同じように保護してください。キーでできることは API キーで制限し、アカウントの二要素認証はアカウントのセキュリティで有効にしてください。