Skip to main content
Glama
Agent Web Adapter

Agent Web Adapter

by jimi-21

Agent Web Adapter

CI Python 3.11+ License: MIT Playwright

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

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

核心架构

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

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

Related MCP server: project-tendril

启动

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

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

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

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、游戏、特殊拖拽和无标签控件仍可能需要人工接管;不要用它绕过网站访问控制。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to operate an isolated local Chromium browser through MCP, with semantic snapshots, ref-based actions, search, research, crawling, and CDP access.
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to control a persistent local browser with live tabs, navigation, interaction, inspection, and state management through MCP.
      6
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to drive isolated local browser profiles, each with its own persistent cookies, login state, fingerprint, and proxy, so authenticated workflows carry across sessions. Exposes tools for navigation, clicking, typing, extraction, screenshots, JS evaluation, tab and cookie management, and raw CDP commands to any MCP client.
      MIT