Pydantic AI and You.com—Delivering Powerful Web Intelligence and Agent Orchestration

A language model answers from what it learned during training. The questions people bring to an agent are about now: a drug cleared last month, an outbreak across two dozen states, a rate decision priced in last week. Closing that gap is an infrastructure problem, not a prompt-engineering trick. The agent needs live search, a disciplined way to read the pages that matter, and a record of what it did and why.

The good news is that you can assemble that infrastructure from composable, mostly open-source pieces: Pydantic AI for the agent and its orchestration, Pydantic AI Harness for reusable capabilities, You.com for the web intelligence, and Pydantic Logfire for tracing and evaluation. This post walks through that stack end to end, from a one-line search tool to a multi-agent M&A deal desk you can run yourself.

Today we're shipping two capabilities in Pydantic AI Harness that make the web-intelligence layer a one-liner: YouSearch and YouResearch, backed by the You.com APIs. Add them to a Pydantic AI agent and it can survey the web, read the pages that matter, and, when a question is bigger than a lookup, hand off to a grounded, multi-step research run that returns a synthesized answer with its sources attached.

You.com Web Search APIs

You.com provides a portfolio of web search APIs built for AI applications. They give agents real-time, LLM-ready access to the web and perform deeper research for agentic workflows. The following You.com APIs work with Pydantic AI:

• Web Search API. Returns real-time web and news results, with query-relevant excerpts or full-page markdown attached to each result.
• Contents API. Gets clean, full-page content from a URL as HTML or Markdown.
• Answer API. Returns a synthesized, citation-grounded answer in one call. It verifies that every citation exists in the source text before it returns, scores 93.48% on the SimpleQA benchmark, and runs at a p50 of 2.67 seconds.
• Research API. Runs multi-step research and returns a well-cited answer, with effort levels from lite to exhaustive.
• Finance Research API. Multi-step research over a dedicated financial index of filings, transcripts, analyst coverage, and fundamentals.

The two harness capabilities map onto these five surfaces: YouSearch wraps Web Search and Contents (the everyday web layer), and YouResearch wraps Answer, Research, and Finance Research (the synthesis layer).

The Challenge

Standard search tools return a list of links for humans to read. You.com's APIs return structured, machine-readable JSON: titles, snippets, highlights, and source URLs an agent can act on directly, with no scraping step and no extra parsing code. That matters because every team building a research agent rebuilds the same retrieval plumbing, and tends to get it subtly wrong:

• Snippet-only search returns titles and one-line teasers, so the agent fetches each promising URL again before judging a source. That is two round trips for one decision.
• Full-text search floods the context window with pages the agent will discard, burning tokens and burying the signal.
• Ungrounded answer endpoints synthesize fluently but leave you unable to check the claims. A healthcare or finance user needs the opposite: an answer whose every statement traces to a source.
• Some questions are not a lookup at all. "How is the private credit market holding up under 2026 stress?" needs dozens of searches, cross-reading, and synthesis. That is an agentic loop, not a single call.

Agentic workflows need fresh data with high accuracy and low latency to be useful. You.com's APIs deliver lower retrieval costs than LLM-bundled search, strong retrieval quality and control, and a portfolio of research endpoints so you can use the right tool for each phase. Wiring all of that together is real boilerplate for every project: rate limits and transient 5xxs that must not abort the run, citations the application can read without dumping raw JSON into the model's context, and offline testability so you are not hitting a paid API in CI. It is exactly the kind of thing a capability should own once.

Choosing the Right Web Search Provider

You have choices when it comes to the web research tools that power your agents. When evaluating providers, consider the following needs and the You.com native primitive each maps to:

You.com provides native single-call excerpt retrieval rather than assembled-excerpt handling, boost_domains weighting rather than allowlist-only filtering, a 500-domain filter capacity, and a low-latency profile. The portfolio of research APIs is the other half of the flexibility: you pick a quick cited answer, a multi-step research run, or the finance-tuned finance_research endpoint to match the job.

Integration

Pydantic AI v2 reorganized agent extension around capabilities: composable units that bundle tools, lifecycle hooks, instructions, and model settings. A capability contributes its tools and guidance to an agent and stacks with every other capability in the list. Pydantic AI Harness is the library of production-ready capabilities built on that seam: Coder, Researcher, Exa, and now You.com.

Wrapping You.com's APIs as capabilities means the retrieval discipline lives in one tested place instead of in every prompt:

• Bounded output. web_search returns query-relevant excerpts by default, so surveying five sources stays cheap; get_page and full-page mode are capped at a character budget you set.
• Structured citations. Every tool returns a ToolReturn: the model sees readable text with a Sources: block, while your application reads the sources as typed records from message metadata, with no text parsing.
• Recoverable errors. Empty results, rate limits, rejected parameters, and transient network failures are returned to the model as a ModelRetry, so the run continues; genuine configuration errors (auth, billing) propagate.
• Testable by design. The capabilities take any client satisfying a small YouClient protocol, so you can drop in a fake and test offline.

There is a nice symmetry here. Pydantic began as a data-validation library and is now one of the most widely used packages in the Python ecosystem, with a large share of modern data-handling code running through it. The You.com Python SDK is built on it too, so its API responses arrive as validated Pydantic models. The same validation runs the whole way through: from the raw You.com response, through the Harness capability, to the agent's typed output. Pydantic, the library, sits underneath Pydantic AI, the framework, and the data flowing through your agent is validated end-to-end.

How to Use

Install the capability and set your You.com API key:

uv add "pydantic-ai-harness[youdotcom]"
export YDC_API_KEY=... # create a key at https://api.you.com

Then add the capabilities to an agent:

from pydantic_ai import Agent
from pydantic_ai_harness import YouResearch, YouSearch

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[YouSearch(), YouResearch()],
)
result = agent.run_sync('What changed with oral PCSK9 inhibitors this summer, and who benefits most?')
print(result.output)

Reading citations from the run needs no parsing. They are structured metadata, carried on each tool return:

from pydantic_ai.messages import ModelRequest, ToolReturnPart

for message in result.all_messages():
    if isinstance(message, ModelRequest):
        for part in message.parts:
            if isinstance(part, ToolReturnPart) and part.metadata is not None:
                for source in part.metadata.get('sources', []):
                    print(source['url'], source['title'])

Expanding With Parameters

Both capabilities are plain dataclasses. Configure them once and attach to any agent. YouSearch exposes the everyday web knobs:

YouSearch(
    num_results=8,                  # 1-20 results per web_search call
    extraction_mode='highlights',   # 'highlights' (default) or 'full_page'
    max_text_chars=10_000,          # cap on get_page / full-page text
    include_domains=['cdc.gov', 'fda.gov'],
    boost_domains=['nejm.org'],
    freshness='month',              # day | week | month | year | YYYY-MM-DDtoYYYY-MM-DD
    country='us',
)

YouResearch exposes the synthesis knobs. Dial research_effort from lite to exhaustive; finance_effort is deep or exhaustive; pass an output_schema and research returns structured JSON you can validate instead of prose:

YouResearch(
    research_effort='deep',      # lite | standard | deep | exhaustive
    finance_effort='exhaustive', # deep | exhaustive
    freshness='month',
    include_domains=['sec.gov', 'federalreserve.gov'],
    output_schema={               # optional: structured research output
        'type': 'object',
        'properties': {'summary': {'type': 'string'}, 'risks': {'type': 'array'}},
    },
)

One accuracy note worth internalizing: domain filters and output_schema apply to answer and research, which draw from the open web. finance_research runs on You.com's curated finance index, so it takes neither. The corpus is the control there. When you need domain-pinned or structured output on a financial topic, reach for research with include_domains instead.

Because these are ordinary Pydantic AI capabilities, they compose with the rest of Harness. Hand the findings to Coder, wrap a domain-pinned instance in PrefixTools, or declare the whole agent in a YAML agent spec instead of Python.

Taking Advantage of Pydantic Logfire

An agent that reads the live web is only trustworthy if you can see what it did. Pydantic Logfire is Pydantic's observability platform, and logfire.instrument_pydantic_ai() turns one agent run into one trace: the model calls, tool calls, retries, and the response your user receives, each a span, with token usage and cost attached.

import logfire

logfire.configure()                    # reads .logfire/ credentials, or LOGFIRE_TOKEN
logfire.instrument_pydantic_ai()       # trace every Pydantic AI run

That single trace changes what you can do when an answer is wrong or slow:

• Tell a prompt problem from a service problem. When a research agent returns a stale figure, the trace shows whether the model never asked for a recent source or whether the search came back empty. Those are different bugs with different fixes, and they look identical from the outside.
• Turn failing runs into evals. Logfire lets you build datasets from the cases that matter, compare a change against them before release, and score live traffic after it ships. A retrieval agent's quality is a moving target, so this is how you keep it from regressing.
• Iterate on prompts safely. Version a prompt, test it against representative inputs, and promote the version that performs better rather than editing in production and hoping.
• Query production data. Ask questions of your traces in SQL, or connect the Logfire MCP server so your coding agent can investigate alongside you.

For regulated work, the trace is also an audit trail. In an M&A, healthcare, or finance context, the record of what the agent searched, which sources it read, and how each claim traces back is not a nicety. It is evidence you can hand to a reviewer.

The You.com web_search tool return already carries metadata.search_uuid and metadata.latency from every Search API response; the capability puts them there deliberately for tracing. With content capture on, each web_search span in Logfire shows the query's You.com latency and a per-query audit identifier alongside the results, so the retrieval cost and quality of the You.com layer sit next to the model's token spend in one trace. The same metadata is available to your application from ToolReturnPart.metadata, so you can join a Logfire trace to a You.com request by search_uuid without either side knowing about the other.

Optional Inference: The Pydantic AI Gateway

The examples so far use a direct provider model string (anthropic:claude-sonnet-4-6). If you would rather not manage a key per provider, the Pydantic AI Gateway gives you a range of LLM providers behind a single key, managed through Logfire. Point your agent at it with the gateway/ prefix:

from pydantic_ai import Agent

agent = Agent('gateway/anthropic:claude-sonnet-4-6')  # or gateway/openai:gpt-5.2

• API key management: access multiple LLM providers with a single Gateway key.
• Cost limits: set spending limits at project, user, and API key levels with daily, weekly, and monthly caps.
• BYOK and managed providers: bring your own API keys from LLM providers, or pay for inference directly through the platform.
• Multi-provider support: access models from OpenAI, Anthropic, Google Cloud, Groq, and AWS Bedrock.
• Routing groups: configure routing groups to fail over between providers serving the same model, or load-balance traffic across them by weight.

Because the Gateway is managed through Logfire, the model calls in your research agent are traced in the same project as the You.com tool calls, so retrieval and inference are observed together. For full details, see the Gateway docs.

What it Looks Like in Practice

The three single-API cookbooks show each surface on its own: a Healthcare example uses the Research API to track the Candida auris outbreak and its antimicrobial resistance; an Education example uses the Web Search API to survey K-12 teacher burnout and retention; a Finance example uses the Finance Research API to assess private credit market stress. Each is a single agent with a single capability, and each is a good place to start.

The flagship pulls all three together into a workflow with real stakes.

Example: An M&A Due-Diligence Deal Desk

Consider a deal team running diligence on a target: a mid-market private credit asset manager that a buyer wants to acquire to expand into asset-backed finance, on the thesis that the target underwrites more conservatively than its distressed peers. Confirming or breaking that thesis needs three kinds of intelligence at once, and they map cleanly onto the You.com surfaces.

• Market scanning is broad and time-boxed. The Web Search API surveys the target's market, product, customers, and competitors, and monitors recent news that could affect the price. Here the domain controls earn their keep: the desk excludes low-signal aggregators and boosts the business press (reuters.com, bloomberg.com, ft.com), so the scan starts from credible sources without a second fetch.
• Financial reconstruction is deep and precise. The Finance Research API pulls multi-year financials, funding and debt, valuation benchmarks, and credit exposure from a curated index of filings, transcripts, analyst coverage, and fundamentals, with every figure cited to its source. Its two effort levels bound the cost of that depth: the desk runs deep (under 120 seconds per call) for a read like this and reserves exhaustive (under 300 seconds per call) for full standalone diligence. Because the index is already finance-specific, this surface takes no domain filters. Each call is a full research run, so the specialist is told to make one comprehensive call rather than many narrow ones.
• Risk research is adversarial. The Research API runs a multi-step investigation into regulatory, legal, security, and reputational exposure, pinned to primary sources with include_domains=['sec.gov', 'justice.gov', 'ftc.gov', 'courtlistener.com'] so allegations from the open web do not masquerade as findings.

Running Web Search first for the broad scan means the expensive financial and risk research is applied surgically, only where the scan says it is warranted.

In Harness this is a small multi-agent composition. A lead agent holds a SubAgents capability naming three specialists, each grounded in a different You.com surface and each returning a typed findings model. The lead routes each delegation to a fast or deep model, bounds each specialist with a timeout and a call budget, keeps a light answer tool for verifying a stray fact, and synthesizes everything into a typed due-diligence memo:

from pydantic import BaseModel, Field
from pydantic_ai import Agent
from pydantic_ai.usage import UsageLimits
from pydantic_ai_harness import SubAgent, SubAgents, YouResearch, YouSearch

market_analyst = Agent(
    MODEL, name='market_analyst', output_type=MarketFindings,
    capabilities=[YouSearch(               # broad-surface scan
        num_results=12, freshness='month', country='us',
        exclude_domains=['reddit.com', 'quora.com', 'pinterest.com'],
        boost_domains=['reuters.com', 'bloomberg.com', 'ft.com', 'wsj.com'],
    )],
)

finance_analyst = Agent(
    MODEL, name='finance_analyst', output_type=FinanceFindings,
    capabilities=[YouResearch(finance_effort='deep')],  # curated finance index
)

risk_analyst = Agent(
    MODEL, name='risk_analyst', output_type=RiskFindings,
    capabilities=[YouResearch(             # regulators and courts
        research_effort='deep', freshness='year', country='us',
        include_domains=['sec.gov', 'justice.gov', 'ftc.gov', 'courtlistener.com'],
    )],
)

class DueDiligenceMemo(BaseModel):
    target: str
    thesis: str
    market: list[str] = Field(description='Findings, each ending with a source URL.')
    financials: list[str] = Field(description='Findings, each ending with a source URL.')
    risks: list[str] = Field(description='Findings, each ending with a source URL.')
    red_flags: list[str]
    open_questions: list[str]
    recommendation: str  # 'proceed' | 'proceed with conditions' | 'pass'
    rationale: str

deal_desk = Agent(
    LEAD_MODEL,
    output_type=DueDiligenceMemo,
    capabilities=[
        SubAgents(
            agents=[
                SubAgent(market_analyst, timeout_seconds=180, max_calls=2),
                SubAgent(finance_analyst, models=['deep'], timeout_seconds=360, max_calls=1,
                         usage_limits=UsageLimits(request_limit=12)),
                SubAgent(risk_analyst, timeout_seconds=300, max_calls=2),
            ],
            models={'fast': FAST_MODEL, 'deep': DEEP_MODEL},  # cost-aware routing menu
            agent_folders=None,
        ),
        YouResearch(research_effort='lite',  # `answer` for single-fact checks
                    guidance='Use `answer` only to verify one specific fact; delegate analysis.'),
    ],
    instructions='Delegate one self-contained brief to each specialist, then synthesize a memo.',
)

memo = deal_desk.run_sync(
    'Target: a mid-market private credit asset manager. '
    'Thesis: acquire to expand into asset-backed finance while the sector is under stress.',
    usage_limits=UsageLimits(request_limit=80),
).output
print(memo.model_dump_json(indent=2))

This is where the Pydantic side of the stack handles the orchestration. Each specialist runs in its own isolated context and returns a typed findings model, so the data is validated at every hop, not just at the end. The lead picks a fast or deep model per delegation, pins the expensive finance run to the deep model, and bounds each specialist with a wall-clock timeout and a call budget, with a tree-wide UsageLimits capping the whole desk. The lead then returns a structured DueDiligenceMemo in which every claim traces back to a source one of its analysts cited. An illustrative slice of that memo:

{
  "recommendation": "proceed with conditions",
  "red_flags": [
    "Reported non-accruals stay benign while public-BDC marks on comparable books show mid-single-digit discounts; the gap suggests slow price discovery (sec.gov)",
    "Two portfolio companies restructured via distressed exchange in H2 2025, not reflected in headline default figures (courtlistener.com)"
  ],
  "open_questions": [
    "Underwriting standard versus distressed peers is asserted, not yet evidenced at the loan-tape level"
  ]
}

The whole run is one Logfire trace: the delegations, each specialist's model and tool calls, the You.com latency behind each search, and the token spend, so the desk's reasoning is auditable after the fact. Swap the specialists, their You.com configuration, the routing menu, or the output models to retarget the desk at another kind of investigation.

Put it to Use

We encourage you to try the You.com APIs for yourself. To that end, we have created cookbooks you can clone from our GitHub repo: https://github.com/youdotcom-oss/pydantic-cookbook

• A Healthcare industry example using the Research API: the Candida auris outbreak and antimicrobial resistance.
• An Education industry example using the Web Search API: K-12 teacher burnout and retention.
• A Finance industry example using the Finance Research API: private credit market stress.
• A flagship M&A due-diligence deal desk that composes all three into the multi-agent workflow shown above.

Each API serves many use cases; showing three different ones lets you see the range, and the deal desk shows how they compose. The cookbooks are model-agnostic (set any Pydantic AI model string), load keys from a .env file, and wire Logfire tracing so every run is observable.

If you do not already have a You.com API key, visit you.com/platform to get a free one; new accounts get $100 in credits. Visit the API docs for full details on all parameters and use cases, and the You.com capability page for the complete harness reference.