进阶 pydantic.dev 2026-11-20 05:57:40 · 5 阅读

第30章 You.com 成为 Pydantic AI 能力:双 Web 搜索 Agent 实战

Pydantic AI Harness 现已集成 You.com 提供的两个全新 web 搜索能力:YouSearch 和 YouResearch。每个能力都带有实时、LLM 可直接使用的 web 搜索 API,支持面向 agent 工作流的深度研究。 五个 API,两种能力。YouSearch 负责检索和阅读,YouResearch 负责解决一次查询搞不定的问题。
能力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在专门的金融索引(财报、电话会议记录、分析师报告、基本面数据)上执行多步研究。
下面介绍每个部分的工作方式,以及在你的 agent 开始替你阅读开放网络之前需要做哪些配置。 两个 agent,同一个问题,8 倍的输入 token 为了对比这两种能力,我们让两个 agent 运行同一个提示词:白银每金衡盎司的最新价格是多少。 这是完整的 gist。运行方法见下文说明,本文就是对该 gist 代码的详细讲解。 在这个例子中,精简版 agent 只做一次搜索,取 3 条结果、每条上限 2000 字符,成本约 $0.01。彻底版 agent 取 8 条结果并用 full_page,还会做一次用 PrefixTools 包裹并限定在你添加的两个域名内的补充搜索,再由 YouResearch 返回一份结构化的简报,成本约 $0.13。两者返回同样的两个字段——价格和日期——并且都嵌套在同一个 Logfire span 下,费用直接从 trace 树上就能看清。 入门 先安装所需的库。我使用 Pydantic AI 作为 agent 框架,Pydantic Logfire 作为可观测层,Anthropic 作为模型提供方。 uv add "pydantic-ai-harness[youdotcom,anthropic]" "pydantic-ai-slim[logfire]" 在 you.com/platform 创建你的访问密钥,以及模型提供方的密钥,然后导出: export YDC_API_KEY='your-you-com-api-key' export PYDANTIC_AI_GATEWAY_API_KEY='your-gateway-api-key' 本例中,模型提供方使用 Pydantic AI Gateway,即 PYDANTIC_AI_GATEWAY_API_KEY。设置密钥的方法是:在 Logfire 中启用 Gateway,点击 API Keys 标签页,如下方视频所示。你可以自带密钥(BYOK)配置自定义 provider,也可以直接用 Logfire 内置的 provider 创建密钥。这样可以无缝切换模型、设置消费上限、按密钥或项目分配预算等。

你也可以直接使用模型提供方的 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;能力层面的差异是:
leanthorough
检索highlights,3 条结果,2000 字符full_page,8 条结果,20000 字符
可信来源无对 lbma.org.uk 和 kitco.com 使用 trusted_web_search
研究环节无YouResearch(research_effort='deep')
每次运行都在同一分钟内背靠背调用两个 agent,所以精简版和彻底版的数据来自同一时刻的网络。下面的数字来自五次这样的运行,标题数字是五组比值的中位数。
leanthorough
输入 token7,93765,987
输出 token159358
耗时5.5s26.3s
单次成本$0.01$0.13
工具调用13
同样的两个字段,输入是 8 倍。五次运行的成对比值从 5.4x 到 11.8x 不等,中位数 8.2x。 其中大部分来自一次工具调用。research 的中位耗时是 16.3 秒,占彻底版总耗时的 62%,token 差异也主要来自它。 instructions 决定这个昂贵的工具会不会被调用,research_effort 只决定调用之后跑多久。用上面的措辞,五次运行都调用了 research,彻底版的输入 token 波动仅 1.4%,从 65,075 到 67,698。 同样五次运行中,精简版的输入 token 在 5,581 到 12,160 之间波动,因为没有任何东西能锚定 highlights 搜索的返回量——除非 agent 调用时网络恰好给了什么。 七分钟内的五次运行衡量的是配置本身,衡量不了白银真正波动的那一天两个 agent 的表现。 这笔交易划不划算,是留给人类决策的问题。彻底版会引用来源,并用一个域名核实报价;精简版五秒内就从开放网络返回一个数字。 为什么这个组合好用 一个会阅读网络的 agent,它的答案就依赖于你无法控制的东西。页面会变,搜索可能返回奇怪的结果,摘要可能悄悄丢掉那条真正重要的来源。但这些都不必靠猜。工具定义是带类型的,输出是经过校验的,格式错误的结果会在你看得见的地方失败;Pydantic Logfire 则保留回执:哪些查询执行了、返回了什么、哪些页面被完整读取、整个运行花了多少钱。 You.com 的贡献在于,它的检索本身就能区分摘录、整页和研究结果,你的 agent 代码不必在单一搜索端点之上自己发明这些区分。 上线前需要注意几点:

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 的组成部分。试试吧!

评论 (0)