# 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 本身就是跨平台 |
| **认证 / 会话处理** | 手动 | 有限 | 一等公民 |
| **反爬意识** | 几乎没有 | 不涉及 | 至关重要 |

两个最关键的点：

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

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

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

1. **多模态大模型能同时读懂截图和 DOM**。GPT-4o、Claude Sonnet 4、Gemini 2.5、Qwen-VL——它们对 UI 元素的视觉定位能力都已经足够强，能够在没有专门视觉训练的情况下驱动浏览器。
2. **无头浏览器基础设施成熟**。Playwright 和 Chrome DevTools Protocol（CDP）让我们能够廉价地在全球任何地方启动一个真实的 Chromium 实例，并加上隐身补丁、代理路由、远程控制。
3. **真实痛点足够大**。世界上一半的数据躺在没有 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）的检查点。

---

## 第二部分：实战教程

我们按由浅入深三步走：

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

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

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

#### 第 1 步：获取 API 密钥

1. 在 `agent.tinyfish.ai` 注册账号
2. 进入 API Keys 页面，点击 **Create API Key**
3. 复制密钥——它只显示一次
4. 写进你的 shell：

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

#### 第 2 步：安装 SDK

```bash
# Python
pip install tinyfish

# 或 TypeScript
npm install @tiny-fish/sdk
```

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

**Python：**

```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：**

```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）：**

```bash
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 边调试边看。

```python
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。

```python
# 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,
            )
        ]
```

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

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

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

```python
# 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 循环大致会经历这样的过程：

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

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

#### 第 3 步：把它做到生产级

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

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

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

```python
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。反爬厂商会关联两个信号——只改一个往往不够：

```python
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。花五分钟翻一翻，省下几天试错时间。如果数据真的只在付费墙后的格式化页面里，问问自己：底层信息源（公告、新闻稿、厂商页面）是不是在防守更弱的地方也有。

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

```python
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）具备驱动浏览器的能力——你自己一行代码都不用写。

一行命令安装：

```bash
# 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` 里加：

```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 官方文档](https://docs.tinyfish.ai)。*