modelscope/ms-agent — optional You.com search engine provider (youcom_search)

[mouse-value-add]

Source Repo

https://github.com/modelscope/ms-agent

Why Selected

Queue B (Tavily-parity), Tier B3. 4.4k★, active (pushed 2026-09-21, very active), Python, Apache-2.0. ModelScope's agent framework with MCP Playground and a clean SearchEngine abstraction that already has Exa, SerpApi, Tavily, and ArXiv providers. Tavily PR is open here — maintainer appetite for provider additions. 2000★+ rule applies: dead-clean surface via existing SearchEngine provider pattern.

Candidate Evaluation Summary

• Stars: 4,399 (2000★+ rule: dead-clean surface via existing provider pattern)
• Activity: Pushed 2026-09-21 (5 days ago), very active
• Language: Python
• Distribution Surface: SearchEngine provider abstraction (SearchEngine base class + search_engine.py factory + websearch_tool.py dispatch + search_request.py generator)
• Existing Providers: Exa, SerpApi, ArXiv, Tavily
• Implementation Path: Clean — single youcom/ directory following TavilySearch pattern exactly

Integration Type

Search engine provider (SearchEngine subclass) — following the repo's existing provider pattern

Distribution Surface Leveraged

The SearchEngine base class (search_base.py), search_engine.py factory, websearch_tool.py dispatch, and search_request.py generator. You.com is registered alongside Exa, SerpApi, Tavily, and ArXiv as a pickable search engine.

Env Vars and Setup

• YDC_API_KEY (optional) — You.com API key. When unset, uses the keyless free tier at https://api.you.com/v1/agents/search. Get a key at https://you.com/platform/api-keys
• In .env.example: documented as optional under the Tools section
• Config: set engine: youcom in projects/deep_research/conf.yaml (commented-out example provided)

Usage Example

Set YDC_API_KEY in .env, then:

# conf.yaml
SEARCH_ENGINE:
  engine: youcom

Or use programmatically:

from ms_agent.tools.search.youcom import YouSearch
engine = YouSearch()
results = engine.search(YouSearchRequest(query='AI agents', num_results=5))

Fallback/Error Handling

• Missing YDC_API_KEY uses the keyless free tier (no error, no config needed)
• API errors (HTTP 429/401/403) raise YouHTTPError with structured fields (status, code, retry_after)
• Used through get_web_search_tool() or get_search_engine(), not directly — all existing error paths handle failures

Validation

• All 4 new files compile (schema.py, http.py, search.py, init.py)
• Schema tests: YouSearchRequest body, YouSearchResult.to_list parsing
• HTTP error classification: quota (429), auth (401/403), transport
• YouSearch class: keyless mode, keyed mode, build_request_from_args
• SearchEngineType.YOCOM and ENGINE_TOOL_NAMES registered
• .env.example updated
• conf.yaml updated with youcom example
• fin_research README updated with You.com mention
• No new dependencies (stdlib only: urllib, json)

Status

• Tracking issue created
• Branch pushed (pending)
• PR opened (pending)
• PR link: TBD

[mouse-value-add]

Implementation Complete

• Branch: https://github.com/mouse-value-add/ms-agent/tree/feat/youcom-search-integration
• PR: feat: add optional you.com search integration modelscope/ms-agent#1004
• Integration Type: Search engine provider (SearchEngine subclass)
• Distribution Surface: Existing SearchEngine abstraction (search_base.py → youcom/ provider)
• Setup: YDC_API_KEY env var (optional — keyless free tier when unset)
• Usage: Set engine: youcom in conf.yaml, or get_search_engine('youcom')
• Validation: All 4 new files compile; schema, HTTP error classification, YouSearch keyless/keyed mode verified
• Fallback: Missing YDC_API_KEY uses keyless tier; API errors raise typed YouHTTPError