Agent Skills 中 Read URL 工具的设计与实践：面向 LLM-as-Judge 研究链的结构化网页内容提取

Agent Skills 中 Read URL 工具的设计与实践面向 LLM-as-Judge 研究链的结构化网页内容提取【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering导读readUrl是 llm-as-judge-skills 示例项目中 Research 工具族webSearch、readUrl、extractClaims、verifyClaim、synthesize的核心成员之一负责把给定 URL 的网页内容提取为带来源元数据的结构化文本供研究型 Agent 做深入阅读与后续的 claim 提取、交叉验证与综合归纳。本文以 tools/research/read-url.md 为骨架结合仓库中 webSearch 工具规范、Research Agent 定义 以及 TypeScript 工具实现模式完整讲解该工具的输入/输出 Schema、内容类型处理策略、错误码设计、实现注意事项以及它在多 Agent 研究流水线中的实际调用位置。读完你可以直接照搬这套工具定义搭建自己的网页阅读工具并将其接入 Agent 的检索—阅读—验证工作流。一、工具定位Research 工具链中承上启下的一环在 llm-as-judge-skills 的 Research Agent 中一个完整的研究任务被拆解为五步webSearch检索→readUrl精读→extractClaims抽取论断→verifyClaim交叉验证→synthesize综合成文。readUrl恰好处于检索命中与深入分析的衔接点上游webSearch返回带 snippet 的结果列表标题、URL、摘要、域名、相关度分数只解决有哪些相关来源的问题下游extractClaims需要的是干净可读的正文文本而不是掺杂导航、广告、侧边栏的原始 HTML——这正是readUrl的输出职责。工具的设计目的在 read-url.md 中被明确为Extract and parse content from a given URL. Returns structured text content with metadata about the source.从给定 URL 提取并解析内容返回带来源元数据的结构化文本。其 description 字段还特别强调Use after webSearch to get full content from relevant results在 webSearch 之后使用以获取相关结果的完整内容说明这两个工具是配套使用的。二、Tool 定义AI SDK Zod 的声明式工具结构readUrl采用 Vercel AI SDK 的tool()工厂函数配合 Zod 描述参数完整定义如下出自 read-url.mdimport { tool } from ai; import { z } from zod; export const readUrl tool({ description: Read and extract content from a URL. Returns the main text content, stripped of navigation and ads. Use after webSearch to get full content from relevant results., parameters: z.object({ url: z.string().url() .describe(The URL to read), contentType: z.enum([auto, article, documentation, paper, code]).default(auto) .describe(Hint for content type to optimize extraction), maxLength: z.number().min(1000).max(50000).default(10000) .describe(Maximum characters to return), extractSections: z.boolean().default(true) .describe(Whether to identify and label sections), includeMetadata: z.boolean().default(true) .describe(Include author, date, and other metadata) }), execute: async (input) { return extractUrlContent(input); } });这段定义透露出三层设计信息与仓库的 工具设计模式 相互印证description 是给模型看的路由信号tools/index.md指出工具的 description 要清晰描述工具做什么。readUrl 的 description 不仅说明功能还写明了使用时机webSearch 之后和收益去掉导航与广告帮助模型在webSearch、readUrl、verifyClaim等多个工具间做出正确选择。Zod 负责类型安全与默认值所有可选参数都通过.default()提供默认值模型不传参也能安全执行z.string().url()在入口处就拦截非法 URL。这与仓库中src/tools/evaluation/direct-score.ts用DirectScoreInputSchema定义输入、z.infer推导类型的做法完全一致。execute 只做一件事把经过校验的输入转交给extractUrlContent内部实现。execute与参数校验、提取逻辑的职责分离是 tools/index.md 中Standard Tool Structure推荐的写法。三、输入参数详解Input Schemaread-url.md 给出的输入参数表如下结合 Tool 定义可以补充取值约束与默认值字段类型必填说明约束 / 默认值urlstring是要读取的 URL必须通过z.string().url()校验非法 URL 在进入 execute 前即被拒绝contentTypeenum否内容类型提示用于优化提取策略auto默认/article/documentation/paper/codemaxLengthnumber否返回的最大字符数默认10000范围1000 ~ 50000z.number().min(1000).max(50000)强制约束extractSectionsboolean否是否识别并标记章节默认true输出中对应content.sections字段includeMetadataboolean否是否包含作者、日期等元数据默认true输出中对应metadata字段参数设计中值得注意的两个工程细节maxLength 的上下限最小 1000、最大 50000 字符的约束既防止模型给出过小的截断值导致正文不完整也限制单次返回过大避免撑爆上下文窗口。这体现了工具输出要服务于上下文工程的思想——在 context-fundamentals 技能中有效管理上下文是核心原则控制读取长度正是其落地手段。contentType 是提示而非开关它只是 hint提示用于让提取器选择更合适的解析策略即便模型猜错类型auto模式下的自动探测仍然兜底。四、输出结构详解Output SchemareadUrl返回结构化结果完整接口如下出自 read-url.mdinterface ReadUrlResult { success: boolean; url: string; title: string; content: { full: string; sections?: { heading: string; level: number; // h11, h22, etc. content: string; }[]; }; metadata?: { author?: string; publishedDate?: string; lastModified?: string; description?: string; keywords?: string[]; source: string; }; stats: { totalCharacters: number; truncated: boolean; sectionsFound: number; }; error?: { code: string; message: string; }; }这个输出结构是刻意面向研究型 Agent设计的几个字段各有用途输出区块字段对下游研究流程的意义顶层success/url/title快速判断读取成败、确认来源身份便于引用溯源content.full去除导航广告后的正文直接作为extractClaims的输入文本content.sections带 heading 与 level 的章节数组支持按章节检索Agent 可只针对命中章节做细读metadataauthor / publishedDate / lastModified / description / keywords / source供研究综合synthesis阶段评估来源权威性与时效性statstotalCharacters / truncated / sectionsFound暴露截断状态防止 Agent 误把不完整内容当全文引用errorcode / message机器可读的错误码供上层做重试或降级决策其中metadata和stats与 Research Agent 的质量标准直接呼应该 Agent 的指令要求note the recency and authority of sources记录来源的时效性与权威性publishedDate、source字段正是为此提供数据而 research-synthesis-prompt.md 在综合阶段要求标注每条 finding 的来源、日期与类型同样依赖这里的 metadata。五、完整使用示例官方使用示例如下出自 read-url.mdconst content await readUrl.execute({ url: https://eugeneyan.com/writing/llm-evaluators/, contentType: article, maxLength: 15000, extractSections: true, includeMetadata: true }); // Result: // { // success: true, // url: https://eugeneyan.com/writing/llm-evaluators/, // title: Evaluating the Effectiveness of LLM-Evaluators, // content: { // full: LLM-evaluators, also known as LLM-as-a-Judge..., // sections: [ // { // heading: Key considerations before adopting an LLM-evaluator, // level: 2, // content: Before reviewing the literature... // }, // ... // ] // }, // metadata: { // author: Eugene Yan, // publishedDate: 2024-06-15, // source: eugeneyan.com // }, // stats: { // totalCharacters: 15000, // truncated: true, // sectionsFound: 8 // } // }示例选用的 eugeneyan.com 这篇文章正是本示例项目 README 所依据的 LLM-Evaluators 研究来源用它做演示既真实又贴合研究素材阅读的场景。注意示例中totalCharacters: 15000与truncated: true当maxLength设为 15000 而正文实际更长时工具会截断并明确标记下游 Agent 需要感知这一信号避免把片段当全文。在实际的 Agent 调用链中这个工具通常不是被直接execute而是由 Research Agent 通过tools注册表调用tools: { webSearch: researchTools.webSearch, readUrl: researchTools.readUrl, extractClaims: researchTools.extractClaims, verifyClaim: researchTools.verifyClaim, synthesize: researchTools.synthesize }见 research-agent.md。模型会在webSearch拿到结果列表后挑选高相关度 URL 调用readUrl获取全文再交给extractClaims。六、Content Type Handling五种内容类型的提取策略针对不同网页形态readUrl提供不同的提取优化策略出自 read-url.md类型优化策略article优先提取正文跳过侧边栏Prioritize main content, skip sidebarsdocumentation保留代码块维持文档结构Preserve code blocks, keep structurepaper抽取摘要、章节与参考文献Extract abstract, sections, referencescode保留格式与语法高亮Preserve formatting, syntax highlightingauto从内容中自动探测类型Detect type from content这五种策略对应的核心诉求是**按内容形态调整信息保真度**文章article场景下导航、侧边栏、推荐位是噪声应尽可能剥离技术文档documentation场景下代码块与层级结构是信息主体必须原样保留——这与仓库 context-fundamentals 中保留代码结构供模型理解的原则一致论文paper场景下摘要、章节、参考文献是后续 claim 验证的重要锚点代码code场景下格式与高亮直接影响可读性。模型只需提供 contentType hint具体解析逻辑由实现方示例中为extractUrlContent分派。从仓库结构看readUrl属于工具规范文档MD 实际 TypeScript 实现双轨模式规范在 tools/research/read-url.md而同类工具的落地方案可参考 src/tools/evaluation/direct-score.ts 中tool({...})execute的写法。七、错误处理面向重试与降级的错误码设计readUrl定义了六种机器可读错误码出自 read-url.mdconst errorCodes { URL_NOT_FOUND: Page does not exist (404), ACCESS_DENIED: Page requires authentication (401/403), TIMEOUT: Request timed out, BLOCKED: Access blocked by robots.txt or rate limit, INVALID_CONTENT: Content could not be parsed, UNSUPPORTED_TYPE: Content type not supported (e.g., binary) };这套错误码设计遵循 tools/index.md 中定义的ToolError模式interface ToolError { code: string; // Machine-readable error code message: string; // Human-readable message retryable: boolean; // Whether retry might help details?: object; // Additional context }每种错误的可重试性不同Agent 的应对策略也应不同错误码含义建议策略URL_NOT_FOUND页面 404 不存在不重试报告来源失效改选其他候选 URLACCESS_DENIED需要认证401/403不重试跳过该来源或换镜像/缓存版本TIMEOUT请求超时可重试配合退避或换更短 maxLength 再试BLOCKED被 robots.txt 或限流拦截不立即重试放慢频率或更换 UA 后隔段时间再试INVALID_CONTENT内容无法解析不重试该来源 HTML 结构异常换源UNSUPPORTED_TYPE内容类型不支持如二进制不重试改请求 PDF/文本版本接口在 Research Agent 的质量标准里Never fabricate information or sources绝不编造信息或来源与clearly indicate when information is uncertain明确标示不确定信息是硬性要求而 readUrl 的error.code正是让 Agent 能够准确表达这个来源读不到/读不全的依据避免把失败伪装成成功结果。八、实现注意事项做一名礼貌且可靠的网络读者read-url.md 的 Implementation Notes 给出六条生产级实现规范逐条解读如下Respect robots.txt读取并遵守目标站点的 robots.txt 指令。这既是法律与道德义务也是避免被封禁的前提——与错误码BLOCKED直接相关。Rate Limiting不要对同一域名发起高频请求Dont hammer the same domain。建议按域名维护请求队列与最小间隔配合滑动窗口限流。User Agent使用合适的 UA 字符串。清晰标识自己是研究型 Agent 的抓取工具并附带联系方式比伪装浏览器更合规也更不容易被 WAF 误伤。Timeouts设置合理超时10~30 秒。超时过长会拖慢整个研究流水线过短又容易误杀慢速站点10~30s 是文档给出的经验区间超时后返回TIMEOUT错误码。JavaScript Rendering对 JS 重渲染的站点如 SPA纯 HTTP 抓取拿不到正文需要评估使用 headless browser如 Playwright/Puppeteer渲染后再提取。代价是更高延迟与资源开销建议仅在auto探测失败或显式标记时启用。Caching对重复读取做内容缓存。研究流水线中同一 URL 可能被多次访问如多轮验证缓存正文与 metadata 能显著降低延迟与对源站的打扰与webSearch工具的缓存建议保持一致见 web-search.md 的 Implementation Notes 第 2 条。从仓库现状看这六条是工具规范的约定层内容具体落地取决于实际实现当把readUrl接入生产环境时建议同时为extractUrlContent补充日志与指标单次提取耗时、截断比例、错误码分布以便持续调优。九、在流水线中与其他工具协同readUrl的价值只有在完整研究流水线中才能最大化。以下是 Research Agent 文档中定义的五步工作流research-agent.mdreadUrl服务于EDeep Reading环节其前后衔接如下C → DInitial Search → Source SelectionwebSearch按 query 返回结果与relevanceScoreAgent 据此筛选要精读的 URL 清单EDeep Reading对每个入选 URL 调用readUrl得到干净正文 章节 metadataFClaim Extraction把content.full与sections交给extractClaims抽取带置信度的论断GCross-Verification论断与metadata.publishedDate、source一起参与verifyClaim的交叉验证时效性与权威性成为置信度评估的输入HSynthesis最终由 research-synthesis-prompt.md 综合其模板要求每条 finding 携带 source/date/type——恰好是readUrl输出的metadata与stats所提供的字段。也就是说readUrl输出的结构化程度直接决定了整条流水线后续环节的质量content.sections支撑章节级引用、metadata支撑来源评估、stats.truncated防止误引不完整内容、error.code支撑失败降级。这也是它在 tools/index.md 的 Research 工具类别中被列为webSearch之后首选工具的原因Find information → webSearch, readUrl。十、结语把 readUrl 的设计思想迁移到自己的 Agent 系统回顾readUrl这个工具其值得复用的设计要点可以总结为四条用 description 承载路由语义一句话说清做什么、什么时候用、带来什么好处让模型在多工具场景下正确选择用 Zod 承载约束与默认值非法输入在入口拦截可选参数全部有安全默认值maxLength的 min/max 限制从源头控制上下文占用用结构化输出承载下游需求正文、章节、元数据、统计、错误码分而治之每个下游环节抽取、验证、综合都能拿到恰好需要的字段用错误码承载失败语义可重试与不可重试的错误清晰区分让 Agent 能做重试、换源、降级等理性决策。如果你正在构建自己的研究型 Agent例如 LLM-as-a-Judge 评测前的资料收集阶段可以直接照搬 read-url.md 的工具定义与错误码约定配合 web-search.md 完成检索—精读闭环再接入 research-synthesis-prompt.md 完成带引用的综合报告。更完整的工程落地方案含真实 TypeScript 实现与测试可继续查阅 src/tools/evaluation/direct-score.ts 与 tests 目录作为扩展同族工具时的参照。【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考