[Integration] heurist-network/heurist-agent-framework - You.com MCP search tools

[mouse-value-add]

Target Repository URL

https://github.com/heurist-network/heurist-agent-framework

Why this repo was selected

• Perfect star range: 819 stars (ideal mid-popular project where PRs can realistically land)
• Excellent recent activity: Last updated 2026-07-26, very active development
• Outstanding search integration fit: Framework explicitly supports "deep research, tool use, memory" and has built-in MCP support plus existing search client architecture
• Python with modular architecture: Easy to work with, clear extension points for search tools
• Professional development: Well-structured framework with external API integration patterns

Candidate evaluation summary

• heurist-network/heurist-agent-framework: SELECTED - Multi-interface AI agent framework with MCP support and explicit "deep research" capabilities plus existing search provider architecture
• lessweb/deepcode-cli: 1990 stars, TypeScript terminal coding assistant - less natural fit for search integration
• OpenCoworkAI/open-cowork: 1923 stars, desktop AI agent app - more complex integration surface

Proposed integration type

You.com search client integration as optional provider following the framework's existing search client patterns

Planned env vars and setup

• Optional YDC_API_KEY for authenticated You.com Search API access
• Falls back to keyless You.com Search API (100 free searches/day) when not provided
• Integration follows existing search client patterns (Exa, Firecrawl, DuckDuckGo)
• No default behavior changes - You.com becomes an opt-in search capability

Expected usage example

from core.clients.search_client import SearchClient

# Using environment variable (YDC_API_KEY) 
search_client = SearchClient(client_type="youcom")

# Or keyless operation
keyless_client = SearchClient(client_type="youcom", api_key="")

results = await search_client.search("AI agent frameworks 2026")

Validation performed

• ✅ Python syntax validation successful for all modified files
• ✅ Follows established search client patterns from existing implementations
• ✅ YouComClient implements full BaseSearchClient interface
• ✅ Proper integration in SearchClient provider registry
• ✅ Both authenticated and keyless operation modes supported
• ✅ Comprehensive error handling and rate limiting
• ✅ Documentation and usage examples provided
• ✅ Complete test suite covering success and error scenarios

Links

• Implementation branch: https://github.com/mouse-value-add/heurist-agent-framework/tree/feat/youcom-search-integration
• OSS PR: feat: add optional You.com search integration heurist-network/heurist-agent-framework#161

Integration type implemented

You.com search client as optional provider in the framework's existing search client architecture

Setup/env vars

• YDC_API_KEY: Optional API key for authenticated You.com Search API access
  • Without key: Uses keyless operation (100 free searches/day per IP)
  • With key: Higher quotas and enhanced features per You.com plan
• YOUCOM_API_KEY: Alternative env var for legacy compatibility
• Integration follows SearchClient(client_type="youcom") pattern

Usage example

# Agent with You.com search capabilities
from core.clients.search_client import SearchClient

search_client = SearchClient(client_type="youcom")
results = await search_client.search("latest AI agent frameworks")

for result in results["data"]:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}") 
    print(f"Type: {result['type']}")

Fallback/error behavior

• Missing API key: Uses keyless You.com Search API operation
• Rate limits (429): Graceful error with upgrade suggestion
• Network failures: Returns empty results with informative error logging
• Invalid queries: Validation with helpful error messages
• Maintains full backward compatibility with existing search functionality

Current status

Implementation complete and PR opened. Awaiting upstream review from Heurist maintainers.