quercle-pydantic-ai

Quercle web search and fetch tools for Pydantic AI.

Installation

uv add quercle-pydantic-ai
# or
pip install quercle-pydantic-ai

Setup

Set your API key as an environment variable:

export QUERCLE_API_KEY=qk_...

Get your API key at quercle.dev.

Quick Start

from pydantic_ai import Agent
from quercle_pydantic_ai import quercle_tools

agent = Agent(
    "openai:gpt-4o",
    tools=quercle_tools(),
    system_prompt="You are a helpful research assistant.",
)

result = agent.run_sync("Search for the latest news about AI agents")
print(result.output)

quercle_tools() returns all 5 tools: search, fetch, raw search, raw fetch, and extract.

Direct Tool Usage

The tools are async (Pydantic AI tools are async by design). For direct usage, use the underlying SDK client:

import asyncio
from quercle import AsyncQuercleClient

async def main():
    client = AsyncQuercleClient()

    # Search
    result = await client.search("best practices for building AI agents")
    print(result.result)

    # Search with domain filtering
    result = await client.search(
        "Python documentation",
        allowed_domains=["docs.python.org"],
    )
    print(result.result)

    # Fetch and analyze a page
    result = await client.fetch(
        "https://en.wikipedia.org/wiki/TypeScript",
        "Summarize the key features of TypeScript",
    )
    print(result.result)

asyncio.run(main())

Custom API Key

tools = quercle_tools(api_key="qk_...")

Agentic Usage

Research Agent

from pydantic_ai import Agent
from quercle_pydantic_ai import quercle_tools

agent = Agent(
    "anthropic:claude-sonnet-4-20250514",
    tools=quercle_tools(),
    system_prompt="You are a research assistant. Search the web to find "
    "accurate, up-to-date information. Always cite your sources.",
)

result = agent.run_sync("What are the latest developments in WebAssembly?")
print(result.output)

Async Agent

import asyncio
from pydantic_ai import Agent
from quercle_pydantic_ai import quercle_tools

agent = Agent("openai:gpt-4o", tools=quercle_tools())

async def main():
    result = await agent.run("Search for trending AI papers this week")
    print(result.output)

asyncio.run(main())

Streaming

import asyncio
from pydantic_ai import Agent
from quercle_pydantic_ai import quercle_tools

agent = Agent("openai:gpt-4o", tools=quercle_tools())

async def main():
    async with agent.run_stream("Summarize the latest AI news") as response:
        async for text in response.stream_text():
            print(text, end="", flush=True)

asyncio.run(main())

Individual Tools

from quercle_pydantic_ai import (
    quercle_search_tool,
    quercle_fetch_tool,
    quercle_raw_search_tool,
    quercle_raw_fetch_tool,
    quercle_extract_tool,
)

# Use only search
agent = Agent("openai:gpt-4o", tools=[quercle_search_tool()])

# Use only fetch
agent = Agent("openai:gpt-4o", tools=[quercle_fetch_tool()])

# Combine specific tools
agent = Agent("openai:gpt-4o", tools=[
    quercle_search_tool(),
    quercle_raw_fetch_tool(),
    quercle_extract_tool(),
])

With QuercleToolset

from pydantic_ai import Agent
from quercle_pydantic_ai import QuercleToolset

# All 5 tools with domain filtering
toolset = QuercleToolset(
    search_allowed_domains=["docs.python.org", "realpython.com"],
)

# Selectively include tools
toolset = QuercleToolset(
    include_raw_fetch=False,
    include_raw_search=False,
    include_extract=False,
)

agent = Agent("openai:gpt-4o", toolsets=[toolset])

Configuration

API Reference

License

MIT