Unique Web Search
Configurable web search tool for Unique assistants: search the web, read pages, and return citation-ready content chunks.
Search Proxy (recommended)
Outbound web access should go through Unique Search Proxy (connectors/unique_search_proxy/). When SEARCH_PROXY_BASE_URL is set, search and crawl calls use unique-search-proxy-sdk; credentials and provider egress stay on the proxy pod.
| Mode | When | Behaviour |
|---|---|---|
| Proxy (recommended) | SEARCH_PROXY_BASE_URL set |
_proxy_search / _proxy_crawl via the SDK |
| Legacy | URL unset | Direct provider calls from this process (_legacy_search / _legacy_crawl) |
- New standard engines (Brave, Perplexity) are proxy-only — legacy raises.
- Custom API always runs locally (never routed through the proxy).
- Future provider work targets Search Proxy only; legacy is preserved for migrated engines.
Packages involved: unique-search-proxy-core (schemas), unique-search-proxy-sdk (HTTP), unique-search-proxy (server). System overview: connectors/unique_search_proxy/README.md.
Architecture
Search engine kinds
Standard search
Query → normalised results (URL / title / snippet / optional content). Optional page crawl via the configured crawler.
| Engine | Proxy | Notes |
|---|---|---|
| legacy + proxy | Requires scraping by default | |
| Brave | proxy-only | Rich snippets; ExposableParam knobs |
| Perplexity | proxy-only | Content extraction knobs; ExposableParam |
| Custom API | always local | Your REST endpoint |
Standard engines that live in proxy-core use ExposableParam (expose + value) for optional provider knobs. See Search Engines README.
Agent search (grounding)
An upstream AI agent / grounded model searches and returns opaque text that this tool parses into WebSearchResults.
| Engine | Proxy | Notes |
|---|---|---|
| Bing (Azure AI Foundry grounding) | legacy + proxy | Configurable requires_scraping |
| VertexAI (Gemini grounding) | legacy + proxy | Configurable requires_scraping |
Agent engines do not use ExposableParam.
Web crawlers (page readers)
| Crawler | Auth | Notes |
|---|---|---|
| Basic | none | HTTP + content-type toggles; tool-local url_blocked_patterns (legacy) |
| Tavily | TAVILY_API_KEY |
Extract API |
| Jina | JINA_API_KEY |
Reader API |
| Firecrawl | FIRECRAWL_API_KEY |
Batch scrape |
No Crawl4AI. Crawler configs have no exposable LLM knobs.
Execution modes
| Mode | Status | Behaviour |
|---|---|---|
| V1 | Stable | Refine query → search → crawl → process |
| V2 | Stable | Parallel plan steps (search / read URL) |
| V3 | Experimental | Agent loop: snippet search vs on-demand read_urls |
Proxy vs legacy is transparent to executors.
Detailed subsystem docs
Configuration
SEARCH_PROXY_BASE_URL— enables the Search Proxy client- Provider API keys (on the proxy pod when proxy is enabled; otherwise on assistants-core for legacy)
- Search / crawler / content-processing settings via
WebSearchConfig
Dependency management (uv.lock + min/latest testing)
This package is a library and uses uv for dependency management.
We run tests additionally with minimal dependencies to ensure that the listed ranges are valid. NOTE: We use lowest-direct, not lowest. Lowest attempts to use the lowest possible dependency versions transitively causing issues if a dependency has incorrect metadata. Example:
- google-cloud-aiplatform says it works with shapely<3.0.0.
- The lowest resolver assumes 1.0 which needs python 2 -> breaks Therefore we use lowest-direct which only sets our direct dependencies to lowest. However, this only correctly verifies our min dependencies if our code correctly lists all the required dependencies and never imports a transitive dependency. We therefore use deptry to ensure we don't use transitive dependencies and that we have no unused dependencies.
Test locally
- Latest deps and deptry:
cd tool_packages/unique_web_search
uv sync
uv run pytest
uv run deptry
- Min deps:
cd tool_packages/unique_web_search
uv venv
uv pip install -e . --resolution=lowest-direct
uv export --only-group dev --no-hashes | uv pip install -r -
uv run --no-sync pytest
1 maintainer
Release files for unique-web-search 2026.34.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| unique_web_search-2026.34.3.tar.gz | 112.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| unique_web_search-2026.34.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 285.4 kB
Release files / unique_web_search-2026.34.3.tar.gz
| Download URL | unique_web_search-2026.34.3.tar.gz |
|---|---|
| Size | 112.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
195ce8f51a6e36baf10feac8b6836e7bc8d1edcda61b1ea07f008535888fd391
|
|
BLAKE2b-256 checksum How to use checksums |
aa17fa00fcc66c23b3025d626fd10224282481e835407b50c44ebb2a87027298
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / unique_web_search-2026.34.3-py3-none-any.whl
| Download URL | unique_web_search-2026.34.3-py3-none-any.whl |
|---|---|
| Size | 172.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f49188c2f917dde07c05460dc04861b3f92f37374541df6ef4d4bc3222bb0d7
|
|
BLAKE2b-256 checksum How to use checksums |
9828dd5773237a91c3152bed01bf7e241f347037b563e9df87b631bb5467bc56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
