第30章 You.com 成为 Pydantic AI 能力:双 Web 搜索 Agent 实战
| 能力 | API | 作用 |
|---|---|---|
| YouSearch() | Web Search | 返回实时网页和新闻结果,每条结果附带与查询相关的摘录或整页 markdown。 |
| YouSearch() | Contents | 从指定 URL 获取干净的整页内容,格式为 HTML 或 Markdown。 |
| YouResearch() | Answer | 一次调用返回经过综合、带引用来源的答案。每条引用在返回前都会对照原文验证。You.com 报告在 SimpleQA 上达到 93.48%,p50 延迟 2.67 秒。 |
| YouResearch() | Research | 执行多步研究并返回引用充分的答案,effort 级别从 lite 到 exhaustive 可选。 |
| YouResearch() | Finance Research | 在专门的金融索引(财报、电话会议记录、分析师报告、基本面数据)上执行多步研究。 |
你也可以直接使用模型提供方的 API key(本例中是 ANTHROPIC_API_KEY),并把 Agent 字符串替换为 'anthropic:claude-sonnet-5' 或你想用的其他模型。
import logfire from pydantic_ai import Agent from pydantic_ai_harness import YouResearch, YouSearch logfire.configure() logfire.instrument_pydantic_ai() lean_agent = Agent('gateway/anthropic:claude-sonnet-5', capabilities=[YouSearch(), YouResearch()]) result = lean_agent.run_sync('What is the latest price of silver?') print(result.output) 只加一个列表项,agent 就能搜索网络了——它的工具、指令和配置都通过 capabilities=[YouSearch(), YouResearch()] 自动接线完成。 接下来加上把它变成一次调研所需的配置: import logfire from pydantic import BaseModel, ConfigDict, Field from pydantic_ai import Agent from pydantic_ai_harness import YouSearch logfire.configure() logfire.instrument_pydantic_ai() class SilverBrief(BaseModel): model_config = ConfigDict(extra='forbid') spot_price_usd_per_oz: float as_of: str = Field(description='The date and source the quoted price is from.') lean_agent = Agent( 'gateway/anthropic:claude-sonnet-5', instructions='Answer with the spot price and its date only. Do not explain what moved it.', output_type=SilverBrief, capabilities=[ YouSearch( num_results=3, extraction_mode='highlights', max_text_chars=2_000, freshness='week', ) ], ) result = lean_agent.run_sync('What is the latest price of silver per troy ounce?') print(result.output.spot_price_usd_per_oz) 三个配置项限制了 agent 能读多少内容。num_results=3 把默认的十条结果砍到三条;extraction_mode='highlights' 只返回与查询相关的摘录,而不是整页正文;max_text_chars=2_000 把任何返回内容截断到 2000 字符(默认 10000)。num_results=3 × max_text_chars=2_000 意味着不管你问什么,agent 每次调用最多只能读到 6000 字符的网页文本。freshness='week' 则把超过一周的报价挡在结果之外。 output_type=SilverBrief 把回复的形状固定为 Pydantic BaseModel,所以你拿到的是一个浮点数和日期字符串,完全按你指定的来。但它不会改变阅读量——两个版本返回同样的两个字段,只是彻底版消耗的输入多得多,成本也更高。 决定返回文本量的配置 web_search 默认使用 extraction_mode='highlights',每条结果以摘录形式返回,看 8 个来源的成本依然可控。模型随后可以用 get_page 选择精读哪些内容。如果你更想一开始就拿到完整 markdown,就切换到 extraction_mode='full_page'。 无论哪个工具,整页文本都受 max_text_chars 限制。截断保留文档开头,因为页面的导语通常承载核心信息,并附加一个 [... page text truncated at N characters] 标记,让模型知道自己拿到的只是页面的一部分。num_results 会被强制执行两次:一次在发给 You.com 的请求里,一次在响应上。 空结果不算失败。查不到东西的查询会返回 No results found for {query!r}.,模型可以转述给用户,或者换个措辞重搜。真正的问题以 ModelRetry 的形式出现:限流、URL 返回为空、You.com 拒绝某个参数、网络抖动。运行会继续,模型再试一次。而认证、计费和权限错误会直接终止运行——这些得你自己修,重试多少次都没用。 Research 及其工作量 如果一个问题预期一次调用就能解决,用 answer。如果需要多轮搜索并做综合,用 research。finance_research 是同一个循环,专门为金融分析调校过。 research 会等待结果返回,而不是返回一个待轮询的任务,深度研究通常要跑好几分钟,所以 timeout_ms 默认是十分钟。工作量通过每个能力上的 research_effort 设置:lite、standard、deep 或 exhaustive。You.com 还有一个 frontier 级别,只能作为后台任务运行,所以这里没有提供。finance_research 使用自己的 finance_effort,可选 deep 或 exhaustive。 要得到结构化的报告输出,可以给 research 传一个 JSON schema: from pydantic import BaseModel, ConfigDict from pydantic_ai_harness import YouResearch class SupplierRisk(BaseModel): model_config = ConfigDict(extra='forbid') supplier: str exposure: str sources: list[str] YouResearch( research_effort='deep', output_schema=SupplierRisk.model_json_schema(), ) 不写 extra='forbid' 的话,You.com 会拒绝这个 schema。它只接受对额外字段封闭的 schema,而这个配置就是在生成的 JSON 里写入 additionalProperties: false 的关键。漏掉它,模型会在第一次 research 调用(几分钟后)收到一个验证错误。 另一条规则在更早的阶段就会检查:You.com 在 lite effort 下会拒绝 schema,这个能力在构造时就会拦截这种组合。 你的应用可以渲染的引用 五个工具都返回 ToolReturn。模型看到的是 return_value,即文本,当工具带有引用时会附加一个 Sources: 区块。你的应用则读取 metadata['sources'],也就是与 YouSource 记录相同的来源: from pydantic_ai.messages import ToolReturnPart for message in result.all_messages(): for part in message.parts: if isinstance(part, ToolReturnPart) and part.metadata: for source in part.metadata.get('sources', []): print(source['url'], source['title']) 模型看不到 metadata,所以这些内容不会占用上下文,UI 里的脚注也不依赖模型能否准确复述 URL。web_search 还会把响应中的 search_uuid 和延迟也放进去——当某次运行出了问题、你需要就某个具体查询向 You.com 求证时,trace 里正好需要这些信息。 限定阅读范围 两个能力都接受相同的控制参数,且作用于 web_search、answer 和 research。例外是 finance_research:它只接受输入和 finance_effort,其他一概不收,所以你设置的域名过滤不会对它生效。include_domains 是白名单,不能与其他域名参数组合;exclude_domains 和 boost_domains 可以组合使用,即黑名单和重排序可以搭配。freshness 可取 day、week、month、year 或 YYYY-MM-DDtoYYYY-MM-DD 区间,country 接受两位字母代码。非法值会在构造时直接抛错。 一个 agent、两套搜索配置是常见需求:用开放网络获取背景,用少数可信域名核实要引用的内容。同一能力的两个实例会注册相同的工具名,所以把第二个用 core 的 PrefixTools 包一层: import logfire from pydantic_ai import Agent from pydantic_ai.capabilities import PrefixTools from pydantic_ai_harness import YouSearch logfire.configure() logfire.instrument_pydantic_ai() thorough_agent = Agent( 'gateway/anthropic:claude-sonnet-5', instructions=( 'You must call `research` exactly once and base the brief on what it ' 'returns; do not answer from search results alone. Use ' '`trusted_web_search` only to confirm the number you quote as the spot ' 'price, and `web_search` to survey context before the research pass.' ), output_type=SilverBrief, capabilities=[ YouSearch( num_results=8, extraction_mode='full_page', max_text_chars=20_000, freshness='week', ), PrefixTools( wrapped=YouSearch( num_results=3, include_domains=['lbma.org.uk', 'kitco.com'], guidance='', ), prefix='trusted', ), YouResearch( research_effort='deep', output_schema=SilverBrief.model_json_schema(), ), ], ) 上面的 agent 去掉了精简版的限制,增加了一个限定在两个域名内的补充搜索,并把撰写工作交给 research。 记得在被包裹的实例上设置 guidance='',或者换成一段说明何时使用这些前缀工具的文字。否则两个实例会贡献相同的默认说明段落。 同样的命名规则也是一个 agent 只配一个 web 搜索能力的原因。任何其他注册 web_search 工具的东西都会与 YouSearch 冲突,agent 会在构造时就失败,而不是等到第一次调用。如果两个都想要,用 PrefixTools 包住其中一个即可。 工具的成本 full_page、8 条结果、每条 20000 字符,意味着最高 160000 字符,而精简版是 6000。两次运行都嵌套在同一个 Logfire span 下,token 数在 trace 树上并排可见: 两次运行的区别在 capabilities 和 instructions;能力层面的差异是:| lean | thorough | |
|---|---|---|
| 检索 | highlights,3 条结果,2000 字符 | full_page,8 条结果,20000 字符 |
| 可信来源 | 无 | 对 lbma.org.uk 和 kitco.com 使用 trusted_web_search |
| 研究环节 | 无 | YouResearch(research_effort='deep') |
| lean | thorough | |
|---|---|---|
| 输入 token | 7,937 | 65,987 |
| 输出 token | 159 | 358 |
| 耗时 | 5.5s | 26.3s |
| 单次成本 | $0.01 | $0.13 |
| 工具调用 | 1 | 3 |
Harness 还处于 0.x 版本,API 在 minor 版本之间可能变化。变更会附带弃用警告,发布说明中会提供迁移指引。
research 会阻塞整个研究过程。在 deep 或 exhaustive 级别下,请把外围的请求超时按分钟而不是秒来设置。
预构建的 client 会按原样使用,超时和主机需要你自己配置。timeout_ms 只对默认 client 生效。
域名过滤器决定 agent 能看到什么,但它读到某个页面后对方能对它说什么,这并不是安全边界。
试一试 到 you.com/platform 拿一个密钥,加上你模型提供方的密钥,然后在你的 web 搜索 Pydantic AI agent 里加上 YouSearch()。用 Logfire 做插桩,查看中间的每一步、校验提示词、分析性能。一个能读网络的 agent,大约两分钟就能跑起来。 当你想要超出第一次运行的更多内容时:You.com 能力文档提供 YouSearch、YouResearch 及其工具集的完整参考。
Pydantic AI Harness 的能力文档列出了所有可用能力,为阅读和复制而写,每个能力都配有示例和工具说明。
You.com 自己维护了四份实操 cookbook,各自面向不同领域:用 research 做抗微生物药物耐药性简报、用 YouSearch 调研 K-12 教师留任率、用 finance_research 分析私募信贷,以及一个用 SubAgents 在三者之间路由的尽调台。如果你的领域更接近其中某一个,而不是通用搜索 agent,就从那里开始。
上面的每个 agent 都用 Pydantic Logfire 做了追踪,它把每次运行变成可以用 SQL 打开和查询的 trace:搜索、页面读取、重试、token 成本。调试时保持 Logfire MCP server 开着,你的 agent 还能把 trace 读给你听。
一旦 agent 开始自己选择来源,Pydantic Evals 就是你下一步需要的——这样,一次让某个问题变准的提示词改动,不会让另一个问题变糟。
如果你用它做出了不错的东西,我们想看到。Harness 在 GitHub 上,issue 是开放的,能力货架之所以不断扩充,主要是因为大家告诉我们还缺什么。欢迎来 Pydantic Slack 打个招呼。 这些 together 构成了 Pydantic Stack 的组成部分。试试吧!