deep-search-agent

A Python library for deep internet searches (deep search), similar to the deep research features of ChatGPT and Claude. Built on top of LangChain's deepagents.

📖 Documentation: https://giurlanda.github.io/deep-search-agent/

Architecture

The create_deep_search_agent factory returns a deep agent configured with the orchestrator + specialized sub-agents + evaluation loop pattern:

Each sub-agent runs with an isolated context: raw page content does not pollute the orchestrator's memory; only the synthetic reports and the files in findings/ bubble up.

Installation

uv sync            # from the repository
# or, as a dependency:
uv add deep-search-agent

Requires Python ≥ 3.12. The search tool needs a reachable SearxNG instance with the JSON format enabled (default: http://localhost:8888).

Quickstart

from deep_search_agent import create_deep_search_agent

agent = create_deep_search_agent(
    model="anthropic:claude-sonnet-4-6",
    searxng_base_url="http://localhost:8888",
    max_research_cycles=3,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "State of the art in quantum error correction in 2026?"}]},
    config={"configurable": {"thread_id": "research-1"}},
)
print(result["messages"][-1].content)

The default evaluation rubric (DEEP_SEARCH_RUBRIC) is injected automatically: the refinement loop works with no configuration. For an ad-hoc rubric, pass it in the invoke state ({"rubric": "- ..."}) or to the factory (rubric="- ...").

Factory parameters

Deep-search-specific parameters:

All other keyword arguments (tools, checkpointer, store, skills, interrupt_on, ...) are passed through unchanged to create_deep_agent.

Extensions

Adding a retrieval agent (RAG) over the internal knowledge base

rag_agent = {
    "name": "rag-agent",
    "description": "Retrieval over the internal company knowledge base",
    "system_prompt": "Search the vector store and save results to findings/.",
    "tools": [my_vector_store_tool],
}

agent = create_deep_search_agent(
    model="anthropic:claude-sonnet-4-6",
    subagents=[rag_agent],
)

Adding search engines

from langchain_tavily import TavilySearch

agent = create_deep_search_agent(
    model="anthropic:claude-sonnet-4-6",
    search_tools=[TavilySearch(max_results=5)],
)

Persistent backend for findings

from deepagents.backends import FilesystemBackend

agent = create_deep_search_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=FilesystemBackend(root_dir="./research", virtual_mode=True),
)

Testing

uv run pytest

The unit tests require neither network nor API keys: HTTP and LLM are simulated.

Publishing

Releases are published to PyPI by the publish workflow, triggered on pushing a v* tag. It uses PyPI Trusted Publishing (OIDC), so no API token is stored.

One-time setup on PyPI (Account → Publishing → Add a pending publisher):

To cut a release: bump __version__ in src/deep_search_agent/__init__.py, update the CHANGELOG, then push a matching tag (e.g. git tag v0.4.1 && git push origin v0.4.1). Build locally with uv build and validate with uvx twine check dist/*.

Package structure

src/deep_search_agent/
├── factory.py       # create_deep_search_agent
├── prompts.py       # orchestrator/sub-agent prompts + default rubric
├── middleware.py    # DefaultRubricMiddleware (rubric auto-injection)
├── subagents.py     # perspective/search/fetch/fact-check agent definitions
└── tools/
    ├── search.py    # SearxNG tool
    └── fetch.py     # URL fetch tool (trafilatura + pypdf)