人工智能AI Agent浏览器控制GUI 自动化MCP 服务【免费下载链接】browser-useAgents that use the browser.项目地址https://gitcode.com/GitHub_Trending/br/browser-use点击查看免费下载本指南以 skills/open-source/references/tools.md 为基础系统讲解 browser-use 的Tools工具体系从快速接入自定义 Action到装饰器参数、Pydantic 输入模型、browser_session等自动注入参数再到内置默认工具清单、exclude_actions裁剪方式与ActionResult全字段上下文控制策略。读完你将能够为 Agent 构建可复用的自定义浏览器操作并精确控制每一步工具结果如何进入 LLM 上下文同时理解底层Registry的注册与注入机制。快速示例10 行代码接入自定义工具Tools是 browser-use 中承载所有可调用工具Action的容器对应源码实现在 browser_use/tools/service.py。创建自定义工具的最简方式是用tools.action(...)装饰一个函数并在创建Agent时通过tools参数传入from browser_use import Tools, ActionResult, BrowserSession tools Tools() tools.action(Ask human for help with a question) async def ask_human(question: str, browser_session: BrowserSession) - ActionResult: answer input(f{question} ) return ActionResult(extracted_contentfThe human responded with: {answer}) agent Agent(taskAsk human for help, llmllm, toolstools)Warning参数名必须是browser_session: BrowserSession不能写成browser: Browser。Agent 按参数名精确注入依赖name matching名字写错会静默失败——函数拿不到浏览器会话且不抛任何异常。从源码看这一步的背后是 browser_use/tools/registry/service.py 中的Registry.action()装饰器它会通过_normalize_action_function_signature()解析函数签名把普通参数自动转成一个 Pydantic 参数模型并把browser_session这类特殊参数识别为注入参数运行时由execute_action()统一填充。因此函数签名就是你定义工具参数 Schema 的方式。添加自定义工具装饰器参数详解tools.action(descriptionFill out banking forms, allowed_domains[https://mybank.com]) async def fill_bank_form(account_number: str) - ActionResult: return ActionResult(extracted_contentfFilled form for account {account_number})装饰器参数description必填描述工具的作用LLM 依据它决定何时调用该工具。在 browser_use/tools/registry/views.py 的RegisteredAction.prompt_description()中description 会与参数 Schema 一起被格式化为action_name: description. (paramtype, ...)形式注入系统提示词所以描述越精确模型越会用对。allowed_domains限定工具可运行的域名默认不限。源码中它与domains是同一参数的两个别名若同时传两者会抛出ValueError。注册后的域名过滤在 browser_use/tools/registry/views.py 的_match_domains()与get_prompt_description()中实现当page_url已知时只有域名匹配的 Action 才会被暴露给 LLMpage_url为空如 about:blank 新标签页时受限工具一律隐藏避免fail open。param_model显式指定参数模型见下节不指定时框架根据函数签名自动生成。terminates_sequence标记该 Action 会改变页面状态如 navigate、search、go_back、switchmulti_act()在执行它后会中止队列中剩余的动作。Pydantic 输入模型当参数较多或有嵌套结构时推荐用一个 PydanticBaseModel作为输入模型让 LLM 生成结构化参数from pydantic import BaseModel, Field class Car(BaseModel): name: str Field(descriptionCar name, e.g. Toyota Camry) price: int Field(descriptionPrice in USD) tools.action(descriptionSave cars to file) def save_cars(cars: list[Car]) - str: with open(cars.json, w) as f: json.dump([c.model_dump() for c in cars], f) return fSaved {len(cars)} cars这种写法的底层逻辑在Registry._normalize_action_function_signature()每个 Action 最终都会被归一化为只接受params: ParamModel与注入参数的关键字调用内置工具的参数模型集中定义在 browser_use/tools/views.py如NavigateAction、ClickElementAction、InputTextAction等自定义工具可参照同样风格。注意返回普通str也是合法的——Tools.act()会把字符串自动包装为ActionResult(extracted_contentresult)见 browser_use/tools/service.py 的act()方法。在自定义工具中操作浏览器通过注入的browser_session可以拿到当前页面并执行交互tools.action(descriptionClick submit button via CSS selector) async def click_submit(browser_session: BrowserSession): page await browser_session.must_get_current_page() elements await page.get_elements_by_css_selector(button[typesubmit]) if not elements: return ActionResult(extracted_contentNo submit button found) await elements[0].click() return ActionResult(extracted_contentClicked!)must_get_current_page()定义在 browser_use/browser/session.py找不到当前页时会抛错页面查找方法实现于 browser_use/actor/page.pyget_elements_by_css_selector()用 CSS 选择器批量取元素get_element_by_prompt()/must_get_element_by_prompt()则用自然语言配合llm定位元素后者在找不到时直接抛异常。注入参数按名字自动填充的特殊依赖Agent 会按参数名填充函数参数。以下特殊名字会被自动注入类型定义见 browser_use/tools/registry/views.py 的SpecialActionParameters与 browser_use/tools/registry/service.py 的_get_special_param_types()参数名类型说明browser_sessionBrowserSession当前浏览器会话CDP 访问、页面操作、事件总线cdp_clientCDPClient直接访问 Chrome DevTools Protocol 客户端page_urlstr当前页面 URL域名过滤与上下文用page_extraction_llmBaseChatModel传给 Agent 的 LLM用于页面级提取file_systemFileSystem文件系统访问读写、保存提取结果available_file_pathslist[str]可用于上传/处理的文件列表has_sensitive_databool该 Action 是否包含敏感数据sensitive_datadict敏感数据字典仅input等显式声明才注入extraction_schemadictAgent 级结构化提取 SchemacontextAny用户通过Agent(context...)传入的任意上下文对象这些参数类型有严格校验Registry._get_special_param_types()定义了期望类型若函数声明了同名参数但类型不兼容例如把browser_session写成BrowserSession之外的任意类型注册时会直接抛ValueError避免运行时静默错误。页面方法通过 browser_sessionpage await browser_session.must_get_current_page() # CSS selector elements await page.get_elements_by_css_selector(button.submit) # LLM-powered (natural language) element await page.get_element_by_prompt(login button, llmpage_extraction_llm) element await page.must_get_element_by_prompt(login button, llmpage_extraction_llm) # raises if not found内置默认工具一览所有内置工具在Tools.__init__()中通过self.registry.action(...)注册完整实现见 browser_use/tools/service.py参数模型见 browser_use/tools/views.py导航与浏览器控制search— 搜索查询duckduckgo 默认、google、bing底层将编码后的查询拼接为搜索 URL 并派发NavigateToUrlEventnavigate— 跳转 URL源码内置了空 DOM 健康检查检测到空白页会等待 3 秒重试、再 reload 并等待 5 秒go_back— 历史后退wait— 等待指定秒数实现中上限 30 秒页面交互click— 按索引点击元素索引从 1 开始检测到select会自动转为获取下拉选项input— 向表单字段输入文本默认clearTrue清空后输入text仅清空、clearFalse追加upload_file— 上传文件校验文件存在于available_file_paths/下载列表/FileSystem并做路径穿越防护scroll— 按页滚动页面pages0.5-10.0支持index滚动指定元素find_text— 滚动到指定文本send_keys— 发送按键Enter、Escape、Tab、Controlo 等快捷键JavaScriptevaluate— 执行自定义 JSshadow DOM、自定义选择器、数据提取源码对执行结果做了 base64 图片识别与 2 万字符截断标签页管理switch— 按 4 位tab_id切换标签页close— 关闭标签页容忍已失效的 target_id内容提取extract— 用 LLM 从页面 Markdown 提取数据支持extract_links、extract_images查询含 image/photo 等关键词时自动开启、start_from_char续传、output_schema结构化输出JSON Schema 校验、already_collected跨页去重超过 1 万字符的结果自动落盘并通过include_extracted_content_only_once控制展示search_page— 页面文本 grep正则/大小写/上下文/css_scope范围限定零 LLM 成本find_elements— 按 CSS 选择器查询 DOM返回 tag、text、属性、子元素数零 LLM 成本视觉screenshot— 请求在下一个浏览器状态中包含截图传file_name则保存为 PNG 文件并返回路径表单控件dropdown_options— 获取下拉框选项原生select与 ARIA menu 均可select_dropdown— 按文本选择下拉选项文件操作write_file— 写文件默认覆盖appendTrue追加支持 .txt/.md/.json/.csv/.html/.xml/.pdf/.docxPDF 由 Markdown 自动转换read_file— 读文件文本、PDF、DOCX、图片replace_file— 在文件中精准替换文本任务完成done— 完成任务始终可用不可被排除传入output_model时自动切换为StructuredOutputAction结构化完成输出经过model_dump(modejson)序列化并自动附带files_to_display与会话内真实下载的文件源码中还有save_as_pdfCDPPage.printToPDF支持纸张规格、页眉页脚模板、去重文件名与navigate的new_tab参数等可自行阅读 browser_use/tools/service.py 与 browser_use/tools/views.py。移除不需要的工具两种方式都可以裁剪工具集合减少 LLM 的选择空间与 token 消耗# 方式一初始化时排除 tools Tools(exclude_actions[search, wait]) agent Agent(task..., llmllm, toolstools) # 方式二初始化后动态排除例如 use_vision ! auto 时禁用截图 tools.exclude_action(screenshot)底层实现为Registry.exclude_action()browser_use/tools/registry/service.py既会把名字加入排除列表防止重新注册也会从ActionRegistry中删除已注册项。内置的done始终保留。工具响应ActionResult 全字段控制简单返回tools.action(My tool) def my_tool() - str: return Task completed successfullyActionResult完全控制tools.action(Advanced tool) def advanced_tool() - ActionResult: return ActionResult( extracted_contentMain result, long_term_memoryRemember this for all future steps, errorSomething went wrong, is_doneTrue, successTrue, attachments[file.pdf], )ActionResult 字段ActionResult定义在 browser_use/agent/views.py字段默认值说明extracted_contentNone主结果传给 LLMinclude_extracted_content_only_onceFalse大内容只展示一次之后从上下文中丢弃long_term_memoryNone始终包含在 LLM 输入中供未来所有步骤使用errorNone错误信息未捕获异常会自动写入is_doneFalse该工具完成整个任务successNone任务是否成功仅配合is_doneTrue使用attachmentsNone要展示给用户的文件metadataNone调试/可观测性数据如点击坐标imagesNonebase64 编码的图片列表文本与图片分离处理注意一个易踩的坑ActionResult内置了一个模型校验器——successTrue只能在is_doneTrue时设置普通成功动作应把success留为None否则会抛ValueError见 browser_use/agent/views.py 的validate_success_requires_done。此外Tools.act()browser_use/tools/service.py为每个动作包了一层墙钟超时默认BROWSER_USE_ACTION_TIMEOUT_S环境变量或 180 秒tools.act(action_timeout...)可覆盖CDP WebSocket 失联时动作会以ActionResult(error...)返回而不是无限挂起。上下文控制策略在长任务中什么内容永远可见、什么只出现一次、什么只进长期记忆直接决定 token 效率与模型稳定性推荐三种策略短内容、永远可见直接返回字符串如Task completed successfully内容会始终出现在 LLM 上下文中长内容只展示一次 持久摘要extracted_content放完整大内容同时设置include_extracted_content_only_onceTrue首步可见、后续丢弃并把精炼摘要放进long_term_memory后续所有步骤持续可见。内置extract、evaluate、read_file正是这套模式的实践永不展示、只进记忆只用long_term_memory内容不进即时上下文、只作长期记忆沉淀。总结browser-use 的Tools体系把LLM 调用工具抽象成了三层tools.action装饰器负责注册与签名归一化browser_use/tools/registry/service.py按名字注入browser_session、file_system等特殊依赖ActionResult负责把执行结果按需路由到即时上下文或长期记忆。掌握了这三个层次你就能在不改框架源码的前提下为任意任务定制精准、高效、上下文可控的浏览器自动化工具。更完整的示例可参考 examples/custom-functions/ 下的actor_use.py、notification.py、file_upload.py等以及 tests/ci/infrastructure/test_registry_core.py 对注册、排除与域过滤的验证用例。赞分享人工智能AI Agent浏览器控制GUI 自动化MCP 服务【免费下载链接】browser-useAgents that use the browser.项目地址https://gitcode.com/GitHub_Trending/br/browser-use点击查看免费下载相关推荐GitHub Copilot SDK 的 Pre-Tool Use Hook在工具执行前实现权限控制、参数改写与上下文注入GitHub Copilot SDK 的 Pre Tool Use Hook在工具执行前实现权限控制、参数改写与上下文注入 onPreToolUse 是 Gi人工智能AI AgentAgent 框架工具调用Nintendo Switch自定义系统注入工具TegraRcmGUI终极指南Nintendo Switch自定义系统注入工具TegraRcmGUI终极指南 想解锁Nintendo Switch的全部潜能吗TegraRcmGUI这款基于桌面应用嵌入式Browser-Use动作系统行为定义与执行Browser Use动作系统行为定义与执行 概述 Browser Use的动作系统是项目核心功能它使AI能够像人类一样与网页交互。该系统基于事件驱动架构人工智能AI Agent浏览器控制GUI 自动化MCP 服务上一篇3步掌握YimMenuGTA5游戏安全增强与功能扩展实战指南下一篇10分钟上手Forest让Java HTTP调用像本地方法一样简单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考