项目定位与核心特性

AgentQL 是一个面向 Web 自动化的查询语言与工具集，让开发者能够使用结构化查询从网页中定位元素并提取数据，而无需依赖脆弱的 CSS 选择器或 XPath。仓库主文档说明其目标是：「用户可以定义结构化数据输出，并在查询中应用 transform，AgentQL 的自然语言选择器能够根据网页内容直观地查找元素，并能在结构相似的不同网站之间复用」。 资料来源：README.md

核心特性包括：

• 与 Playwright 深度集成：Python 与 JavaScript SDK 均通过 Playwright 扩展提供，由 agentql.wrap(...) 包装 Playwright 的 Page 对象以注入查询能力。 资料来源：README.md examples/python/first_steps/main.py
• 跨站点兼容：同一查询可在结构相似的不同网站上复用。 资料来源：README.md
• 结构化输出：返回数据的形状由查询本身定义，列表使用 [] 表示。 资料来源：examples/python/list_query_usage/main.py
• 自然语言选择器：通过 page.get_by_prompt("Button to display Qwilfish page") 等方式定位元素。 资料来源：examples/python/first_steps/main.py
• 抗 UI 变更：随页面结构变化自适应。 资料来源：README.md

SDK 与工具生态

仓库提供三类主要使用方式，覆盖从 SDK 到直接 API 调用的完整路径：Python SDK、JavaScript SDK 与 REST API，并提供 LangChain、Zapier 以及 MCP Server 等集成。 资料来源：README.md

示例脚本在 examples/examples.md 中按 Python 与 JavaScript 两栏分类组织，覆盖电商列表、新闻聚合、Google Maps 抓取、分页采集、滚动加载等典型场景。 资料来源：examples/examples.md

快速入门：典型查询流程

下图展示了使用 AgentQL 进行查询与数据提取的端到端流程：

flowchart LR
    A[定义 AgentQL 查询字符串] --> B[启动 Playwright 浏览器]
    B --> C["agentql.wrap 创建 Page"]
    C --> D[page.goto 打开目标 URL]
    D --> E["query_elements / query_data / get_by_prompt"]
    E --> F{返回类型}
    F -->|元素句柄| G[Playwright 操作元素]
    F -->|结构化数据| H[写入 CSV 或业务逻辑]

下面以 Python 为例给出最小可用代码片段，源自 first_steps 与 list_query_usage 示例：

import agentql
from playwright.sync_api import sync_playwright

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

with sync_playwright() as p, p.chromium.launch(headless=False) as browser:
    page = agentql.wrap(browser.new_page())
    page.goto("https://scrapeme.live/shop")
    response = page.query_elements(SEARCH_BOX_QUERY)
    response.search_product_box.type("fish", delay=200)
    page.keyboard.press("Enter")
    data = page.query_data(PRODUCT_DATA_QUERY)

JavaScript 侧使用模式相同，运行命令为 node main.js，并依赖 AgentQL Debugger Chrome 扩展来调试查询。 资料来源：examples/js/list-query-usage/README.md examples/js/maps_scraper/README.md

常见使用模式与示例索引

仓库提供了覆盖多种典型网页交互模式的示例脚本，便于开发者按需参考：

• 列表查询：使用 products[] { ... } 提取重复项并写入 CSV，参见 list_query_usage 示例。 资料来源：examples/python/list_query_usage/main.py
• 分页采集：跨多个分页页面重复执行同一查询，分别支持 HackerNews 与电商列表场景。 资料来源：examples/python/collect_paginated_news_headlines/README.md examples/python/collect_paginated_ecommerce_listing_data/README.md
• 多源并发抓取：在同一浏览器上下文中通过 asyncio.gather 并发抓取多个 URL，并将其结果合并到 CSV。 资料来源：examples/python/news-aggregator/main.py
• 无限滚动：使用 key_press_end_scroll 或 mouse_wheel_scroll 加载后续内容，文档提示两种方式在不同站点行为差异较大。 资料来源：examples/python/infinite_scroll/README.md
• 情感分析：与 OpenAI GPT 模型结合对 YouTube 评论做情感分析。 资料来源：examples/js/news-aggregator/README.md

社区反馈与已知限制

社区用户对 AgentQL 与浏览器自动化平台的集成持续提出改进建议。Issue #128 讨论了在 Cloudflare Workers 边缘环境中运行 AgentQL JavaScript SDK 的兼容性挑战。Issue #121 反馈了查询有时会解析到「无用的 span 元素」而非期望目标的情况。Issue #64 指出文档示例页面曾存在失效链接，已修正指向 examples/run_script_online_in_google_colab。这些讨论提示用户：在边缘运行时或 DOM 结构不稳定的站点上使用 AgentQL 时，应保留对查询结果的校验与回退逻辑，并优先使用 Chrome 调试器验证查询表达式。

See Also

• AgentQL 官方文档：https://docs.agentql.com
• AgentQL 查询语言入门：https://docs.agentql.com/agentql-query/query-intro
• Python SDK 安装：https://docs.agentql.com/python-sdk/installation
• JavaScript SDK 安装：https://docs.agentql.com/javascript-sdk/installation
• Starlog 项目深度文章：https://starlog.is/articles/automation/tinyfish-io-agentql

一、定位与总体能力

AgentQL 是由 tinyfish-io 维护的开源项目，目标是为浏览器自动化和数据采集场景提供一种「结构化查询 + 自然语言选择器」相结合的 Web 数据提取范式。根据根目录 README.md 的描述，AgentQL 的核心特性包括：

• 与 Playwright 深度集成的 Python 与 JavaScript SDK；
• 跨站兼容（同一份查询可在多个结构相似的网站上复用）；
• 由查询形状直接驱动结构化输出；
• 自然语言选择器（self-healing）能随 UI 变更自动恢复；
• 支持公开页、私有页以及登录后的页面（"Works on any page, public or private, any site, any URL, even behind authentication"）。

这一组合让 AgentQL 区别于传统的 CSS/XPath 抓取方式：它把「在哪里取数据」与「取出的数据长什么样」合并到同一条 AgentQL 查询中。

二、SDK 安装与初始化

AgentQL 官方同时提供 Python 与 JavaScript 两套 SDK，根目录的 README.md 列出了安装入口：

JavaScript 侧的实际依赖关系在 examples/js/package.json 中可看到：agentql: "latest"、playwright: "^1.48.2"，并额外引入 playwright-dompath 与 openai 用于 DOM 路径调试和后续的 LLM 分析。overrides 字段强制锁定 axios、flatted、follow-redirects、lodash、minimatch 等下游安全版本。

Python 与 JavaScript 在初始化时都遵循「先启动 Playwright，再用 AgentQL 包装 Page」的模式。Python 示例 examples/python/first_steps/main.py 的写法如下：

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

with sync_playwright() as playwright, playwright.chromium.launch(headless=False) as browser:
    page = agentql.wrap(browser.new_page())
    page.goto(URL)

JavaScript 示例 examples/js/get-by-prompt/main.js 中则是先用 configure({ apiKey }) 写入 API 密钥（process.env.AGENTQL_API_KEY），再通过 await wrap(await browser.newPage()) 拿到具备 AgentQL 能力的页面对象。

三、两类核心 API：`query_data` 与 `get_by_prompt`

AgentQL 的 SDK 主要暴露两种能力——数据提取与元素定位，二者在示例中互为补充。

3.1 数据查询 `query_data`

通过 query_data 提交一条 AgentQL 查询，返回与查询结构对应的 Python/JS 对象。Python 示例 examples/python/list_query_usage/main.py 中典型的查询形态为：

{
    products[] {
        name
        price(integer)
    }
}

方括号 [] 表示数组，(integer) 等类型注解会把抓取结果强制转换为指定类型。JavaScript 示例 examples/js/list-query-usage/main.js 复用相同语法，只需将字段写成 JS 风格。

3.2 元素定位 `get_by_prompt`

get_by_prompt 接收一段自然语言描述，返回页面上与之最匹配的 ElementHandle。Python 端用法见 examples/python/get_by_prompt/main.py；JavaScript 端对应实现见 examples/js/get-by-prompt/main.js：

const signUpBtn = await page.getByPrompt('Sign up button');
if (signUpBtn) {
    await signUpBtn.click();
}

返回的元素为 null 时表示未找到，调用方需自行做空值保护。

四、典型工作流

下图展示从「准备查询」到「在浏览器中执行」再到「消费结果」的一次完整调用流程：

sequenceDiagram
    participant Dev as 开发者
    participant Page as agentql-wrapped Page
    participant Engine as AgentQL 服务
    participant Browser as Chromium

    Dev->>Page: page.goto(url)
    Page->>Browser: 渲染目标网页
    Dev->>Page: page.query_data(QUERY)
    Page->>Engine: 上传 DOM + 查询
    Engine-->>Page: 返回结构化 JSON
    Dev->>Page: page.get_by_prompt(prompt)
    Page->>Engine: 上传 DOM + 自然语言
    Engine-->>Page: 返回 ElementHandle
    Dev->>Browser: element.click() / fill()

上图的步骤直接对应了 examples/python/first_steps/main.py 中的 _extract_product_data（先 query_data 取商品列表）和 _add_qwilfish_to_cart（先 get_by_prompt 拿到「Add to cart」按钮再点击）的执行顺序。

五、典型使用场景

仓库的 examples/ 目录已经按业务场景对 SDK 进行了分组，可在 examples/examples.md 找到入口索引。常见模式包括：

• 分页采集：examples/python/collect_paginated_news_headlines/README.md 演示了在 HackerNews 多页之间循环 query_data 的写法。
• 无限滚动：examples/python/infinite_scroll/README.md 提醒开发者「按 End 键」并非万能，可改用 mouse_wheel_scroll，并可替换 page.goto 以适配自建站点。
• 与 LLM 组合：examples/python/perform_sentiment_analysis/main.py 展示了将 query_data 拿到的评论交给 OpenAI gpt-3.5-turbo 做情感分析的完整链路，体现 AgentQL 作为「数据采集前置层」的定位。

六、常见问题与社区反馈

• Edge 环境兼容性：社区 issue #128 报告 AgentQL JS SDK 在 Cloudflare Browser Rendering 中遇到 Node.js 兼容性问题，原因是 SDK 依赖的部分原生模块与 Workerd 边缘运行时存在差异，部署到 Workers 时需要额外适配。
• 选择器误命中：社区 issue #121 反馈在某些企业招聘站上 query_data 会落到无关的 <span> 上。这是 AgentQL 自然语言选择器的常见陷阱，建议先用 AgentQL Debugger Chrome 扩展 在浏览器内复现，再调整查询措辞。
• 文档链接失效：issue #64 指出官方文档 Examples > Collab 链接指向了错误的目录，正确路径应为 examples/run_script_online_in_google_colab，在使用 Colab 入口前需注意核对。

七、See Also

• 官方文档：docs.agentql.com
• Python SDK 指南：docs.agentql.com/python-sdk/installation
• JavaScript SDK 指南：docs.agentql.com/javascript-sdk/installation
• AgentQL 查询语言：docs.agentql.com/agentql-query/query-intro
• REST API 参考：docs.agentql.com/rest-api/api-reference
• 集成入口（MCP、LangChain、Zapier）：docs.agentql.com/integrations

概述

AgentQL 是一个面向 Web 自动化的查询语言与 SDK 套件，核心价值在于用结构化查询替代脆弱的 CSS/XPath 选择器，使脚本能够"自愈"地适应 UI 变化。本页聚焦仓库 examples/ 目录中收录的典型脚本场景，帮助开发者快速识别与自己需求最接近的参考实现。

根据 README.md 的描述，AgentQL 提供 Python 与 JavaScript 两套 SDK、与 Playwright 的无缝集成、自然语言选择器以及跨站点复用查询的能力。社区中也已有第三方（如 Starlog 在 issue #148 中报道的深度文章）对其自动化能力进行系统性介绍。

用例分类

examples/ 目录按语言拆分为 python/ 与 js/ 两个子目录，并通过 examples/examples.md 提供总入口。综合各 README 描述，可归纳为以下几类典型场景。

数据采集与跨页抓取

• 分页新闻头条抓取：通过指定查询与翻页数，跨多页抓取 HackerNews 列表。Python 与 JavaScript 版本入口分别位于 examples/python/collect_paginated_news_headlines/README.md 与 examples/js/collect-paginated-news-headlines/README.md。
• 分页电商数据采集：在多页商品列表中收集数据。参考 examples/python/collect_paginated_ecommerce_listing_data/README.md 与 examples/js/collect-paginated-ecommerce-data/README.md。
• Google Maps 抓取并导出 CSV：见 examples/js/maps_scraper/README.md。

跨站点内容聚合与并发抓取

examples/python/news-aggregator/main.py 展示了在同一浏览器上下文中并发打开多个标签页抓取多家媒体头条，并写入 CSV 的模式。其核心是 async with async_playwright() ... await asyncio.gather(...)，借助共享 BrowserContext 实现高并发抓取。该用例的运行说明见 examples/python/news-aggregator/README.md，JavaScript 对应版本为 examples/js/news-aggregator/README.md。

与 LLM 集成的分析流水线

examples/python/perform_sentiment_analysis/README.md 演示了如何将 AgentQL 抓取的 YouTube 评论接入 OpenAI GPT-3.5 进行情感分析，需要额外安装 openai 并设置 OPENAI_API_KEY 环境变量。

列表型与交互型查询

• 列表查询：通过 products[] 等数组语法批量返回结构化数据，见 examples/python/list_query_usage/README.md 与 examples/js/list-query-usage/README.md。
• 滚动加载：针对无限滚动页面，examples/python/infinite_scroll/README.md 提示开发者可使用 key_press_end_scroll 或 mouse_wheel_scroll 等多种方式触发加载，并警惕 End 键在视频页等场景被重新映射的问题。
• 搜索 + 元素交互：examples/python/first_steps/main.py 演示了 query_elements 配合 Playwright 原生 API（如 .type()、keyboard.press("Enter")）完成搜索、提交、并通过 get_by_prompt("Button to display Qwilfish page") 使用自然语言提示定位按钮。

典型工作流

下表汇总了主要示例所采用的核心 API 模式，便于横向对照。

已知问题与使用注意

社区中 issue #121 报告了"查询元素被解析为无用 span、未命中预期元素"的情况，说明自然语言与 AgentQL 查询在面对非常规 DOM 结构（如招聘网站嵌套表单）时仍可能出现定位偏差。开发者应优先安装并使用 AgentQL Debugger Chrome 扩展（各示例 README 中均反复推荐）来验证查询与页面元素的匹配关系。

此外，issue #128 中开发者尝试将 JavaScript SDK 跑在 Cloudflare Workers 的 Browser Rendering 环境中时遇到 Node.js 兼容性问题，表明当前 SDK 主要面向标准 Node.js / Python 环境，边缘计算场景可能需要额外适配。issue #64 提醒文档链接曾指向错误的目录，实际 Colab 示例位于 examples/run_script_online_in_google_colab 而非 application_examples/google_Colaboratory。

See Also

• README.md — 项目总览与功能列表
• examples/examples.md — 示例目录入口
• AgentQL 官方文档：https://docs.agentql.com
• AgentQL 查询语言入门：https://docs.agentql.com/agentql-query/query-intro
• 社区深度文章：https://starlog.is/articles/automation/tinyfish-io-agentql

1. 部署形态与运行配置

AgentQL 通过 Python 与 JavaScript SDK 暴露能力，二者均围绕 Playwright 构建，便于在多种浏览器自动化栈中复用。README.md 中明确将 Playwright 集成作为核心特性，并指出用户可以在公开或受身份保护的页面上运行查询。

Python SDK 默认基于同步 Playwright 入口，开发者通过 agentql.wrap 包装原生 Page 对象，从而在现有自动化代码中插入查询语句：

# examples/python/first_steps/main.py
import agentql
from playwright.sync_api import sync_playwright

with sync_playwright() as playwright, playwright.chromium.launch(headless=False) as browser:
    page = agentql.wrap(browser.new_page())
    page.goto(URL)

资料来源：examples/python/first_steps/main.py

对于需要并发抓取的聚合场景，示例展示了使用 async_playwright + asyncio.gather 在同一浏览器上下文内多标签页并行采集的方法，从而避免反复冷启动带来的延迟。examples/python/news-aggregator/main.py 中的 fetch_data 与 main 协程演示了这一模式。

JavaScript SDK 则通过 CommonJS 风格的 require('agentql') 引入，调用前需先通过 configure({ apiKey }) 完成鉴权配置：

// examples/js/get-by-prompt/main.js
const { wrap, configure } = require('agentql');
configure({ apiKey: process.env.AGENTQL_API_KEY });
const page = await wrap(await browser.newPage());

资料来源：examples/js/get-by-prompt/main.js

2. 与第三方系统的集成模式

2.1 大语言模型集成

perform_sentiment_analysis 示例演示了 AgentQL 与 OpenAI GPT-3.5 的两阶段流水线：先用 page.query_data(QUERY) 抽取结构化评论，再将文本交给 LLM 做摘要与情感分析。运行前需设置 OPENAI_API_KEY 环境变量。资料来源：examples/python/perform_sentiment_analysis/README.md

2.2 无限滚动与动态加载

针对现代站点的懒加载场景，仓库提供了 infinite_scroll 示例。其文档明确指出：按 End 键到底部并不总是可靠的，应当根据页面结构选择 mouse_wheel_scroll 或键盘模拟等不同策略，必要时切换到自定义目标站点做对比调试。资料来源：examples/python/infinite_scroll/README.md

2.3 依赖与包管理

JavaScript 示例统一在 examples/js/package.json 中声明 agentql、playwright、playwright-dompath、openai 等依赖，并通过 overrides 字段锁定 axios、lodash、minimatch 等传递依赖的安全版本，体现出对供应链风险的主动管控。scripts 段则集成 ESLint 与 Prettier 工具链，便于跨示例统一代码风格。

3. 社区实践与已知限制

下列议题来自社区讨论，反映了 AgentQL 在真实场景下的痛点与改进方向：

资料来源：README.md、examples/examples.md

4. 端到端工作流

flowchart LR
    A[配置 API Key] --> B[Playwright 启动浏览器]
    B --> C[agentql.wrap 包装 Page]
    C --> D{选择交互方式}
    D -->|结构化数据| E[page.query_data]
    D -->|定位元素| F[page.get_by_prompt]
    D -->|选择器| G[AgentQL Query]
    E --> H[业务后处理]
    F --> H
    G --> H
    H --> I[导出 / 接入 LLM]

上图概括了从鉴权到结果消费的标准路径：configure 与 wrap 是统一入口；查询侧可在结构化抽取、自然语言提示与显式查询语法之间切换；后处理环节既可以保存为 CSV（参考 examples/python/news-aggregator/main.py），也可以送入 OpenAI 等模型做语义分析。

5. 上手建议

• 优先复用示例脚手架：examples/examples.md 将 Python 与 JavaScript 示例分目录组织，先复制最接近目标场景的脚手架再改造，可显著降低试错成本。
• 使用官方调试器：README.md 推荐安装 AgentQL Debugger Chrome 扩展以交互式打磨查询语法，这与社区议题 #121 中反馈的选择器误命中问题直接相关。
• 关注运行时约束：在边缘或受限 Node 环境中部署前，应先参考议题 #128 评估 Playwright 与 SDK 的兼容边界。

See Also

• Python SDK 安装与快速上手
• JavaScript SDK 安装与快速上手
• REST API 参考
• AgentQL 查询语言介绍

Pitfall Log / 踩坑日志

项目：tinyfish-io/agentql

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Dependency Dashboard。

1. 安装坑 · 来源证据：Dependency Dashboard

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinyfish-io/agentql/issues/114 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Starlog published a deep-dive on tinyfish-io/agentql

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Starlog published a deep-dive on tinyfish-io/agentql
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/tinyfish-io/agentql/issues/148 | 来源类型 github_issue 暴露的待验证使用条件。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/tinyfish-io/agentql | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/tinyfish-io/agentql | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/tinyfish-io/agentql | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/tinyfish-io/agentql | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/tinyfish-io/agentql | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/tinyfish-io/agentql | release_recency=unknown