LLM-as-a-Judge 智能体的 Web Search 工具设计指南：从 Zod 模式契约到研究管线落地（Agent-Skills-for-Context-Engineering 实战）

LLM-as-a-Judge 智能体的 Web Search 工具设计指南从 Zod 模式契约到研究管线落地Agent-Skills-for-Context-Engineering 实战【免费下载链接】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本文以 examples/llm-as-judge-skills/tools/research/web-search.md 的规格文档为骨架结合仓库中 Research Agent 定义、工具设计模式与 TypeScript 实现系统讲解如何为 LLM-as-a-Judge 智能体设计一个生产级 Web 搜索工具包括tool() Zod 的接口契约、输入输出模式、过滤参数、查询优化技巧与工程化落地要点。读者读完可掌握在 Agent Skills 框架下从工具规格文档到Agent 注册调用的完整设计方法。一、webSearch 在项目中的定位研究工具链的第一环在llm-as-judge-skills示例项目中Web Search 工具属于三类工具中的Research 类。项目将工具按职责划分为三个目录见 tools/index.mdEvaluation 工具tools/evaluation/directScore、pairwiseCompare、generateRubric等负责评估 LLM 输出质量Research 工具tools/research/webSearch、readUrl、extractClaims、verifyClaim、synthesize负责信息的采集、抽取、验证与综合Orchestration 工具tools/orchestration/delegateToAgent、parallelExecution、waitForCompletion等负责多智能体工作流编排。webSearch是整个研究管线的入口动作它负责找到信息随后由 read-url.md 负责读取内容、extractClaims负责抽取论点、verifyClaim负责交叉验证、synthesize负责综合成稿。这个顺序在 research-agent.md 的研究工作流图中被明确为Research Question → Query Decomposition → Initial Search → Source Selection → Deep Reading → Claim Extraction → Cross-Verification → Synthesis → Final Report其中Initial Search 与 Source Selection 两步正是 webSearch 的职责边界。需要说明的是从仓库源码结构看src/tools/下目前仅包含 evaluation 类工具的实际 TypeScript 实现如 direct-score.tsresearch 类工具以Markdown 规格文档 Agent 工具注册引用的形式定义接口契约research-agent.md 中通过researchTools.webSearch引用这恰好体现该项目先定契约、再落实现的工具开发方法论。二、工具定义AI SDKtool()与 Zod 参数契约web-search.md 使用 Vercel AI SDK 的tool()工厂函数与 Zod 模式定义工具。完整定义如下原文照录import { tool } from ai; import { z } from zod; export const webSearch tool({ description: Search the web for information on a topic. Returns relevant results with snippets and URLs. Use for gathering current information, verifying facts, or research., parameters: z.object({ query: z.string() .describe(Search query - be specific for better results), maxResults: z.number().min(1).max(20).default(10) .describe(Maximum number of results to return), filters: z.object({ dateRange: z.enum([day, week, month, year, any]).default(any) .describe(Limit results to a time period), sourceType: z.enum([all, news, academic, documentation]).default(all) .describe(Type of sources to prioritize), excludeDomains: z.array(z.string()).optional() .describe(Domains to exclude from results) }).optional() }), execute: async (input) { return performWebSearch(input); } });这段定义本身就是一个值得逐行拆解的工具设计样板description双要素既要说明工具能做什么search the web也要说明何时用gathering current information, verifying facts, or research。因为 LLM 是通过 description 来做工具选择的写清楚适用场景能显著提高 Agent 的工具路由准确率query的.describe()提示 Agentbe specific for better results引导模型在调用前把模糊问题改写成精确查询词这在多轮研究场景中尤其重要maxResults的边界约束min(1).max(20)既防止空结果集也防止单次调用拉回过多噪声结果挤占上下文窗口——这正是本项目Context Engineering理念在工具层的体现控制信息进入上下文的量就是控制上下文质量filters整体可选日期、来源类型、排除域名都属于锦上添花的过滤能力不设默认强制值保持工具对简单场景的最小调用成本。对比仓库中已落地的 direct-score.ts 可以看到同一套模式tool({ description, parameters: XxxInputSchema, execute })。该文件还把 Zod Schema 单独导出为DirectScoreInputSchema并配合z.infertypeof ...派生类型让运行时校验与编译期类型共享同一来源direct-score.ts这是 webSearch 落地时可以直接复用的组织方式。三、输入模式Input Schema逐字段解析原文档给出了输入字段总表这里逐字段展开说明取值约束与设计意图字段类型必填说明querystring是搜索查询词描述要求尽量具体以获得更佳结果maxResultsnumber否最大返回条数min(1)max(20)默认10filters.dateRangeenum否时间范围过滤可选day/week/month/year/any默认anyfilters.sourceTypeenum否来源类型优先级可选all/news/academic/documentation默认allfilters.excludeDomainsstring[]否需要从结果中排除的域名列表设计上的几个关键点maxResults的上限 20 是有意为之搜索结果会带着 snippet 摘要进入 LLM 上下文条数越多 token 消耗越大。把它限定在 20 以内是结果召回与上下文成本之间的显式平衡点sourceType是给评估类任务的关键杠杆academic适合文献综述型研究documentation适合技术方案调研news适合时效性内容核查。在 LLM-as-a-Judge 场景里用学术来源支撑事实类评分能显著提升判断的可信度excludeDomains与 Research Agent 配置形成呼应research-agent.md 中的ResearchConfig同样定义了excludedDomains: string[]与preferredSources: string[]见 research-agent.md说明来源白/黑名单是贯穿 Agent 配置与工具参数两个层面的统一设计。四、输出契约结构化结果、相关性分数与元数据web-search.md 定义了统一的返回结构这是让结果可被 LLM 直接消费的关键interface WebSearchResult { success: boolean; results: { title: string; url: string; snippet: string; source: string; // Domain name publishedDate?: string; relevanceScore: number; }[]; totalResults: number; metadata: { query: string; searchTimeMs: number; filtersApplied: string[]; }; }几个值得注意的输出设计success: boolean顶层标志让调用方无论人类还是 Agent都能先判断整体成败而不是逐个结果判断。这与 tools/index.md 中定义的统一ToolResultT模式{ success, data?, error?, metadata }一脉相承——本项目所有工具的输出都以success为第一层约定snippet摘要是给 LLM 的上下文精华在未打开原文前snippet 已足以支撑 Agent 做初筛Source Selection避免对每条结果都发起 URL 读取请求relevanceScore用于排序与取舍Agent 可以依据该分数决定读哪几个 URL从而把有限的readUrl调用预算花在最相关的来源上metadata.filtersApplied记录实际生效的过滤器便于追溯这次结果是在什么过滤条件下得到的对评估与调试都很有价值。从上下文工程的角度看这个输出结构的设计意图是把一次搜索压缩成一个自包含、可排序、可追溯的结构化摘要块让后续的readUrl、extractClaims、verifyClaim、synthesize每一步都能在其之上做增量处理而不必回溯原始查询。五、完整调用示例与返回结果解析原文档给出了一个 LLM 评估主题的搜索示例原文照录const results await webSearch.execute({ query: LLM-as-a-Judge evaluation methods 2024, maxResults: 10, filters: { dateRange: year, sourceType: academic } }); // Result: // { // success: true, // results: [ // { // title: Judging LLM-as-a-Judge with MT-Bench, // url: https://example.com/papers/judging-llm-judge, // snippet: We study the effectiveness of LLM-as-a-Judge..., // source: arxiv.org, // publishedDate: 2024-01-15, // relevanceScore: 0.95 // }, // ... // ], // totalResults: 10, // metadata: { // query: LLM-as-a-Judge evaluation methods 2024, // searchTimeMs: 342, // filtersApplied: [dateRange:year, sourceType:academic] // } // }这段示例的工程含义查询词自带年份 2024配合dateRange: year形成显式时间词 隐式时间过滤的双保险这正是Query Optimization Tips中 Recency 策略的实际应用sourceType: academic优先学术来源当研究主题是评估方法学时期望返回的是论文而非营销软文relevanceScore: 0.95表示该条结果与查询高度相关返回的 snippet 足够支撑下一步决策Agent 看到 We study the effectiveness of LLM-as-a-Judge... 后即可决定对source: arxiv.org的这条结果发起readUrl深度阅读。这种搜索 → 摘要初筛 → 精读的级联方式与 research-synthesis-prompt.md 中多来源信息 → 主题提炼 → 共识/分歧 → 行动洞察的综合范式衔接webSearch 负责把信息广度带进管线后端的 synthesize 阶段负责把广度收敛为判断深度。六、查询优化技巧让 LLM 生成更高质量的搜索词webSearch 的检索质量很大程度上取决于 Agent 生成的查询词质量。原文档给出五条优化建议Specific Terms使用精确术语用专业术语替代口语化表达例如用 position bias mitigation 而非 how judges get trickedQuotes引号锁定精确短语对需要精确匹配的短语加引号例如LLM-as-a-Judge避免搜索引擎做同义改写Operators运算符支持site:限定站点、-term排除词、OR并列词例如site:arxiv.org LLM judge OR evaluatorContext补充上下文词在查询中带上领域上下文词帮助搜索引擎理解意图例如在搜索评估方法时附加 evaluation metrics 一类限定词Recency补充年份对时效性信息显式加上年份如2024配合dateRange过滤获得最新结果。这五条技巧可以进一步包装成 Research Agent 的查询构造规范写进系统指令。参考 research-agent.md 中 Research Agent 的 instructionsBreak down complex research questions into searchable queries / Start with broad searches to understand the landscape / Narrow down to specific sources for detailed information——先宽后窄broad → narrow正是这套查询策略在 Agent 层面的制度化第一轮用宽泛查询摸清全景第二轮用精确术语、引号与运算符收缩到高质量来源。七、工程化实现要点错误处理、缓存、限流与隐私原文档对实现层面给出五项硬性要求这是把能跑的工具变成生产可用工具的分水岭Rate Limiting限流为搜索 API 设置适当的速率限制避免触发服务商限额也避免同一域名被频繁请求Caching缓存对重复查询缓存结果。搜索是研究管线中高频且昂贵的操作缓存能同时降低延迟与 API 成本Result Quality结果质量过滤低质量来源如 SEO 垃圾站可与excludeDomains配合维护一份已知低质域名黑名单Error Handling错误处理优雅处理 API 失败超时、限流、鉴权失败并在返回结果中明确呈现失败状态Privacy隐私合理记录查询日志避免把敏感查询词写入明文日志。关于错误处理仓库 tools/index.md 给出了本项目的标准错误响应模式webSearch 应当遵守同一约定interface ToolError { code: string; // Machine-readable error code message: string; // Human-readable message retryable: boolean; // Whether retry might help details?: object; // Additional context }retryable字段是关键对于限流、超时这类重试可能成功的错误调用方可以自动重试对于鉴权失败这类重试无意义的错误则应直接上报而不是空耗资源。这与 read-url.md 中定义的错误码体系如URL_NOT_FOUND、ACCESS_DENIED、TIMEOUT、BLOCKED是同一设计哲学的两种应用。从已实现的 direct-score.ts 可以看到这种错误处理的实际写法try/catch包裹核心逻辑失败时返回success: false的结构化结果而不是抛出异常中断 Agent 流程同时在metadata中记录evaluationTimeMs供观测。webSearch 的searchTimeMs正是同一套结构化结果 耗时元数据模式。八、与 Research Agent 的集成工具注册与配置注入web-search.md 定义的webSearch在 research-agent.md 中被注册进 Research Agent 的工具集import { ToolLoopAgent } from ai; import { openai } from ai-sdk/openai; import { researchTools } from ../tools; export const researchAgent new ToolLoopAgent({ name: researcher, model: openai(gpt-4o), instructions: ..., tools: { webSearch: researchTools.webSearch, readUrl: researchTools.readUrl, extractClaims: researchTools.extractClaims, verifyClaim: researchTools.verifyClaim, synthesize: researchTools.synthesize } });这段注册代码揭示了 webSearch 的使用上下文它不是独立调用的单发工具而是 Research Agent 在ToolLoopAgent循环中反复调用的研究循环组件。Agent 可以自主决定先搜几次摸清全景broad再带过滤器精搜narrow接着对命中结果调用readUrl精读最后synthesize成报告。同时Research Agent 定义了搜索相关的配置项与 webSearch 的参数形成两层配合配置项默认值与 webSearch 的对应关系maxSearchResults: number10对应maxResults默认值preferredSources: string[][]可转化为搜索时的站点偏好excludedDomains: string[][]对应filters.excludeDomainsrequireRecentSources: booleanfalse对应filters.dateRange的启用策略maxSourceAgeany对应dateRange的上限策略这种Agent 级配置研究策略 工具级参数单次执行的分层让搜索行为既能被全局策略约束又能被单次调用灵活覆盖是 agents/index.md 中Agent 是能力的组合者工具是能力的执行者这一架构思想的直接体现。九、组合使用从 webSearch 到综合报告的完整研究管线webSearch 单独使用价值有限它的威力体现在与研究工具链的组合中。仓库中可串起一条完整可运行的管线对应 research-agent.md 的工作流图Research Question ↓ Query Decomposition拆解为可搜索子问题 ↓ webSearchInitial Searchbroad → narrow带 dateRange/sourceType 过滤 ↓ Source Selection依据 snippet relevanceScore 选择来源 ↓ readUrlDeep Reading抽取正文与章节结构 ↓ extractClaimsClaim Extraction识别论点 ↓ verifyClaimCross-Verification多源交叉验证 ↓ synthesizeSynthesis综合成稿 Final Report其中readUrl见 read-url.md的 description 明确写道 Use after webSearch to get full content from relevant results即这两个工具在文档层面就约定好了先后顺序。而管线的终点 research-synthesis-prompt.md 则要求综合结果必须包含 Executive Summary、Key Themes、Areas of Consensus、Areas of Disagreement、Gaps and Limitations、Actionable Insights、Source Quality Assessment 七个部分并要求 Distinguish between facts, claims, and opinions / Note the recency and authority of sources——这些质量要求恰好是 webSearch 在采集阶段就要通过sourceType、publishedDate、relevanceScore提前打好标签的信息。采集阶段的数据质量决定了综合阶段的分析质量。十、落地检查清单基于原文档与仓库证据实现 webSearch 时的自检清单如下契约先行先用 Zod Schema 定义好输入输出照 web-search.md 的tool()模板并参照 direct-score.ts 用z.infer派生 TS 类型输出统一返回结构遵守success首层标志与metadata观测字段的约定参照 tools/index.md 的ToolResultT模式错误可重试实现{ code, message, retryable }错误结构区分可重试与不可重试失败质量与成本平衡通过maxResults上限、snippet 初筛、结果缓存控制上下文成本接入 Agent在 Agent 的tools注册表中注册并将查询构造规范具体术语、引号、运算符、年份写入 Agent instructions串起管线与readUrl、extractClaims、verifyClaim、synthesize组合使用让搜索 → 精读 → 验证 → 综合形成闭环。遵循以上检查清单即可在 Agent Skills for Context Engineering 框架内从一份规格文档出发交付一个接口清晰、错误可控、可被 LLM 高效调用的生产级 Web Search 工具。【免费下载链接】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），仅供参考