AgentQL

AgentQL是什么

AgentQL是TinyFish推出的AI网页查询语言与开发工具套件，用自然语言描述需要的数据或页面元素。它适合构建网页数据提取、浏览器自动化、测试流程和能够使用网站的AI Agent。

与依赖固定CSS或XPath选择器的脚本不同，AgentQL根据元素的含义、上下文和查询结构进行定位。页面布局变化时，语义查询通常比位置选择器更容易复用，但仍需通过测试和异常处理保证生产可靠性。

核心功能

• 使用自然语言字段名称定位网页元素和数据
• 按照查询结构返回嵌套对象或列表
• 在Python和JavaScript中结合Playwright自动操作网页
• 通过REST API从任意编程语言发起数据查询
• 使用远程浏览器运行需要会话和交互的任务
• 从网页、PDF和图像中提取结构化内容
• 利用Debugger扩展在真实网页上调试查询
• 通过Playground试验提示词并导出脚本
• 连接LangChain、Zapier和MCP等自动化生态

AgentQL查询语言

AgentQL查询以字段结构定义需要找什么以及结果长什么样，字段名称本身可以表达语义。列表、嵌套对象和补充说明可组合使用，使输出结构在执行前就较为明确。

语义定位的工作方式

• 理解字段名称在当前页面中的业务含义
• 结合周围文字、标签和页面层级判断目标
• 不要求开发者提前知道具体DOM路径
• 相似网站可尝试复用相同查询结构
• 页面重排后仍可能找到语义相同的元素
• 歧义较大时可加入更具体的自然语言说明

网页数据提取

开发者可以用SDK或REST API提取公开网页及获授权页面中的结构化数据。输出结构由查询定义，能够减少后续清洗工作，但空值、重复项和页面状态仍需在业务代码中处理。

• 商品名称、价格、库存和评价采集
• 新闻标题、日期、作者和正文整理
• 搜索结果、目录和分页列表提取
• 登录后后台数据的授权采集
• 动态加载与无限滚动页面处理
• 跨相似站点统一字段输出

浏览器自动化

AgentQL的Python和JavaScript SDK建立在Playwright工作流之上，可返回能够点击、填写和读取的页面元素。开发者仍可使用Playwright的等待、浏览器上下文、网络和断言能力。

• 打开网页并定位输入框、按钮和菜单
• 填写表单、选择选项和提交任务
• 关闭Cookie提示或弹窗
• 翻页、滚动并等待异步内容出现
• 在登录会话中执行获授权操作
• 把提取结果写入后续数据工作流

Python与JavaScript SDK

REST API与文档提取

REST API可用API Key认证并返回结构化数据，既能查询网页，也能处理PDF和图像文件。文档查询按页或按图像计算调用，因此大文件需要预估请求量。

• 从任意支持网络请求的语言调用
• 使用Query精确指定结构或用Prompt描述目标
• 选择快速或标准提取模式
• 创建远程浏览器会话执行交互任务
• 配置浏览器特征与代理位置
• 通过请求标识追踪运行和错误

远程浏览器

AgentQL套餐包含一定的远程浏览器时长和并发会话，可用于云端执行动态网页工作流。Starter、Professional的包含时长、超额费和并发上限差异明显。

• 在托管环境中运行需要JavaScript的页面
• 维持多步骤交互所需的浏览器会话
• 按地区配置受支持的代理出口
• 选择轻量或更强调反检测的浏览器配置
• 设置非活动超时避免遗留会话耗费时长
• 按任务隔离Cookie、登录和本地存储

Debugger与Playground

Debugger扩展会在浏览器开发者工具中增加AgentQL面板，可直接在当前网页测试查询并高亮匹配元素。Playground更适合探索查询、优化提示和生成可继续开发的脚本。

• 切换元素查询和数据提取模式
• 查看查询命中的页面区域
• 检查列表与嵌套结构是否符合预期
• 为歧义字段补充自然语言上下文
• 在进入代码前快速验证目标网站
• 将验证后的结果迁移到SDK或API

适用场景

• 构建能够访问网页和执行任务的AI Agent
• 抓取电商、新闻、目录或公开研究数据
• 自动填写内部系统和合作伙伴门户表单
• 监控页面字段、价格、状态或内容变化
• 为测试脚本提供更易维护的语义定位
• 从PDF和图片中提取固定结构信息
• 跨多个结构不同但语义相似的网站采集数据
• 把网页信息接入LangChain、Zapier或内部流程

适合哪些用户

• 需要快速开发网页Agent的AI工程师
• 维护Playwright自动化的Python和Node.js开发者
• 需要结构化网页数据的数据与研究团队
• 希望降低选择器维护成本的测试工程师
• 要用REST API接入网页数据的后端团队
• 需要专有云或本地部署的企业客户

AgentQL价格

AgentQL提供免费试用、Starter、Professional和Enterprise方案。公开价格按月展示，API与远程浏览器在包含额度之外分别按量收费。

免费试用不要求信用卡，适合在正式选型前验证查询和远程浏览器。税费、代理、专业服务或企业交付成本是否另计，应以结算页和订单为准。

套餐选择建议

快速开始教程

1. 注册开发者账号并创建API Key。
2. 安装Debugger扩展，在目标网页打开开发者工具。
3. 先用简单字段查询定位一个明确元素。
4. 用列表和嵌套结构定义完整输出。
5. 在调试器中分别检查元素和数据结果。
6. 安装Python或JavaScript SDK并初始化项目。
7. 将验证后的查询加入Playwright脚本。
8. 添加等待、重试、空值和异常页面处理后再上线。

数据提取教程

1. 确认目标数据的使用权限和网站条款。
2. 列出需要返回的字段、类型和层级关系。
3. 为重复项目使用列表并为子字段建立嵌套结构。
4. 选择具有代表性的页面测试正常和缺失字段。
5. 处理分页、无限滚动和动态加载状态。
6. 验证重复项、空值、类型和字符编码。
7. 设置频率限制、缓存和失败重试。
8. 定期抽样对比原页面以发现质量变化。

生产部署教程

1. 估算每月网页、文档页数和远程浏览器小时。
2. 按并发与速率上限选择合适套餐。
3. 将API Key存入密钥管理系统并限制访问范围。
4. 为登录会话和不同客户隔离浏览器上下文。
5. 对超时、验证码、封禁和页面变化设置明确状态。
6. 记录请求标识、目标、耗时、结果和错误原因。
7. 设置调用量、浏览器时长和费用告警。
8. 安排人工复核高影响数据和自动操作。

查询设计建议

• 使用业务含义明确且稳定的字段名称
• 只在必要时加入位置和外观描述
• 用嵌套结构表达真实数据关系
• 对多个项目显式使用列表
• 把复杂页面拆成可验证的小查询
• 为可选字段接受空值并记录缺失原因
• 使用代表性页面和异常页面建立回归测试

可靠性与质量评估

安全与合规

• 只访问公开或已获得授权的页面和账户
• 遵守网站条款、访问频率和数据使用限制
• 不要在查询、日志或代码中暴露API Key
• 对Cookie、会话和下载文件实施隔离与加密
• 避免采集与业务无关的个人或敏感信息
• 对提交、购买、删除等高影响操作保留人工确认
• 为自动化设置速率、预算和允许域名清单
• 准备验证码、访问阻断和人工接管流程

产品优势

• 自然语言定位比固定DOM路径更易理解和维护
• 查询本身定义结构化输出，减少后处理代码
• 同一工具同时覆盖数据提取和网页交互
• Python与JavaScript SDK直接衔接Playwright
• REST API便于其他语言和无状态任务接入
• 提供调试器、Playground、CLI和丰富示例
• 可查询网页、PDF和图像等多种来源
• 核心SDK与示例在GitHub以MIT许可证公开

使用限制与注意事项

• 语义定位仍可能在歧义页面命中错误元素
• 网站登录、验证码和反自动化机制可能阻断流程
• 动态页面需要合理等待，不能只依赖单次查询
• 页面内容错误会直接影响提取结果
• API调用和远程浏览器分别产生用量成本
• PDF按页面计算调用，大文件成本会快速增加
• 跨站复用查询前仍需逐站验证字段语义
• 自动化不应规避网站安全措施或访问限制
• 云端服务与开源SDK不同，完整平台不能仅靠仓库自托管

GitHub与开源情况

AgentQL官方GitHub仓库公开Python、JavaScript集成、示例和开发资源，并采用MIT许可证。托管API、远程浏览器、开发者门户和企业服务仍属于商业平台，不应理解为全部云服务开源。

基本信息

推荐指数

4.6 / 5。AgentQL适合希望用语义查询降低网页选择器维护成本的开发者和Agent团队，工具链、Playwright集成与公开价格较完整；生产使用仍需处理页面歧义、访问限制、质量监测和按量成本。

常见问题

AgentQL主要做什么？

它用自然语言查询定位网页数据和元素，并通过SDK或API完成结构化提取与浏览器自动化。

AgentQL和Playwright是什么关系？

AgentQL SDK在Playwright工作流中增加语义查询能力，原有的浏览器控制、等待和断言能力仍可继续使用。

AgentQL可以免费使用吗？

可以。免费试用提供300次调用，Starter每月提供50次免费调用并允许按量付费。

Professional多少钱？

Professional公开价格为每月99美元，包含10,000次API调用和500小时远程浏览器。

AgentQL能提取PDF吗？

可以，REST API支持PDF和图像；PDF通常按页面计算API调用。

AgentQL支持哪些语言？

官方提供Python与JavaScript SDK，其他语言可以通过REST API接入。

AgentQL能处理登录页面吗？

可以在获得授权的浏览器会话中处理登录后页面，但必须保护凭据并遵守网站规则。

AgentQL开源吗？

官方代码仓库采用MIT许可证，但托管API、远程浏览器和企业服务仍是商业产品。

语义选择器会永远稳定吗？

不会。它能降低页面结构变化带来的维护压力，但歧义、内容变化和访问状态仍可能导致失败。