Build a research agent with Pydantic AI

Install

pip install pydantic-ai httpx

Step by step

1. 1

   Model the answer you want

   Start from the output type. Everything else follows from it, and the model is constrained to produce something that validates — which removes an entire category of downstream parsing bugs.

   from pydantic import BaseModel, Field
   
   
   class Finding(BaseModel):
       claim: str
       url: str
       independent_sources: int = Field(
           description="How many separately-owned hosts carry this claim"
       )
   
   
   class Research(BaseModel):
       answer: str
       findings: list[Finding]
       caveats: list[str] = Field(
           default_factory=list,
           description="Claims resting on a single source, or gaps in coverage",
       )

2. 2

   Inject the client, register the tool

   deps_type makes the httpx client an explicit dependency. In a test you pass a stub; in production you pass a real client with your timeouts. No global state, no monkeypatching.

   from dataclasses import dataclass
   import httpx
   from pydantic_ai import Agent, RunContext
   
   
   @dataclass
   class Deps:
       client: httpx.AsyncClient
       api_key: str
   
   
   agent = Agent(
       "anthropic:claude-opus-5",
       deps_type=Deps,
       output_type=Research,
       system_prompt=(
           "Search before you answer. Put any claim resting on a single source "
           "in caveats rather than stating it plainly."
       ),
   )
   
   
   @agent.tool
   async def web_search(ctx: RunContext[Deps], query: str, min_sources: int = 2) -> list[dict]:
       """Search the web. Returns metadata only, never page bodies."""
       r = await ctx.deps.client.get(
           "https://api.unlob.com/search",
           headers={"x-api-key": ctx.deps.api_key},
           params={"q": query, "min_independent_sources": min_sources, "limit": 8},
       )
       r.raise_for_status()
       return r.json()["results"]

3. 3

   Test it without the network

   This is the payoff for the dependency injection. Because the HTTP client arrives through deps rather than being imported, a test hands the agent a stub transport and asserts on the validated output — no network, no model spend, no mocking library.

   import httpx, pytest
   from pydantic_ai.models.test import TestModel
   
   from agent import agent, Deps, Research
   
   
   @pytest.mark.asyncio
   async def test_flags_single_source_claims():
       # A stub transport: the agent never touches the network.
       def handler(request: httpx.Request) -> httpx.Response:
           return httpx.Response(200, json={"results": [
               {"url": "https://example.com/a", "title": "A",
                "snippet": "...", "independent_sources": 1},
           ]})
   
       transport = httpx.MockTransport(handler)
       async with httpx.AsyncClient(transport=transport) as client:
           deps = Deps(client=client, api_key="test")
           # TestModel exercises the tools and the output schema without
           # calling a real provider.
           with agent.override(model=TestModel()):
               result = await agent.run("anything", deps=deps)
   
       assert isinstance(result.output, Research)

What happens when it runs

What will go wrong

The failures that cost an afternoon rather than a minute, because they produce something that looks like it is working.

• !

  Validation failures are retried, not raised. The model gets the error and another attempt, which is usually what you want — but a badly-specified output type turns into a quiet retry loop that costs real money. Watch the retry count.

• !

  Field descriptions are prompt. `independent_sources` gets populated correctly because the Field description explains what it means; drop it and the model invents a number.

• !

  deps_type must match what you pass to run(). The mismatch is caught by your type checker and not at runtime, so run mypy or pyright — that is most of the point of using this framework.

• !

  Use the provider-prefixed model string (`anthropic:claude-opus-5`). A bare model name resolves against the default provider and produces a confusing auth error.