SurfSense Walmart 子代理解析多代理架构下的商品数据采集与评论挖掘实战【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense导读Walmart 是美国最大的零售电商平台之一其商品详情、价格、库存与海量用户评论是产品调研、竞品分析和价格追踪的重要数据源。SurfSense 以多代理multi-agent架构组织智能体系统一个 supervisor 代理负责拆解用户问题再把具体任务委派给按数据源划分的专业子代理。本文围绕 walmart/system_prompt.md 展开完整讲解 Walmart 子代理的职责边界、可用工具walmart_scrape与walmart_reviews、执行剧本、输出契约与失败策略并结合作品仓库中的能力注册、输入/输出 Schema 与执行器源码从参数到计费逐层剖析其底层实现。读完本文你将掌握 SurfSense 中 Walmart 数据采集子代理的完整工作原理以及如何配置walmart_scrape、walmart_reviews实现商品发现、详情抓取与深度评论挖掘。一、子代理定位专业化的数据源分工1.1 从 supervisor 到专业子代理的委派模型在 SurfSense 的多代理聊天架构中Walmart 子代理位于 subagents/builtins/walmart/ 目录。根据 system_prompt.md 第 1-2 行的定义You are the SurfSense Walmart sub-agent. You receive delegated instructions from a supervisor agent and return structured results for supervisor synthesis.即Walmart 子代理不直接面向终端用户而是接收 supervisor 代理委派的指令完成数据采集后把结构化结果交还给 supervisor 做最终综合。这种一个 supervisor 多个数据源专业子代理的分工保证了商品数据、搜索结果、社媒内容等不同来源的采集逻辑彼此隔离、各自专注。与 Walmart 子代理并列的还有 amazon、google_search、reddit、indeed、youtube、tiktok、instagram、google_maps、web_crawler 等子代理Walmart 子代理只是其中专注于美国 Walmart 公开数据的那个。1.2 子代理的组装方式agent.py 中build_subagent()展示了子代理如何被组装通过read_md_file(__package__, system_prompt)读取本目录下的 system_prompt.md 作为系统提示词通过read_md_file(__package__, description)读取 description.md 作为子代理路由描述通过load_tools()装配walmart_scrape与walmart_reviews两个能力工具最后调用pack_subagent(...)打包为SurfSenseSubagentSpec交给 deepagents 运行时调度。从源码结构看每个 builtin 子代理都遵循完全相同的目录约定agent.pydescription.mdsystem_prompt.mdtools/因此 system_prompt 是子代理行为定义的核心载体而 description.md 则决定了 supervisor 在什么场景下把任务路由给这个子代理例如find X on Walmart、Walmart price of X、reviews for this Walmart product等触发语。1.3 职责边界out_of_scopesystem_prompt.md 用out_of_scope明确划定了边界不做通用网页搜索——那是 Google Search 专业子代理的职责不读取或提取任意非 Walmart 页面——这类 URL 应返回给 web crawling 专业子代理不生成交付物、不做 connector 变更——子代理只返回 findings由 supervisor 决定后续动作只处理 Walmart 公开匿名数据——绝不接触需要登录或卖家账户的内容。这条边界是理解整个多代理体系的关键每个子代理都是单数据源专家跨源需求必须回到 supervisor 层面协调。二、可用工具两个 verb 一个读者2.1 工具清单system_prompt.md 的available_tools声明了三个工具工具用途walmart_scrape商品详情与搜索/类目列表抓取walmart_reviews针对单个商品的分页深度评论抓取read_run/search_run免费读取已存储的抓取输出前两个工具来自 tools/index.py它把WALMART_SCRAPE与WALMART_REVIEWS两个能力_CI_VERBS通过build_capability_tools()包装成 LangChain 工具暴露给模型并定义NAME walmart与一个空的RULESET。也就是说子代理可用的核心动词完全由 capabilities 层的注册表驱动而不是在子代理代码里硬编码。2.2 工具使用策略playbookplaybook提供了具体的操作剧本商品发现调用walmart_scrape并传入search_terms例如[air fryer]指定商品在urls中传入 Walmart 商品 URL/ip/...或搜索/类目/浏览 URL加速列表抓取设置include_detailsfalse只返回卡片级结果不逐个打开商品详情页采样评论walmart_scrape默认携带页面上的小规模评论样本include_reviews_sampletrue评论无关时可关闭深度评论挖掘使用walmart_reviews传入商品urls或数字item_idsusItemId按需调高max_reviews并设置sort_bymost-recent、most-helpful、rating-high、rating-low批量合并把多个 URL 或搜索词合并到一次调用而不是发起多次单源调用结果读取大结果被截断时用read_run/search_run分页读取见include snippetrun_reader/对比请求结合会话中已有的历史工具结果报告具体 delta价格涨跌、评分变化、库存变化。2.3 存储结果的分页读取run_readerrun_reader.md 被以include snippetrun_reader/的方式注入系统提示词其要点是大型工具结果会被完整存储只向模型展示以run_uuid结尾的预览禁止重复调用工具来查看更多内容而应使用read_run(ref, offset, limit)分页读取每行是一个 JSON 结果项或用search_run(ref, pattern)做正则检索若单个结果项本身超出响应长度用char_offset在该行内部继续偏移读取截断提示会给出下一个值。这套机制既控制了上下文窗口的消耗又保证了结果的完整性——对包含数百条商品/评论的抓取尤其重要。三、能力注册与输入契约walmart_scrape 详解3.1 能力注册Walmart 的抓取能力在 capabilities/walmart/scrape/definition.py 中注册为名为walmart.scrape的Capabilitynamewalmart.scrapedescription抓取公开的 Walmart 商品详情、搜索/类目列表、价格、卖家、变体、库存与页面评论样本billing_unitBillingUnit.WALMART_PRODUCT按商品计费docs_url/docs/connectors/native/walmart能力注册后即可被子代理通过build_capability_tools()复用这也是 tools/index.py 能直接引用WALMART_SCRAPE的原因。3.2 输入参数ScrapeInputscrape/schemas.py 用 Pydantic 定义了ScrapeInput各字段如下参数类型默认值说明urlslist[HttpUrlStr][]Walmart 商品/搜索/类目/浏览 URL最多 20 个search_termslist[str][]搜索词最多 20 个例如air fryermax_itemsint10每个来源最多返回的商品数范围 1-100include_detailsboolTrue是否打开每个商品页抓详情设为False只返回卡片级结果include_reviews_sampleboolTrue是否附带页面上的评论样本评论无关时关闭关键校验规则_require_source第 27-35 行urls与search_terms至少提供一个否则抛错 Provide at least one URL or search term.两者数量之和不得超过MAX_WALMART_SOURCES 20。底层实现方面start_urls()方法会把每个搜索词构造成https://www.walmart.com/search?qquote_plus(term)搜索 URL与直接传入的urls合并后作为抓取起点estimated_units则按search_products direct_products计算最坏情况下的商品量并封顶在MAX_WALMART_RESULTS 1000。3.3 输出与计费ScrapeOutputScrapeOutput包含一个items: list[ProductItem]列表。根据 description.mdProductItem携带的结构化字段包括标题、item idusItemId、品牌、价格与划线价、星级评分与评论数、库存、图片、特性features、卖家与商品变体。计费上billable_units属性只统计成功的商品条目——带有error标记的条目不计费第 58-65 行。同时ScrapeOutput中的错误会以结构化 per-input 的形式返回便于子代理定位失败来源。四、深度评论挖掘walmart_reviews 详解4.1 能力注册与计费模式capabilities/walmart/reviews/definition.py 注册了walmart.reviewsbilling_unitBillingUnit.WALMART_REVIEW——按条评论计费对应配置项WALMART_MICROS_PER_REVIEW定义文件第 1-2 行注释明确说明description抓取深度分页的公开 Walmart 商品评论包含评分、正文、作者、已验证购买标记、图片与卖家回复。4.2 输入参数ReviewsInputreviews/schemas.py 定义的ReviewsInput参数类型默认值说明urlslist[HttpUrlStr][]商品 URL/ip/...或评论页 URL最多 20 个item_idslist[str][]数字型商品 idusItemId最多 20 个max_reviewsint200每商品最多返回的评论数范围 1-5000每页 10 条sort_byLiteralmost-recent排序most-recent/most-helpful/rating-high/rating-low校验规则urls与item_ids至少提供一个。两种输入最终都会解析为评论页所依赖的usItemId见sources()方法第 50-52 行。estimated_units的计算是(urls 数量 item_ids 数量) × max_reviews这正好印证了 system_prompt 中Reviews are billed per review, so keepmax_reviewsto what the task actually requires的告诫——max_reviews直接线性放大计费量代理应只按任务实际需要设置。4.3 输出与计费ReviewsOutputReviewsOutput.items直接复用抓取层的ReviewItem评论正文、评分、作者、验证购买标记、图片、卖家回复按抓取器的发射顺序排列。billable_units同样每条成功返回的评论 一个计费单位错误条目不计费。五、工具策略与失败处理5.1 工具使用策略tool_policysystem_prompt.md 的tool_policy强调三点只用available_tools中声明的工具只报告工具输出中真实存在的结果——严禁虚构标题、item id、价格、评分或评论参数合法性约束walmart_scrape至少提供urls或search_terms之一walmart_reviews至少提供urls或item_ids之一——这两条约束与前述 Pydantic 校验一一对应。5.2 失败策略failure_policy场景返回请求信息不足无可用搜索词、URL 或 item idstatusblockedmissing_fields指明缺失字段工具调用失败statuserror 简明的恢复建议next_step无有效证据statusblocked 更窄的查询建议或仍需要的范围5.3 安全要求safety证据不完整或相互矛盾时明确报告不确定性绝不把未经证实的说法当作事实陈述。六、输出契约结构化 JSON 交付6.1 返回格式output_contract要求子代理只返回一个 JSON 对象禁止输出 Markdown 或散文{ status: success | partial | blocked | error, action_summary: string, evidence: { findings: string[], sources: string[], confidence: high | medium | low }, next_step: string | null, missing_fields: string[] | null, assumptions: string[] | null }6.2 路由专属规则evidence.findings最多 10 条每条必须是描述一个独立商品、评论主题或差异delta的单句不得粘贴原始抓取载荷evidence.sources最多 10 个 URL每条 finding 对应一个如适用且每个 URL 只列出一次。6.3 通用契约output_contract_baseoutput_contract_base.md 定义了所有子代理通用的状态机规则statussuccess→next_stepnull、missing_fieldsnullstatuspartial|blocked|error→next_step必须非空next_step只能用于你自己无法完成的动作——如果下一步是自己工具的调用如用read_run/search_run分页读取存储结果、或调整参数重跑应立即执行并返回改进后的结果而不是返回partialstatusblocked且因缺失必要输入 →missing_fields必须非空assumptions记录你对用户意图的推断无推断时为null从抓取运行中引用 finding 时应把该运行标注的[n]工具结果中的 Cite this scraper run as [n]原样附加到 finding 文本保证引用在最终答案中可追溯不得伪造标签。这套契约的价值在于它把子代理的产出从自由文本规约为机器可解析的结构supervisor 可以直接消费findings/sources/confidence进行综合也能根据status/next_step/missing_fields决定重试、追问或转入其他子代理是多代理协作稳定性的关键保障。七、应用场景与最佳实践综合 description.md 与上述机制Walmart 子代理典型应用于产品调研按搜索词发现商品抓取标题、价格、评分、卖家与变体价格追踪对同一商品在会话中多次抓取报告价格涨跌 delta目录富化通过item_idusItemId对已有目录条目补充详情评论挖掘用walmart_reviews拉取大量评论分析口碑主题。最佳实践建议优先把多个搜索词/URL合并为单次调用减少往返只需列表时设置include_detailsfalse只需商品时关闭include_reviews_sample控制成本与噪声按任务实际需要设置max_reviews避免按条计费被线性放大大结果用read_run/search_run分页不要重复触发抓取工具对比类任务依赖会话内已有结果计算 delta而非重新抓取。八、总结SurfSense 的 Walmart 子代理是一个典型的单数据源专业子代理实现system_prompt.md 定义了职责、工具、剧本与输出契约capabilities/walmart/ 下的 definition/schemas 提供了walmart.scrape与walmart.reviews两个可复用能力包含严格的输入校验、批量上限20 个来源、max_items1-100、max_reviews1-5000与透明的按商品/按评论计费模型tools/index.py 则把能力注册表无缝接入 deepagents 的工具体系。理解这套提示词 能力注册 Schema 契约的组装方式也就理解了 SurfSense 整个多代理平台可扩展的专业子代理架构。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考