---
name: agentbrowser
description: Control a real, visible AgentBrowser window through its authenticated local Agent Protocol v2 API. Use for website operation, authenticated workflows, form filling, downloads, QA, and human handoff.
license: Provided by AgentBrowser (https://agentbrowser.top).
---

# AgentBrowser Skill

Control the user-visible Windows browser through AgentBrowser. The user can watch every action and take over for login, CAPTCHA, OTP, payment, or sensitive approval.

## Connection

- Base URL: `${AGENTBROWSER_BASE_URL}`; default `http://127.0.0.1:10001`.
- Read the current local token from `api_token.txt` beside AgentBrowser.
- Send `X-AgentBrowser-Token: <token>` on every request.
- Never send this local token to a website or remote person.

Begin with `GET /agent/v2/capabilities`. A `401` means the token is missing or stale; reread the token file instead of retrying blindly.

## Required workflow

1. Start a session:
   `POST /agent/v2/sessions/start` with `{ "name":"task name", "description":"user goal" }`.
2. Authorize it:
   `POST /agent/v2/sessions/{sessionId}/authorize` with `{ "mode":"control", "durationMinutes":30, "reason":"user-requested browser task" }`.
3. List tabs with `GET /agent/v2/tabs`, or create one:
   `POST /agent/v2/tabs/new` with `{ "sessionId", "url" }`.
4. Inspect before acting:
   `POST /agent/v2/page/snapshot` with `{ "sessionId", "tabId", "includeText":true, "includeElements":true }`.
5. Perform one atomic action:
   `POST /agent/v2/action/act` with `{ "sessionId", "tabId", "intent", "target", "value"?, "key"? }`.
6. Verify with a fresh snapshot, `POST /agent/v2/assert`, or the appropriate `POST /agent/v2/page/wait-*` endpoint.

Supported `intent` values are `click`, `fill`, `focus`, `hover`, `key`, and `scroll`. Prefer a fresh `target.elementId` returned by snapshot. Do not reuse an element ID after navigation or a major DOM change.

Example fill:

```json
{
  "sessionId": "ses_...",
  "tabId": "tab_...",
  "intent": "fill",
  "target": { "elementId": "el_..." },
  "value": "SO-10231"
}
```

Example Enter key:

```json
{
  "sessionId": "ses_...",
  "tabId": "tab_...",
  "intent": "key",
  "target": { "elementId": "el_..." },
  "key": "Enter"
}
```

## Human handoff

For login, CAPTCHA, OTP, payment, or sensitive approval:

`POST /agent/v2/handoff/request` with `{ "sessionId", "reason":"CAPTCHA requires user input" }`.

Stop acting while handoff is active. The AgentBrowser client displays an explicit takeover banner. After the user finishes, they can return control in the client, or you may call:

`POST /agent/v2/handoff/complete` with `{ "sessionId", "reason":"user completed the sensitive step" }`.

Then take a fresh snapshot before continuing.

## Safety rules

1. Operate only within the user-authorized task and websites.
2. Announce consequential actions before performing them.
3. Never invent credentials or bypass anti-bot, CAPTCHA, OTP, or payment confirmation.
4. Use one atomic action per call and verify the result.
5. On failure, snapshot again and adapt; do not repeat stale selectors or element IDs.
6. Use the session timeline and artifacts for audit evidence instead of free-form logs.