基于 Vercel AI SDK 构建 Research Agent：多源检索、事实核验与引文追踪的完整实现指南（Agent-Skills-for-Context-Engineering）

基于 Vercel AI SDK 构建 Research Agent多源检索、事实核验与引文追踪的完整实现指南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示例仓库中的 Research Agent 设计文档为主体系统讲解如何在 Vercel AI SDK 6 的ToolLoopAgent架构上实现一个具备查询分解、多源检索、声明抽取、交叉核验与综合归纳能力的自动化研究智能体。你将掌握其 Agent 定义、五大工具契约、ResearchConfig全部配置项、研究流水线与引用追踪机制并能结合仓库中的工具规格文档与配置源码直接落地到自己的研究型系统中。一、Research Agent 在项目中的定位在examples/llm-as-judge-skillsLLM-as-a-Judge 技能示例中Research Agent 与 Evaluator Agent、Orchestrator Agent 共同构成一套三 Agent 协作体系。它承担的是多 Agent 流水线的信息上游职责——先收集与核验事实再由 Evaluator 评估输出质量由 Orchestrator 负责任务分解与结果汇总。依据 agents/index.md 的说明Research Agent 的核心定位是Gather, verify, and synthesize information from multiple sources从多个来源收集、核验并综合信息。它最适用于知识库建设、事实核查、市场调研与技术文档撰写四类场景。本文所讲解的 Agent 定义、工具与配置均位于 research-agent.md其配套的详细工具规格见 tools/research/ 目录。二、Agent 定义基于 ToolLoopAgent 的声明式实现Research Agent 直接复用 Vercel AI SDK 6 的ToolLoopAgent抽象通过instructions注入研究方法论通过tools声明工具集无需手写循环控制逻辑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: You are an expert research analyst. Your role is to: 1. Break down complex research questions into searchable queries 2. Gather information from multiple sources 3. Verify and cross-reference claims 4. Synthesize findings into coherent summaries 5. Provide proper citations for all claims Research Methodology: - Start with broad searches to understand the landscape - Narrow down to specific sources for detailed information - Always verify facts from multiple sources when possible - Distinguish between facts, claims, and opinions - Note the recency and authority of sources Quality Standards: - Never fabricate information or sources - Clearly indicate when information is uncertain - Provide direct quotes when precision matters - Include source URLs/references for verification, tools: { webSearch: researchTools.webSearch, readUrl: researchTools.readUrl, extractClaims: researchTools.extractClaims, verifyClaim: researchTools.verifyClaim, synthesize: researchTools.synthesize } });值得注意的两点设计模型选择该示例使用openai(gpt-4o)。仓库中的 src/config/index.ts 表明模型名可通过环境变量OPENAI_MODEL覆盖默认gpt-4o而密钥通过OPENAI_API_KEY注入validateConfig()会在缺少密钥时抛出明确错误。这与 README 中OPENAI_MODELgpt-5.2的示例并不冲突——这正说明模型是可配置的。指令即方法论instructions不是简单的角色描述而是把先宽后窄、多源核验、区分事实/主张/观点、标注来源时效与权威性等研究规范编码进了系统提示确保模型在工具循环中遵循一致的研究纪律。三、五大研究工具的能力契约Research Agent 通过五个工具覆盖检索 → 阅读 → 抽取 → 核验 → 综合的完整链路。仓库在 tools/research/web-search.md 与 tools/research/read-url.md 中给出了前两个工具的完整规格其余工具在 research-agent.md 的能力章节定义了输入输出契约。3.1 Web SearchwebSearch输入搜索查询字符串可选的时间范围/来源类型过滤器。输出相关结果列表含 snippet 与 URL、来源元数据。配套规格文档将其参数 Schema 细化为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), sourceType: z.enum([all, news, academic, documentation]).default(all), excludeDomains: z.array(z.string()).optional() }).optional() })每个结果包含title / url / snippet / source域名/ publishedDate? / relevanceScore整体返回success / results / totalResults / metadatametadata 中记录query、searchTimeMs与已生效的filtersApplied。规格文档还给出 5 条查询优化建议使用精确术语、用引号锁定短语、支持site:、-term、OR操作符、携带上下文词、加年份提升时效性。实现层面则要求做好限流、缓存、低质来源过滤、API 失败优雅降级与查询日志隐私。3.2 URL ReadingreadUrl输入目标 URL内容类型article / paper / documentation 等。输出抽取后的文本内容、识别出的关键章节、出版元数据。其 Zod Schema 定义了五个参数参数类型默认值说明urlstring须为合法 URL—要读取的地址contentTypeenumautoauto / article / documentation / paper / code用于优化抽取策略maxLengthnumber1000–5000010000最大返回字符数extractSectionsbooleantrue是否识别并标注章节标题includeMetadatabooleantrue是否返回作者、日期等元数据不同内容类型的抽取策略也不同article优先主内容、跳过侧栏documentation保留代码块与结构paper抽取摘要、章节与参考文献code保留格式与语法高亮auto自动探测。输出结构包含content.full、按 heading 分层的content.sections[]、metadataauthor / publishedDate / lastModified / keywords / source以及statstotalCharacters / truncated / sectionsFound。错误处理方面定义了标准错误码URL_NOT_FOUND404、ACCESS_DENIED401/403、TIMEOUT、BLOCKEDrobots.txt 或限流、INVALID_CONTENT、UNSUPPORTED_TYPE如二进制。实现时还需遵守 robots.txt、限制对同一域名的请求频率、设置 10–30 秒合理超时并对 JS 重度渲染站点考虑无头浏览器。3.3 Claim ExtractionextractClaims输入来源文本要抽取的声明类型。输出声明列表、每条声明的置信度与支撑上下文。它负责把一段文本拆解为可独立核验的最小事实单元claim并标注置信度——这是后续交叉验证的数据基础。3.4 Claim VerificationverifyClaim输入待核验的声明原始来源。输出核验状态、支持/矛盾的来源列表、置信度评估。该工具对应了 Agent 指令中Always verify facts from multiple sources when possible的质量标准是防止单一来源偏差的关键环节。3.5 Synthesissynthesize输入研究成果目标格式需要回答的关键问题。输出综合摘要、关键洞察、来源引用。综合环节并非简单拼接而是要求归纳共识与分歧、标注不确定性并给出可行动结论。仓库在 prompts/research/research-synthesis-prompt.md 中提供了配套的综合提示模板我们将在第五节详细展开。四、ResearchConfig配置项与默认值全解析research-agent.md给出了完整的ResearchConfig接口及默认值分为三组interface ResearchConfig { // Search configuration maxSearchResults: number; preferredSources: string[]; excludedDomains: string[]; // Verification settings minSourcesForVerification: number; requireRecentSources: boolean; maxSourceAge: 1month | 6months | 1year | any; // Output configuration citationStyle: inline | footnote | endnote; summaryLength: brief | standard | comprehensive; includeSourceQuality: boolean; } const defaultConfig: ResearchConfig { maxSearchResults: 10, preferredSources: [], excludedDomains: [], minSourcesForVerification: 2, requireRecentSources: false, maxSourceAge: any, citationStyle: inline, summaryLength: standard, includeSourceQuality: true };各配置项含义与实用建议配置项默认值作用与建议maxSearchResults10单次搜索返回结果上限。建议结合场景调整宽泛背景调研可取更大值精确事实核验 5–10 条即可。对应 webSearch 工具maxResults1–20的上层约束preferredSources[]优先来源白名单如arxiv.org。当研究问题对来源权威性敏感时如学术主题应优先配置excludedDomains[]排除域名黑名单可直接映射到 webSearch 的filters.excludeDomains用于过滤低质站点minSourcesForVerification2声明核验所需的最少独立来源数。取 2 是至少双源印证的平衡点提高它可增强结论可靠性但会显著增加检索成本requireRecentSourcesfalse是否强制要求近期来源。对时效敏感的主题技术趋势、市场行情建议开启maxSourceAgeany来源最大可接受时效枚举1month / 6months / 1year / any。与上项配合使用citationStyleinline引用风格inline文中内联、footnote脚注、endnote尾注summaryLengthstandard摘要长度brief / standard / comprehensiveincludeSourceQualitytrue是否在输出中包含来源质量评估对应综合报告中的 Source Quality Assessment 章节五、研究综合提示模板与引用机制综合环节的提示模板research-synthesis-prompt.md定义了稳定的输出骨架确保不同研究任务产出结构一致的报告。模板要求综合必须覆盖Executive Summary2–3 句话的关键发现概览Key Themes跨来源涌现的主要主题Findings by Topic按研究问题组织的分主题发现Areas of Consensus多来源一致之处Areas of Disagreement来源冲突或分歧之处Gaps and Limitations未回答的问题与信息局限Actionable Insights可落地的实用结论Source Quality Assessment来源可靠性与相关性评估模板使用 Mustache 风格变量渲染核心变量为research_question与findings数组每个元素含source / date / type / content。在判断标准上给出 5 条最佳实践主题提炼需基于 3 个以上来源、事实类主张以学术来源优先于博客、标注发现可能过时、不夸大来源未支撑的结论、以实用 takeaways 收尾。三种引用风格风格格式适用Inline默认Finding or claim [Author/Source, Date]通用场景读者可即时定位出处FootnoteFinding or claim[1] 文末脚注列表报告、出版物风格EndnoteFinding or claim (see Sources: Source Name) Sources 列表需要集中引用区时六、研究流水线从问题到最终报告research-agent.md用 Mermaid 图完整定义了八阶段流水线Query Decomposition查询分解对应指令中Break down complex research questions into searchable queries把复合问题拆为多个可检索子查询Initial Search初始检索先宽泛搜索以理解领域全貌对应 webSearch 的Start with broad searchesSource Selection来源选择结合preferredSources、excludedDomains、relevanceScore与来源权威性筛选Deep Reading深度阅读对选中来源执行 readUrl 抽取正文Claim Extraction声明抽取将正文拆解为带置信度的独立声明Cross-Verification交叉核验对每条声明用minSourcesForVerification默认 2个独立来源验证Synthesis综合归纳按第五节模板生成结构化报告Final Report最终报告输出含完整引用的结论。七、使用示例一次完整的自动调研research-agent.md给出的调用方式非常简洁——只需传入一个自然语言 promptAgent 会在工具循环中自行完成上述流水线import { researchAgent } from ./agents/research-agent; const research await researchAgent.generate({ prompt: Research the current state of LLM evaluation methods. I need to understand: 1. What are the main approaches to evaluating LLM outputs? 2. What are the limitations of human evaluation? 3. How reliable are LLM-based evaluators compared to humans? 4. What are best practices for implementing LLM-as-a-Judge? Provide a comprehensive summary with citations. });这里展示了一个高质量研究 prompt 的写法先给出研究主题LLM evaluation methods 的现状再以编号问题明确信息需求最后声明输出要求comprehensive summary with citations。ToolLoopAgent会自动循环调用webSearch → readUrl → extractClaims → verifyClaim → synthesize直到产出满足指令约束的结果。八、与其他 Agent 的集成方式8.1 被 Orchestrator 委托调用Research Agent 是 Orchestrator 声明的四个可委托 Agentevaluator / researcher / writer / analyst之一见 tools/orchestration/delegate-to-agent.md。委托时需传入完整上下文、期望输出格式与成功标准例如await delegateToAgent.execute({ agentName: researcher, task: Research current best practices for LLM evaluation, context: { constraints: [Focus on 2024 publications, Include citations] }, expectedOutput: { format: markdown } });8.2 四种典型集成场景research-agent.md的 Integration Points 章节给出了四类落地场景Knowledge Base Building知识库建设将研究成果沉淀为内部知识存储可为 skills/context-fundamentals 所讲的上下文工程提供事实底座Fact Checking事实核查核验生成内容中的声明可与 Evaluator Agent 配合形成生成—核验—评估闭环Market Research市场调研采集竞争情报与行业动态Technical Documentation技术文档调研实现方案与最佳实践支撑文档撰写。在 Orchestrator 的典型编排中Research Agent 通常处于流水线首段Sequential Pipeline 的Task → Research Agent → Analyst → Writer → Evaluator或在并行扇出模式中与其他 Agent 并行执行后汇聚到合成阶段。九、落地与运行前提当前仓库中Research Agent 以完整的 Agent 定义与工具规格文档形式呈现agents/research-agent/research-agent.md、tools/research/而src/tools/目录下目前包含的是evaluation 类工具direct-score / pairwise-compare / generate-rubric的 TypeScript 实现研究类工具webSearch、readUrl 等在仓库中停留在规格文档层面需要按上述 Schema 自行接入具体的搜索与抓取服务。运行本项目的前提条件依据 README.md 与 src/config/index.ts在项目根目录创建.env配置OPENAI_API_KEY必填缺失时validateConfig()会抛错与OPENAI_MODEL可选默认gpt-4o执行npm install安装依赖npm test运行测试套件若要启用 Anthropic 模型如 Evaluator/Orchestrator 示例中的claude-sonnet-4-20250514还需配置ANTHROPIC_API_KEY。十、小结Research Agent 的设计展示了如何用声明式方式构建一个严谨的研究型 AgentToolLoopAgent负责循环控制instructions承载研究方法论与质量标准五工具契约覆盖检索—阅读—抽取—核验—综合全链路ResearchConfig把来源偏好、核验强度与引用风格参数化综合提示模板则保证不同任务产出结构一致、可引用的报告。对任何需要可靠信息采集与事实核验能力的 Agent 系统这套架构都提供了可直接借鉴的完整范式。【免费下载链接】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），仅供参考