Web Agent 科普与实战——让 AI 学会"上网"

引言：当 AI 学会浏览网页

想象一下这样的场景：你对着 AI 说"帮我在主流旅行网站上找出下周二从北京飞新加坡、价格在 3000 元以内的三个直飞航班，对比之后用我保存的信用卡订下最划算的那个"——然后 AI 真的打开了一个浏览器，自主导航预订流程，处理路上的各种弹窗与验证页，填写乘客信息，最终把订单确认号交到你手上。

这并不是科幻，而是 Web Agent（网页智能体） 正在成为现实。如果说 Extra06 介绍的 GUI Agent 教会了 AI 如何操作手机和桌面应用，那么本章要介绍的就是它在网页世界的近亲——以浏览器为主要行动表面的智能体。

Web 之所以值得拥有一章独立的篇幅，有两个理由。第一，世界上最有价值的数据与工作流，大部分都跑在网页上——比手机 App 或桌面软件多得多。第二，Web 是一个独立的技术问题：它的感知、行动和可靠性挑战和移动/桌面 GUI Agent 有本质区别。你没法把 Mobile-Agent-v3 直接接到 Chrome 上就当作 Web Agent，这条路走不通。

本章的承诺是，读完之后你将：

理解 Web Agent 与传统 RPA、通用 GUI Agent 的本质区别
掌握三种主流感知策略（DOM、视觉、混合），并理解为什么生产级系统普遍走混合路线
通过 SDK 调用，以及作为工具集成进第七章构建的 HelloAgents 框架，亲手使用一个生产级的 Web Agent 服务——TinyFish
学会诊断和绕开常见的反爬机制
知道什么时候 不应该 使用托管型 Web Agent

第一部分：Web Agent 技术科普

1.1 什么是 Web Agent？

Web Agent 是一类以网页浏览器为主要行动表面的自主智能体。它通过 DOM、可访问性树和屏幕截图的某种组合来感知页面，用大语言模型推理下一步该做什么，然后在真实浏览器实例里执行动作——点击、输入、滚动、跳转。

关键词是自主。一个用 Playwright 写死的爬虫脚本不是 Web Agent，它只是一段脆弱的程序，目标网站稍微改一下按钮位置就崩了。而 Web Agent 是在运行时根据自己 "看到" 的内容动态决定下一步动作的。

1.1.1 Web Agent vs RPA vs GUI Agent

这条技术血缘很重要。我们把三者放在一起对比：

维度	传统 RPA（Selenium、UiPath）	GUI Agent（Mobile-Agent、AutoGLM）	Web Agent（Browser-Use、TinyFish）
主要表面	Web 或桌面	移动 + 桌面，以截图为主	网页浏览器
感知方式	DOM 选择器（XPath、CSS）	视觉（VLM 解析截图）	DOM + 可访问性树 + 视觉（混合）
动作机制	固定脚本	基于坐标的点击	选择器、坐标和语义目标的混合
能否适应 UI 变化	不能——立即失效	能——视觉具备语义弹性	能——多种锚定信号
跨平台能力	有限	天然跨平台	Web 本身就是跨平台
认证 / 会话处理	手动	有限	一等公民
反爬意识	几乎没有	不涉及	至关重要

两个最关键的点：

Web Agent 不是 "限定在 Chrome 上的 GUI Agent"。它会利用 DOM、可访问性树和网络层的结构化信息——这些信息要么不存在于移动/桌面环境，要么 GUI Agent 选择不用。生产级 Web Agent 一定是混合的：视觉负责理解布局，DOM/AX-tree 负责精准定位，根据动作的具体情况切换。
Web 有它独有的对手。Cloudflare、DataDome、PerimeterX、指纹识别、行为生物特征分析——这些在手机/桌面 GUI Agent 上都不存在。一个不考虑反爬的 Web Agent 在生产环境就是一个返回空结果的 Web Agent。

1.1.2 为什么 Web Agent 在 2024–2026 突然爆发？

三股力量在同一时间汇合：

多模态大模型能同时读懂截图和 DOM。GPT-4o、Claude Sonnet 4、Gemini 2.5、Qwen-VL——它们对 UI 元素的视觉定位能力都已经足够强，能够在没有专门视觉训练的情况下驱动浏览器。
无头浏览器基础设施成熟。Playwright 和 Chrome DevTools Protocol（CDP）让我们能够廉价地在全球任何地方启动一个真实的 Chromium 实例，并加上隐身补丁、代理路由、远程控制。
真实痛点足够大。世界上一半的数据躺在没有 API 的网页背后——价格、库存、政府公开档案、新闻档案、各种厂商给企业部署的内部仪表盘。把这些工作流自动化的经济价值是巨大的，而只有 Web Agent 能填上这个空白。

我们还正好赶上各大 AI 实验室开始直接把这个能力产品化的时刻——Anthropic 的 Computer Use、OpenAI 的 Operator、Google 的 Project Mariner。"Web Agent" 正在迅速成为每个 AI 原生产品都会接入的基础能力。

1.2 核心技术架构

和所有 GUI Agent 一样，Web Agent 也是一个 感知 → 推理 → 行动 的闭环。但每一层都有 Web 特有的微妙之处。

1.2.1 感知层：三种策略，各有致命弱点

业界有三种主流的感知策略，每一种都有另两种正好能补足的弱点：

策略 A——基于 DOM：解析页面的 HTML 和可访问性树。又快又准，能直接告诉你元素的类型、文本内容、选择器。失败场景：页面是 Canvas 渲染的 SPA（Google Docs、Figma 等），或者站点故意混淆 DOM，或者有意义的内容渲染进了爬虫读不到的 Shadow DOM。

策略 B——基于视觉：截屏 → 输入视觉大模型 → 模型识别要点击的元素并输出坐标。失败场景：模型把小字读错，元素位置幻觉，4K 页面上有些东西它就是看不到。而且成本高——每一步都要调一次 VLM 推理。

策略 C——混合（生产环境的赢家）：用视觉做布局理解和上下文推理（"这三个搜索框里，哪个才是我要的？"），再用 DOM 或可访问性树做精确定位（"这是要点击的具体元素"）。所有认真的生产级 Web Agent——Operator、Computer Use、Browser-Use、TinyFish——最终都走向了混合路线。

业界为什么会收敛到这一点？经验数据说话：在常见的生产工作流上，经过混合方案 + 隐身浏览器 + 反爬加固的成熟系统，成功率已经稳定在 90% 左右；而纯视觉、未加固的方案在 WebArena 这类对抗性学术基准上往往只有 30–40%。注意这两个数字衡量的是 不同的东西——学术基准刻意构造长链路、刁钻场景；生产系统是在真实业务流上做了大量针对性调优。但两条曲线都在显示同一件事：混合方案在工程上明显占优。

1.2.2 推理层：记忆、反思和状态问题

Web 在推理层最大的挑战是 状态突变。页面会在你眼皮底下变：

无限滚动会随着你滚到底部不断加载新内容
页面加载两秒后冒出一个模态框，把你想点的按钮挡住了
点完 "加入购物车" 后页面重渲染，你之前那份 DOM 快照立即失效
登录流程会经过三个中间页才把你送到 dashboard

一个合格的 Web Agent 需要具备：

任务分解 —— 把 "帮我找周六价格 3000 以下的航班" 拆成一系列具体步骤
反思 —— 注意到一个动作没有产生预期效果，并能恢复
记忆 —— 翻到第二页时记住第一页搜索结果的内容
状态追踪 —— 区分 "按钮消失因为我点击了它" 和 "按钮消失因为页面崩了"

这正是第四章的 ReAct 范式 大放异彩的舞台。Web Agent 本质上就是一个 ReAct 循环，其中动作空间是 {click, type, scroll, navigate, wait, extract}，观察是下一个页面状态。

1.2.3 行动层：Web 上独特的难点

动作空间乍看和移动 GUI Agent 类似——点击、输入、滚动。但 Web 层多出了：

会话状态：cookies、localStorage、sessionStorage 需要跨动作保持（或刻意清空）
导航历史：后退、前进、新标签页、切换标签
文件下载与上传：不走 DOM
iframe 与 Shadow DOM 遍历：一个网页不是一个文档，而是文档的树
网络层关注点：你点完 "提交" 后，可能要等一个 XHR 完成才算 "做完"

只用坐标的 Web Agent 会碰上以上每一个限制。这就是混合方案成为生产标准的原因。

1.3 Web 独有的那些难题

下面这些问题，Extra06 没有也无法覆盖，因为它们在移动和桌面上根本不存在：

反爬机制。Cloudflare、DataDome、PerimeterX、Akamai Bot Manager。它们盯着你的 TLS 指纹、浏览器 JavaScript 对象签名、鼠标移动模式、操作时序。一个朴素的 Playwright 脚本几秒钟就被拦下了。生产级 Web Agent 需要 隐身浏览器（打了补丁、看起来和真实用户浏览器无法区分的 Chromium），通常还要搭配住宅 IP 代理。

认证与会话保持。OAuth 流程、二次验证、会话 cookie、"记住我" token、登录时的验证码。一个登不进去的 Web Agent 只能看到公开网页。带加密凭据库（vault）的方案是新兴模式。

动态内容与竞态条件。无限滚动、懒加载图片、800ms 后才出现的模态框、阻塞点击的动画。智能体必须知道页面什么时候算 "就绪"，而 "就绪" 没有清晰的定义。

JS 重型 SPA。当你访问一个现代 React 或 Vue 站点时，初始 HTML 基本是空的——真正的 DOM 是 JavaScript 在三秒后渲染出来的。朴素的爬虫看不到任何内容。

网络、地理与限流。有些内容被地理限制，有些接口按 IP 做限流，有些站点会在检测到 "太多" 来自同一来源的请求时静默降级响应。

成本与延迟。每一步动作都是一次 LLM 调用 + 一次浏览器往返。10 步的自动化任务可能要 30–60 秒，光 LLM 的 token 成本就是 0.10–1.00 美元。这正是业界拼命追求更小、更快、专门为 Web 微调的模型的原因。

1.4 2026 年的全景图：四类玩家的对比

2026 年的 Web Agent 生态系统大致可以分为四类，每一类的存在都对应一个真实的取舍：

类别	代表项目	优势	弱点
原始浏览器自动化	Playwright、Puppeteer、Selenium	快、可重复、免费、完全可控	没有 AI、脆弱，每次 UI 变动都要修脚本
开源 AI Web Agent	Browser-Use、Skyvern、WebVoyager、AgentE	免费、可魔改、完全透明	自己部署，自己处理反爬、代理、基础设施、可观测性
Computer-use API	Anthropic Computer Use、OpenAI Operator、Google Project Mariner	通用推理能力强、模型前沿	贵、UX 有立场、没有内建反爬或地理路由，常常以桌面为主而非纯 Web
托管型 Web 自动化 API	TinyFish、Browserbase、Apify、Bright Data	隐身浏览器 + 代理 + 智能体循环一揽子打包，几分钟就能跑通；自带可观测性	有厂商依赖、对内部智能体循环控制更少、按任务计费

诚实的判断：每个类别都赢在不同的轴上。你是研究员、想研究 Agent 行为？用开源。你是个人开发者、爬一个没反爬的小站？纯 Playwright 就够了。你在为产品做功能、需要在真实世界（包含反爬）的站点上"开箱即用"？托管 API 能为你省下几周时间。

第二部分我们将用 TinyFish 来做实战练习——它的 API 设计在这一类里是最干净的，并且把智能体循环明确暴露出来，方便学习。

1.5 真实世界中的应用场景

下面是 Web Agent 已经在生产环境落地的（不完全）列表：

电商监控：价格、库存、对手商品、评价聚合
B2B 数据增强与销售线索生成：从类 LinkedIn 站点抓取信息、构建公司数据库
遗留 Web 系统的内部 RPA：成千上万的公司，核心业务还跑在没有 API 的纯 UI 系统上，Web Agent 终于让它们可以被自动化
质量保证与自动化测试：回归测试、可访问性审计、内容合规
研究类智能体（第十四章主题）：一个不能浏览网页的研究智能体瞎了一半，Web Agent 是 DeepResearch 类系统天然的后端
旅行与预订工作流（第十三章主题）：旅行助手在 "能真正完成预订" 而不是 "只能给推荐" 之后，使用价值会翻 10 倍
个人自动化：盯一个职位发布、监控商品补货、跟踪政府公示

1.6 当前技术的真实局限

请对你的读者诚实。Web Agent 既令人兴奋，又有它的边界：

成功率：基准 vs 生产是两条曲线。生产级 Web Agent（混合方案 + 隐身 + 反爬加固）在常见业务流上已经能稳定在 90% 左右；但在 WebArena、VisualWebArena 这类刻意构造的对抗性学术基准上，最好的系统也还在持续追赶。换句话说：工程闭环上能做到的事，比学术评测看起来要多得多——但任务本身越偏门、链路越长，差距越大。
反爬是一场移动的猫鼠游戏。上个月好用的方案这个月可能就被识破。厂商对抗永无止境。
成本真实存在。托管 API 平均每个任务 0.10–1.00 美元。自部署省钱、烧的是工程时间。
验证码是硬上限。厂商再怎么宣传，现代 Web Agent 依然没法可靠地解开 reCAPTCHA 或 hCaptcha。务实的做法是设计任务时绕开它，而不是硬扛。
幻觉的代价是真金白银。一个填错的表单字段，可能让快递寄到错的地址。高风险动作必须有人类在环（human-in-the-loop）的检查点。

第二部分：实战教程

我们按由浅入深三步走：

极速上手——5 分钟内跑通第一个 TinyFish 调用，零框架、零环境
观察智能体工作——用直播 URL 可视化调试每一次运行
集成进 HelloAgents——把 TinyFish 包成一个 Tool，接入第七章框架里的 ReAct 智能体

2.1 极速上手：5 分钟内你的第一个 Web Agent

TinyFish 是一个托管型的 Web Agent API。你给它一个 URL 和一段自然语言 目标（goal），它返回结构化 JSON。

第 1 步：获取 API 密钥

在 agent.tinyfish.ai 注册账号
进入 API Keys 页面，点击 Create API Key
复制密钥——它只显示一次

写进你的 shell：

export TINYFISH_API_KEY="sk-tinyfish-..."

第 2 步：安装 SDK

# Python
pip install tinyfish

# 或 TypeScript
npm install @tiny-fish/sdk

第 3 步：你的第一个自动化任务

Python：

from tinyfish import TinyFish, CompleteEvent

client = TinyFish()  # 自动从环境变量读取 TINYFISH_API_KEY

with client.agent.stream(
    url="https://scrapeme.live/shop",
    goal="提取前 2 个产品的名称和价格，以 JSON 形式返回。",
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print(event.result_json)

TypeScript：

import { TinyFish, EventType } from "@tiny-fish/sdk";

const client = new TinyFish();

const stream = await client.agent.stream({
  url: "https://scrapeme.live/shop",
  goal: "提取前 2 个产品的名称和价格，以 JSON 形式返回。",
});

for await (const event of stream) {
  if (event.type === EventType.COMPLETE) {
    console.log(event.result);
  }
}

原始 HTTP（不用 SDK）：

curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://scrapeme.live/shop",
    "goal": "提取前 2 个产品的名称和价格"
  }'

运行起来，你会看到 Server-Sent Events 实时流进终端：

{"type": "STARTED", "run_id": "abc123"}
{"type": "STREAMING_URL", "run_id": "abc123", "streaming_url": "https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0"}
{"type": "PROGRESS", "run_id": "abc123", "purpose": "Visit the page to extract product information"}
{"type": "PROGRESS", "run_id": "abc123", "purpose": "Check for product information on the page"}
{"type": "COMPLETE", "run_id": "abc123", "status": "COMPLETED", "result": {
  "products": [
    {"name": "Bulbasaur", "price": "$63.00"},
    {"name": "Ivysaur", "price": "$87.00"}
  ]
}}

就这样——你刚刚跑完了一个 Web Agent。这一次调用背后发生的事：数据中心里启动了一个真实的 Chromium 浏览器，导航到目标页面，解析布局，识别出商品卡片，提取数据，并把进度流式返回给你。

请求的解剖

TinyFish 的 /run-sse 端点接收的 JSON 字段（重点字段已加粗）：

字段	类型	说明
`url`	string	起始页面
`goal`	string	自然语言指令
`output_schema`	object	可选的 JSON Schema 子集，约束返回结构
`browser_profile`	`"lite"` \| `"stealth"`	默认 `lite`
`proxy_config`	object	可选 `{enabled, type, country_code}`
`use_vault`	boolean	是否使用保存的凭据完成登录
`credential_item_ids`	string[]	限定 vault 中的具体凭据

三个端点，三种模式：

POST /v1/automation/run——同步，阻塞到完成，返回最终结果
POST /v1/automation/run-async——发后即忘，立即返回 run_id
POST /v1/automation/run-sse——流式，实时把进度事件推回给你

短任务（< 30 秒）用同步；批量作业用异步；要在 UI 上实时显示进度时用 SSE。

2.2 观察智能体工作——直播 URL

TinyFish 在教学上最有用的一个功能是 streaming_url：每次运行都会产生一个 URL，让你 实时观看浏览器。你可以把它嵌进自己产品的 iframe 里，也可以直接在浏览器开个 Tab 边调试边看。

from tinyfish import TinyFish, CompleteEvent

client = TinyFish()

with client.agent.stream(
    url="https://scrapeme.live/shop",
    goal="提取前 3 个产品的名称和价格",
    on_streaming_url=lambda e: print(f"\n实时观看：{e.streaming_url}\n"),
    on_progress=lambda e: print(f"  → {e.purpose}"),
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print("\n最终结果：", event.result_json)

跑起来几乎瞬间就拿到一个可点击 URL。在浏览器里打开它——你看到的就是 智能体正在驱动的真实浏览器会话。页面在加载、鼠标在移动、字段在填写。这是大多数读者会发出 "卧槽，它真的在做" 的瞬间。

而且这不只是个演示噱头。直播流是调试 Web Agent 最好用 的工具：

一次运行返回了空结果？打开直播——很可能你会看到一个 Cloudflare "Checking your browser" 拦截页，或者一个意料之外的弹窗
智能体点错了按钮？看直播、改 goal
在做面向用户的产品？把直播 URL 嵌进 iframe，让用户看着工作发生

2.3 怎么写好 goal

goal 这一个字段几乎就是 TinyFish 的全部 API 表面——写好它，是 90% 成功率和 30% 成功率的分水岭。

TinyFish 官方推荐的心智模型：把智能体当成一个 "字面执行" 的助理，坐在浏览器前。它能看到屏幕上的一切、能动手——但它没法猜你的意思。

一个出色的 goal 最多包含七个组件：

组件	示例
目标（Objective）	"提取定价信息"
范围（Target）	"从定价表中"
字段（Fields）	"套餐名、月费、包含功能"
结构（Schema）	"返回 JSON：`[{plan: string, price_monthly: number}]`"
步骤（Steps）	"先关掉 cookie 横幅"
护栏（Guardrails）	"不要点击任何'立即购买'按钮"
边缘情况（Edge cases）	"如果价格显示为'联系我们'，置为 null"

从最差到最好的演变：

模糊（必然失败）：

"获取这个页面的定价"

好一些（可能能跑）：

"提取产品名称、价格和库存状态"

生产级品质：

1. 等待页面完全加载。
2. 如果有 cookie 同意横幅，点击"全部接受"。
3. 定位定价区。
4. 对每个套餐，提取：套餐名称、月费（数字）、包含功能（字符串数组）。

不要点击任何购买或结账按钮。
如果套餐显示"联系我们"，monthly_price 置为 null。

返回 JSON：[{"plan": string, "monthly_price": number | null, "features": string[]}]

TinyFish 自己的测试里，相同任务下具体的 goal 完成速度快 4.9 倍、返回的多余数据少 16 倍。Goal 写作就是新的 Prompt 工程，并且和所有 Prompt 工程一样，复利明显。

2.4 主菜：把 TinyFish 集成进 HelloAgents

这一节是本章的核心。直接调 API 当然可以——但本书，尤其是第四章和第七章，一直在传达的核心信息是：当外部服务变成你自己框架里的工具，真正的力量才出现。这就是 "使用 AI" 和 "用 AI 构建" 之间的分水岭。

我们要把 TinyFish 包装成一个 HelloAgents 的 Tool，接入 ReActAgent。

提示：HelloAgents 是你在第七章构建的配套框架。如果还没装：pip install hello-agents。想要和正文完全对应的版本，可以切到 GitHub 上的 learn_version 分支。

第 1 步：定义 `TinyFishWebTool`

我们写一个工具，把 Web 自动化暴露成单一能力。智能体用自然语言描述自己想做什么，工具负责调用 API 并返回结构化 JSON。

# tools/tinyfish_tool.py
import json
import os
from typing import Any, Dict, List

from tinyfish import (
    TinyFish,
    BrowserProfile,
    ProxyConfig,
    ProxyCountryCode,
)

from hello_agents.tools import Tool, ToolParameter


class TinyFishWebTool(Tool):
    """让 ReAct 智能体通过自然语言驱动真实浏览器的工具。"""

    def __init__(self, api_key: str | None = None):
        super().__init__(
            name="web_automation",
            description=(
                "使用自然语言自动化任何网页。输入一个 JSON 字符串，包含两个必需字段："
                "`url`（起始页面）和 `goal`（清晰具体的任务描述）。"
                "可选字段：`stealth`（布尔值，针对有反爬保护的站点）、"
                "`country`（US/GB/CA/DE/FR/JP/AU，用于地理路由）。"
                "返回智能体抽取的结构化 JSON，或错误描述。"
            ),
        )
        self.client = TinyFish(
            api_key=api_key or os.environ["TINYFISH_API_KEY"],
        )

    def run(self, parameters: Dict[str, Any]) -> str:
        # ToolRegistry 会把 ReAct 的输入文本包成 {"input": "..."}
        raw = parameters.get("input", "")
        try:
            params = json.loads(raw)
        except json.JSONDecodeError:
            return json.dumps(
                {"error": "输入必须是合法的 JSON 字符串"},
                ensure_ascii=False,
            )

        url = params.get("url")
        goal = params.get("goal")
        if not url or not goal:
            return json.dumps(
                {"error": "缺少必需字段 url 或 goal"},
                ensure_ascii=False,
            )

        kwargs: Dict[str, Any] = {"url": url, "goal": goal}
        if params.get("stealth"):
            kwargs["browser_profile"] = BrowserProfile.STEALTH
        if (country := params.get("country")):
            kwargs["proxy_config"] = ProxyConfig(
                enabled=True,
                country_code=ProxyCountryCode(country),
            )

        # 用同步 run——ReAct 循环要拿到结果再继续。
        # 长任务可以改用 queue + 轮询。
        run = self.client.agent.run(**kwargs)

        if run.status.value != "COMPLETED" or run.result is None:
            err = run.error.message if run.error else "未知失败"
            return json.dumps(
                {"error": err, "status": run.status.value},
                ensure_ascii=False,
            )

        return json.dumps(
            {"data": run.result, "run_id": run.run_id},
            ensure_ascii=False,
        )

    def get_parameters(self) -> List[ToolParameter]:
        return [
            ToolParameter(
                name="input",
                type="string",
                description=(
                    "JSON 字符串，字段：url（必需）、goal（必需）、"
                    "stealth（可选）、country（可选）"
                ),
                required=True,
            )
        ]

代码里有几处值得特别留意：

工具的 description 是 LLM 决定是否调用它时唯一看到的信息。要像在跟一个从没读过你代码的初级开发者交代一样写描述——把输入、输出、何时使用都讲清楚。
工具永远返回字符串。ReAct 是文本进、文本出。我们把结果序列化成 JSON，让智能体在下一步 "Thought" 中能继续推理。
stealth 和 country 不是默认开启而是可选参数。让 LLM 自己决定——通过工具描述告诉它什么时候该开。

第 2 步：把工具接入 ReAct 智能体

# main.py
from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry
from tools.tinyfish_tool import TinyFishWebTool

llm = HelloAgentsLLM()  # 从 .env 读取 provider 配置
registry = ToolRegistry()
registry.register_tool(TinyFishWebTool())

agent = ReActAgent(
    agent_name="research_assistant",
    llm=llm,
    tool_registry=registry,
)

result = agent.run(
    "查询苹果官方商店和京东上 iPhone 17 Pro 的当前价格，"
    "在考虑商品页面所标的运费后告诉我哪个更便宜。"
)
print(result)

运行起来，ReAct 循环大致会经历这样的过程：

Thought（思考）："我需要从两个不同的站点拿价格。我应该调用两次 web_automation。"
Action（行动）：web_automation({"url": "https://www.apple.com/.../iphone-17-pro", "goal": "提取 iPhone 17 Pro 起步价。返回 JSON: {price_cny: number, free_shipping: boolean}"})
Observation（观察）：{"data": {"price_cny": 9999, "free_shipping": true}}
Thought："现在拿京东价格。京东有反爬——我应该启用 stealth。"
Action：web_automation({"url": "https://item.jd.com/...", "goal": "...", "stealth": true})
Observation：{"data": {"price_cny": 9799, "free_shipping": true}}
Thought："两边都包邮。京东便宜 200 元。"
Final Answer："京东目前比苹果官方便宜 200 元：京东 ¥9,799，苹果官方 ¥9,999，两家都免运费。"

刚刚发生的事，正是第七章希望传达的核心：外部服务作为一等公民进入你自己的框架。ReAct 循环没变，LLM 也没变。我们只是加了一个工具，你的智能体就具备了在公开网络上行动的能力。这就是 可组合性。

第 3 步：把它做到生产级

上面的版本演示足够了。真实生产环境还要再加几样：

1. 验证内容，不要只看状态

COMPLETED 的运行也可能返回垃圾，如果智能体撞上了软拦截（Cloudflare 挑战页、验证码、把 "访问被拒绝" 渲染成正文）。永远要检查 结果内容：

def is_real_success(result: dict | None) -> bool:
    if not result:
        return False
    s = json.dumps(result, ensure_ascii=False).lower()
    failure_signals = ["captcha", "blocked", "access denied", "could not", "unable to"]
    return not any(signal in s for signal in failure_signals)

2. 能缓存就缓存

一次 30 秒的网页自动化是昂贵的。如果同一会话里 ReAct 智能体两次要求同一个 URL，应该返回缓存结果。（第八章的记忆系统是个合适的着力点。）

3. 设置超时

TinyFish 内部每次运行有 10 分钟超时，但你的工具应该更早失败——多数有意义的任务在 10–60 秒内完成。超过这个时间，多半是卡在挑战页上了。

4. 用直播流做可观测

把每次运行的 streaming_url 记下来，写日志。生产环境出问题时，运行录像是定位故障最快的工具。

2.5 应对反爬

你的智能体迟早会撞上一个返回空结果或 403 的站点。这是诊断流程：

第 1 步——确认问题就是反爬。打开失败那次运行的 streaming_url，找以下几种特征：

你看到什么	大概率原因
Cloudflare "Checking your browser" 页	Cloudflare 机器人检测
DataDome 弹窗或重定向	DataDome
空白页或永远转圈	基于 IP 或指纹的拦截
验证码（reCAPTCHA、hCaptcha）	验证码——硬上限
"Access Denied" / 403	IP 或 User-Agent 拦截
该看到内容时却出现登录墙	基于会话的反爬

第 2 步——隐身和代理一起开。隐身改变浏览器指纹，代理改变 IP。反爬厂商会关联两个信号——只改一个往往不够：

run = client.agent.run(
    url="https://protected-site.com",
    goal="提取商品价格",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
)

第 3 步——让智能体表现得更像人类。有些站点关注行为而不只是指纹。在 goal 里加上：

显式关闭 cookie 横幅
抽取前等页面加载完成
用视觉描述元素（"蓝色的'加入购物车'按钮"），不要用选择器
多步流程用编号步骤，让智能体自己慢下来

第 4 步——实在不行就换打法。有些站点死命拦爬虫，但会大方提供 RSS、sitemap、公开 API。花五分钟翻一翻，省下几天试错时间。如果数据真的只在付费墙后的格式化页面里，问问自己：底层信息源（公告、新闻稿、厂商页面）是不是在防守更弱的地方也有。

一段完整的、加固过的范例：

from tinyfish import (
    TinyFish, BrowserProfile, ProxyConfig, ProxyCountryCode,
    CompleteEvent, RunStatus,
)

client = TinyFish()

with client.agent.stream(
    url="https://protected-site.com/pricing",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
    goal="""
        1. 等待页面完全加载。
        2. 关闭任何 cookie 同意 / GDPR 横幅。
        3. 继续之前等待 1 秒。
        4. 定位定价区（通常是网格或卡片表格）。
        5. 对每个套餐，提取：套餐名、月费、年费（如有）。

        如果出现 Cloudflare 或安全检查页，等它自动通过。
        如果看到 Access Denied 或 CAPTCHA 页，返回 {"error": "blocked"}。
        不要点击任何购买或结账按钮。

        返回 JSON：[{"plan": "Pro", "monthly_price": 49, "annual_price": 39}]
    """,
    on_streaming_url=lambda e: print(f"实时观看：{e.streaming_url}"),
    on_progress=lambda e: print(f"  → {e.purpose}"),
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            if event.status == RunStatus.COMPLETED:
                print("结果：", event.result_json)
            else:
                print("失败：", event.error.message if event.error else "unknown")

重要的诚实声明：包括 TinyFish 在内，没有任何 Web Agent 能可靠地解开现代验证码（reCAPTCHA v2/v3、hCaptcha）。如果一个站点向你弹出验证码，那目前就是一道硬墙。正确的做法是把你的运行设计得不去触发它，而不是硬扛。

2.6 加餐：通过 MCP 调用 TinyFish（对应第十章）

第十章介绍了 MCP（Model Context Protocol）——Anthropic 提出的、让 AI 助手连接外部工具和数据的开放协议。TinyFish 暴露了一个 MCP 服务器。这意味着，你可以让任何兼容 MCP 的助手（Claude Desktop、Cursor、Windsurf、Claude Code）具备驱动浏览器的能力——你自己一行代码都不用写。

一行命令安装：

# Claude Code
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code

# Claude Desktop
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude

# Cursor
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client cursor

或者手动在 claude_desktop_config.json 里加：

{
  "mcpServers": {
    "tinyfish": {
      "url": "https://agent.tinyfish.ai/mcp"
    }
  }
}

重启后，你的助手会多出 run_web_automation、search、fetch_content、create_browser_session 等工具。然后你就可以直接对 Claude 说：

"并行抓取以下 5 个竞品的定价页，把结果整理成表格。"

Claude 就会用 TinyFish 在背后完成这件事，批量执行，实时反馈进度。

这正是第十章预告的 一次构建、处处可用 的回报。MCP 作为分发协议，把每一个工具都变成了 每个 AI 助手都能直接使用 的能力。

第三部分：综合思考

3.1 什么时候不要用托管 Web Agent

为了诚实：托管 Web Agent 并不总是正确选择。

有官方 API——用 API。API 更快、更便宜、更可靠
高频率爬取无反爬站点——纯 Playwright 就够了，便宜几个数量级
错误代价高的关键工作流——不管你用什么工具，永远要在关键步骤加上人类在环检查点
你完全可控的内部工具——干脆加一个 API 端点

什么时候用托管 Web Agent：目标站点在外部、没有 API、有反爬保护、流程是多步的，而且工程时间比任务级单价更值钱。

3.2 Web Agent 接下来的方向

这个领域走得很快。未来 12–24 个月值得关注的几件事：

更小、更快、专为 Web 微调的模型。前沿模型对 "点击蓝色按钮" 是杀鸡用牛刀。下一代 OS 专家智能体——例如 Qwen-VL-2.5-VL 之后的模型——会大幅压低单步动作的延迟和成本。
认证会话成为一等公民。Vault 集成（加密的密码管理器桥接）开始落地。这将解锁下一波智能体应用——银行、医疗、内部工具，这些场景登录是入口。
学术基准向生产水位靠拢。常见业务流上的生产成功率已经稳定在 90% 左右；WebArena 这类对抗性基准上的分数也在快速攀升，差距正在被工程和模型两端同时压缩。
本地 Web Agent。隐私敏感任务（医疗记录、税务）需要本地运行的智能体。本地 VLM 配合本地 Chromium 已经看起来可行。
Web Agent 评测成熟化。第十二章讲的评测方法学正好适用——很快会看到面向生产 Web Agent 的标准化评测套件。

3.3 接下来该往哪走

如果这一章勾起了你的兴趣，下面几条路可以继续：

结合第八章（记忆）：让你的 Web Agent 记住昨天爬到了什么，今天只取增量
结合第十二章（评估）：给你的 Web Agent 装上成功率追踪。你会很快摸清楚哪些站点需要 stealth、哪些 goal 需要再细化
结合第十三章和第十四章：旅行助手和 DeepResearch 智能体一旦把动作空间扩展到 "真实浏览器"，会发生质变。试试用 Web Agent 做后端重写其中一个
可以研究的开源替代品：Browser-Use（Python）、Skyvern（Python）、WebVoyager（研究基准）、AgentE（开源智能体基础设施）
基准：WebArena、VisualWebArena、Mind2Web、WebVoyager-2024——把论文读一遍，你就会清楚 2026 年的 Web Agent 在哪个水位

结语

归根到底，Web Agent 不过就是一个 ReAct 循环——只不过它的行动表面是浏览器。前面章节里你学到的一切——感知、推理、行动、记忆、评估——都直接适用。新的东西是这个 对抗性环境：真实网站对自动化的敌意，是移动 App 和桌面软件所没有的，这种敌意正是 Web Agent 工程之所以独立成为一门学问的原因。

好消息是：你不需要从零解决这一切。像 TinyFish 这样的生产级原语，正是为此而存在。作为一个 AI 原生智能体的构建者，你的工作是把这些原语组合成有用的东西——并且把这件事在你自己 从头到尾理解 的框架里完成。

去构建吧。开放的 Web 是世界上最大的行动表面，从未有过比现在更好的时机，去教会一个智能体使用它。

致谢：感谢 TinyFish 团队对本章技术细节的输入。所有 API 细节核对自 TinyFish 官方文档。

Extra11-WebAgent科普与实战.md 36 KB Historik Rå