在实际 AI 应用开发中构建一个能够理解用户意图、自主操作网页并完成复杂任务的智能体AI Agent是当前技术探索的前沿。这类网页 Agent 的核心挑战在于如何将大语言模型LLM的推理能力与浏览器环境的精确控制能力无缝衔接实现从“说”到“做”的跨越。传统的自动化脚本僵硬且无法应对动态变化的网页结构而单纯调用 API 的聊天模型又缺乏执行具体操作的能力。因此一个能够理解自然语言指令、规划操作步骤、执行浏览器交互并验证结果的“上网办事 AI”系统成为了提升自动化水平的关键。本文将深入探讨如何从零开始构建一个简易但功能完整的网页操作 AI Agent。我们将以 Spring AI 作为与 LLM 交互的框架基础模拟一个需要登录、查询、填写表单等操作的业务场景。通过拆解任务规划、动作执行、状态验证等核心模块你将理解 AI Agent 的工作原理并能够动手实现一个可运行的原型。本文适合有一定 Java/Spring Boot 基础并对 AI 应用集成、自动化测试或智能流程自动化感兴趣的开发者。1. 理解网页 AI Agent 的核心架构与工作流程在开始编码之前必须厘清一个网页 AI Agent 是如何工作的。它不是一个单一的模型而是一个由多个组件协同工作的系统。1.1 从用户指令到浏览器动作的转化链用户的一句自然语言指令如“帮我登录系统并查询上个月的订单”需要被转化为一系列具体的、可执行的浏览器操作。这个转化过程通常遵循感知-规划-执行-验证的循环ReAct 模式的一种体现。任务解析与规划AI Agent 首先需要理解用户的终极目标并将其分解为一系列原子化的子任务。例如“登录系统”可分解为“打开登录页”、“定位用户名输入框”、“输入用户名”、“定位密码输入框”、“输入密码”、“定位并点击登录按钮”。规划器通常是 LLM需要理解网页操作的常见原子动作如 click, type, navigate, extract_text 等。环境感知与状态获取在执行每个动作前Agent 需要知道当前网页的状态。这通常通过获取页面的 DOM 结构、可视元素信息或截图来实现。精简且结构化的页面信息如关键元素的 ID、类名、文本内容会被提供给 LLM作为其决策的“眼睛”。动作选择与参数生成基于当前状态和子任务目标LLM 需要决定下一步执行哪个原子动作并生成该动作所需的精确参数。例如决定执行type动作并指定参数selector: “#username”和text: “myUser”。动作执行由浏览器自动化驱动工具如 Selenium、Playwright接收并执行上一步生成的动作指令。结果验证与循环动作执行后Agent 再次感知页面状态判断子任务是否完成例如是否出现了“登录成功”的提示或页面跳转并决定是继续下一个子任务还是重新规划当前任务。1.2 关键组件与技术选型为了构建这个系统我们需要选择合适的工具链大脑LLM 接口Spring AI。它提供了统一的 API 来接入多种大模型如 OpenAI GPT、Azure OpenAI、Ollama 本地模型等简化了对话、提示词工程和函数调用的集成。我们将用它来实现任务规划和动作选择。手脚浏览器自动化Selenium或Playwright。两者都能驱动浏览器进行自动化操作。Playwright 在现代化、速度和稳定性方面更优本文示例将使用 Playwright for Java。协调中枢Agent 核心逻辑自定义的 Spring Boot 服务。它将串联 LLM 调用和浏览器操作维护任务状态处理异常循环。注意本文旨在阐述原理和提供可运行的示例其性能、稳定性和处理复杂网页的能力无法与新闻中提到的商用级产品如 Handoff相提并论。后者通常集成了更强大的视觉模型VLM用于理解页面、更鲁棒的异常处理机制以及针对海量网站的训练数据。2. 环境准备与项目初始化我们将创建一个标准的 Spring Boot 项目并集成 Spring AI 和 Playwright。2.1 基础环境与工具确保你的开发环境满足以下要求组件要求说明JDK17 或更高版本Spring Boot 3.x 的基线要求。Maven3.6 或 Gradle用于项目构建和依赖管理。IDEIntelliJ IDEA 或 Eclipse推荐使用 IntelliJ IDEA其对 Spring Boot 支持更好。浏览器Chrome/EdgePlaywright 需要安装对应的浏览器驱动。2.2 创建 Spring Boot 项目并配置依赖使用 start.spring.io 或 IDE 创建新项目选择以下依赖Spring WebSpring AI (如果列表中有否则需手动添加)在pom.xml中我们需要添加 Spring AI 和 Playwright 的依赖。由于 Spring AI 生态在快速演进请根据官方文档使用最新稳定版本。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version !-- 使用与Spring AI兼容的版本 -- relativePath/ /parent groupIdcom.example/groupId artifactIdweb-ai-agent/artifactId version0.0.1-SNAPSHOT/version nameweb-ai-agent/name descriptionDemo project for Web AI Agent/description properties java.version17/java.version spring-ai.version0.8.1/spring-ai.version !-- 请检查最新版本 -- /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI OpenAI 集成 (示例使用OpenAI API) -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version${spring-ai.version}/version /dependency !-- Playwright for Java -- dependency groupIdcom.microsoft.playwright/groupId artifactIdplaywright/artifactId version1.40.0/version /dependency !-- Lombok 简化代码 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration excludes exclude groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /exclude /excludes /configuration /plugin /plugins /build /project2.3 配置 Spring AI 连接在application.yml或application.properties中配置 Spring AI这里以 OpenAI 为例。你需要一个有效的 OpenAI API Key。# application.yml spring: ai: openai: api-key: ${OPENAI_API_KEY:your-api-key-here} # 建议使用环境变量 chat: options: model: gpt-4-turbo-preview # 或 gpt-3.5-turbo根据需求选择 temperature: 0.1 # 降低随机性使Agent行为更确定重要将your-api-key-here替换为你自己的 API Key或通过环境变量OPENAI_API_KEY设置。出于安全考虑切勿将真实密钥提交到代码仓库。3. 构建网页 AI Agent 核心模块我们的 Agent 将包含几个核心类定义动作的工具类、描述页面状态的类、协调整个流程的 Agent 服务类。3.1 定义原子动作工具首先我们定义 Agent 可以执行的一系列原子操作。这些操作将被封装成“工具”Tools供 LLM 通过函数调用Function Calling来调用。// com.example.agent.tools.BrowserActions.java package com.example.agent.tools; import com.microsoft.playwright.*; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.tool.annotation.Tool; import org.springframework.stereotype.Component; import java.util.List; import java.util.stream.Collectors; Component Slf4j RequiredArgsConstructor public class BrowserActions { private final Page page; // Playwright 页面对象通过配置注入 Tool(description “导航至指定的URL”) public String navigateTo(String url) { log.info(“执行导航: {}”, url); page.navigate(url); return “已导航至: “ url; } Tool(description “使用CSS选择器点击页面元素”) public String click(String selector) { log.info(“尝试点击: {}”, selector); try { page.locator(selector).first().click(); return “成功点击元素: “ selector; } catch (PlaywrightException e) { return “点击失败元素可能不存在或不可点击: “ selector “。错误: “ e.getMessage(); } } Tool(description “使用CSS选择器向输入框输入文本”) public String type(String selector, String text) { log.info(“在 {} 中输入: {}”, selector, text); try { page.locator(selector).first().fill(text); return “已在 “ selector “ 中输入文本: “ text; } catch (PlaywrightException e) { return “输入失败: “ selector “。错误: “ e.getMessage(); } } Tool(description “获取当前页面可见的主要文本内容用于理解页面状态”) public String getPageContent() { // 获取body内所有可见文本可进行简化处理 String allText page.locator(“body”).innerText(); // 截取前2000字符避免上下文过长实际可根据模型限制调整 String simplifiedContent allText.length() 2000 ? allText.substring(0, 2000) “...” : allText; log.info(“获取页面内容长度: {}”, simplifiedContent.length()); return “当前页面主要内容: \n” simplifiedContent; } Tool(description “使用CSS选择器获取特定元素的文本内容”) public String getElementText(String selector) { try { String text page.locator(selector).first().innerText(); return “元素 “ selector “ 的文本是: “ text; } catch (PlaywrightException e) { return “无法获取元素 “ selector “ 的文本: “ e.getMessage(); } } Tool(description “获取当前页面的URL”) public String getCurrentUrl() { String url page.url(); return “当前URL是: “ url; } }Tool注解是 Spring AI 提供的它会将这个方法描述注册给 LLM使 LLM 知道可以调用这些功能。方法的返回字符串将成为 LLM 下一步推理的依据。3.2 配置 Playwright 运行环境我们需要一个配置类来初始化 Playwright 的 Browser 和 Page 对象并将其注入到 Spring 容器中。// com.example.agent.config.PlaywrightConfig.java package com.example.agent.config; import com.microsoft.playwright.*; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Scope; import javax.annotation.PreDestroy; Configuration public class PlaywrightConfig { private Playwright playwright; private Browser browser; Bean Scope(“prototype”) // 每次注入时创建新的Page适合并发场景。这里为简单用单例。 public Page page() { if (playwright null) { playwright Playwright.create(); } if (browser null) { // 使用Chromium可配置为firefox或webkit browser playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(false)); // 设为true则无头模式 } return browser.newPage(); } PreDestroy public void close() { if (browser ! null) { browser.close(); } if (playwright ! null) { playwright.close(); } } }将setHeadless(false)改为true可以在服务器上无界面运行。开发阶段设为false便于观察 Agent 的操作过程。3.3 实现 Agent 协调服务这是最核心的部分它负责接收用户指令调用 LLM 进行规划并管理工具执行的循环。// com.example.agent.service.WebAgentService.java package com.example.agent.service; import com.example.agent.tools.BrowserActions; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.SystemPromptTemplate; import org.springframework.stereotype.Service; import java.util.List; import java.util.Map; Service Slf4j RequiredArgsConstructor public class WebAgentService { private final ChatClient chatClient; private final BrowserActions browserActions; // 系统提示词定义了Agent的角色、能力和规则 private final String SYSTEM_PROMPT “”” 你是一个专业的网页操作AI助手。你的目标是根据用户的指令通过操作浏览器来完成网页任务。 你可以使用的工具动作有 - navigateTo(url): 导航到指定网址。 - click(selector): 点击一个CSS选择器指定的元素。 - type(selector, text): 向一个CSS选择器指定的输入框输入文本。 - getPageContent(): 获取当前页面的主要文本内容用于了解页面状态。 - getElementText(selector): 获取特定元素的文本。 - getCurrentUrl(): 获取当前页面URL。 操作规则 1. 在决定下一步动作前通常先使用getPageContent了解当前页面。 2. 使用CSS选择器来定位元素。选择器应尽量精确如#loginBtn优于button。 3. 每次调用工具后我会把工具执行的结果反馈给你。 4. 根据反馈结果判断当前子任务是否完成并决定下一步。 5. 如果工具执行失败返回错误信息请分析原因并尝试其他策略如使用不同的选择器。 6. 当用户指令中的所有任务都完成或者你判断无法继续时用一段总结性的话回复用户结束本次任务。 当前任务{userInstruction} “””; public String executeTask(String userInstruction) { log.info(“开始执行任务: {}”, userInstruction); StringBuilder fullHistory new StringBuilder(); // 初始化系统提示词 String systemMessage new SystemPromptTemplate(SYSTEM_PROMPT) .createMessage(Map.of(“userInstruction”, userInstruction)) .getContents(); // 构建ChatClient启用工具调用 var client chatClient.prompt() .system(s - s.text(systemMessage)) .advisors(new SimpleLoggerAdvisor()) // 可选用于日志记录请求响应 .tools(browserActions) // 注册工具 .build(); // 初始获取页面状态假设从某个起始页或about:blank开始 // 这里为了示例我们让Agent自己决定第一步。更复杂的实现可以预设首页。 String initialThought “我将开始执行任务” userInstruction “。首先我需要了解当前页面状态。”; fullHistory.append(“AI: “).append(initialThought).append(“\n”); // 与LLM进行多轮交互模拟思考-行动循环 // 为了示例我们限制最大交互轮数 int maxTurns 10; ChatResponse response null; for (int i 0; i maxTurns; i) { log.info(“—— 第 {} 轮交互 ——”, i 1); // 构建用户消息包含历史对话和最新的工具执行结果 String userMessageForThisTurn (i 0) ? “开始任务。” : “请根据以上工具执行结果继续下一步。”; if (fullHistory.length() 0) { userMessageForThisTurn fullHistory.toString() “\n” userMessageForThisTurn; } response client.call(userMessageForThisTurn); // 处理响应 String aiResponse response.getResult().getOutput().getContent(); fullHistory.append(“AI: “).append(aiResponse).append(“\n”); log.info(“AI 响应: {}”, aiResponse); // 检查响应中是否包含工具调用 // 在Spring AI中工具调用的结果会自动附加到下一轮对话的上下文中。 // 我们这里简化处理如果AI的响应看起来是在描述动作而非最终答案并且没有检测到明显的最终结论就继续循环。 // 更严谨的做法是解析ChatResponse中的ToolCall对象。 if (isTaskFinished(aiResponse)) { log.info(“任务完成或AI决定结束。”); break; } // 等待一小段时间模拟人类操作间隔也让页面有足够时间加载 try { Thread.sleep(1000); } catch (InterruptedException e) { Thread.currentThread().interrupt(); } } String finalResult (response ! null) ? response.getResult().getOutput().getContent() : “任务执行超时或未完成。”; log.info(“任务最终结果: {}”, finalResult); return finalResult; } private boolean isTaskFinished(String aiResponse) { // 简单的启发式规则如果AI的回复是总结性、告知性话语且不包含明显的工具调用意图则认为任务结束。 // 这是一个非常简化的实现。生产环境需要更复杂的逻辑例如检测LLM返回的特定结束标记。 String lowerResponse aiResponse.toLowerCase(); return lowerResponse.contains(“任务完成”) || lowerResponse.contains(“已完成”) || lowerResponse.contains(“无法继续”) || lowerResponse.contains(“总结”) || (lowerResponse.contains(“成功”) lowerResponse.length() 150); // 简短的成功消息 } }3.4 创建 REST 控制器提供一个简单的 HTTP 端点来触发 Agent 执行任务。// com.example.agent.controller.AgentController.java package com.example.agent.controller; import com.example.agent.service.WebAgentService; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController RequestMapping(“/api/agent”) RequiredArgsConstructor public class AgentController { private final WebAgentService agentService; PostMapping(“/execute”) public MapString, String executeTask(RequestBody MapString, String request) { String instruction request.get(“instruction”); if (instruction null || instruction.isBlank()) { return Map.of(“error”, “Instruction cannot be empty”); } String result agentService.executeTask(instruction); return Map.of(“result”, result); } }4. 运行验证与结果分析4.1 启动应用并测试确保OPENAI_API_KEY环境变量已设置或直接在application.yml中配置正确的 API Key。运行 Spring Boot 主类WebAiAgentApplication。应用启动后Playwright 会启动一个 Chromium 浏览器窗口如果headless设为false。使用curl、Postman 或任何 HTTP 客户端向http://localhost:8080/api/agent/execute发送 POST 请求。请求示例curl -X POST http://localhost:8080/api/agent/execute \ -H “Content-Type: application/json” \ -d ‘{“instruction”: “打开百度首页在搜索框里输入‘Spring AI’然后点击搜索按钮。”}’预期行为你将看到浏览器自动完成以下操作导航到https://www.baidu.com。尝试定位搜索输入框可能使用类似#kw的选择器。输入 “Spring AI”。尝试定位搜索按钮可能使用类似#su的选择器并点击。页面跳转到搜索结果页。控制台日志示例开始执行任务: 打开百度首页在搜索框里输入‘Spring AI’然后点击搜索按钮。 —— 第 1 轮交互 —— 获取页面内容长度: 1850 AI 响应: 当前页面是空白页(about:blank)。我需要先导航到百度首页。我将使用 navigateTo 工具。 —— 第 2 轮交互 —— 执行导航: https://www.baidu.com AI 响应: 已成功导航至百度首页。现在我需要找到搜索框并输入文本。我先获取一下页面内容来定位元素。 —— 第 3 轮交互 —— 获取页面内容长度: 1250 AI 响应: 我看到页面了。搜索框的CSS选择器可能是 #kw。我将尝试向它输入‘Spring AI’。 —— 第 4 轮交互 —— 在 #kw 中输入: Spring AI AI 响应: 输入成功。现在我需要找到搜索按钮并点击。按钮的选择器可能是 #su。 —— 第 5 轮交互 —— 尝试点击: #su AI 响应: 点击成功。页面应该正在跳转到搜索结果。任务完成。我已成功在百度搜索了‘Spring AI’。 任务最终结果: 任务完成。我已成功在百度搜索了‘Spring AI’。4.2 结果分析与局限性通过上述测试我们验证了 Agent 的基本工作流程理解指令 - 规划步骤导航-获取内容-定位输入框-输入-定位按钮-点击- 执行动作 - 验证结果。然而这个简易 Agent 存在明显的局限性元素定位脆弱完全依赖 LLM 从文本内容中猜测 CSS 选择器极不可靠。百度首页的选择器是已知的但对于未知网站LLM 很难猜对。状态判断简单isTaskFinished方法过于简单无法准确判断复杂任务的完成状态。无视觉感知仅依赖页面文本无法“看到”按钮、图标、验证码等视觉元素。错误处理薄弱工具调用失败后仅将错误信息返回给 LLM缺乏重试、回退等策略。提示词工程初级系统提示词可以优化例如加入更详细的动作规范、网站特定知识结构化数据等。5. 常见问题排查与优化方向在实际运行中你可能会遇到以下问题5.1 问题排查清单问题现象可能原因检查与解决思路应用启动失败提示No such beanSpring AI 或 Playwright 依赖未正确引入或版本冲突。1. 检查pom.xml依赖版本兼容性。2. 运行mvn clean compile查看编译错误。3. 确认SpringBootApplication主类位置正确。调用 API 返回 401 错误OpenAI API Key 无效或未设置。1. 检查application.yml中的spring.ai.openai.api-key。2. 确认环境变量OPENAI_API_KEY已设置并生效。3. 在 OpenAI 平台检查 API Key 的余额和状态。浏览器没有启动或瞬间关闭Playwright 浏览器配置问题。1. 检查PlaywrightConfig中setHeadless(false)是否被设置。2. 检查系统是否安装了 Chromium/Chrome。3. Playwright 首次运行会自动安装浏览器可能需要网络。查看日志。Agent 执行失败LLM 无法理解任务提示词Prompt不够清晰或指令模糊。1. 在WebAgentService的SYSTEM_PROMPT中增加更具体的例子。2. 确保用户指令是明确、可操作的网页任务。3. 尝试更换更强大的模型如gpt-4。Agent 卡住不断重复获取页面内容isTaskFinished逻辑有缺陷或 LLM 陷入循环。1. 增加交互轮数限制maxTurns并记录日志。2. 优化isTaskFinished方法或让 LLM 在最终回复中必须包含特定结束符。3. 在提示词中强调“避免重复操作”。元素定位失败点击或输入不生效LLM 猜错了 CSS 选择器或页面动态加载导致元素未就绪。1. 在工具方法中加入更详细的错误日志和等待逻辑如page.waitForSelector。2. 考虑提供更强大的页面状态描述如关键元素的 ID、Name 列表而不仅仅是全文。3.这是核心难点见下文优化方向。5.2 核心优化方向增强元素定位能力简易 Agent 最大的瓶颈是元素定位。以下是几种进阶方案方案一提供结构化页面描述在getPageContent工具中不返回纯文本而是返回一个结构化 JSON描述页面上所有可交互元素按钮、输入框、链接及其属性id, name, class, text, type。Tool(description “获取当前页面的结构化可交互元素信息”) public String getPageStructure() { // 使用 Playwright 执行 JavaScript 来收集元素信息 Object result page.evaluate(“”” () { const elements []; const interactives document.querySelectorAll(‘input, button, a, select, textarea, [role”button”]’); interactives.forEach(el { elements.push({ tag: el.tagName.toLowerCase(), id: el.id, name: el.name, classes: Array.from(el.classList), type: el.type, text: el.innerText || el.value || el.placeholder, // 计算一个简单的基于位置和属性的选择器 selector: el.id ? #${el.id} : [name”${el.name}”] || ${el.tagName}.${Array.from(el.classList)[0]} || el.tagName }); }); return JSON.stringify(elements.slice(0, 50)); // 限制数量 } “””); return “可交互元素列表: “ result.toString(); }然后在系统提示词中要求 LLM 优先使用这些结构化信息中的selector字段。方案二集成视觉模型VLM这是商用级 Agent如 Handoff可能采用的方法。对页面进行截图然后使用视觉语言模型如 GPT-4V来描述页面布局和可点击区域甚至直接输出元素的坐标或选择器。这需要集成额外的 VLM API 和图像处理逻辑复杂度较高。方案三混合定位策略结合多种方式首选固定选择器为常见网站如登录页预配置关键元素的选择器映射。回退到语义匹配使用 LLM 分析元素文本innerText和用户指令的语义相似度来选择最可能的元素。最终使用坐标点击如果以上都失败可以描述区域让用户确认或使用 VLM。5.3 生产环境考量如果计划将此类 Agent 用于更严肃的场景必须考虑以下几点稳定性与容错超时与重试为每个工具调用和 LLM 请求设置超时并实现重试机制。异常边界定义清晰的异常类型如元素未找到、网络超时、任务不可解并制定恢复策略如重置页面、重新开始子任务。状态持久化对于长任务需要保存执行状态支持断点续跑。性能与成本LLM 调用优化减少不必要的getPageContent调用使用更精简的页面描述。模型选型任务规划可以用强模型如 GPT-4简单的状态判断可以用便宜模型如 GPT-3.5-Turbo。缓存对常见页面的结构描述进行缓存。安全与权限指令过滤严格校验用户指令防止其要求访问非法网站或执行危险操作。沙箱环境在隔离的浏览器环境中运行 Agent限制其访问本地文件系统或内部网络。操作确认对于敏感操作如支付、删除设计人工确认环节。可观测性详细日志记录每一轮 LLM 的请求响应、工具调用参数和结果、页面快照或URL。链路追踪为每个用户会话生成唯一 ID便于追踪完整执行路径和排查问题。构建一个鲁棒的网页 AI Agent 是一个系统工程涉及提示词工程、大模型能力、浏览器自动化、计算机视觉和软件架构的深度融合。本文提供的简易实现揭示了其核心工作流程与挑战可以作为你深入探索的起点。从解决一个具体的、定义良好的小任务如自动填写某个固定表单开始逐步迭代其元素定位、状态判断和异常处理能力是迈向更通用 Agent 的务实路径。