Skip to main content
Glama
Agent Web Adapter

Agent Web Adapter

by jimi-21
README.md
# Agent Web Adapter

[![CI](https://github.com/jimi-21/agent-web-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/jimi-21/agent-web-adapter/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Playwright](https://img.shields.io/badge/browser-Playwright-45ba4b.svg)](https://playwright.dev/)

**Local-first, verifiable and auditable browser execution for AI agents.**

把现有网页实时转换为智能体可观察、可操作、可验证的本地接口。支持页面操作、结构化数据采集、多网址批处理和业务流程回放,不需要网站改造,也不要求接入大模型。

## 核心架构

```text
AI Agent / CLI / Console
          │
          ▼
  ActionContract + Domain Policy
          │
          ▼
 WebMCP first ──► deterministic DOM / iframe / Shadow DOM
          │
          ▼
 Approval + Postconditions + ExecutionEvidence hash chain
```

**不是只做页面抓取**:每次执行都绑定页面状态和参数,支持高风险审批、业务后置条件、工作流自愈和可校验的执行证据。

## 启动

Windows 双击 `启动 Agent Web Adapter.bat`。首次启动会创建项目内的独立 Python 环境;已有 Edge 时直接使用独立 Edge 自动化实例,否则下载 Chromium。

- 控制台:http://127.0.0.1:8765(端口占用时自动递增)
- API 文档:控制台同端口的 `/api/docs`
- 内置演示:控制台同端口的 `/demo`

要求 Python 3.11+。也可以手动安装:

```bash
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.lock
.venv/Scripts/python -m pip install -e . --no-deps
.venv/Scripts/python -m playwright install chromium
.venv/Scripts/python -m agent_web_adapter serve --open
```

## 应用场景

### 网页操作与结果验证

输入网址创建会话,在“语义动作”中执行点击、填表、选择、勾选和滚动,再用可见文本或 URL 后置条件验证结果。适合后台录入、信息查询、表单处理和重复网页操作。

### 结构化数据采集

在“数据提取”中识别表格、商品卡片、文章列表和搜索结果,预览字段并导出 CSV 或 JSON。默认排除导航、面包屑、页脚和侧栏噪声,也可勾选“包含侧栏/导航”。适合商品研究、内容聚合、名单整理和网页数据归档。

### 多网址批量处理

点击“批量网址”,每行输入一个网址,最多 20 个。每个网址独立执行,失败项不会中断整个批次,成功项可单独导出。

### 业务流程录制与回放

1. 点击“录制流程”。
2. 正常执行页面动作和结果验证。
3. 停止录制,输入名称并保存。
4. 在“工作流”中回放。

动作使用语义标签而非屏幕坐标定位。API、MCP 和 CLI 支持 `{{variable}}` 变量,例如把搜索词保存为 `{{query}}`,运行时传入 `{"query":"键盘"}`。工作流保存在项目内的 `.agent-web-data/`;不要写入密码等秘密信息。

## MCP

将 `mcp-config.example.json` 中的服务配置加入 MCP 客户端。服务通过 stdio 提供 18 个工具:

- 页面:`open_page`、`list_pages`、`observe_page`、`navigate_page`、`scroll_page`、`close_page`
- 操作:`execute_action`、`verify_page`
- 数据:`extract_data`、`batch_extract_data`
- 流程:`save_workflow`、`list_workflows`、`run_workflow`、`delete_workflow`
- 审计:`list_execution_evidence`、`get_execution_evidence`、`verify_evidence_chain`
- 基准:`run_benchmark`

## CLI

```bash
agent-web snapshot https://example.com --output page-state.json
agent-web extract https://example.com --csv records.csv
agent-web batch-extract https://example.com/a https://example.com/b --output batch.json
agent-web workflow-list
agent-web workflow-run WORKFLOW_ID --variables '{"query":"键盘"}'
agent-web serve --visible-browser
agent-web mcp
agent-web evidence-list
agent-web evidence-show EVIDENCE_ID
agent-web evidence-verify
agent-web benchmark --base-url http://127.0.0.1:8765 --output benchmark.json
```

## v1.4 WebMCP 优先与企业流程基准库

- 通过 `document.modelContext.getTools()` 发现网站原生 WebMCP 工具,通过 `executeTool()` 调用。
- 原生工具与 DOM 控件使用统一动作契约;原生工具优先排列,`actionKind=auto` 可用于同名工具优先路由。
- `readOnlyHint` 和 `consequentialHint` 参与风险判断,高风险 WebMCP 工具仍需要确认。
- 工具返回值进入执行结果,证据记录后端、输出摘要和受限长度的输出内容。
- `/webmcp-demo` 提供原生 API 检测;不支持时明确使用同接口本地兼容 polyfill,不冒充原生支持。
- 自定义基准套件支持 `name/tasks`、业务域、负责人、关键级别和 `{{baseUrl}}` 环境变量。
- 企业报告按业务域聚合成功率;示例位于 `examples/procurement-suite.json`。
- API 基准请求支持 `baseUrl` 和 `suite`;MCP `run_benchmark` 支持 `base_url` 和 `suite`;CLI 支持 `--suite`。

## v1.3 复杂页面与质量基准

- 页面观察、动作执行、全文验证和数据提取支持同源/跨域 iframe 与开放 Shadow DOM。
- 动作契约保留 frame、shadow、控件角色和输入类型等语义上下文。
- 工作流记录风险等级与语义指纹;标签变化后可谨慎自愈,并记录原标签、实际标签和修复分数。
- 高风险或敏感控件变化后禁止自动修复执行;候选不唯一时停止。
- 数据提取支持筛选后的单条语义记录,过滤嵌套父容器和聚合父记录噪声。
- `/complex-demo` 提供 Shadow DOM、iframe、异步状态和增量列表演示;`/demo?variant=renamed` 提供自愈场景。
- 控制台“质量基准”、`POST /api/benchmark/run`、MCP `run_benchmark` 和 CLI `benchmark` 可运行同一组真实任务,输出成功率、耗时、提取结果和证据链状态。

## v1.2 可信执行

- 每个动作包含 `ActionContract`:页面状态摘要、参数模式、前置条件、预期影响、风险和契约哈希。
- 高风险审批同时绑定动作、页面状态和实际参数;参数改变后旧令牌失效,敏感参数只保留摘要和脱敏值。
- 填表、选择和勾选自动检查真实控件状态;执行接口支持 `postconditions` 业务后置条件。
- 每次已执行动作生成 `ExecutionEvidence`,记录审批、前后 URL/状态、参数摘要和验证结果。
- 本地证据通过前后哈希链接,可在控制台或 CLI 校验篡改;它是篡改检测机制,不是不可破解的签名系统。
- 创建会话支持 `allowedDomains` / `blockedDomains`,并作用于导航请求。
- 控制台新增“审计证据”视图;`/security-demo` 提供无真实交易的完整安全演示。

证据默认保存在项目内 `.agent-web-data/evidence/`。依赖版本固定在 `requirements.lock`。

## v1.1.1 反馈修复

- 修复 `workflow-list` 对模型列表的 JSON 序列化。
- 商品标题优先读取完整标题属性,跳过封面空链接。
- 可见文本验证改为检查浏览器完整正文,不受内容摘要截断影响。
- 默认过滤导航、侧栏和面包屑数据集,支持 `includeAuxiliary` 按需恢复。
- 将 radio 单选与 checkbox 多选区分,二者均可执行。
- 演示站结果计数进入可验证内容状态。

`observe` 支持 `maxContentLength`(200–50000);CLI 对应参数为 `--max-content-length`。提取接口和 CLI 支持 `includeAuxiliary` / `--include-auxiliary`。

## 安全与边界

服务默认只监听 `127.0.0.1`。页面文字只作为不可信数据处理;支持提示词注入告警、状态过期保护和高风险操作确认。密码等敏感输入值不会写入执行记录。高风险或敏感步骤不会由工作流自动回放,需要在控制台单独处理。

验证码、复杂 Canvas、游戏、特殊拖拽和无标签控件仍可能需要人工接管;不要用它绕过网站访问控制。