> For clean Markdown of any page, append `.md` to the page URL.
> Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL).
> Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key).
> Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing.
> OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`.

# Pydantic AI

[Pydantic AI](https://pydantic.dev/docs/ai/) is a Python agent framework from the Pydantic team. Its capability library, [Pydantic AI Harness](https://pydantic.dev/docs/ai/harness/), includes two capabilities backed by You.com APIs:

* **`YouSearch`** adds `web_search` (Web Search API) and `get_page` (Contents API).
* **`YouResearch`** adds `answer` (Answer API), `research` (Research API), and `finance_research` (Finance Research API).

Each tool returns a `Sources:` block the model can cite, plus the same sources as structured metadata for your code.

---

## Getting Started

### Install the Package

```bash
pip install "pydantic-ai-harness[youdotcom,anthropic]"
```

The `youdotcom` extra installs the You.com [Python SDK](/docs/integrations/python-sdk), and `anthropic` installs the model provider used in the examples below. For another provider, add its Pydantic AI extra, such as `"pydantic-ai-slim[openai]"`. Requires Python 3.11+.

Pydantic AI Harness is on 0.x releases, so its API can change between minor versions.

### Set Your API Keys

```bash
export YDC_API_KEY="<YDC_API_KEY>"
export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
```

Get your You.com API key at [you.com/platform](https://you.com/platform). Creating a capability without `YDC_API_KEY` set raises an error.

---

## Usage

#### Basic

```python
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 in the latest stable Python release?')
print(result.output)
```

Use `YouSearch` alone if the agent only needs search and page reads.

#### Search controls

```python
from pydantic_ai_harness import YouSearch

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

`web_search` returns query-relevant excerpts by default, and the agent reads promising pages in full with `get_page`. `include_domains` can't be combined with `exclude_domains` or `boost_domains`. The [request controls guide](/docs/guides/search/request-controls) explains each filter.

#### Research controls

```python
from pydantic_ai_harness import YouResearch

YouResearch(
    research_effort='deep',  # lite, standard (default), deep, or exhaustive
    finance_effort='deep',   # deep (default) or exhaustive
    include_domains=['sec.gov', 'federalreserve.gov'],
    freshness='year',
)
```

Domain and `freshness` settings apply to `answer` and `research`. `finance_research` takes only `finance_effort`. Set `output_schema` to get [structured output](/docs/guides/research/structured-output) from `research` at any effort except `lite`. The background-only `frontier` effort is not available.

`research` and `finance_research` wait for the full answer, so `YouResearch` allows up to 10 minutes per request by default.

#### Citations

Read the sources from the run's message history. No text parsing is needed:

```python
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'])
```

`web_search` metadata also carries the Web Search API `search_uuid` and `latency` for tracing.

The [Pydantic AI Harness reference](https://pydantic.dev/docs/ai/harness/youdotcom/) lists every field and covers custom clients, multiple instances, native search fallback, and YAML agent specs.

---

## Tools

| Tool               | Capability    | API                  | Use when                                                        |
| ------------------ | ------------- | -------------------- | --------------------------------------------------------------- |
| `web_search`       | `YouSearch`   | Web Search API       | Survey the web. Returns up to `num_results` pages with excerpts |
| `get_page`         | `YouSearch`   | Contents API         | Read one URL in full as markdown                                |
| `answer`           | `YouResearch` | Answer API           | One question, one cited answer                                  |
| `research`         | `YouResearch` | Research API         | Questions that need many searches and a cited write-up          |
| `finance_research` | `YouResearch` | Finance Research API | Companies, markets, and financial instruments                   |

Each tool call is billed at the [rate of its underlying API](/docs/administration/billing).

## Error Handling

| Failure                                       | Behavior                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------ |
| `web_search` finds nothing                    | Returns `No results found for '<query>'.` and the run continues          |
| Empty result, 422, 429, 5xx, or network error | Sent to the model as `ModelRetry`, so it can fix the input or try again  |
| 401, 402, or 403                              | Raised, and the run stops until you fix the key, credits, or permissions |

The [error code reference](/docs/using-the-api/error-code-reference) lists what each status means.

---

## Durable Execution

Under Temporal, Prefect, or DBOS, each You.com request is recorded under the capability `id` (`you_search` or `you_research`), so a recovered run reuses the result instead of calling the API again. Keep the `id` stable once deployed—renaming it breaks in-flight runs.

A Temporal activity times out after 60 seconds by default, which `research` can exceed. Give the `you_research` toolset more time:

```python
from datetime import timedelta

from pydantic_ai.durable_exec.temporal import TemporalDurability
from temporalio.workflow import ActivityConfig

TemporalDurability(
    toolset_activity_config={
        'you_research': ActivityConfig(start_to_close_timeout=timedelta(minutes=10)),
    },
)
```

---

## Cookbook

The [pydantic-cookbook](https://github.com/youdotcom-oss/pydantic-cookbook) repo has four runnable examples:

| Example                            | Main API             | Topic                                                          |
| ---------------------------------- | -------------------- | -------------------------------------------------------------- |
| `starters/education_web_search.py` | Web Search API       | K-12 teacher burnout and retention                             |
| `starters/healthcare_research.py`  | Research API         | *Candida auris* outbreak and antimicrobial resistance          |
| `starters/finance_research.py`     | Finance Research API | Private credit market stress                                   |
| `deal_desk.py`                     | All five             | Due diligence with a lead agent and three specialist subagents |

```bash
git clone https://github.com/youdotcom-oss/pydantic-cookbook
cd pydantic-cookbook
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # add YDC_API_KEY and OPENROUTER_API_KEY
make smoke             # builds every agent without network calls
make run-edu           # or run-health, run-finance, run-deal
```

---

## Resources

#### [Pydantic AI Harness Reference](https://pydantic.dev/docs/ai/harness/youdotcom/)

Every YouSearch and YouResearch field, with defaults

#### [Cookbook on GitHub](https://github.com/youdotcom-oss/pydantic-cookbook)

Four runnable examples, including the multi-agent deal desk

#### [Pydantic AI and You.com](https://you.com/resources/pydantic-and-ydc-delivering-powerful-web-intelligence-and-agent-orchestration)

Launch post covering Logfire tracing and the deal desk

#### [PyPI](https://pypi.org/project/pydantic-ai-harness/)

The pydantic-ai-harness package

#### [Web Search API Reference](/docs/api-reference/search/v1-search)

Parameters and response schema behind `web_search`

#### [Research API Reference](/docs/api-reference/research/v1-research)

Parameters and response schema behind `research`