agentql

让 AI 精准「看见」网页：AgentQL 如何革新网页数据采集

场景切入：当爭虫遇上动态网页

想象一下这个日常困境——你写了一个爬虫去抓取某电商网站的商品价格，上线三天后网站改版了，CSS 类名全部变化，你的爬虫瞬间废休。传统方案是重新抓取 DOM 写 XPath/CSS Selector，但每次改版都要重写一遍，开发成本极高。

更鲇棘的是那些需要登录、无限滑动、Cookie 弹窗障挡的动态网页。普通爬虫对这些场景几乎无计乎之功，而 Selenium/Playwright 虽然能模仿浏览器行为，却依然依赖精确的 CSS 选择器来定位元素——本质上依然是「机械式」的操作，没有真正的「理解能力」。

AgentQL 正是为解决这些问题而生。它让 AI 来理解网页结构，用自然语言描述你想要的元素和数据，AI 自动找到匹配位置，还能随页面变化自我修复。

背景科普：Tinyfish AI 的创业贴注

AgentQL 由 Tinyfish AI 公司开发维护，团队将全部精力押注在「AI + 浏览器自动化」这一交叉领域。项目采用 MIT 开源协议，允许自由使用和商业化。从代码仓库看，团队使用 pre-commit 做代码质量把控，包含 TruffleHog 秈钥扫描和 Semgrep 静态分析，安全意识较强。Python SDK 和 JavaScript SDK 并行维护，且都有完整的 CI/CD 流水线（GitHub Actions pre-commit 流水线）。

核心机制：自然语言查询的原理

AgentQL 的查询语言基于 GraphQL-like 语法，允许开发者用结构化的方式描述期望提取的 DOM 结构和数据：

PRODUCT_DATA_QUERY = """
{
    price_currency
    products[] {
        name
        price(integer)
    }
}
"""

这一查询告诉 AgentQL：「找到价格货币符号、所有产品列表，提取名称和整数类型的价格」。AgentQL 内部将自然语言描述转化为 LLM Prompt，结合当前页面的 DOM 语义信息，定位最匹配的元素。

自愉能力是 AgentQL 的核心亮点。传统的 CSS Selector 在页面改版后立即失效，而 AgentQL 的查询基于「语义」而非「位置」。当页面结构变化时，相同的自然语言查询依然能找到新位置对应的元素，大幅降低维护成本。

Playwright 集成是另一关键设计。AgentQL 不重复造轮子，而是作为 Playwright 的扩展层工作：

import agentql
from agentql.ext.playwright.sync_api import Page
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = agentql.wrap(browser.new_page())  # 一行代码接入 AgentQL

agentql.wrap() 将标准 Playwright Page 对象包装为增强版，赋予其 query_elements() 和 query_data() 方法。这意味着任何现有的 Playwright 脚本都可以零成本迁移到 AgentQL，同时保留 Playwright 的全部底层能力（cookies、截图、键盘模拟等）。

技术架构：双 SDK + REST API + MCP Server

AgentQL 的技术架构分为三层：

Python SDK（主语言）：基于 Playwright Python 封装，提供同步 API，适合脚本化和定时任务。通过 pip install agentql 一行安装，配合 Playwright 本身的跨浏览器支持（Chromium/Firefox/WebKit），覆盖主流场景。examples/ 目录包含 20+ 完整示例，覆盖电商数据采集、新闻聚合、Google Maps 爬取、社交评论等常见场景，且每个示例都有 Google Colab 在线运行版本，降低入门门槛。

JavaScript SDK：与 Python SDK 功能对等，面向前端工程师和 Node.js 环境。同样集成 Playwright，提供类似 API 设计。

REST API：无需安装 SDK，通过 HTTP 请求调用 AgentQL 查询能力，适合无服务器环境和轻量级集成。

MCP Server：Model Context Protocol 服务器，支持与主流 Agent 框架（Langchain、AutoGPT 等）集成，将网页交互能力注入 AI Agent 的工具集中。

Chrome 调试扩展是 AgentQL 的差异化亮点。开发者安装浏览器扩展后，可以在任意网页上实时调试 AgentQL 查询——输入自然语言查询，立即高亮显示匹配的元素，无需写代码即可快速迭代查询语句，找到最优方案后再导出为 Python/JavaScript 脚本。

代码质量分析

从仓库结构来看，AgentQL 展现了较高的工程化水准：

• 模块化设计：Python 和 JS SDK 完全独立维护，各自目录下的配置文件（pylintrc/.eslintrc）反映了两套不同的代码规范体系
• 测试覆盖：examples/ 目录下每个脚本都有配套说明，README 包含从安装到运行的全链路指引
• 安全实践：TruffleHog 扫描秈钥泄露，osv-scanner 检查依贝漏洞，pre-commit 自动化代码检查
• 文档质量：官方网站 docs.agentql.com 提供完整 API 参考、查询语言规范和快速入门指南，远超一般开源项目的文档水平
• 授权协议：MIT 慷松许可，商业使用无限制

主要局限在于：缺乏 Docker 部署支持，需要手动安装 Playwright 浏览器依赖（playwright install），在头部服务器环境下首次配置有一定复杂度。此外，由于依赖 LLM 做查询理解，每次查询的网络延迟会比传统爬虫高，不适合超大批量场景。

行业意义：AI 时代的数据采集新范式

传统爬虫行业正在经历从「规则驱动」到「AI 驱动」的范式转变。AgentQL 代表了一种新兴方向：让 AI 理解网页语义，而非依赖人工编写的 DOM 选择器。

这一方向的竞争产品包括 Firecrawl（AI 驱动网页爬取）、Crawlab（分布式爬虫管理）和 Browserbase（浏览器自动化云平台）。AgentQL 的差异化在于：查询语言的表达力（GraphQL-like 结构化查询）、Playwright 的深度集成，以及 Chrome 调试扩展带来的极佳开发者体验。

随着 LLM API 成本持续下降和推理速度提升，「AI 原生」的网页自动化工具将正步代替传统的规则爬虫，成为 AI Agent 获取实时网络数据的主流方式。AgentQL 正是这一趋势的先行者之一。

数据来源：GitHub（tinyfish-io/agentql），截至 2026 年6月