Repository navigation
feat(tool): add Sofya as a selectable web_search provider - #560
Open
yusufgurdogan wants to merge 2 commits into
Open
yusufgurdogan wants to merge 2 commits into
yusufgurdogan wants to merge 2 commits into
Conversation
Adds Sofya (https://sofya.co) beside You.com, Brave Search, Tavily, SearXNG, Serply and Keenable, selected with AGENTIC_WEB_SEARCH_PROVIDER=sofya and SOFYA_API_KEY. Requests are POST /v1/search with a bearer key at the snippets depth. count is clamped to 20, freshness and domain filters are forwarded to Sofya's own parameters, and domain filters are re-checked on the response. Sofya takes at most 10 bare host names per list, so only such entries are sent and the rest is left to the gateway filter. WebSearchHandler::from_config computes the provider's concurrency ceiling once instead of once per match arm, which keeps web_search/mod.rs within the production file size limit. Signed-off-by: Yusuf Gürdoğan <yusufgurdogan@protonmail.com>
yusufgurdogan
requested review from
bbrowning,
haoshan98,
jiahuei,
leseb,
noobHappylife,
qandrew and
tjtanaa
as code owners
November 17, 2026 09:36
Signed-off-by: Yusuf Gürdoğan <yusufgurdogan@protonmail.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Sofya (API docs), a web search API for AI agents, as a selectable
web_searchprovider beside You.com, Brave Search, Tavily, SearXNG, Serply and Keenable. It follows the shape of the Tavily and Keenable providers (#329, #507). There is no linked issue.Disclosure: I work on Sofya. Happy to change the variable name, the default depth or the docs wording.
Changes by API
/v1/responses)web_searchcan run on Sofya withAGENTIC_WEB_SEARCH_PROVIDER=sofyaandSOFYA_API_KEY/v1/messages)web_search_20250305runs on the same configured providerHow the shared tool contract maps to Sofya's
POST /v1/search:Authorization: Bearer, never in the body, andDebugstays redacted through the sharedApiKey.search_depth: "snippets",topic: "general"request, so all hits land inwebandnewsstays empty.count(orsearch_context_size) is clamped to 20 asmax_results.freshnessis sent as Sofya'sfreshness:day,week,month,year, orYYYY-MM-DD:YYYY-MM-DD. Both sides treat the range as inclusive, so the dates are not widened.include_domains/exclude_domainsand re-checked on the response by the sharedDomainFilter. Sofya takes at most 10 bare host names per list and answers 422 otherwise, so only such entries are sent and the rest is left to the gateway filter.country,language,safesearchand the You.com-specific arguments have no Sofya parameter and are logged as ignored at debug level.description(the snippet), falling back tocontent;page_ageispublished_date; blank URLs are dropped; anullresultsis empty.metadata[]carries"provider": "sofya", theX-Request-Idresponse header assearch_uuidandelapsed_msaslatencyin seconds.SOFYA_API_KEYwithout echoing anything secret. 402 (out of credits, or a key limit) and 429 (withRetry-After) are never retried. Other statuses include the upstream body.WebSearchHandler::from_confignow computes the provider's concurrency ceiling once instead of once per match arm. The values are the same; without it the new arm putsweb_search/mod.rsat 507 production lines, over the 500 limit. If you prefer an exception entry in.rust-file-sizes.jsoninstead, I will switch.Flow
flowchart LR M[model calls web_search] --> H[WebSearchHandler] H -->|provider = sofya| S[SofyaSearchProvider, new] S -->|POST /v1/search, Bearer key| A[Sofya API] A -->|results, elapsed_ms, X-Request-Id| S S -->|DomainFilter re-check| H H --> O[web_search_call output]New modules
tool/web_search/sofya.rs: request shaping and response mapping for Sofya. It sits next totavily.rsandkeenable.rsand implements the sameWebSearchProvidertrait.Class diagram
classDiagram class WebSearchProvider { <<trait>> search(query, args, config) max_concurrent_requests() } class SofyaSearchProvider { client api_key: ApiKey base_url max_concurrent_requests } class SofyaSearchRequest { body: SofyaSearchBody domain_filter: DomainFilter } class SofyaSearchResponse { results: Vec~SofyaResult~ elapsed_ms } WebSearchProvider <|.. SofyaSearchProvider WebSearchHandler --> WebSearchProvider SofyaSearchProvider ..> SofyaSearchRequest : builds from WebSearchArguments SofyaSearchProvider ..> SofyaSearchResponse : parses SofyaSearchResponse ..> WebSearchProviderResponse : maps to WebSearchProviderKind --> SofyaSearchProvider : Sofya selectsTest Plan
sofya.rscover: redactedDebugand default/override base URL; the missing-key error; endpoint and bearer header; body shape, clamping and ignored arguments; freshness keywords and ranges; which domain entries are forwarded and the cap of 10; config filter precedence and the conflict check; response mapping with thecontentfallback, blank URLs,nullresults and the response-side domain filter.config.rskind assertions and the unknown-provider message now includesofya;web_search_config_selects_sofya_from_environment, plus akeenable -> sofyacase in the provider-switch loop.SofyaSearchProvider::search: a plain query,freshness: weekwith an allowlist that mixes host names and a path entry, a date range with 12 blocked domains, and an invalid key. Results,page_age,search_uuidandlatencycame back as mapped; the invalid key gaveSofya rejected the API key (401 Unauthorized); check SOFYA_API_KEY. The same body with a path entry or 11 domains sent directly returns 422, which is why those are not forwarded.cargo fmt --all -- --check: clean.cargo clippy -p agentic-server-core -p agentic-server --all-targets -- -D warnings: clean.cargo test -p agentic-server-core -p agentic-server: 3127 passed, 0 failed, 25 ignored.pre-commit run --all-files: all hooks pass, includingrust-file-sizes.