[Integration] bytedance/deer-flow — You.com web_search provider + setup wizard entry

[brainsparker]

Target Repository URL

https://github.com/bytedance/deer-flow

You.com API(s)

search

Estimated Complexity

medium

Integration Description

DeerFlow is ByteDance's open-source long-horizon SuperAgent harness (LangGraph/LangChain: sandboxes, memory, skills, sub-agents). It exposes an explicit deerflow.community.<vendor> contribution namespace for search and fetch providers. Eight web_search providers ship today — DuckDuckGo (keyless default), Tavily, InfoQuest, Exa, Firecrawl, fastCRW, Brave, GroundRoute — plus Serper and SearXNG in the config template. You.com is absent from all of them.

This integration adds You.com as a web_search provider: a new deerflow.community.youcom package exposing web_search_tool, registered in the setup wizard's provider picker, the config template, the doctor check, and the backend + frontend docs.

Because DeerFlow is a long-horizon research harness, search volume per session is high — well above a chat wrapper.

Target Repo Contributing Guidelines

https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Planned Approach

Single PR against main (not main-1.x, which is maintenance-only and shares no code with v2). Scope is web_search only — no web_fetch; Jina AI / Crawl4AI / Browserless already own that slot.

Files:

• backend/packages/harness/deerflow/community/youcom/{__init__.py,tools.py} — web_search_tool via @tool("web_search", parse_docstring=True), httpx only (already a core dependency), modeled on the groundroute and brave providers.
• backend/tests/test_youcom_tools.py — mirrors test_groundroute_tools.py.
• config.example.yaml — commented web_search stanza in the provider block.
• scripts/wizard/providers.py — SearchProvider entry appended to SEARCH_PROVIDERS (appended, so existing wizard test indices don't shift).
• scripts/doctor.py — provider entry so make doctor recognizes the tool.
• backend/docs/CONFIGURATION.md, frontend/src/content/{en,zh}/harness/tools.mdx — docs.

Dual-mode auth, which is the differentiator against every other keyed provider in that picker:

• No key → https://api.you.com/v1/agents/search (keyless, 100 free searches/day). Makes You.com the second zero-config option in the wizard alongside DuckDuckGo, and the only real API among them.
• YDC_API_KEY set (env or tool api_key config) → https://api.you.com/v1/search with X-API-Key.

Both paths return the same response shape, so normalization is shared. Endpoint and headers are picked together off whether a key is present, so a stale key never reaches the keyless path.

Status Checklist

• Claimed this integration (self-assign)
• Filed issue or opened discussion in target repo
• Opened PR in target repo
• You.com API calls send the standard integration User-Agent (youdotcom-integration/<owner>-<repo>)
• You.com links in contributed docs carry the standard UTM parameters
• PR merged or rejected

Links

Target repo issue: none filed — a mechanical provider addition is not issue-first here (GroundRoute #3675, Crawl4AI #3821 both landed as cold PRs)
Target repo PR: bytedance/deer-flow#4897

Additional Notes

Merge precedent: GroundRoute (#3675), Crawl4AI (#3821), and fastCRW all landed post-2.0 in the current 2.1.0 cycle — small vendors, in-cycle merges, no issue-first requirement for a mechanical provider addition. GroundRoute's PR is the structural template.

Merge latency risk: ~386 open PRs / ~574 open issues. Expect the PR to sit.

Positioning: DeerFlow README banner-promotes BytePlus InfoQuest as ByteDance's own search and crawling toolset, and it is already in the wizard with a quality claim attached. Provider slot and docs slot are winnable; default is not. Tavily's existing "Recommended, free tier available" wizard string is deliberately left untouched — editing it would turn a mechanical provider addition into a positioning argument and stall the merge.

Fallback if the PR stalls: DeerFlow has adopted the Claude skills format (.agent/skills, skills/public/, npx skills add, a shipping claude-to-deerflow skill) and supports configurable MCP servers with OAuth. Our MCP endpoint plus a SKILL.md is a zero-permission second shot needing no maintainer approval.

No new dependency: httpx is already core to the harness. No pyproject extra is added, so uv.lock stays untouched (the repo has a CI gate enforcing lock sync).

---

User-Agent shipped: deerflow-harness/<version> youdotcom-integration/bytedance-deer-flow (case 1 — contributed into a third-party repo; version read via importlib.metadata). Sent to You.com hosts only, on both the keyed and keyless paths, and pinned by a parametrized test.

UTM campaign: 2026-08-oss-integrations, utm_source=bytedance-deer-flow, utm_medium=oss_integration. Links placed in config.example.yaml (utm_content=sample) and both tools.mdx docs pages (utm_content=docs).

[brainsparker]

PR opened: bytedance/deer-flow#4897 — feat(community): add You.com web search provider

Ratchet: Not Started → PR Submitted.

Scope shipped (10 files, +604/-5):

• backend/packages/harness/deerflow/community/youcom/{tools.py,__init__.py} — web_search_tool, httpx only.
• scripts/wizard/providers.py — SEARCH_PROVIDERS entry (the setup-wizard picker).
• scripts/doctor.py — registered under free_providers["web_search"], so make doctor reports ok with no key.
• config.example.yaml, backend/docs/CONFIGURATION.md, frontend/src/content/{en,zh}/harness/tools.mdx, and the provider list in backend/packages/harness/deerflow/tools/AGENTS.md.
• backend/tests/test_youcom_tools.py — 24 tests.

Dual-mode auth is the differentiator. With no key the provider uses api.you.com/v1/agents/search (keyless free tier); with YDC_API_KEY set it uses api.you.com/v1/search with X-API-Key. That makes You.com the second zero-config option in the wizard alongside DuckDuckGo, and the only real search API among them — so make setup can hand a fresh install a working search API without a signup detour. The wizard entry therefore uses env_var=None; a keyed operator sets the var themselves.

Endpoint and headers are always chosen together, so a stale key can never hit the keyless path. Pinned by a test.

Verified beyond CI: full backend suite green locally (11798 passed, 78 skipped), lint clean, and the real tool driven against the live API on both paths. Doctor output confirmed. Tavily's "Recommended, free tier available" wizard string was deliberately left untouched.

Appended, not inserted, at the end of SEARCH_PROVIDERS — an existing wizard test asserts index 3 is Exa, and reordering would have turned a mechanical addition into a positioning argument.

Next: watch for review. Repo has ~386 open PRs, so expect latency. If it stalls, the fallback is the MCP endpoint + a SKILL.md via their .agent/skills / npx skills add path, which needs no maintainer approval.

[brainsparker]

Blocked on CLA — needs a human.

license/cla is pending on PR #4897. The lint and unit-test workflows haven't started either, which is consistent with a first-time-contributor gate on top of it.

Sign here: https://cla-assistant.io/bytedance/deer-flow?pullRequest=4897

Nothing else is outstanding — mergeable: MERGEABLE, auto-labeled area:backend, area:frontend, area:ci, area:docs, size/L, risk:medium.

[brainsparker]

CLA signed — unblocked. license/cla now passes on PR #4897 and the PR is MERGEABLE.

Remaining checks (pr-labels pass; issue-triage and reviewing skipped) are triage automation. The backend lint and unit-test workflows still haven't been dispatched — DeerFlow's backend-unit-tests.yml triggers on pull_request types [opened, synchronize, reopened, ready_for_review], so a first-time contributor's run likely needs maintainer approval. Nothing further to do on our side; the local run was green (11798 passed, lint clean).