iflow-mcp_howe829-websearch-mcp-server 0.1.0__py3-none-any.whl

config.py

@@ -0,0 +1,20 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    bing_search_base_url: str
+    google_search_base_url: str
+    cc: str
+    language: str
+    impersonate: str
+    host: str
+    port: int
+    server_mode: str
+    llm_base_url: str
+    llm_api_key: str
+    llm_model_name: str
+
+
+settings = Settings()

http_client.py

@@ -0,0 +1,66 @@
+import asyncio
+import sys
+import nodriver as uc
+from curl_cffi import requests, AsyncSession
+from markitdown import MarkItDown
+from io import BytesIO
+from requests import Request
+from typing import Optional
+from config import settings
+
+md = MarkItDown(enable_plugins=False)
+
+
+class AsyncHttpClient:
+    def __init__(self):
+        if self.is_windows:
+            self._session = requests.Session(impersonate=settings.impersonate)
+        else:
+            self._session = AsyncSession(impersonate=settings.impersonate)
+
+    @property
+    def is_windows(self):
+        return sys.platform.startswith("win")
+
+    async def _get_by_curl_async(self, url: str, params: Optional[dict]) -> str:
+        self._session.acurl.loop = asyncio.get_running_loop()
+        response = await self._session.get(url=url, params=params)
+        return response.text
+
+    def _get_by_curl(self, url: str, params: Optional[dict]) -> str:
+        response = self._session.get(url=url, params=params)
+        return response.text
+
+    async def _get_by_browser(self, url: str, params: Optional[dict]) -> str:
+        driver = await uc.start()
+        try:
+            req = Request("GET", url, params=params).prepare()
+            url = req.url if req.url is not None else url
+            tab = await driver.get(url)
+            await asyncio.sleep(5)
+            text = await tab.get_content()
+            return text
+        except Exception as e:
+            return f"Error when using browser: {str(e)}"
+        finally:
+            driver.stop()
+
+    async def get(
+        self, url: str, params: Optional[dict] = None, use_browser: bool = False
+    ) -> str:
+        if use_browser:
+            return await self._get_by_browser(url, params)
+        if self.is_windows:
+            return self._get_by_curl(url, params)
+        return await self._get_by_curl_async(url, params)
+
+    async def get_markdown(
+        self, url: str, params: Optional[dict] = None, use_browser: bool = False
+    ) -> str:
+        text = await self.get(url=url, params=params, use_browser=use_browser)
+        buffer = BytesIO(text.encode("utf-8"))
+        result = md.convert(buffer)
+        return result.text_content
+
+
+aio_client = AsyncHttpClient()

iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_howe829-websearch-mcp-server
+Version: 0.1.0
+Summary: Add your description here
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: curl-cffi>=0.11.1
+Requires-Dist: fastmcp>=2.5.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: markitdown[all]>=0.1.1
+Requires-Dist: nodriver>=0.46.1
+Requires-Dist: openai-agents[litellm]>=0.0.17
+Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pytest-asyncio>=1.0.0
+Requires-Dist: pytest>=8.3.5
+Requires-Dist: ruff>=0.11.12
+Description-Content-Type: text/markdown
+
+# WebSearch MCP Server
+
+A simple web search server that supports free search and converts URL content to Markdown. [中文](README-zh.md)
+
+## Features
+
+-   **Web Search:** Perform web searches using different providers. Supported providers: Bing, Baidu, Google(with browser_use).
+-   **Markdown Conversion:** Convert the content of a URL into Markdown format.
+-   **Wechat Official Account Articles:** Search and retrive wechat official account articles content.
+-   **GitHub Search:** Easily search for anything on GitHub — repositories, users, issues, and more.
+
+## Getting Started
+
+### Prerequisites
+
+-   Python 3.12 or higher
+-   uv for dependency management (or pip)
+
+### Installation
+
+1.  Clone the repository:
+
+    ```bash
+    git clone https://github.com/Howe829/websearch-mcp-server.git
+    cd websearch-mcp-server
+    ```
+
+2.  Install the dependencies using uv (Recomend):
+
+    ```bash
+    uv venv && uv sync
+    ```
+
+    Or, if you prefer using pip:
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+### Configuration
+
+1.  Create a `.env` file based on the `.env.example` file:
+
+    ```bash
+    cp .env.example .env
+    ```
+
+2.  Modify the `.env` file with your desired settings:
+
+    ```
+    BING_SEARCH_BASE_URL="https://www.bing.com"
+    LANGUAGE="en"
+    CC="us"
+    IMPERSONATE="edge"
+    HOST=127.0.0.1
+    PORT=8002
+    SERVER_MODE=streamable-http
+    ```
+
+### Usage
+
+Run the server using uv:
+
+```bash
+uv run python server.py
+```
+
+Or run the server using python:
+
+```bash
+source .venv/bin/activate
+python server.py
+```
+
+## Contribution
+Contributions are welcome!
+
+This project uses pytest for unit tests
+```bash
+uv pip install pytest
+uv pip install pytest-asyncio
+uv run pytest
+```
+
+And use the ruff for code sytle formatting
+```bash
+uv pip install ruff
+ruff format .
+```
+
+use mcp inpector to debug this server
+```bash
+uv run fastmcp dev server.py
+```

iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+config.py,sha256=YJ-ghBsucZW3X4jAUhhklVAAleNt7Sp0K4_jnxdbqXk,431
+http_client.py,sha256=S5n21NcVI27C4nMMgssHFEB3LR8vMGaUqtPAYMkjJvI,2214
+providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+providers/baidu.py,sha256=1Ed0FANU-B4UBMwRZLHs6gbP1s-Wcq2NPkvlygwwMLg,1286
+providers/base.py,sha256=2KrFcQQyemQzxHnyzFyX4Wq4ZXvKkjZMz2L-FcmOalg,652
+providers/bing.py,sha256=UcW5rGClRVwdLUnKgR5ai72hCvtUztFH23HhDdCr1Fs,1468
+providers/enums.py,sha256=ASog8l8ruMDLxBYRb_I2HOQ-kypbKGXKtf6nAcS2Ee0,475
+providers/factory.py,sha256=VLMHjTO6IsSa9nllxcL43ejCsu1rTR4F6xLjVnxGK68,991
+providers/github.py,sha256=PIZcXVvOir9Z57xKOFsDNGNSPE7efpRkl_tQKPb8hrY,539
+providers/google.py,sha256=woJaA-C6MZU8osn5KywNGooSKGduKaZJJmVNxZxTYsM,942
+providers/wechat.py,sha256=n7v5KHiQmrhHtKc4cI7YGNMd4GDp3MFy7XhdTc0PvCM,371
+server.py,sha256=W8UcidG39nqAIzPO_cpaNeohTQ4WGLD5Nki0pbWvLTA,5549
+xagents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xagents/agent.py,sha256=kKXNywezkhqOUeojP8vEkSk9f1EKtUG8pa3DRmLV6uA,2333
+xagents/query_optimizer.py,sha256=Z8Sz4Lpkyfnl0PoVv6tuXv3eGYBXPFZiZg-rmHu1Vvc,2677
+xagents/result_formatter.py,sha256=le9Nw4WLayUoWZqqvAYjgb1J2BEvXqtCvkEgdYqC018,2195
+iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/METADATA,sha256=_HzWBiojgoItnep9Wmy3AAqv8tzXFjp-44Gqnph1bqU,2458
+iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=iILKixFfn48v6KB6N8J_cw2DaW4eU6fdzHqhg5XYLDc,53
+iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=sWqgeExPhDaW2FhUEKSl7rsxIfMzSgo8Nj8i0ilWnJs,1072
+iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/RECORD,,

iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+websearch-mcp-server = server:main

iflow_mcp_howe829_websearch_mcp_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Howard Chan]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

providers/baidu.py

@@ -0,0 +1,35 @@
+from providers.base import BaseWebSearchProvider
+
+
+class BaiduSearch(BaseWebSearchProvider):
+    def _get_url(self):
+        return "https://www.baidu.com/s"
+
+    def _get_params(self, query: str, **kwargs) -> dict:
+        params = {
+            "wd": query,
+        }
+        return params
+
+    @property
+    def description(self):
+        return """
+        Strengths:
+        - Strong understanding of Chinese language and entity recognition
+        - Better coverage of local Chinese content (government, regional news, company sites)
+        - Excellent performance with brand names and trending topics
+        - Fast, responsive search experience
+        
+        Weaknesses:
+        - Weak support for English-language queries
+        - Limited support for structured queries (e.g., Boolean logic, site:, filetype:)
+        - Poor international or technical content retrieval compared to Bing or Google
+        
+        Query Strategy:
+        - For Chinese: Use natural language phrasing with brand or location keywords (e.g., “今日金价 上海黄金交易所”)
+        - Avoid complex English queries; translate and rephrase into Chinese where possible
+        - Emphasize relevance over syntax — focus on intent expression
+        """
+
+
+baidu_search = BaiduSearch()

providers/base.py

@@ -0,0 +1,21 @@
+from abc import abstractmethod
+from pydantic import BaseModel
+from config import settings
+from http_client import aio_client
+
+
+class BaseWebSearchProvider(BaseModel):
+    @abstractmethod
+    def _get_url(self) -> str:
+        raise NotImplementedError
+
+    @abstractmethod
+    def _get_params(self, query: str, **kwargs) -> dict:
+        raise NotImplementedError
+
+    async def search(self, query: str, use_browser: bool = False, **kwargs) -> str:
+        url = self._get_url()
+        params = self._get_params(query=query, **kwargs)
+        return await aio_client.get_markdown(
+            url=url, params=params, use_browser=use_browser
+        )

providers/bing.py

@@ -0,0 +1,41 @@
+from providers.base import BaseWebSearchProvider
+from config import settings
+
+
+class BingSearch(BaseWebSearchProvider):
+    """
+    please check out https://www.bing.com/account/general for more information
+    """
+
+    def _get_url(self):
+        return f"{settings.bing_search_base_url}/search"
+
+    def _get_params(self, query: str, **kwargs) -> dict:
+        params = {
+            "q": query,
+            "cc": kwargs.get("cc") or settings.cc,
+            "setlang": kwargs.get("lang") or settings.language,
+        }
+        return params
+
+    @property
+    def description(self):
+        return """
+        Strengths:
+        - Excellent support for English queries
+        - Handles structured search operators well (site:, filetype:, before:, after:, etc.)
+        - Good at answering natural language questions (especially in English)
+        - Strong performance for technical, coding, and international finance topics
+        
+        Weaknesses:
+        - Less effective at retrieving localized Chinese content
+        - Sometimes inferior Chinese-language result quality compared to Baidu
+        
+        Query Strategy:
+        - For English: Use precise keywords + operators (e.g., `gold price today site:kitco.com`)
+        - For Chinese: Keep queries concise but add intent-enhancing modifiers (e.g., “实时”, “走势图”)
+        - Prefer Bing for technical, financial, or global information needs
+        """
+
+
+bing_search = BingSearch()

providers/enums.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+
+class WebSearchProvidersEnum(str, Enum):
+    BAIDU = "baidu"
+    BING = "bing"
+    WECHAT = "wechat"
+    GITHUB = "github"
+    GOOGLE = "google"
+
+
+class GithubSearchTypesEnum(str, Enum):
+    REPO = "repositories"
+    CODE = "code"
+    ISSUE = "issues"
+    PR = "pullrequests"
+    DISCUSS = "discussions"
+    USER = "users"
+    COMMIT = "commits"
+    PACKAGE = "registrypackages"
+    WIKI = "wikis"
+    TOPIC = "topics"
+    MARKETPLACE = "marketplace"

providers/factory.py

@@ -0,0 +1,24 @@
+from providers.base import BaseWebSearchProvider
+from providers.enums import WebSearchProvidersEnum
+from providers.bing import bing_search
+from providers.wechat import wechat_search
+from providers.github import github_search
+from providers.baidu import baidu_search
+from providers.google import google_search
+
+
+class WebSearchProviderFactory:
+    def get_provider(self, provider_name: str) -> BaseWebSearchProvider:
+        match provider_name:
+            case WebSearchProvidersEnum.BAIDU.value:
+                return baidu_search
+            case WebSearchProvidersEnum.BING.value:
+                return bing_search
+            case WebSearchProvidersEnum.WECHAT.value:
+                return wechat_search
+            case WebSearchProvidersEnum.GITHUB.value:
+                return github_search
+            case WebSearchProvidersEnum.GOOGLE.value:
+                return google_search
+            case _:
+                raise ValueError(f"Unsupported provider: [{provider_name}]")

providers/github.py

@@ -0,0 +1,22 @@
+from providers.base import BaseWebSearchProvider
+from providers.enums import GithubSearchTypesEnum
+
+
+class GithubSearch(BaseWebSearchProvider):
+    """
+    https://www.github.com
+    """
+
+    def _get_url(self):
+        return "https://www.github.com/search"
+
+    def _get_params(self, query: str, **kwargs) -> dict:
+        params = {
+            "q": query,
+            "type": kwargs.get("type", GithubSearchTypesEnum.REPO.value),
+            "p": kwargs.get("page", 1),
+        }
+        return params
+
+
+github_search = GithubSearch()

providers/google.py

@@ -0,0 +1,30 @@
+from providers.base import BaseWebSearchProvider
+from config import settings
+from http_client import aio_client
+
+
+class GoogleSearch(BaseWebSearchProvider):
+    def _get_url(self):
+        return f"{settings.google_search_base_url}/search"
+
+    def _get_params(self, query: str, **kwargs) -> dict:
+        cc = kwargs.get("cc") or settings.cc
+        lang = kwargs.get("lang") or settings.language
+        params = {
+            "q": query,
+            "lr": f"lang_{lang}",
+            "cr": f"country{cc.upper()}",
+        }
+        return params
+
+    async def search(self, query: str, **kwargs) -> str:
+        url = self._get_url()
+        params = self._get_params(query=query, **kwargs)
+        return await aio_client.get_markdown(
+            url=url,
+            params=params,
+            use_browser=True,  # google search must use browser to query, due to it's strictly anti-bot pilocy
+        )
+
+
+google_search = GoogleSearch()

providers/wechat.py

@@ -0,0 +1,17 @@
+from providers.base import BaseWebSearchProvider
+
+
+class WechatSearch(BaseWebSearchProvider):
+    """
+    https://weixin.sogou.com
+    """
+
+    def _get_url(self):
+        return "https://weixin.sogou.com/weixin"
+
+    def _get_params(self, query: str, **kwargs) -> dict:
+        params = {"query": query, "type": 2}
+        return params
+
+
+wechat_search = WechatSearch()

server.py

@@ -0,0 +1,211 @@
+import re
+import asyncio
+from fastmcp import FastMCP
+from urllib.parse import urljoin
+from typing import Literal
+
+from providers.factory import WebSearchProviderFactory
+from providers.enums import WebSearchProvidersEnum, GithubSearchTypesEnum
+from http_client import aio_client
+from config import settings
+from xagents.agent import agent_search, SearchResult
+
+server = FastMCP("WebSearch MCP Server")
+
+provider_factory = WebSearchProviderFactory()
+
+@server.tool(name="AgentSearch")
+async def agent_search_tool(
+    query: str,
+) -> SearchResult:
+    """
+    Perform a agentic search
+
+    Args:
+        query: The search query.
+
+    Returns:
+        instance of SearchResult
+    """
+    return await agent_search.search(query)
+    
+
+@server.tool(name="BingSearch")
+async def bing_search(
+    query: str,
+    cc: str = "us",
+    lang: str = "en",
+    use_browser: bool = False,
+) -> str:
+    """
+    Perform a bing search.
+
+    Args:
+        query: The search query.
+        cc: Country/Region code for example: us, cn, jp, etc.
+        lang: Language such as en, zh-CN, ja, etc
+        use_browser: Whether to use a browser to query, you must try use_browser=False first
+
+    Returns:
+        Search result in markdown syntax.
+    """
+
+    engine = provider_factory.get_provider(
+        provider_name=WebSearchProvidersEnum.BING.value
+    )
+    result = await engine.search(query=query, use_browser=use_browser, cc=cc, lang=lang)
+    return result
+
+
+@server.tool(name="BaiduSearch")
+async def baidu_search(
+    query: str,
+    use_browser: bool = False,
+) -> str:
+    """
+    Perform a baidu search.
+
+    Args:
+        query: The search query.
+        use_browser: Whether to use a browser to query, you must try use_browser=False first
+
+    Returns:
+        Search result in markdown syntax.
+    """
+
+    engine = provider_factory.get_provider(
+        provider_name=WebSearchProvidersEnum.BAIDU.value
+    )
+    result = await engine.search(query=query, use_browser=use_browser)
+    return result
+
+
+@server.tool(name="GoogleSearch")
+async def websearch(
+    query: str,
+    cc: str = "us",
+    lang: str = "en",
+) -> str:
+    """
+    Perform a google search.
+
+     Args:
+         query: The search query.
+         cc: Country/Region code for example: us, cn, jp, etc.
+         lang: Language such as en, zh-CN, ja, etc
+
+     Returns:
+         Search result in markdown syntax.
+    """
+
+    engine = provider_factory.get_provider(
+        provider_name=WebSearchProvidersEnum.GOOGLE.value
+    )
+    result = await engine.search(query=query, cc=cc, lang=lang)
+    return result
+
+
+@server.tool(name="OpenUrl")
+async def open_url(url: str) -> str:
+    """
+    Open a URL and retrieve its content.
+
+    Args:
+        url: The URL to be opened.
+
+    Returns:
+        Web content in markdown syntax.
+    """
+    return await aio_client.get_markdown(url)
+
+
+@server.tool(name="OpenWechatArticleLink")
+async def open_wechat_article_link(link: str) -> dict:
+    """
+    Open a wechat article link and retrieve its content.
+    Remember you have to do the WechatSearch first before you open the link, otherwise it will be failed
+
+    Args:
+        url: The URL to be opened.Generally starts with '/link'
+
+    Returns:
+        Web content in markdown syntax.
+    """
+    url = urljoin("https://weixin.sogou.com", link)
+    result = await aio_client.get(url)
+    parts = re.findall(r"url\s*\+=\s*'([^']+)'", result)
+    full_url = "".join(parts)
+    if not full_url.startswith("https"):
+        return {"error": f"bad request with link [{link}]"}
+    text = await aio_client.get_markdown(full_url)
+    return {"url": full_url, "content": text}
+
+
+@server.tool(name="WechatSearch")
+async def wechat_search(query: str) -> str:
+    """
+    Search WeChat Articles
+    Args:
+        query: search query.
+
+    Returns:
+        Search result in markdown syntax.
+    """
+
+    engine = provider_factory.get_provider(
+        provider_name=WebSearchProvidersEnum.WECHAT.value
+    )
+    result = await engine.search(query=query)
+    return result
+
+
+@server.tool(name="GithubSearch")
+async def github_search(
+    query: str,
+    type: Literal[
+        GithubSearchTypesEnum.REPO,
+        GithubSearchTypesEnum.CODE,
+        GithubSearchTypesEnum.ISSUE,
+        GithubSearchTypesEnum.PR,
+        GithubSearchTypesEnum.DISCUSS,
+        GithubSearchTypesEnum.USER,
+        GithubSearchTypesEnum.COMMIT,
+        GithubSearchTypesEnum.PACKAGE,
+        GithubSearchTypesEnum.WIKI,
+        GithubSearchTypesEnum.TOPIC,
+        GithubSearchTypesEnum.MARKETPLACE,
+    ],
+    page: int = 1,
+) -> str:
+    """
+    Search All Github
+    Args:
+        query: search query.
+        type: search type support: repositoris, code, issues, pullrequests, users, discussions, commits, packages, wikis, topics, marketplace.
+        page: pagination param default is 1
+
+    Returns:
+        Search result in markdown syntax.
+    """
+
+    engine = provider_factory.get_provider(
+        provider_name=WebSearchProvidersEnum.GITHUB.value
+    )
+    result = await engine.search(query=query, type=type, page=page)
+    return result
+
+
+async def main():
+    match settings.server_mode:
+        case "stdio":
+            await server.run_async(transport=settings.server_mode)
+        case "sse" | "streamable-http":
+            await server.run_async(
+                transport=settings.server_mode, host=settings.host, port=settings.port
+            )
+        case _:
+            raise ValueError(f"Unsupported server mode [{settings.server_mode}]")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

xagents/agent.py

@@ -0,0 +1,59 @@
+from agents import Runner
+from pydantic import BaseModel
+from asyncio import TaskGroup
+from loguru import logger
+
+from xagents.query_optimizer import query_opt_agent, WebSearchPlan, WebSearchItem
+from xagents.result_formatter import result_format_agent, SearchResult
+from providers.factory import WebSearchProviderFactory
+
+
+class RawSearchResult(BaseModel):
+    engine_name: str
+    content: str
+
+
+class AgentSearch:
+    async def _optimize_query(self, query: str) -> WebSearchPlan:
+        result = await Runner.run(input=query, starting_agent=query_opt_agent)
+        return result.final_output_as(WebSearchPlan)
+
+    async def _perform_search(self, item: WebSearchItem) -> RawSearchResult:
+        engine = WebSearchProviderFactory().get_provider(item.engine_name)
+        result = await engine.search(query=item.query, use_browser=True)
+        return RawSearchResult(engine_name=item.engine_name, content=result)
+
+    async def _format_result(self, raw_result: RawSearchResult) -> SearchResult:
+        result = await Runner.run(
+            input=raw_result.model_dump_json(), starting_agent=result_format_agent
+        )
+        return result.final_output_as(SearchResult)
+
+    async def _execute_search_plan(self, plan: WebSearchPlan) -> list[RawSearchResult]:
+        tasks = []
+        async with TaskGroup() as tg:
+            for search_item in plan.searches:
+                task = tg.create_task(self._perform_search(search_item))
+                tasks.append(task)
+
+        results: list[RawSearchResult] = [t.result() for t in tasks]
+        return results
+
+    def _merge_search_results(self, search_results: list[SearchResult]) -> SearchResult:
+        items = []
+        for r in search_results:
+            items.extend(r.items)
+        return SearchResult(items=items)
+
+    async def search(self, query: str) -> SearchResult:
+        search_plan = await self._optimize_query(query=query)
+        raw_results = await self._execute_search_plan(plan=search_plan)
+        tasks = []
+        async with TaskGroup() as tg:
+            for raw_result in raw_results:
+                task = tg.create_task(self._format_result(raw_result))
+                tasks.append(task)
+        results: list[SearchResult] = [t.result() for t in tasks]
+        return self._merge_search_results(results)
+
+agent_search = AgentSearch()

xagents/query_optimizer.py

@@ -0,0 +1,72 @@
+from agents import Agent
+from config import settings
+from agents.extensions.models.litellm_model import LitellmModel
+from pydantic import BaseModel, Field
+
+
+class WebSearchItem(BaseModel):
+    engine_name: str = Field(
+        description="websearch engine name in lowercase eg: bing, baidu"
+    )
+    query: str = Field(description="optimized query")
+
+
+class WebSearchPlan(BaseModel):
+    searches: list[WebSearchItem]
+
+
+INSTRUCTION = """
+You are a Query Optimizer Agent.
+Your task is to reformulate user-provided search queries to maximize search effectiveness, based on the selected search engine and the query's language.
+You must understand and adapt to the strengths and limitations of each search engine, and generate optimized queries that match their search capabilities.
+---
+🔍 Bing (Microsoft Search Engine)
+- Strengths:
+  - Excellent for English-language queries.
+  - Supports advanced operators like `site:`, `filetype:`, `intitle:`, `before:`, `after:`.
+  - Well-suited for technical, financial, and global information.
+  - Handles both keyword and natural language queries.
+
+- Query Optimization Strategy:
+  - For English queries, use precise keywords + advanced operators.
+  - For Chinese queries, use concise keywords + add clarity-enhancing modifiers (e.g., 实时, 走势).
+  - Add context (e.g., date, topic scope) to disambiguate broad queries.
+---
+
+🔍 Baidu (Chinese Search Engine)
+
+- Strengths:
+  - Strong Chinese-language understanding and entity recognition.
+  - Excellent access to local Chinese content, government sources, brands, and services.
+  - Excels in natural-language, brand-aware queries.
+
+- Weaknesses:
+  - Poor support for English queries and advanced operators.
+  - Limited support for Boolean/structured syntax.
+
+- Query Optimization Strategy:
+  - Use natural, fluent Chinese queries.
+  - Add brand names, location terms, or entity types to improve precision.
+  - Avoid using English or complex operators. Translate English concepts into Chinese and simplify.
+
+---
+
+🎯 Optimization Rules:
+
+- Detect the language of the original query.
+- Match query complexity to search engine capabilities.
+- Add specificity (brand, time, location) and intent indicators (e.g., "实时", "technical analysis", "forecast").
+- Avoid redundant words or vague terms.
+- Your goal is to maximize the relevance and precision of search results for the target engine.
+"""
+
+query_opt_agent = Agent(
+    name="Query Optimizer Agent",
+    instructions=INSTRUCTION,
+    model=LitellmModel(
+        model=f"openai/{settings.llm_model_name}",
+        base_url=settings.llm_base_url,
+        api_key=settings.llm_api_key,
+    ),
+    output_type=WebSearchPlan,
+)

xagents/result_formatter.py

@@ -0,0 +1,53 @@
+from pydantic import BaseModel, Field
+from agents import Agent
+from agents.extensions.models.litellm_model import LitellmModel
+from config import settings
+
+class SearchResultItem(BaseModel):
+    title: str = Field(description="search item title")
+    description: str = Field(description="search item description")
+    source_url: str = Field(description="search item source url")
+    engine:str = Field(description="search engine name")
+
+class SearchResult(BaseModel):
+    items: list[SearchResultItem]
+
+INSTRCUTION = """
+You are a Search Result Formatter Agent.
+
+Your task is to extract structured search result items from unstructured or semi-structured search result content written in Markdown.
+
+Each result must be extracted as a SearchResultItem object with the following fields:
+- title: The clickable title of the result (typically found in bold or header formatting).
+- description: A concise summary or snippet describing the content of the result.
+- source_url: The original source URL (typically found in parentheses or Markdown links).
+
+---
+
+🧪 Input Format:
+You will receive search results formatted in Markdown, for example:
+
+- **Gold Price Today - Kitco**
+  [https://www.kitco.com/gold-price-today](https://www.kitco.com/gold-price-today)  
+  Live spot gold prices and charts. Get historical data and news updates on XAUUSD.
+
+- **Shanghai Gold Exchange Daily Price**
+  [https://www.sge.com.cn](https://www.sge.com.cn)  
+  Official gold trading prices published by the Shanghai Gold Exchange.
+
+---
+
+✅ Extraction Rules:
+1. For each search engine group (e.g., Bing, Baidu), extract **at most the top 3 results**.
+2. Extract each result as one `SearchResultItem`.
+3. If a result has multiple lines, group them based on proximity (title + description + link).
+4. Ignore Markdown formatting — only extract plain text content.
+5. If any field is missing, skip the entry.
+6. Return a **JSON array** of SearchResultItem objects.
+"""
+result_format_agent = Agent(
+    name="ResultFormatAgent",
+    instructions=INSTRCUTION,
+    model=LitellmModel(model=f"openai/{settings.llm_model_name}", base_url=settings.llm_base_url, api_key=settings.llm_api_key),
+    output_type=SearchResult
+)