{"slug": "you-com-is-now-a-pydantic-ai-capability", "title": "You.com is now a Pydantic AI capability", "summary": "Pydantic AI Harness now integrates You.com's YouSearch and YouResearch web search capabilities, providing real-time LLM-ready access and deep research for agentic workflows. You.com reports 93.48% on SimpleQA at a p50 of 2.67 seconds for its Answer API. The integration includes five APIs across two capabilities, with costs ranging from about $0.01 for a lean agent to $0.13 for a thorough agent.", "body_md": "[Pydantic AI Harness](https://pydantic.dev/docs/ai/harness/overview/) now has two new web search capabilities from [You.com](https://you.com/?utm_source=pydantic&utm_medium=partnership&utm_campaign=youdotcom-pydantic-ai-harness), `YouSearch`\n\nand `YouResearch`\n\n. Each one comes with web search APIs that provide real-time LLM-ready access to the web and perform deep research for agentic workflows.\n\nFive APIs, two capabilities. `YouSearch`\n\nfor surveying and reading, `YouResearch`\n\nfor the questions a single lookup cannot settle.\n\n| Capability | API | What it does |\n|---|---|---|\n`YouSearch()` |\nWeb Search | Returns real-time web and news results, with query-relevant excerpts or full-page markdown attached to each result. |\n`YouSearch()` |\nContents | Gets clean, full-page content from a URL as HTML or Markdown. |\n`YouResearch()` |\nAnswer | Returns a synthesized, citation-grounded answer in one call. Every citation is verified against the source text before the answer comes back. You.com reports 93.48% on SimpleQA at a p50 of 2.67 seconds. |\n`YouResearch()` |\nResearch | Runs multi-step research and returns a well-cited answer, with effort levels from `lite` to `exhaustive` . |\n`YouResearch()` |\nFinance Research | Multi-step research over a dedicated financial index of filings, transcripts, analyst coverage, and fundamentals. |\n\nHere is how each part works, and what to set before an agent starts reading the open web on your behalf.\n\nTwo agents, same question, 8x more input tokens\n\nTo illustrate how the two capabilities compare, two agents run the same prompt: **what is the latest price of silver per troy ounce**.\n\nHere is the [gist](https://gist.github.com/laisbsc/47426a4445eb963aec38ab9052917167) with the full code. To run, follow the instructions below. This post is a walkthrough of the code shown in the gist.\n\nIn this example, the **lean agent** performs a single search with three results and a 2,000 character cap. It costs about $0.01. The **thorough agent** gets eight results and `full_page`\n\n, a second search wrapped in `PrefixTools`\n\nand pinned to two domains you add, and `YouResearch`\n\nreturning a typed brief. It costs about $0.13. Both return the same two fields, a price and a date, and both nest under one [Logfire](/logfire) span, so the bill reads straight off the trace tree.\n\nGetting started\n\nStart by installing the required libraries. I'm using [Pydantic AI](https://pydantic.dev/pydantic-ai) as the agent framework, [Pydantic Logfire](https://pydantic.dev/logfire) as the observability layer and Anthropic as the model provider.\n\n```\nuv add \"pydantic-ai-harness[youdotcom,anthropic]\" \"pydantic-ai-slim[logfire]\"\n```\n\nCreate your access keys at [you.com/platform](https://you.com/platform?utm_source=pydantic&utm_medium=partnership&utm_campaign=youdotcom-pydantic-ai-harness), and your model provider's key. Export both with:\n\n```\nexport YDC_API_KEY='your-you-com-api-key'\nexport PYDANTIC_AI_GATEWAY_API_KEY='your-gateway-api-key'\n```\n\nIn this example, the model provider uses [Pydantic AI Gateway](https://pydantic.dev/ai-gateway) with `PYDANTIC_AI_GATEWAY_API_KEY`\n\n. To set your key, enable the Gateway in Logfire and click the API Keys tab, as shown on the video below. You can choose to set up a custom provider by bringing your own key (BYOK), or create a key using built-in providers on Logfire. This allows you to swap models seamlessly, set up spending caps, assign budgets per key or project, and more.\n\nYou can also use your model provider's API key directly (`ANTHROPIC_API_KEY`\n\n, in this case) and replace the Agent string with `'anthropic:claude-sonnet-5'`\n\nor any other model you'd like to use.\n\n``` python\nimport logfire\nfrom pydantic_ai import Agent\nfrom pydantic_ai_harness import YouResearch, YouSearch\n\nlogfire.configure()\nlogfire.instrument_pydantic_ai()\n\nlean_agent = Agent('gateway/anthropic:claude-sonnet-5', capabilities=[YouSearch(), YouResearch()])\n\nresult = lean_agent.run_sync('What is the latest price of silver?')\nprint(result.output)\n```\n\nOne list entry, and the agent can search the web. It comes with its tools, instructions, and settings already wired together with `capabilities=[YouSearch(), YouResearch()]`\n\n.\n\nNow add the settings that turn it into a survey:\n\n``` python\nimport logfire\nfrom pydantic import BaseModel, ConfigDict, Field\nfrom pydantic_ai import Agent\nfrom pydantic_ai_harness import YouSearch\n\nlogfire.configure()\nlogfire.instrument_pydantic_ai()\n\nclass SilverBrief(BaseModel):\n    model_config = ConfigDict(extra='forbid')\n\n    spot_price_usd_per_oz: float\n    as_of: str = Field(description='The date and source the quoted price is from.')\n\nlean_agent = Agent(\n    'gateway/anthropic:claude-sonnet-5',\n    instructions='Answer with the spot price and its date only. Do not explain what moved it.',\n    output_type=SilverBrief,\n    capabilities=[\n        YouSearch(\n            num_results=3,\n            extraction_mode='highlights',\n            max_text_chars=2_000,\n            freshness='week',\n        )\n    ],\n)\n\nresult = lean_agent.run_sync('What is the latest price of silver per troy ounce?')\nprint(result.output.spot_price_usd_per_oz)\n```\n\nThree settings cap what this agent can read. `num_results=3`\n\ncuts the default of ten. `extraction_mode='highlights'`\n\nreturns query-relevant excerpts only, instead of entire page bodies. `max_text_chars=2_000`\n\ntruncates anything that comes back, down from a default of 10,000. `num_results=3`\n\n× `max_text_chars=2_000`\n\ncaps the agent at 6,000 characters of web text per call, whatever you ask it. `freshness='week'`\n\nkeeps quotes older than a week out of the results.\n\n`output_type=SilverBrief`\n\nsets the shape of the reply to a [Pydantic BaseModel](https://pydantic.dev/docs/validation/dev/concepts/models/), so you get a float and a date string, according to what you specify. It does not change how much reading happens first. Both return the same two fields, while the thorough run uses substantially more input and costs more to produce them.\n\nSetting that decides how much text comes back\n\n`web_search`\n\ndefaults to `extraction_mode='highlights'`\n\n, so each result arrives as excerpts and looking at eight sources stays affordable. The model then picks what to read with `get_page`\n\n. Switch to `extraction_mode='full_page'`\n\nwhen you would rather have the markdown up front.\n\nFull page text, from either tool, is capped at `max_text_chars`\n\n. The cap keeps the head of the document, since a page's lead usually carries the substance, and appends a `[... page text truncated at N characters]`\n\nmarker so the model knows it is holding part of a page. `num_results`\n\nis enforced twice, once in the request to You.com and again on the response.\n\nEmpty results are not a failure. A query that matches nothing returns `No results found for {query!r}.`\n\n, which the model can pass to the user or use to reword the search. Real problems arrive as a `ModelRetry`\n\n: a rate limit, a URL that came back empty, a parameter You.com rejected, a network blip. The run continues and the model gets another go. Authentication, billing, and permission errors stop it, because those are yours to fix and no amount of retrying helps.\n\nResearch, and how hard it works\n\nUse `answer`\n\nfor a question you expect one call to settle. Use `research`\n\nwhen it needs many searches and a synthesis across them. `finance_research`\n\nis the same loop tuned for financial analysis.\n\n`research`\n\nwaits for its result instead of returning a job to poll, and a deep pass regularly runs for minutes, so `timeout_ms`\n\ndefaults to ten minutes. Effort is set per capability with `research_effort`\n\n: `lite`\n\n, `standard`\n\n, `deep`\n\n, or `exhaustive`\n\n. You.com also has a `frontier`\n\nlevel, which only runs as a background job, so it is not offered here. `finance_research`\n\ntakes its own `finance_effort`\n\n, either `deep`\n\nor `exhaustive`\n\n.\n\nFor a structured report output, give `research`\n\na JSON schema:\n\n``` python\nfrom pydantic import BaseModel, ConfigDict\nfrom pydantic_ai_harness import YouResearch\n\nclass SupplierRisk(BaseModel):\n    model_config = ConfigDict(extra='forbid')\n\n    supplier: str\n    exposure: str\n    sources: list[str]\n\nYouResearch(\n    research_effort='deep',\n    output_schema=SupplierRisk.model_json_schema(),\n)\n```\n\nWithout `extra='forbid'`\n\n, You.com rejects the schema. It only accepts one that closes itself to extra keys, and that config is what puts `additionalProperties: false`\n\nin the generated JSON. Leave it out and the model gets a validation error back on its first `research`\n\ncall, several minutes in.\n\nThe other rule is checked earlier: You.com rejects a schema at `lite`\n\neffort, and the capability catches that pairing when you construct it.\n\nCitations your application can render\n\nEvery one of the five tools returns a [ ToolReturn](https://pydantic.dev/docs/ai/tools-toolsets/tools-advanced/#advanced-tool-returns). The model sees\n\n`return_value`\n\n, the text, with a `Sources:`\n\nblock appended when the tool has citations. Your application reads `metadata['sources']`\n\n, the same sources as `YouSource`\n\nrecords:\n\n``` python\nfrom pydantic_ai.messages import ToolReturnPart\n\nfor message in result.all_messages():\n    for part in message.parts:\n        if isinstance(part, ToolReturnPart) and part.metadata:\n            for source in part.metadata.get('sources', []):\n                print(source['url'], source['title'])\n```\n\nThe model never sees metadata, so nothing here competes for context, and the footnotes in your UI never depend on the model repeating a URL correctly. `web_search`\n\nputs the response's `search_uuid`\n\nand `latency`\n\nin there too, which is what you want in a trace when a run went sideways, and you need to ask You.com about one specific query.\n\nScoping what it reads\n\nBoth capabilities take the same controls, and they reach `web_search`\n\n, `answer`\n\n, and `research`\n\n. `finance_research`\n\nis the exception: it takes its input and `finance_effort`\n\n, nothing else, so a domain filter you set will not narrow it. `include_domains`\n\nis an allowlist and cannot be combined with either. `exclude_domains`\n\nand `boost_domains`\n\ndo combine, so a denylist and a re-rank work together. `freshness`\n\ntakes `day`\n\n, `week`\n\n, `month`\n\n, `year`\n\n, or a `YYYY-MM-DDtoYYYY-MM-DD`\n\nrange, and `country`\n\ntakes a two-letter code. Bad values raise at construction time.\n\nOne agent, two search setups, is a common ask: the open web for context, a couple of trusted domains for anything it will cite. Two instances of the same capability would register the same tool names, so wrap the second in core's `PrefixTools`\n\n:\n\n``` python\nimport logfire\nfrom pydantic_ai import Agent\nfrom pydantic_ai.capabilities import PrefixTools\nfrom pydantic_ai_harness import YouSearch\n\nlogfire.configure()\nlogfire.instrument_pydantic_ai()\n\nthorough_agent = Agent(\n    'gateway/anthropic:claude-sonnet-5',\n    instructions=(\n        'You must call `research` exactly once and base the brief on what it '\n        'returns; do not answer from search results alone. Use '\n        '`trusted_web_search` only to confirm the number you quote as the spot '\n        'price, and `web_search` to survey context before the research pass.'\n    ),\n    output_type=SilverBrief,\n    capabilities=[\n        YouSearch(\n            num_results=8,\n            extraction_mode='full_page',\n            max_text_chars=20_000,\n            freshness='week',\n        ),\n        PrefixTools(\n            wrapped=YouSearch(\n                num_results=3,\n                include_domains=['lbma.org.uk', 'kitco.com'],\n                guidance='',\n            ),\n            prefix='trusted',\n        ),\n        YouResearch(\n            research_effort='deep',\n            output_schema=SilverBrief.model_json_schema(),\n        ),\n    ],\n)\n```\n\nThe agent above removes the lean agent's limits, adds a second search pinned to two domains, and sends the write-up through `research`\n\n.\n\nSet `guidance=''`\n\non the wrapped instance, or replace it with text explaining when the prefixed tools apply. Otherwise, both instances contribute the same default paragraph.\n\nThe same naming rule is why an agent gets one web search capability. Anything else registering a `web_search`\n\ntool collides with `YouSearch`\n\n, and the agent fails at construction rather than at the first call. Wrap one of them in `PrefixTools`\n\nif you want both.\n\nWhat the tools cost\n\nEight results at `full_page`\n\nand 20,000 characters each is a 160,000 character ceiling, against the lean agent's 6,000. Both runs nest under one Logfire span, so the token counts sit next to each other in the trace tree:\n\nThe two differ in `capabilities`\n\nand `instructions`\n\n; the capability differences are:\n\n| lean | thorough | |\n|---|---|---|\n| survey | `highlights` , 3 results, 2,000 chars |\n`full_page` , 8 results, 20,000 chars |\n| trusted source | none | `trusted_web_search` on lbma.org.uk and kitco.com |\n| research pass | none | `YouResearch(research_effort='deep')` |\n\nEach run calls both agents back to back on the same question, so the lean number and the thorough number come from the same minute of the web. The figures below are five such runs, and the headline is the median of the five ratios.\n\n| lean | thorough | |\n|---|---|---|\n| input tokens | 7,937 | 65,987 |\n| output tokens | 159 | 358 |\n| wall time | 5.5s | 26.3s |\n| cost per run | $0.01 | $0.13 |\n| tool calls | 1 | 3 |\n\nEight times the input for the same two fields. Across the five runs the paired ratio ran from 5.4x to 11.8x, median 8.2x.\n\nOne tool call accounts for most of that. `research`\n\ntook a median 16.3 seconds, 62% of the thorough run's wall time, and carries most of the token difference.\n\nInstructions decide whether the expensive tool runs at all. `research_effort`\n\nonly decides how long it runs once it does. With the wording above, `research`\n\nwas called in all five runs and the thorough agent's input tokens varied by 1.4%, from 65,075 to 67,698.\n\nThe lean agent's input tokens varied from 5,581 to 12,160 across the same five runs, because nothing anchors what a highlights search returns except what the web served when the agent called.\n\nFive runs inside seven minutes measures the configuration. It does not measure how either agent behaves on a day when silver is actually moving.\n\nWhether the trade is worth making is a question for the human in the loop. The thorough brief cites its sources and checks the quoted price against a domain. The lean one returns a number from the open web in five seconds.\n\nWhy this pairing works\n\nAn agent that reads the web is an agent whose answers depend on things you do not control. Pages change, a search returns something odd, a summary quietly drops the one source that mattered. None of that has to be guesswork. The tool definitions are typed and the outputs are validated, so a malformed result fails where you can see it, and [Pydantic Logfire](https://pydantic.dev/logfire) keeps the receipt: which queries ran, what came back, which pages were read in full, and what the whole run cost.\n\nYou.com's contribution is retrieval that already distinguishes an excerpt from a page from a research pass, so your agent code does not have to invent that distinction on top of a single search endpoint.\n\nSome caveats before you ship:\n\n- Harness is on 0.x releases, so the API can change between minor versions. Changes come with deprecation warnings and migration guidance in the release notes.\n`research`\n\nblocks for the length of the pass. At`deep`\n\nor`exhaustive`\n\n, size the surrounding request timeouts for minutes, not seconds.- A prebuilt\n`client`\n\nis used as given, so its timeout and host are yours to configure.`timeout_ms`\n\nonly applies to the default client. - Domain filters shape what the agent can see. They are not a security boundary for what it can be told by a page it does read.\n\nTry it\n\nGet a key at [you.com/platform](https://you.com/platform?utm_source=partner-pydantic&utm_medium=referral&utm_campaign=2026-08-pydantic-integration), your model provider's key, and add `YouSearch()`\n\nto your web search Pydantic AI agents. Instrument with Logfire to see all the steps in between, validate your prompts, and analyze performance. You can get a working web-reading agent that takes about two minutes to set up.\n\nWhen you want more than the first run:\n\n- The\n[You.com capability docs](https://pydantic.dev/docs/ai/harness/youdotcom/)carry the full reference for`YouSearch`\n\n,`YouResearch`\n\n, and their toolsets. - The\n[Pydantic AI Harness capabilities](https://pydantic.dev/docs/ai/capabilities/overview/)docs list every available capability, written to be read and copied, with examples and tool descriptions behind each capability. - You.com keeps\n[four worked cookbooks](https://github.com/youdotcom-oss/pydantic-cookbook)of their own, each grounded in a different field: an antimicrobial resistance brief through`research`\n\n, a survey of K-12 teacher retention on`YouSearch`\n\n, a private credit read through`finance_research`\n\n, and a due-diligence desk that routes across all three with`SubAgents`\n\n. Start there if your domain is closer to one of those than to a generic search agent. - Every agent above is traced with\n[Pydantic Logfire](https://pydantic.dev/logfire), which turns each run into a trace you can open and query with SQL: searches, page reads, retries, token costs. Keep the[Logfire MCP server](https://pydantic.dev/docs/logfire/guides/mcp-server/)open while you debug one and your agent can read its own traces back to you. [Pydantic Evals](https://pydantic.dev/docs/ai/evals/evals/)is the next thing you want once the agent is choosing its own sources, so a prompt change that sharpens one question does not blunt another.\n\nIf you build something good with this, we would like to see it. The harness lives on [GitHub](https://github.com/pydantic/pydantic-ai-harness), the issues are open, and the capability shelf grows mostly because people tell us what is missing from it. Come say hello in the [Pydantic Slack](https://pydantic.dev/docs/logfire/join-slack/).\n\nTogether, these are pieces of [the Pydantic Stack](https://pydantic.dev/). Try it out!", "url": "https://wpnews.pro/news/you-com-is-now-a-pydantic-ai-capability", "canonical_source": "https://pydantic.dev/articles/youdotcom-pydantic-ai-harness", "published_at": "2026-09-01 09:00:00+00:00", "updated_at": "2026-09-01 20:55:03.982354+00:00", "lang": "en", "topics": ["ai-tools", "ai-research", "ai-infrastructure"], "entities": ["Pydantic AI Harness", "You.com", "YouSearch", "YouResearch", "Pydantic Logfire", "Anthropic", "Pydantic AI Gateway"], "alternates": {"html": "https://wpnews.pro/news/you-com-is-now-a-pydantic-ai-capability", "markdown": "https://wpnews.pro/news/you-com-is-now-a-pydantic-ai-capability.md", "text": "https://wpnews.pro/news/you-com-is-now-a-pydantic-ai-capability.txt", "jsonld": "https://wpnews.pro/news/you-com-is-now-a-pydantic-ai-capability.jsonld"}}