# AgentBrowser HTTP 专用指南

仅用于已明确配置的本机 HTTP 适配器；MCP 客户端使用对应 Skill。

## HTTP 专用接入

本节只用于用户已配置的本机 HTTP 适配器。默认地址 `http://127.0.0.1:10001`；适配器从运行目录的 `api_token.txt` 取得当前 Token，通过 `X-AgentBrowser-Token` 请求头发送给本机 API。不得输出 Token、发给网站、放入 URL 或要求用户贴进聊天。重启后 Token 会更新。

只支持 `/agent/v2/*`；V1 和历史 `/api/*` 路由不提供兼容。先 `GET /agent/v2/capabilities`，再创建当前任务的独立会话：

`POST /agent/v2/sessions/start`

```json
{
  "name": "检查帮助页的接入说明",
  "description": "检查当前帮助页并返回已核实的接入步骤",
  "metadata": {
    "agentName": "Codex",
    "projectName": "AgentBrowser",
    "taskTitle": "检查帮助页的接入说明",
    "clientName": "本机 HTTP 适配器"
  }
}
```

HTTP 会话接口为兼容旧程序不强制校验这些身份字段，但新适配器应主动提供，确保窗口可辨识。name 与 metadata.taskTitle 使用同一具体任务名称。agentName 最多 60 字符，projectName 最多 100，taskTitle 最多 120；无项目填“无项目”，未知 AI 填“未知 AI”。可选 metadata.conversationLabel、metadata.clientInstanceId 各最多 120 字符，仅在已知时提供，不含控制字符、凭据或敏感页面内容；自报信息不代表可信系统身份。

2.2.8 起可在创建会话的请求顶层指定 `environmentId`（`[a-z][a-z0-9-]{0,63}`）。省略或 `default` 沿用原登录环境；不同 ID 使用独立持久登录，同 ID 共享该环境登录。先检查 capabilities.browser.isolatedLoginEnvironments 并核对创建回执；原始 HTTP 不支持命名环境时返回 `ENVIRONMENT_UNSUPPORTED`，MCP 无法确认绑定时返回 `ENVIRONMENT_BINDING_UNAVAILABLE`。不要改用 default 绕过账号隔离。结束任务不会清除环境登录；环境名不是实际账号身份。

保存返回的 sessionId、windowId 和 tabId，不借用其他任务的标签页或前台窗口。以下请求均传当前 sessionId：

1. `POST /agent/v2/page/navigate`：传 sessionId、tabId、url。
2. `POST /agent/v2/page/wait-load-state`：等待加载完成。
3. `POST /agent/v2/page/observe`：取得当前页面及元素信息；跨域 iframe 操作保留返回的 frameId。
4. `POST /agent/v2/action/act`：传目标、动作和必要值，每次执行一个有意义的操作。
5. 再次观察，并用 `POST /agent/v2/assert` 验证实际结果。
6. 仅在任务真正完成后 `POST /agent/v2/sessions/{sessionId}/complete`。

页面列表使用 `GET /agent/v2/tabs?sessionId=...`，任务状态使用 `GET /agent/v2/sessions?sessionId=...`。普通页面操作按当前自动化规则执行，不要求每次先申请临时 control/full 授权；旧 authorize 接口不等于用户对任意业务的授权。

### 有目的的截图与本地 OCR（2.2.4）

截图前明确目的、希望读取的内容及其位置。DOM 可读取的内容优先 observe/text；需要视觉证据时 screenshot；图片/Canvas 内文字使用 recognize。先传 purpose、target 和 prepareOnly=true 查看目标可见性、needsScroll、mayNeedLargerViewport、视口/窗口和输出能力；这一步不截图、不滚动、不最大化。仅在需要时显式传 scrollIntoView=true（必须有 target）或 maximize=true；默认保持页面和窗口，目标未完整进入视口不能冒充已截到。

`POST /agent/v2/page/recognize` 的 operation=status 查询实际本地引擎和语言，operation=ocr 按 purpose 读取。可选同会话 sourceArtifactId 读取原截图，不能与实时采集参数混用；可选 includeImage 返回同一图像。字块坐标为图片像素，不能当作 DOM 元素；重新观察后继续原 action/assert，并核对关键编号。没有自动云端回退、引擎下载或系统语言安装。

MCP 对应 browser_screenshot / browser_recognize，同名参数按 tools/list；图像使用原生 image 内容块，HTTP 图像仍为 Base64。取消、零留存、产物与语言限制详见 [在线接入帮助](https://agentbrowser.top/guides)。

2.2.5 候选增加读取不足反馈：本地 OCR 失败、语言不可用或无文字时，检查 status=external_ai_required 和 recognitionSucceeded=false，直接用自身视觉能力读取自动附带的同一原图；ok=true 不等于识别成功。图表含义直接截图交由调用方 AI 判断，不接入额外模型。无法看图则明确反馈能力不足；取消、遮罩失败、跨任务等错误不附备用图片，不得绕过保护。

## 人工接管与授权

读取会话响应的 `automation.requiredHandoffTypes`，默认空选。收到 `CONFIGURED_HANDOFF_REQUIRED` 时按用户设置交接；AI 能力不足时也可主动请求。MCP 使用 `browser_request_handoff`；HTTP 使用 `POST /agent/v2/handoff/request`，提交当前 sessionId、具体 reason 和可选 type。原因说明用户要做什么，不含密码或验证码。

接管暂停期间仅观察和查询状态；用户在对应窗口点击“完成并交还 AI”后再继续，不自行宣称人工步骤完成或代为解除暂停。用户主动提供的凭据仅用于已授权的本次登录，不复述、记录或保存。已授权的普通步骤不反复要求确认；目标、收件人、金额、权限或不可逆后果超出授权时先确认。配置空选不代表可以越过用户授权或网站安全机制。

## 错误、升级与验收

- `LICENSE_REQUIRED`：当前操作缺少有效试用或订阅，引导用户在客户端账户/激活窗口或官网账户页激活、刷新或续费。首次认证激活提供一次性 30 天试用，有效试用与付费功能相同，不提供永久免费版；不要伪造授权或重启试用。恢复账户、查询历史和安全结束任务以服务端允许范围为准。
- 旧宿主的 `LICENSE_LIMIT_REACHED`：读取 error.details.occupyingSessions，报告占用任务的名称、source 自报来源、状态、lastActivityAtUtc 和窗口关联。旧任务字段可能为空，旧版可能没有列表，不猜归属。联系所属客户端结束自有任务或等待；只有用户明确允许才结束其他任务，不重复创建或修改许可。没有自己的新会话时，不向占用者发送接管请求。窗口存在或长时间无操作都不证明业务已经完成。当前有效订阅不设版本并发额度。
- `INVALID_WEB_ACCESS_SCENARIO`：按错误补齐或修正 MCP 启动字段后重试，不继续隐式操作旧任务。
- `SESSION_REQUIRED`：显式指定正确任务；`SESSION_INACTIVE`：该任务已结束，不将动作转给其他任务。
- HTTP 200 仍需检查响应 ok/error；成功调用不是业务完成。
- 浏览器升级后重连 MCP 才会加载新工具协议；已复制的 Skill 必须另行更新。旧会话兼容不代表新启动可省略身份。
- 页面结果、导出文件或实际记录验证后才报告完成；未通过时记录明确缺口。

完整端点、响应及兼容范围见 [在线接入帮助](https://agentbrowser.top/guides)。
