From 2f67b2a838bfa3e72a66afb240e0ba72f50c8216 Mon Sep 17 00:00:00 2001
From: jasinluo <jasinluo@tencent.com>
Date: Tue, 21 Apr 2026 21:00:42 +0800
Subject: [PATCH] =?UTF-8?q?feature:=20=E6=96=B0=E5=A2=9E=20web=5Fsearch=20?=
 =?UTF-8?q?=E5=B7=A5=E5=85=B7=EF=BC=8C=E6=94=AF=E6=8C=81=20duckduckgo=20?=
 =?UTF-8?q?=E4=B8=8E=20google=20=20=20=20=20=20=20=20=20=20=E6=96=B0?=
 =?UTF-8?q?=E5=A2=9E=20web=5Ffetch=20=E5=B7=A5=E5=85=B7=20=20=20=20=20=20?=
 =?UTF-8?q?=20=20=20=20=E6=96=B0=E5=A2=9E=20=E7=9B=B8=E5=85=B3=E7=A4=BA?=
 =?UTF-8?q?=E4=BE=8B=E5=92=8C=E4=BD=BF=E7=94=A8=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .flake8                                   |    2 +-
 docs/mkdocs/en/tool.md                    |  581 ++++++++++
 docs/mkdocs/zh/tool.md                    |  585 ++++++++++
 examples/webfetch_tool/.env               |    4 +
 examples/webfetch_tool/README.md          |  278 +++++
 examples/webfetch_tool/agent/__init__.py  |    5 +
 examples/webfetch_tool/agent/agent.py     |  166 +++
 examples/webfetch_tool/agent/config.py    |   19 +
 examples/webfetch_tool/agent/prompts.py   |   28 +
 examples/webfetch_tool/run_agent.py       |  213 ++++
 examples/websearch_tool/.env              |   12 +
 examples/websearch_tool/README.md         |  346 ++++++
 examples/websearch_tool/agent/__init__.py |    5 +
 examples/websearch_tool/agent/agent.py    |  149 +++
 examples/websearch_tool/agent/config.py   |   33 +
 examples/websearch_tool/agent/prompts.py  |   46 +
 examples/websearch_tool/run_agent.py      |  245 +++++
 pyproject.toml                            |    1 +
 tests/tools/test_websearch_tool.py        | 1191 +++++++++++++++++++++
 trpc_agent_sdk/tools/__init__.py          |   10 +
 trpc_agent_sdk/tools/_webfetch_tool.py    |  705 ++++++++++++
 trpc_agent_sdk/tools/_websearch_tool.py   |  724 +++++++++++++
 22 files changed, 5347 insertions(+), 1 deletion(-)
 create mode 100644 examples/webfetch_tool/.env
 create mode 100644 examples/webfetch_tool/README.md
 create mode 100644 examples/webfetch_tool/agent/__init__.py
 create mode 100644 examples/webfetch_tool/agent/agent.py
 create mode 100644 examples/webfetch_tool/agent/config.py
 create mode 100644 examples/webfetch_tool/agent/prompts.py
 create mode 100644 examples/webfetch_tool/run_agent.py
 create mode 100644 examples/websearch_tool/.env
 create mode 100644 examples/websearch_tool/README.md
 create mode 100644 examples/websearch_tool/agent/__init__.py
 create mode 100644 examples/websearch_tool/agent/agent.py
 create mode 100644 examples/websearch_tool/agent/config.py
 create mode 100644 examples/websearch_tool/agent/prompts.py
 create mode 100644 examples/websearch_tool/run_agent.py
 create mode 100644 tests/tools/test_websearch_tool.py
 create mode 100644 trpc_agent_sdk/tools/_webfetch_tool.py
 create mode 100644 trpc_agent_sdk/tools/_websearch_tool.py

diff --git a/.flake8 b/.flake8
index ff9a93a..e0688a3 100644
--- a/.flake8
+++ b/.flake8
@@ -1,3 +1,3 @@
 [flake8]
 max-line-length = 120
-ignore = E402
+ignore = E402, W503
diff --git a/docs/mkdocs/en/tool.md b/docs/mkdocs/en/tool.md
index f3d4a8f..ed2823c 100644
--- a/docs/mkdocs/en/tool.md
+++ b/docs/mkdocs/en/tool.md
@@ -2260,3 +2260,584 @@ print(regular_tool.is_streaming)  # False
 
 - [Streaming Tools Complete Example](../../../examples/streaming_tools/run_agent.py) - Streaming tools running example
 - [Function Tools Documentation](#function-tools) - Usage of standard function tools
+
+## WebFetchTool
+
+`WebFetchTool` is the built-in **single-URL web fetching tool** in the trpc-agent-python framework. When an Agent needs to read, summarize, or cite content from a public web page, it can use this tool to issue a single HTTP GET request. The framework then converts the response into structured text consumable by the LLM: HTML is reduced to plain Markdown text, textual MIME types such as `text/*` and `application/json` are returned as-is, and binary responses are rejected with a structured error.
+
+### Features
+
+- **HTTP GET**: HTML is automatically converted to plain Markdown text, with non-content blocks such as `<script>`, `<style>`, and `<svg>` removed; other textual MIME types are returned as-is; binary responses (PDFs, images, archives, and so on) are rejected with the `UNSUPPORTED_CONTENT_TYPE` error
+- **SSRF protection**: `block_private_network=True` (default) performs DNS resolution checks on the request target and **every redirect hop**, rejecting loopback, private, link-local (including the `169.254.169.254` cloud metadata endpoint), reserved, multicast, and unspecified addresses
+- **Domain allowlist and blocklist**: `allowed_domains` and `blocked_domains` are **tool-level** settings with subdomain-aware matching (`www.` is stripped, and `python.org` also matches `docs.python.org`)
+- **Dual truncation by content and bytes**: `max_content_length` (characters) and `max_response_bytes` (bytes) separately control the returned text length and the raw response bytes actually read; the LLM can further control the result at call time through the `max_length` parameter
+- **Manual redirect control**: `follow_redirects` and `max_redirects` provide a predictable upper bound for redirect chains and prevent infinite redirects
+- **In-process LRU cache**: when `enable_cache=True`, an LRU cache for URL -> `FetchResult` is enabled; `cache_ttl_seconds` and `cache_max_bytes` control the TTL and cache byte budget; on a cache hit, the response is marked with `cached=true`; cache keys use URL normalization (scheme case normalization, `www.` stripping, and ignoring default ports and trailing `/`)
+
+### WebFetchTool Parameters
+
+| Parameter | Type | Default | Description |
+|------|------|--------|------|
+| `timeout` | `float` | `30.0` | HTTP timeout in seconds |
+| `user_agent` | `str` | `"trpc-agent-python-webfetch/1.0"` | HTTP `User-Agent` header, used to help downstream systems identify request sources in logs |
+| `proxy` | `Optional[str]` | `None` | Optional HTTP proxy URL, passed directly to `httpx` |
+| `http_client` | `Optional[httpx.AsyncClient]` | `None` | Optional prebuilt `httpx.AsyncClient` for connection pool reuse (its lifecycle is managed by the caller) |
+| `max_content_length` | `int` | `100_000` | Maximum number of characters returned in `content`; `0` means unlimited; can be overridden by the call-time `max_length` argument |
+| `max_response_bytes` | `int` | `5 * 1024 * 1024` (5 MB) | Maximum number of raw response bytes to read; `0` means unlimited; streaming reads stop once the limit is reached |
+| `allowed_domains` | `Optional[List[str]]` | `None` | Tool-level host allowlist (subdomain-aware, with `www.` stripped); cannot be overridden by the LLM |
+| `blocked_domains` | `Optional[List[str]]` | `None` | Tool-level host blocklist; uses the same matching rules as the allowlist; checked **before the allowlist** |
+| `block_private_network` | `bool` | `True` | SSRF protection switch; when enabled, rejects any target that resolves to private, loopback, link-local, or similar addresses |
+| `follow_redirects` | `bool` | `True` | Whether to manually follow 3xx redirects |
+| `max_redirects` | `int` | `5` | Maximum number of redirect hops |
+| `enable_cache` | `bool` | `False` | Whether to enable the in-process LRU cache |
+| `cache_ttl_seconds` | `float` | `900.0` (15 minutes) | Cache entry TTL; once expired, the next access will bypass and evict the entry |
+| `cache_max_bytes` | `int` | `50 * 1024 * 1024` (50 MB) | Total cache byte capacity; entries exceeding the capacity are silently skipped |
+| `filters_name` | `Optional[List[str]]` | `None` | Names of associated filters, passed through to `BaseTool` |
+| `filters` | `Optional[List[BaseFilter]]` | `None` | Filter instances injected directly, passed through to `BaseTool` |
+
+**LLM call-time parameters** (filled by the LLM at invocation time, not constructor arguments):
+
+| Parameter | Type | Required | Description |
+|------|------|------|------|
+| `url` | `string` | Yes | Absolute `http(s)` URL that must include the scheme, such as `https://docs.python.org/3/whatsnew/3.13.html` |
+| `max_length` | `integer` | No | Character limit for `content` in this call (overrides the tool-level `max_content_length`); `0` disables this limit |
+
+**`FetchResult` return fields**:
+
+| Field | Type | Description |
+|------|------|------|
+| `url` | `str` | Final URL after redirects |
+| `status_code` | `int` | HTTP status code (`0` if the request did not complete) |
+| `status_text` | `str` | HTTP reason phrase |
+| `content_type` | `str` | Normalized media type without additional parameters |
+| `content` | `str` | Textual response body, which may be truncated |
+| `bytes` | `int` | UTF-8 byte length of `content` |
+| `duration_ms` | `int` | Total request duration in milliseconds |
+| `cached` | `bool` | Whether the in-process LRU cache was hit |
+| `error` | `str` | Structured error code when the request fails or is rejected, such as `BLOCKED_URL`, `SSRF_BLOCKED_URL`, `HTTP_STATUS`, `UNSUPPORTED_CONTENT_TYPE`, or `HTTP_ERROR` |
+
+### Usage
+
+#### Create a WebFetchTool Agent
+
+```python
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel, OpenAIModel
+from trpc_agent_sdk.tools import WebFetchTool
+
+from .config import get_model_config
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """Create the LLM model."""
+    api_key, url, model_name = get_model_config()
+    return OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+
+
+def create_default_fetch_agent() -> LlmAgent:
+    """Create a WebFetchTool Agent."""
+    web_fetch = WebFetchTool(
+        timeout=10.0, # Request timeout
+        user_agent="trpc-agent-python-webfetch-example/1.0", # User-Agent header
+        max_content_length=4000, # Maximum returned text length
+        max_response_bytes=1 * 1024 * 1024, # Maximum raw response bytes to read
+        follow_redirects=True, # Manually follow redirect chains
+        max_redirects=3, # Maximum number of redirect hops
+        block_private_network=True, # Enable SSRF protection
+        # allowed_domains=["python.org"], # Domain allowlist
+        # blocked_domains=["example.com"], # Domain blocklist
+        # enable_cache=True, # Enable cache
+        # cache_ttl_seconds=120.0, # Cache TTL
+        # cache_max_bytes=1 * 1024 * 1024, # Cache byte budget
+    )
+    return LlmAgent(
+        name="default_webfetch_assistant",
+        description="Web-reading assistant that fetches a single URL and summarises its textual content.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+```
+
+> **Note**:
+> - `allowed_domains` and `blocked_domains` are **tool-level** settings and **cannot be overridden by the LLM in call arguments**; matching is **subdomain-aware** (`www.` is stripped), and **every redirect hop is revalidated** to prevent bypasses such as "an allowed first hop redirecting to a blocked host"
+> - `block_private_network=True` enables SSRF protection by default; consider disabling it only when the caller already restricts targets with an external allowlist and fully trusts the input
+> - `enable_cache` is disabled by default and must be explicitly enabled; cache keys apply URL normalization (scheme case normalization, `www.` stripping, ignoring default ports, and ignoring trailing `/`), so `https://example.com` and `https://www.example.com/` share the same cache entry
+
+#### Drive the Agent and Print Tool Events
+
+`run_agent.py` drives the Agent by executing each `(label, query)` scenario in sequence and extracting `function_call` / `function_response` from the event stream so that tool invocations can be observed directly:
+
+```python
+import asyncio
+import uuid
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content, Part
+
+load_dotenv()
+
+APP_NAME = "webfetch_agent_demo"
+USER_ID = "demo_user"
+
+
+async def _run_one_query(runner: Runner, *, label: str, query: str) -> None:
+    """Drive a single user query through ``runner`` and pretty-print events."""
+    session_id = str(uuid.uuid4())
+    await runner.session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+        session_id=session_id,
+        state={"user_name": USER_ID},
+    )
+
+    print(f"\n========== {label} ==========")
+    print(f"📝 User: {query}")
+    print("🤖 Assistant: ", end="", flush=True)
+
+    user_content = Content(parts=[Part.from_text(text=query)])
+    async for event in runner.run_async(
+            user_id=USER_ID,
+            session_id=session_id,
+            new_message=user_content,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text, end="", flush=True)
+            continue
+
+        for part in event.content.parts:
+            # Skip thought parts
+            if part.thought:
+                continue
+            # Print tool calls
+            if part.function_call:
+                print(f"\n🔧 [Invoke Tool: {part.function_call.name}({part.function_call.args})]")
+            # Print tool responses
+            elif part.function_response:
+                resp = part.function_response.response
+                print(f"📊 [Tool Result: {resp}]")
+
+    print("\n" + "-" * 40)
+
+
+async def _drive_agent(agent: LlmAgent, *, scenarios: list[tuple[str, str]]) -> None:
+    """Drive the Agent through the scenarios."""
+    runner = Runner(
+        app_name=APP_NAME,
+        agent=agent,
+        session_service=InMemorySessionService(),
+    )
+    for label, query in scenarios:
+        await _run_one_query(runner, label=label, query=query)
+
+
+async def main() -> None:
+    from agent.agent import default_fetch_agent
+
+    await _drive_agent(default_fetch_agent, scenarios=[
+        ("Default · plain fetch",
+         "Fetch https://example.com and summarise the page in one short paragraph.")
+    ])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+#### Example Output
+
+**Example return value**:
+
+When fetching succeeds, the `FetchResult` inside `function_response` looks like this:
+
+```python
+{
+    "url": "https://example.com",
+    "status_code": 200,
+    "status_text": "OK",
+    "content_type": "text/html",
+    "content": "Example Domain\n\n# Example Domain\n\nThis domain is for use in ...",
+    "bytes": 183,
+    "duration_ms": 87,
+    "cached": False,
+    "error": "",
+}
+```
+
+When the cache is hit, `cached=True`; when the request is blocked by domain policy or SSRF protection, `error` contains a structured error code:
+
+```python
+# Rejected by domain policy
+{"url": "https://example.com", "error": "BLOCKED_URL: 'example.com' is not permitted by the tool's domain policy", ...}
+
+# Rejected by SSRF protection (for example, when the target resolves to 127.0.0.1)
+{"url": "http://localhost:8080", "error": "SSRF_BLOCKED_URL: localhost resolves to private/reserved address 127.0.0.1", ...}
+
+# Rejected because the response is binary
+{"url": "https://example.com/a.pdf", "error": "UNSUPPORTED_CONTENT_TYPE: application/pdf", ...}
+```
+
+It is recommended to specify in the Agent's `instruction` that when the tool returns an `error` field, the Agent should **repeat the error code and explain the reason** to the user rather than inventing content; when `content` is truncated or served from cache, that should also be stated explicitly in the response
+
+### Best Practices
+
+- **Security first**: when deploying an Agent in environments that can access cloud metadata endpoints such as AWS EC2 `169.254.169.254` or other internal resources, **keep the default `block_private_network=True`**
+- **Content truncation**: to prevent long pages from exhausting the context window, set `max_content_length` to a reasonable value that matches the model window, for example 4000 to 20000 characters; if the LLM only needs a summary, it can further limit the result through `max_length`
+- **Byte budget**: for large files such as oversized HTML pages or log pages, prefer relying on `max_response_bytes` to stop early at the network layer rather than downloading first and truncating later
+- **Cache strategy**: enable `enable_cache=True` for hot documents, changelogs, or status pages, and size `cache_max_bytes` according to the average page size; note that an overly long TTL may return stale content, and `cached=true` can be used for downstream handling
+- **Domain policy**: use `allowed_domains` when the Agent should be restricted to trusted sites; use `blocked_domains` to exclude noisy or high-risk sites; both can be combined, with the **blocklist taking precedence**
+- **Using it with MCP tools**: when a dedicated MCP fetching tool is available with capabilities such as authentication, JavaScript rendering, or form submission, prefer the MCP tool; `WebFetchTool` is better suited for quickly reading public documentation-style pages that do not require login
+- **Custom HTTP behavior**: when you need to integrate with a corporate proxy, mTLS, or a reused connection pool, configure `proxy` or inject `http_client`
+
+### Complete Example
+
+The complete WebFetchTool usage example is available at: [examples/webfetch_tool/run_agent.py](../../../examples/webfetch_tool/run_agent.py)
+
+The example covers the following scenarios:
+
+- Baseline: default HTTP behavior plus default SSRF behavior
+- Per-call override with `max_length`: the LLM further limits the returned text length in the call arguments
+- LRU cache hit: fetch the same URL twice in succession, with `cached=true` on the second response
+- Allowlist rejection: a host outside the allowlist is rejected with `BLOCKED_URL`
+- Blocklist rejection: a host in the blocklist is rejected with `BLOCKED_URL`
+
+## WebSearchTool
+
+`WebSearchTool` is the built-in **public web search tool** in the trpc-agent-python framework. When an Agent needs to answer questions about "latest developments / version numbers / events / definitions / factual topics" that fall beyond the model's knowledge cutoff, it can use this tool to call mainstream search-engine retrieval APIs, obtain structured results containing titles, URLs, and snippets, and then list all citations in a `Sources:` section as Markdown hyperlinks according to the prescribed format.
+
+This tool uses a **pluggable provider** design and currently includes two built-in backends:
+
+- **`duckduckgo` (default)**: DuckDuckGo Instant Answer API, which **does not require an API key**. It returns DDG-curated instant answers / abstracts / definitions and related topics, making it suitable for encyclopedia, definition, and fact-based queries. Note that it does not return full real-time web search results, but rather DDG's curated result set
+- **`google`**: Google Custom Search (CSE) JSON API, which requires `api_key` and `engine_id` (that is, the CSE `cx`). It returns real public web search results and supports native CSE parameters such as `siteSearch`, `hl` (language), `safe` (SafeSearch), and `dateRestrict` (freshness)
+
+On top of that, `WebSearchTool` also provides **domain allowlist/blocklist filtering, URL normalization and deduplication, result truncation, mandatory citation-policy injection, and HTTP connection-pool reuse**, helping you integrate network retrieval into LLM Agents in a stable and controllable way for production environments.
+
+### Features
+
+- **Dual provider support**: switch between `duckduckgo` (keyless, suitable for definitions/encyclopedia/facts) and `google` (requires CSE API credentials and supports real public web search) through the `provider` parameter, while exposing a consistent `FunctionDeclaration` to the LLM
+- **Domain allowlist/blocklist**: the LLM may fill in `allowed_domains` or `blocked_domains` at call time (the two are mutually exclusive). The tool performs **subdomain-aware** matching (`www.` is stripped, and `python.org` also matches `docs.python.org`). For Google, a single allowed domain takes the server-side `siteSearch` fast path, while multiple domains automatically fall back to client-side filtering
+- **URL normalization and deduplication**: `dedup_urls=True` (default) merges duplicate hits by a normalized scheme/host/path key, preventing the same source from appearing multiple times in the `Sources:` section. Set it to `False` to preserve the raw recall list for downstream re-rankers, diversified sampling, or offline evaluation
+- **Result truncation**: `results_num`, `snippet_len`, and `title_len` control the number of returned items and the character limits for each snippet and title. All parameters are clamped to `[1, _MAX_*]` to avoid misconfiguration that would exceed the context window. The LLM can further control the returned count at call time via the `count` parameter
+- **Mandatory citation policy**: during `process_request`, the tool automatically appends instructions to the LLM and **strictly requires** that: (1) the final answer must end with `Sources:` section listing the URLs returned by the tool in `[Title](URL)` format; (2) the Agent must not fabricate URLs; and (3) for "latest/recent" queries, the **current year and month** must be included in the search input to reduce stale-year hallucinations
+- **Provider-native parameter passthrough**: `ddg_extra_params` and `google_extra_params` let you pin provider-specific advanced parameters at the Agent level, such as Google CSE's `safe`, `dateRestrict`, `gl`, and `cr`, so they are automatically included in every tool invocation without exposing additional fields in the `FunctionDeclaration`
+- **Shared `httpx` connection pool**: by passing a prebuilt `httpx.AsyncClient` through the `http_client` constructor argument, you can reuse the connection pool across multiple Agents or multiple invocations. The caller is responsible for managing its lifecycle (the tool will not call `aclose`)
+- **Structured output**: always returns a `WebSearchResult` containing `query`, `provider`, `results: List[{title, url, snippet}]`, and `summary`, making it easier both for the LLM to compose citations and for downstream re-ranking or RAG pipelines
+
+### WebSearchTool Parameters
+
+| Parameter | Type | Default | Description |
+|------|------|--------|------|
+| `provider` | `Literal["duckduckgo", "google"]` | `"duckduckgo"` | Search backend. `google` requires both `api_key` and `engine_id`; otherwise a not-configured message is returned at call time |
+| `api_key` | `Optional[str]` | `None` | Google CSE API key. If omitted, falls back to the `GOOGLE_CSE_API_KEY` environment variable |
+| `engine_id` | `Optional[str]` | `None` | Google CSE engine ID (that is, `cx`). If omitted, falls back to the `GOOGLE_CSE_ENGINE_ID` environment variable |
+| `base_url` | `Optional[str]` | provider default | Override the provider's API base URL (mainly for testing or proxies) |
+| `user_agent` | `str` | `"trpc-agent-python-websearch/1.0"` | HTTP `User-Agent` header, used to help downstream systems distinguish request traffic in logs |
+| `proxy` | `Optional[str]` | `None` | Optional HTTP proxy URL, passed directly to `httpx` |
+| `lang` | `Optional[str]` | `None` | Default Google CSE language (maps to `hl`). Ignored by DDG. Can be overridden by the call-time `lang` parameter |
+| `http_client` | `Optional[httpx.AsyncClient]` | `None` | Optional prebuilt `httpx.AsyncClient` for connection-pool reuse (its lifecycle is managed by the caller) |
+| `results_num` | `int` | `5` | Default upper bound on returned results, clamped to `[1, 10]`; can be overridden by the call-time `count` parameter |
+| `snippet_len` | `int` | `300` | Character limit for each `snippet`, clamped to `[1, 1000]` |
+| `title_len` | `int` | `100` | Character limit for each `title`, clamped to `[1, 200]` |
+| `timeout` | `float` | `15.0` | HTTP timeout in seconds |
+| `dedup_urls` | `bool` | `True` | Whether to merge duplicate URLs by normalized key; if `False`, the original hit order is preserved |
+| `ddg_extra_params` | `Optional[dict]` | `None` | Additional query parameters passed through to DDG |
+| `google_extra_params` | `Optional[dict]` | `None` | Additional query parameters passed through to Google CSE, such as `{"safe": "active"}`, `{"dateRestrict": "m6"}`, or `{"gl": "us"}` |
+| `filters_name` | `Optional[List[str]]` | `None` | Names of associated filters, passed through to `BaseTool` |
+| `filters` | `Optional[List[BaseFilter]]` | `None` | Filter instances injected directly, passed through to `BaseTool` |
+
+**LLM call-time parameters** (filled by the LLM at invocation time, not constructor arguments):
+
+| Parameter | Type | Required | Description |
+|------|------|------|------|
+| `query` | `string` | Yes | Search keywords, at least 2 characters. For topics such as "latest" or "version number", it is recommended to explicitly include the year or version number |
+| `count` | `integer` | No | Upper bound on the number of results returned in this call, clamped to `1-10`; defaults to the tool-level `results_num` |
+| `allowed_domains` | `array[string]` | No | Domain allowlist (host only, subdomain-aware, with `www.` stripped automatically); mutually exclusive with `blocked_domains` |
+| `blocked_domains` | `array[string]` | No | Domain blocklist, using the same matching rules as `allowed_domains`; mutually exclusive with `allowed_domains` |
+| `lang` | `string` | No | Only effective for Google CSE (maps to `hl`). Ignored by DDG. Overrides the tool-level `lang` |
+
+**`WebSearchResult` return fields**:
+
+| Field | Type | Description |
+|------|------|------|
+| `query` | `str` | Query term used for this search (echoed back verbatim) |
+| `provider` | `"duckduckgo" \| "google"` | Provider actually used |
+| `results` | `List[SearchHit]` | Structured hit list, where each item contains `title`, `url`, and `snippet` |
+| `summary` | `str` | Aggregated summary from DDG instant answers / abstracts / definitions. For Google, this field is also populated when spelling correction or API errors occur |
+
+When call-time arguments are invalid, such as passing both `allowed_domains` and `blocked_domains`, or when `query` is too short, or when an HTTP error occurs, the tool returns a structured error object such as `{"error": "INVALID_ARGS: ..."}` or `{"error": "HTTP_ERROR: ..."}`, making it easier for the LLM to perform graceful fallback handling.
+
+### Usage
+
+#### Build a WebSearchTool Agent
+
+Create a WebSearchTool Agent (using the default DuckDuckGo provider as an example, which runs **without any API key**):
+
+```python
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel, OpenAIModel
+from trpc_agent_sdk.tools import WebSearchTool
+
+from .config import get_model_config
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """Create the LLM model."""
+    api_key, url, model_name = get_model_config()
+    return OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+
+
+def create_ddg_agent() -> LlmAgent:
+    """Create a WebSearchTool Agent based on DuckDuckGo."""
+    web_search = WebSearchTool(
+        provider="duckduckgo",     # Keyless; suitable for definitions, encyclopedia, and fact-based queries
+        results_num=3,             # Return up to 3 results by default
+        snippet_len=300,           # Each snippet is capped at 300 characters
+        title_len=80,              # Each title is capped at 80 characters
+        timeout=10.0,
+        # dedup_urls=False,                    # Disable URL normalization/deduplication and keep the raw recall list
+        # ddg_extra_params={"region": "us-en"},  # Pass through DDG-native parameters
+    )
+    return LlmAgent(
+        name="ddg_research_assistant",
+        description="Web research assistant powered by DuckDuckGo Instant Answers.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_search],
+    )
+```
+
+**Switch to Google Custom Search**: when you need real public web search results, or need freshness, language, or SafeSearch controls, switch to `provider="google"`. Google requires an API key from the [Google Cloud Console](https://developers.google.com/custom-search/v1/overview) and a `cx` value from a [Programmable Search Engine](https://programmablesearchengine.google.com/):
+
+```python
+import httpx
+
+from .config import get_google_cse_config, get_http_proxy
+
+# Created and owned by the application. Call await shared_client.aclose() before exit.
+shared_client = httpx.AsyncClient(
+    timeout=15.0,
+    limits=httpx.Limits(max_connections=16, max_keepalive_connections=8),
+)
+
+
+def create_google_agent() -> LlmAgent:
+    """Create a WebSearchTool Agent based on Google Custom Search."""
+    api_key, engine_id = get_google_cse_config()
+    web_search = WebSearchTool(
+        provider="google", # Use Google Custom Search
+        api_key=api_key, # Google CSE API key
+        engine_id=engine_id, # Google CSE engine ID
+        user_agent="trpc-agent-python-websearch-demo/1.0 (+google-cse)", # User-Agent header
+        proxy=get_http_proxy(),                # Optional outbound proxy
+        lang="en", # Language setting
+        http_client=shared_client,             # Reuse the connection pool; the caller must close it explicitly
+        results_num=3, # Number of results
+        snippet_len=240, # Character limit for each snippet
+        title_len=80, # Character limit for each title
+        timeout=15.0, # Timeout
+        dedup_urls=True, # Enable URL normalization and deduplication
+        google_extra_params={"safe": "active"},       # Enable Google SafeSearch
+        # google_extra_params={"dateRestrict": "m6"}, # Keep only results indexed within the last 6 months
+    )
+    return LlmAgent(
+        name="google_research_assistant",
+        description="Web research assistant powered by Google Custom Search (SafeSearch on).",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_search],
+    )
+```
+
+> **Note**:
+> - `allowed_domains` and `blocked_domains` are filled in by the **LLM in the call arguments** rather than the constructor. The LLM may decide whether to use them based on the user prompt. The two are mutually exclusive, and passing both returns `INVALID_ARGS`
+> - When an external `http_client` is provided, `WebSearchTool` will **not** call `aclose()` for you. The caller must explicitly close it in the **same event loop** to avoid `Unclosed client` warnings
+> - Even when an external client is reused, the tool still force-applies the constructor's `timeout` and `user_agent` on every `GET` request, ensuring that the Agent-level constraints always remain in effect
+> - Other commonly used Google CSE passthrough parameters include `gl` (geographic bias), `cr` (country restriction), `filter`, and `sort`. For DuckDuckGo, parameters such as `region` and `kl` can be passed through via `ddg_extra_params`
+
+#### Drive the Agent and Print Tool Events
+
+`run_agent.py` drives the Agent by executing each `(label, query)` scenario in sequence and extracting `function_call` / `function_response` from the event stream so that tool invocations can be observed directly:
+
+```python
+import asyncio
+import uuid
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content, Part
+
+load_dotenv()
+
+APP_NAME = "websearch_agent_demo"
+USER_ID = "demo_user"
+
+
+async def _run_one_query(runner: Runner, *, label: str, query: str) -> None:
+    """Drive a single user query through ``runner`` and pretty-print events."""
+    session_id = str(uuid.uuid4())
+    await runner.session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+        session_id=session_id,
+        state={"user_name": USER_ID},
+    )
+
+    print(f"\n========== {label} ==========")
+    print(f"📝 User: {query}")
+    print("🤖 Assistant: ", end="", flush=True)
+
+    user_content = Content(parts=[Part.from_text(text=query)])
+    async for event in runner.run_async(
+            user_id=USER_ID,
+            session_id=session_id,
+            new_message=user_content,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text, end="", flush=True)
+            continue
+
+        for part in event.content.parts:
+            if part.thought:
+                continue
+            # Print tool calls
+            if part.function_call:
+                print(f"\n🔧 [Invoke Tool: {part.function_call.name}({part.function_call.args})]")
+            # Print tool responses
+            elif part.function_response:
+                resp = part.function_response.response
+                print(f"📊 [Tool Result: {resp}]") # Tool response
+
+    print("\n" + "-" * 40)
+
+
+async def _drive_agent(agent: LlmAgent, *, scenarios: list[tuple[str, str]]) -> None:
+    """Drive the Agent through the scenarios."""
+    runner = Runner(
+        app_name=APP_NAME,
+        agent=agent,
+        session_service=InMemorySessionService(),
+    )
+    for label, query in scenarios:
+        await _run_one_query(runner, label=label, query=query)
+
+
+async def main() -> None:
+    from agent.agent import ddg_agent
+
+    await _drive_agent(ddg_agent, scenarios=[
+        ("DuckDuckGo · plain lookup",
+         "Look up the entity 'Python (programming language)' and summarise it in "
+         "one paragraph. Use count=1.")
+    ])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+After seeing the prompt above, the LLM automatically assembles a tool call similar to the following from the `FunctionDeclaration`:
+
+```python
+# function_call.args generated automatically by the LLM
+{
+    "query": "Python (programming language)",
+    "count": 3,
+    "allowed_domains": ["wikipedia.org"],
+}
+```
+
+#### Example Output
+
+**Example return value**:
+
+When the call succeeds, the `WebSearchResult` inside `function_response` looks like this:
+
+```python
+{
+    "query": "Python 3.13 release highlights",
+    "provider": "google",
+    "results": [
+        {
+            "title": "What's New In Python 3.13",
+            "url": "https://docs.python.org/3/whatsnew/3.13.html",
+            "snippet": "This article explains the new features in Python 3.13, compared to 3.12 ...",
+        },
+        {
+            "title": "Python 3.13.0 Release Notes",
+            "url": "https://www.python.org/downloads/release/python-3130/",
+            "snippet": "Python 3.13 is the newest major release ...",
+        },
+    ],
+    "summary": "",
+}
+```
+
+For the DuckDuckGo provider, when an instant answer is hit, the `summary` field contains the aggregated summary text returned by DDG, such as a Wikipedia abstract or dictionary definition, which the LLM may cite directly. When DDG has no `Results`, the tool falls back to returning the DDG search-page URL as the only source, ensuring that the `Sources:` section is never empty.
+
+**Error handling**: when arguments are invalid or an HTTP error occurs, the tool returns a structured error object:
+
+```python
+# Passing both the allowlist and blocklist
+{"error": "INVALID_ARGS: cannot specify both allowed_domains and blocked_domains in the same request"}
+
+# Query is too short
+{"error": "INVALID_QUERY: query must be at least 2 characters"}
+
+# Google CSE is not configured with api_key / engine_id
+{"query": "...", "provider": "google", "results": [],
+ "summary": "Google provider is not configured: set api_key + engine_id ..."}
+
+# Network / HTTP error
+{"error": "HTTP_ERROR: ConnectTimeout(...)", "provider": "google", "query": "..."}
+```
+
+It is recommended to specify in the Agent's `instruction` that when the tool returns an `error` field, the Agent should **repeat the reason for the error and offer a fallback option** to the user, such as retrying later, changing the query, or checking the domain allowlist, rather than fabricating content.
+
+**Automatically injected citation policy**: `WebSearchTool.process_request` automatically calls `append_instructions` before each request and strictly requires the LLM to:
+
+- Append a `Sources:` section at the end of the answer and list the URLs returned by the tool in `[Title](URL)` format
+- **Never fabricate URLs** and cite only the URLs actually returned by the tool
+- For "latest/recent/current" queries, include the **current month and year** in the search input to reduce stale-year hallucinations
+
+You do not need to restate this logic in the user's own `instruction`; it takes effect automatically as long as `WebSearchTool` is mounted.
+
+### Best Practices
+
+- **Provider selection**: use the default `duckduckgo` provider when you need lightweight definition, encyclopedia, or fact-based lookups without an API key. Switch to `google` with CSE credentials when you need real public web search or controls over site, language, SafeSearch, or freshness
+- **Result truncation**: to prevent long snippets from exceeding the context window, configure `snippet_len`, `title_len`, and `results_num` to match the model window. When the LLM only needs a small number of sources, it can further tighten the result set via the call-time `count` parameter
+- **Domain strategy**: when the Agent should be restricted to trusted sites such as official documentation or a company website, explicitly instruct the LLM in the prompt to fill in `allowed_domains`. Use `blocked_domains` to exclude content farms or noisy domains. The two are mutually exclusive
+- **Google multi-domain filtering**: Google CSE `siteSearch` accepts only a single value, so when multiple allowed or blocked domains are provided, the tool automatically falls back to client-side filtering. If you want a single domain to take the server-side fast path, constrain the prompt so that the LLM passes only one domain at a time
+- **Deduplication toggle**: URL normalization and deduplication are enabled by default to avoid repeating the same source in the `Sources:` section. Set `dedup_urls=False` to preserve the raw recall list for downstream re-rankers, diversified sampling, or offline evaluation
+- **Freshness control**: for Agents that answer "latest / what's new / today" queries, pin `google_extra_params={"dateRestrict": "m6"}` (last 6 months), `"m1"` (1 month), or `"d7"` (7 days) at the Agent level. This is more reliable than repeatedly emphasizing freshness in the prompt
+- **Connection-pool reuse**: when multiple `WebSearchTool` instances are mounted in the same process or the tool is called at high frequency, pass a shared `httpx.AsyncClient` via `http_client` and explicitly `aclose()` it when the program exits
+- **Credentials and proxies**: inject the Google CSE `api_key` and `engine_id` through environment variables (`GOOGLE_CSE_API_KEY` and `GOOGLE_CSE_ENGINE_ID`) rather than hard-coding them in source code. When a corporate outbound proxy is required, configure it through the `proxy` parameter
+- **Using it with WebFetchTool**: `WebSearchTool` is used to "discover URLs", while `WebFetchTool` is used to "read full page content". When the LLM needs to closely read, summarize, or quote a specific search result, mount both tools on the Agent to form a two-stage workflow of "search -> close reading"
+- **Using it with Knowledge/RAG**: when search results are used as real-time supplementary material in a RAG pipeline, refer to [examples/knowledge_with_searchtool_rag_agent](../../../examples/knowledge_with_searchtool_rag_agent)
+
+### Complete Example
+
+The complete WebSearchTool usage example is available at: [examples/websearch_tool/run_agent.py](../../../examples/websearch_tool/run_agent.py)
+
+The example builds four independent Agents and covers the following scenarios:
+
+- **DuckDuckGo baseline** (`ddg_agent`, `dedup_urls=True`): entity-name query + allowlist + blocklist
+- **DuckDuckGo raw-hit mode** (`ddg_raw_agent`, `dedup_urls=False`): preserves the provider's raw recall list for downstream processing
+- **Google baseline** (`google_agent`, `safe=active`): real public web search + server-side single-domain `siteSearch` + client-side multi-domain filtering + blocklist + per-call `lang` override
+- **Google freshness Agent** (`google_raw_agent`, `dateRestrict=m6` + `dedup_urls=False`): keeps only results indexed within the last 6 months, suitable for "latest / what's new" queries
diff --git a/docs/mkdocs/zh/tool.md b/docs/mkdocs/zh/tool.md
index 41dd7a9..2e6b4e4 100644
--- a/docs/mkdocs/zh/tool.md
+++ b/docs/mkdocs/zh/tool.md
@@ -31,6 +31,8 @@ Agent 通过以下步骤动态使用工具：
 | [File Tools](#file-tools) | 文件操作和文本处理 | 使用 FileToolSet 或单独工具 | 读写文件、搜索、命令执行 |
 | [LangChain Tools](#langchain-tools) | 复用 LangChain 生态工具 | 封装为异步函数并包装为 FunctionTool | 联网搜索（Tavily）等 |
 | [Streaming Tools（流式工具）](#streaming-tools流式工具) | 实时预览长文本生成 | 使用 StreamingFunctionTool | 代码生成、文档写作 |
+| [WebFetchTool](#webfetchtool) | 抓取并文本化单个公网 URL | 实例化 WebFetchTool 并加入 tools | 阅读文档页、RFC、changelog、新闻 |
+| [WebSearchTool](#websearchtool) | 公网搜索引擎检索 | 实例化 WebSearchTool 并加入 tools | 实时资讯、版本发布、事实/定义查询 |
 | [Agent Code Executor](./code_executor.md) | 自动生成并执行代码场景、数据处理场景 | 配置 CodeExecutor | API 自动调用、表格数据处理 |
 ---
 
@@ -2260,3 +2262,586 @@ print(regular_tool.is_streaming)  # False
 
 - [流式工具完整示例](../../../examples/streaming_tools/run_agent.py) - 流式工具运行示例
 - [函数工具文档](#function-tools) - 普通函数工具的使用
+
+## WebFetchTool (网页获取工具)
+
+`WebFetchTool` 是 trpc-agent-python 框架内置的**单 URL 联网抓取工具**。当 Agent 需要阅读、摘要或引用某个公开网页的内容时，可以通过该工具发起一次 HTTP GET 请求，框架会将响应统一转换为可供 LLM 消费的结构化文本：HTML 会被裁剪为 Markdown 纯文本，其它 `text/*` / `application/json` 等文本型 MIME 按原样返回，二进制响应则以结构化错误拒收。
+
+### 功能特性
+
+- **单次 HTTP GET**：HTML 自动转换为 Markdown 纯文本（去除 `<script>` / `<style>` / `<svg>` 等非内容块）；其他文本型 MIME 按原样返回；二进制响应（PDF、图片、归档等）以 `UNSUPPORTED_CONTENT_TYPE` 错误拒收
+- **SSRF 防护**：`block_private_network=True`（默认）会对请求目标及**每一跳重定向**做 DNS 解析校验，拒绝回环 / 私网 / 链路本地（含 `169.254.169.254` 云元数据端点）/ 保留 / 组播 / 未指定地址
+- **域名白/黑名单**：`allowed_domains` / `blocked_domains` 为**工具级**配置，子域感知匹配（`www.` 前缀剥离，`python.org` 同时匹配 `docs.python.org`）
+- **内容与字节双重裁剪**：`max_content_length`（字符）与 `max_response_bytes`（字节）分别控制返回文本长度与实际读取的原始字节；LLM 还可在调用时通过 `max_length` 参数进一步控制
+- **手动重定向控制**：`follow_redirects` / `max_redirects` 提供可预期的重定向循环上限，避免无限跳转
+- **进程内 LRU 缓存**：`enable_cache=True` 时启用 URL → `FetchResult` LRU；`cache_ttl_seconds` / `cache_max_bytes` 控制TTL与缓存字节预算，命中时响应上 `cached=true`，缓存键会做 URL 归一化（统一 scheme 大小写、剥离 `www.`、忽略默认端口和尾部 `/`）
+
+### WebFetchTool 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `timeout` | `float` | `30.0` | HTTP 超时时间（秒） |
+| `user_agent` | `str` | `"trpc-agent-python-webfetch/1.0"` | HTTP `User-Agent` 头，便于下游日志区分来源流量 |
+| `proxy` | `Optional[str]` | `None` | 可选的 HTTP 代理 URL，直接转发给 `httpx` |
+| `http_client` | `Optional[httpx.AsyncClient]` | `None` | 可选的预构建 `httpx.AsyncClient`，用于复用连接池（调用方负责其生命周期） |
+| `max_content_length` | `int` | `100_000` | 返回 `content` 的字符上限，`0` 表示不限；可被调用参数 `max_length` 覆盖 |
+| `max_response_bytes` | `int` | `5 * 1024 * 1024`（5 MB） | 读取的原始响应字节上限，`0` 表示不限；流式读取命中上限即终止 |
+| `allowed_domains` | `Optional[List[str]]` | `None` | 工具级 host 白名单（子域感知，`www.` 前缀剥离），LLM 无法覆盖 |
+| `blocked_domains` | `Optional[List[str]]` | `None` | 工具级 host 黑名单，匹配规则同白名单；**优先于白名单**检查 |
+| `block_private_network` | `bool` | `True` | SSRF 防护开关；开启时拒绝所有解析到私网 / 回环 / 链路本地等地址的目标 |
+| `follow_redirects` | `bool` | `True` | 是否手动跟随 3xx 重定向 |
+| `max_redirects` | `int` | `5` | 重定向最大跳数上限 |
+| `enable_cache` | `bool` | `False` | 是否启用进程内 LRU 缓存 |
+| `cache_ttl_seconds` | `float` | `900.0`（15 分钟） | 缓存项 TTL，超时后下次访问穿透并淘汰 |
+| `cache_max_bytes` | `int` | `50 * 1024 * 1024`（50 MB） | 缓存总字节容量；超过该容量将被静默跳过 |
+| `filters_name` | `Optional[List[str]]` | `None` | 关联的 filter 名称，透传给 `BaseTool` |
+| `filters` | `Optional[List[BaseFilter]]` | `None` | 直接注入的 filter 实例，透传给 `BaseTool` |
+
+**LLM 调用参数**（由 LLM 在调用时填充，非构造参数）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | 是 | 绝对 http(s) URL，必须包含 scheme（如 `https://docs.python.org/3/whatsnew/3.13.html`） |
+| `max_length` | `integer` | 否 | 本次调用的 `content` 字符上限（覆盖工具级 `max_content_length`），`0` 禁用该上限 |
+
+**`FetchResult` 返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | `str` | 重定向后最终的 URL |
+| `status_code` | `int` | HTTP 状态码（请求未完成时为 `0`） |
+| `status_text` | `str` | HTTP 状态原因短语 |
+| `content_type` | `str` | 规范化后的 media type（无附加参数） |
+| `content` | `str` | 文本化后的正文，可能被截断 |
+| `bytes` | `int` | `content` 的 UTF-8 字节长度 |
+| `duration_ms` | `int` | 整个请求的耗时（毫秒） |
+| `cached` | `bool` | 是否命中进程内 LRU 缓存 |
+| `error` | `str` | 失败或被拒绝时的结构化错误码（如 `BLOCKED_URL` / `SSRF_BLOCKED_URL` / `HTTP_STATUS` / `UNSUPPORTED_CONTENT_TYPE` / `HTTP_ERROR`） |
+
+### 使用方式
+
+#### 构造 WebFetchTool Agent
+
+在`agent/agent.py` 中创建 WebFetchTool Agent：
+
+```python
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel, OpenAIModel
+from trpc_agent_sdk.tools import WebFetchTool
+
+from .config import get_model_config
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """创建 LLM 模型"""
+    api_key, url, model_name = get_model_config()
+    return OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+
+
+def create_default_fetch_agent() -> LlmAgent:
+    """创建 WebFetchTool Agent"""
+    web_fetch = WebFetchTool(
+        timeout=10.0, # 超时时间配置
+        user_agent="trpc-agent-python-webfetch-example/1.0", # User-Agent 头
+        max_content_length=4000, # 返回文本字符上限
+        max_response_bytes=1 * 1024 * 1024, # 读取的原始字节上限
+        follow_redirects=True, # 手动重定向循环
+        max_redirects=3, # 重定向最大跳数上限
+        block_private_network=True, # SSRF 防护开关
+        # allowed_domains=["python.org"], # 域名白名单
+        # blocked_domains=["example.com"], # 域名黑名单
+        # enable_cache=True, # 启用缓存
+        # cache_ttl_seconds=120.0, # 缓存TTL
+        # cache_max_bytes=1 * 1024 * 1024, # 缓存字节容量
+    )
+    return LlmAgent(
+        name="default_webfetch_assistant",
+        description="Web-reading assistant that fetches a single URL and summarises its textual content.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+```
+
+> **注意**：
+> - `allowed_domains` / `blocked_domains` 是**工具级**配置，LLM **无法在调用参数里覆盖**；匹配规则为**子域感知**（`www.` 前缀会被剥离），且**每一跳重定向都会重新校验**，防止"合法首跳 → 跳到被禁主机"的绕过
+> - `block_private_network=True` 默认开启 SSRF 防护；仅当调用方已用外部白名单限定目标且确信输入可信时可以考虑关闭
+> - `enable_cache` 默认关闭，需显式 opt-in；缓存键会做 URL 归一化（统一 scheme 大小写、剥离 `www.`、忽略默认端口、忽略尾 `/`），`https://example.com` 与 `https://www.example.com/` 共享同一条缓存项
+
+#### 驱动 Agent 并打印工具事件
+
+`run_agent.py` 驱动 Agent，逐条执行 `(label, query)` 场景，并从事件流里提取 `function_call` / `function_response` 以便直观观察工具调用：
+
+```python
+import asyncio
+import uuid
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content, Part
+
+load_dotenv()
+
+APP_NAME = "webfetch_agent_demo"
+USER_ID = "demo_user"
+
+
+async def _run_one_query(runner: Runner, *, label: str, query: str) -> None:
+    """Drive a single user query through ``runner`` and pretty-print events."""
+    session_id = str(uuid.uuid4())
+    await runner.session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+        session_id=session_id,
+        state={"user_name": USER_ID},
+    )
+
+    print(f"\n========== {label} ==========")
+    print(f"📝 User: {query}")
+    print("🤖 Assistant: ", end="", flush=True)
+
+    user_content = Content(parts=[Part.from_text(text=query)])
+    async for event in runner.run_async(
+            user_id=USER_ID,
+            session_id=session_id,
+            new_message=user_content,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text, end="", flush=True)
+            continue
+
+        for part in event.content.parts:
+            # 跳过思考部分
+            if part.thought:
+                continue
+            # 打印工具调用
+            if part.function_call:
+                print(f"\n🔧 [Invoke Tool: {part.function_call.name}({part.function_call.args})]")
+            # 打印工具响应
+            elif part.function_response:
+                resp = part.function_response.response
+                print(f"📊 [Tool Result: {resp}]")
+
+    print("\n" + "-" * 40)
+
+
+async def _drive_agent(agent: LlmAgent, *, scenarios: list[tuple[str, str]]) -> None:
+    """驱动 Agent 执行场景"""
+    runner = Runner(
+        app_name=APP_NAME,
+        agent=agent,
+        session_service=InMemorySessionService(),
+    )
+    for label, query in scenarios:
+        await _run_one_query(runner, label=label, query=query)
+
+
+async def main() -> None:
+    from agent.agent import default_fetch_agent
+
+    await _drive_agent(default_fetch_agent, scenarios=[
+        ("Default · plain fetch",
+         "Fetch https://example.com and summarise the page in one short paragraph.")
+    ])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+#### 运行示例
+
+**返回值示例**：
+
+成功抓取时，`function_response` 中的 `FetchResult` 形如：
+
+```python
+{
+    "url": "https://example.com",
+    "status_code": 200,
+    "status_text": "OK",
+    "content_type": "text/html",
+    "content": "Example Domain\n\n# Example Domain\n\nThis domain is for use in ...",
+    "bytes": 183,
+    "duration_ms": 87,
+    "cached": False,
+    "error": "",
+}
+```
+
+命中缓存时 `cached=True`；被域名策略或 SSRF 防护拦截时 `error` 会包含结构化错误码：
+
+```python
+# 被域名策略拒绝
+{"url": "https://example.com", "error": "BLOCKED_URL: 'example.com' is not permitted by the tool's domain policy", ...}
+
+# 被 SSRF 防护拒绝（如目标解析到 127.0.0.1）
+{"url": "http://localhost:8080", "error": "SSRF_BLOCKED_URL: localhost resolves to private/reserved address 127.0.0.1", ...}
+
+# 二进制响应被拒
+{"url": "https://example.com/a.pdf", "error": "UNSUPPORTED_CONTENT_TYPE: application/pdf", ...}
+```
+
+建议在 Agent 的 `instruction` 中约定：当工具返回 `error` 字段时，应向用户**复述错误码并解释原因**，而不是编造内容；当 `content` 被截断或命中缓存时，也应在回答中显式说明
+
+### WebFetchTool 最佳实践
+
+- **安全优先**：在能访问云元数据端点（如 AWS EC2 的 `169.254.169.254`）或内网资源的环境中部署 Agent 时，**保留 `block_private_network=True` 默认值**
+- **内容裁剪**：为防止长页面撑爆上下文窗口，建议为 `max_content_length` 设置一个与模型窗口匹配的合理值（例如 4000~20000 字符）；LLM 仅需摘要时可通过 `max_length`设置
+- **字节预算**：对大文件（如巨型 HTML、日志页）优先依赖 `max_response_bytes` 在网络层提前止损，而不是先下载再裁剪
+- **缓存策略**：对热点文档 / changelog / status page 打开 `enable_cache=True`，并依据页面平均大小设置 `cache_max_bytes`；注意 TTL 过长可能返回过期内容，`cached=true` 可用于下游判断
+- **域名策略**：需要把 Agent 限定在可信站点时使用 `allowed_domains`；想屏蔽噪声或高风险站点则使用 `blocked_domains`；两者可组合使用，**黑名单优先**
+- **与 MCP 工具配合**：当存在专用的 MCP 抓取工具（带鉴权、JS 渲染、表单提交能力）时，优先使用 MCP 工具；`WebFetchTool` 更适合对无需登录的公开文档类页面做快速阅读
+- **自定义 HTTP 行为**：需要对接公司代理、mTLS 或复用连接池时，通过构造参数 `proxy` 或注入 `http_client` 实现
+
+### WebFetchTool 完整示例
+
+完整的 WebFetchTool 使用示例见：[examples/webfetch_tool/run_agent.py](../../../examples/webfetch_tool/run_agent.py)
+
+示例中覆盖了以下场景：
+
+- 基线：HTTP 形态默认项 + SSRF 默认项
+- `max_length` 按调用覆盖：LLM 在调用参数里进一步返回文本长度
+- LRU 缓存命中：同一 URL 连续抓取两次，第二次 `cached=true`
+- 白名单拒绝：非白名单主机被拒并返回 `BLOCKED_URL`
+- 黑名单拒绝：黑名单主机被拒并返回 `BLOCKED_URL`
+
+## WebSearchTool （网络搜索工具）
+
+`WebSearchTool` 是 trpc-agent-python 框架内置的**公网搜索工具**。当 Agent 需要回答"最新动态 / 版本号 / 事件 / 定义 / 事实类"等超出模型知识截止日期的问题时，可以通过该工具调用主流搜索引擎的检索 API，获取带标题、URL 与摘要的结构化结果，并按约定将所有引用以 Markdown 超链接的形式列在 `Sources:` 段落中。
+
+该工具采用**可插拔 provider** 设计，目前内置两种后端：
+
+- **`duckduckgo`（默认）**：DuckDuckGo Instant Answer API，**无需 API Key**。返回 DDG 精选的 instant answer / abstract / definition 摘要及相关主题，适合百科/定义/事实类查询；注意返回的并非完整的实时网页结果，而是 DDG 的 curated 结果集
+- **`google`**：Google Custom Search（CSE）JSON API，需要配置 `api_key` 与 `engine_id`（即 CSE 的 `cx`）；返回真实的公网搜索结果，支持 `siteSearch`、`hl`（语言）、`safe`（SafeSearch）、`dateRestrict`（时效性）等 CSE 原生参数
+
+在此基础上，`WebSearchTool` 还内置了**域名白/黑名单过滤、URL 归一化去重、结果裁剪、引用规范强制注入、HTTP 连接池复用**等能力，帮助你在生产环境中稳定、可控地把联网检索接入 LLM Agent。
+
+### 功能特性
+
+- **双 Provider 支持**：`duckduckgo`（keyless，适合定义/百科）与 `google`（需要 CSE API Key，支持真实公网搜索）通过 `provider` 参数切换，对 LLM 暴露的 `FunctionDeclaration` 保持一致
+- **域名白/黑名单**：LLM 可在调用时填入 `allowed_domains` / `blocked_domains`（二者互斥），工具会做**子域感知**匹配（`www.` 前缀剥离，`python.org` 同时匹配 `docs.python.org`）；Google 单域名时走服务端 `siteSearch` 快速路径，多域名自动回退到客户端过滤
+- **URL 归一化去重**：`dedup_urls=True`（默认）会按 scheme/host/path 归一化键合并重复命中，避免 `Sources:` 段里出现同一来源多次；设置为 `False` 可保留原始召回列表，便于接入下游 re-ranker / 多样化采样 / 离线评估
+- **结果裁剪**：`results_num` / `snippet_len` / `title_len` 分别控制返回条数、单条摘要与标题的字符上限，所有参数都会按 `[1, _MAX_*]` 做 clamp，避免误配超上下文窗口；LLM 还可通过 `count` 参数在调用时进一步控制返回条数
+- **强制引用规范**：工具在 `process_request` 阶段自动向 LLM 追加指令，**强制**要求：（1）回答末尾必须追加 `Sources:` 段并以 `[Title](URL)` 列出工具返回的 URL；（2）不得编造 URL；（3）涉及"最新/recent"类查询时使用**当前年月**入参，避免幻觉旧年份
+- **Provider 原生参数透传**：`ddg_extra_params` / `google_extra_params` 让你把 provider 专属的高级参数（如 Google CSE 的 `safe`、`dateRestrict`、`gl`、`cr`）固化在 agent 层，每次工具调用自动带上，无需在 `FunctionDeclaration` 里额外暴露
+- **共享 httpx 连接池**：通过构造参数 `http_client` 传入预建好的 `httpx.AsyncClient`，可在多个 agent / 多次调用之间复用连接池；调用方负责其生命周期（工具不会帮你 `aclose`）
+- **结构化输出**：统一返回 `WebSearchResult`，包含 `query` / `provider` / `results: List[{title, url, snippet}]` / `summary`，便于 LLM 引用拼装，也便于下游做 re-rank / RAG
+
+### WebSearchTool 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `provider` | `Literal["duckduckgo", "google"]` | `"duckduckgo"` | 搜索后端；`google` 需要同时配置 `api_key` 与 `engine_id`，否则调用时返回未配置提示 |
+| `api_key` | `Optional[str]` | `None` | Google CSE API Key，缺省时回退到环境变量 `GOOGLE_CSE_API_KEY` |
+| `engine_id` | `Optional[str]` | `None` | Google CSE 引擎 ID（即 `cx`），缺省时回退到环境变量 `GOOGLE_CSE_ENGINE_ID` |
+| `base_url` | `Optional[str]` | provider 默认 | 覆盖 provider 的 API Base URL（主要用于测试 / 代理） |
+| `user_agent` | `str` | `"trpc-agent-python-websearch/1.0"` | HTTP `User-Agent` 头，便于下游日志区分来源流量 |
+| `proxy` | `Optional[str]` | `None` | 可选的 HTTP 代理 URL，直接转发给 `httpx` |
+| `lang` | `Optional[str]` | `None` | Google CSE 默认语言（对应 `hl` 参数），DDG 会忽略；LLM 可通过调用参数 `lang` 覆盖 |
+| `http_client` | `Optional[httpx.AsyncClient]` | `None` | 可选的预构建 `httpx.AsyncClient`，用于复用连接池（调用方负责生命周期） |
+| `results_num` | `int` | `5` | 默认返回条数上限，clamp 到 `[1, 10]`；可被调用参数 `count` 覆盖 |
+| `snippet_len` | `int` | `300` | 单条 `snippet` 的字符上限，clamp 到 `[1, 1000]` |
+| `title_len` | `int` | `100` | 单条 `title` 的字符上限，clamp 到 `[1, 200]` |
+| `timeout` | `float` | `15.0` | HTTP 超时时间（秒） |
+| `dedup_urls` | `bool` | `True` | 是否按归一化键合并重复 URL；`False` 时保留原始命中顺序 |
+| `ddg_extra_params` | `Optional[dict]` | `None` | 透传给 DDG 的额外查询参数 |
+| `google_extra_params` | `Optional[dict]` | `None` | 透传给 Google CSE 的额外查询参数（如 `{"safe": "active"}`、`{"dateRestrict": "m6"}`、`{"gl": "us"}` 等） |
+| `filters_name` | `Optional[List[str]]` | `None` | 关联的 filter 名称，透传给 `BaseTool` |
+| `filters` | `Optional[List[BaseFilter]]` | `None` | 直接注入的 filter 实例，透传给 `BaseTool` |
+
+**LLM 调用参数**（由 LLM 在调用时填充，非构造参数）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `query` | `string` | 是 | 检索关键词，至少 2 个字符；对于"最新/版本号"类主题建议显式带上年份/版本号 |
+| `count` | `integer` | 否 | 本次调用的返回条数上限，`1-10`（clamp）；默认为工具级 `results_num` |
+| `allowed_domains` | `array[string]` | 否 | 域名白名单（host only，子域感知，`www.` 自动剥离）；与 `blocked_domains` 互斥 |
+| `blocked_domains` | `array[string]` | 否 | 域名黑名单，匹配规则同上；与 `allowed_domains` 互斥 |
+| `lang` | `string` | 否 | 仅 Google CSE 生效（对应 `hl`），DDG 会忽略；覆盖工具级 `lang` |
+
+**`WebSearchResult` 返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `query` | `str` | 本次检索的查询词（原样回显） |
+| `provider` | `"duckduckgo" \| "google"` | 实际使用的 provider |
+| `results` | `List[SearchHit]` | 结构化命中列表，每项包含 `title` / `url` / `snippet` |
+| `summary` | `str` | DDG 的 instant answer / abstract / definition 聚合摘要；Google 在发生拼写纠错或 API 错误时也会写入此字段 |
+
+当调用参数非法（如同时传入 `allowed_domains` 与 `blocked_domains`、`query` 过短）或 HTTP 出错时，工具会返回结构化错误对象（如 `{"error": "INVALID_ARGS: ..."}` / `{"error": "HTTP_ERROR: ..."}`），便于 LLM 做降级处理。
+
+### 使用方式
+
+#### 构造 WebSearchTool Agent
+
+在 `agent/agent.py` 中创建 WebSearchTool Agent（以默认的 DuckDuckGo provider 为例，**无需任何 API Key** 即可开跑）：
+
+```python
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel, OpenAIModel
+from trpc_agent_sdk.tools import WebSearchTool
+
+from .config import get_model_config
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """创建 LLM 模型"""
+    api_key, url, model_name = get_model_config()
+    return OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+
+
+def create_ddg_agent() -> LlmAgent:
+    """创建基于 DuckDuckGo 的 WebSearchTool Agent"""
+    web_search = WebSearchTool(
+        provider="duckduckgo",     # keyless，适合定义/百科/事实类查询
+        results_num=3,             # 默认返回最多 3 条
+        snippet_len=300,           # 每条摘要最多 300 字符
+        title_len=80,              # 每条标题最多 80 字符
+        timeout=10.0,
+        # dedup_urls=False,                    # 关闭 URL 归一化去重，保留原始召回
+        # ddg_extra_params={"region": "us-en"},  # DDG 原生参数透传
+    )
+    return LlmAgent(
+        name="ddg_research_assistant",
+        description="Web research assistant powered by DuckDuckGo Instant Answers.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_search],
+    )
+```
+
+**切换到 Google Custom Search**：当需要真正的公网搜索结果、或需要时效性/语言/SafeSearch 控制时，切换到 `provider="google"`。Google 需要先在 [Google Cloud Console](https://developers.google.com/custom-search/v1/overview) 申请 API Key，在 [Programmable Search Engine](https://programmablesearchengine.google.com/) 创建引擎获取 `cx`；
+
+```python
+import httpx
+
+from .config import get_google_cse_config, get_http_proxy
+
+# 业务侧创建并负责生命周期：程序退出前调用 await shared_client.aclose()
+shared_client = httpx.AsyncClient(
+    timeout=15.0,
+    limits=httpx.Limits(max_connections=16, max_keepalive_connections=8),
+)
+
+
+def create_google_agent() -> LlmAgent:
+    """创建基于 Google Custom Search 的 WebSearchTool Agent"""
+    api_key, engine_id = get_google_cse_config()
+    web_search = WebSearchTool(
+        provider="google", # 使用 Google Custom Search
+        api_key=api_key, # Google CSE API Key
+        engine_id=engine_id, # Google CSE Engine ID
+        user_agent="trpc-agent-python-websearch-demo/1.0 (+google-cse)", # User-Agent 头
+        proxy=get_http_proxy(),                # 可选：出口代理
+        lang="en", # 语言设定
+        http_client=shared_client,             # 复用连接池，需要调用方显式关闭
+        results_num=3, # 返回条数
+        snippet_len=240, # 单条摘要字符上限
+        title_len=80, # 单条标题字符上限
+        timeout=15.0, # 超时时间
+        dedup_urls=True, # 开启 URL 归一化去重
+        google_extra_params={"safe": "active"},       # 打开 Google SafeSearch
+        # google_extra_params={"dateRestrict": "m6"}, # 仅保留过去 6 个月索引的结果
+    )
+    return LlmAgent(
+        name="google_research_assistant",
+        description="Web research assistant powered by Google Custom Search (SafeSearch on).",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_search],
+    )
+```
+
+> **注意**：
+> - `allowed_domains` / `blocked_domains` 由 **LLM 在调用参数里**填入（而非构造参数），LLM 可根据用户 prompt 决定是否启用；两者互斥，同时传入会返回 `INVALID_ARGS`
+> - 当传入外部 `http_client` 时，`WebSearchTool` **不会**帮你调用 `aclose()`，需要调用方在**同一个事件循环**内显式关闭，避免 `Unclosed client` 警告
+> - 即使复用外部 client，工具内部仍会在每次 `GET` 时强制应用构造器里的 `timeout` 与 `user_agent`，保证 agent 层的约束始终生效
+> - 其他常用的 Google CSE 透传参数包括 `gl`（地理偏向）、`cr`（国家限制）、`filter`、`sort` 等；对 DuckDuckGo 可通过 `ddg_extra_params` 透传 `region`、`kl` 等
+
+#### 驱动 Agent 并打印工具事件
+
+`run_agent.py` 驱动 Agent，逐条执行 `(label, query)` 场景，并从事件流里提取 `function_call` / `function_response` 以便直观观察工具调用：
+
+```python
+import asyncio
+import uuid
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content, Part
+
+load_dotenv()
+
+APP_NAME = "websearch_agent_demo"
+USER_ID = "demo_user"
+
+
+async def _run_one_query(runner: Runner, *, label: str, query: str) -> None:
+    """Drive a single user query through ``runner`` and pretty-print events."""
+    session_id = str(uuid.uuid4())
+    await runner.session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+        session_id=session_id,
+        state={"user_name": USER_ID},
+    )
+
+    print(f"\n========== {label} ==========")
+    print(f"📝 User: {query}")
+    print("🤖 Assistant: ", end="", flush=True)
+
+    user_content = Content(parts=[Part.from_text(text=query)])
+    async for event in runner.run_async(
+            user_id=USER_ID,
+            session_id=session_id,
+            new_message=user_content,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text, end="", flush=True)
+            continue
+
+        for part in event.content.parts:
+            if part.thought:
+                continue
+            # 打印工具调用  
+            if part.function_call:
+                print(f"\n🔧 [Invoke Tool: {part.function_call.name}({part.function_call.args})]")
+            # 打印工具响应
+            elif part.function_response:
+                resp = part.function_response.response
+                print(f"📊 [Tool Result: {resp}]") # 工具响应
+
+    print("\n" + "-" * 40)
+
+
+async def _drive_agent(agent: LlmAgent, *, scenarios: list[tuple[str, str]]) -> None:
+    """驱动 Agent 执行场景"""
+    runner = Runner(
+        app_name=APP_NAME,
+        agent=agent,
+        session_service=InMemorySessionService(),
+    )
+    for label, query in scenarios:
+        await _run_one_query(runner, label=label, query=query)
+
+
+async def main() -> None:
+    from agent.agent import ddg_agent
+
+    await _drive_agent(ddg_agent, scenarios=[
+        ("DuckDuckGo · plain lookup",
+         "Look up the entity 'Python (programming language)' and summarise it in "
+         "one paragraph. Use count=1.")
+    ])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+LLM 看到上述 prompt 后，会按 `FunctionDeclaration` 自动组装出类似如下的工具调用：
+
+```python
+# LLM 自动生成的 function_call.args
+{
+    "query": "Python (programming language)",
+    "count": 3,
+    "allowed_domains": ["wikipedia.org"],
+}
+```
+
+#### 运行示例
+
+**返回值示例**：
+
+成功时，`function_response` 中的 `WebSearchResult` 形如：
+
+```python
+{
+    "query": "Python 3.13 release highlights",
+    "provider": "google",
+    "results": [
+        {
+            "title": "What's New In Python 3.13",
+            "url": "https://docs.python.org/3/whatsnew/3.13.html",
+            "snippet": "This article explains the new features in Python 3.13, compared to 3.12 ...",
+        },
+        {
+            "title": "Python 3.13.0 Release Notes",
+            "url": "https://www.python.org/downloads/release/python-3130/",
+            "snippet": "Python 3.13 is the newest major release ...",
+        },
+    ],
+    "summary": "",
+}
+```
+
+DuckDuckGo provider 在命中 instant answer 时，`summary` 字段会包含 DDG 聚合的摘要文本（如维基摘要、词典定义等），LLM 可直接引用；当 DDG 没有 `Results` 时，工具会兜底把 DDG 搜索页 URL 作为唯一来源返回，保证 `Sources:` 段不为空。
+
+**错误处理**：当参数非法或 HTTP 出错时，工具返回结构化错误对象：
+
+```python
+# 同时传入白/黑名单
+{"error": "INVALID_ARGS: cannot specify both allowed_domains and blocked_domains in the same request"}
+
+# query 过短
+{"error": "INVALID_QUERY: query must be at least 2 characters"}
+
+# Google CSE 未配置 api_key / engine_id
+{"query": "...", "provider": "google", "results": [],
+ "summary": "Google provider is not configured: set api_key + engine_id ..."}
+
+# 网络 / HTTP 错误
+{"error": "HTTP_ERROR: ConnectTimeout(...)", "provider": "google", "query": "..."}
+```
+
+建议在 Agent 的 `instruction` 中约定：当工具返回 `error` 字段时，应向用户**复述错误原因并给出降级方案**（如提示用户稍后重试、改换查询词、检查域名白名单等），而不是编造内容。
+
+**自动注入的引用规范**：`WebSearchTool.process_request` 会在每次请求前自动 `append_instructions`，强制要求 LLM：
+
+- 回答末尾必须追加 `Sources:` 段并以 `[Title](URL)` 列出工具返回的 URL
+- **不得编造 URL**，只能引用工具实际返回的 URL
+- 涉及"最新/recent/current"类查询时使用**当前月份与年份**入参，避免幻觉旧年份
+
+这部分逻辑无需用户在 `instruction` 中重复声明，只要挂载 `WebSearchTool` 即自动生效。
+
+### WebSearchTool 最佳实践
+
+- **Provider 选择**：仅需无 API Key、轻量的定义/百科/事实类检索时使用默认的 `duckduckgo`；需要真实公网搜索、支持 site/语言/SafeSearch/时效性时切换到 `google` 并配置 CSE 凭据
+- **结果裁剪**：为防止长摘要超过上下文窗口，建议为 `snippet_len` / `title_len` / `results_num` 设置与模型窗口匹配的合理值；LLM 仅需少量来源时可通过调用参数 `count` 进一步收紧
+- **域名策略**：需要把 Agent 限定在可信站点（如企业官网、官方文档）时，在 prompt 中显式要求 LLM 填入 `allowed_domains`；想屏蔽内容农场或噪声站点时使用 `blocked_domains`；两者互斥
+- **Google 多域名过滤**：Google CSE 的 `siteSearch` 只接受单个值，因此多域名白/黑名单时工具会自动回退到客户端过滤。若希望单域名走服务端快速路径，prompt 中约束 LLM 一次只传一个域名即可
+- **去重开关**：默认开启URL归一化去重，避免 `Sources:` 段里出现同一来源多次；设置为 `False` 可保留原始召回列表，便于接入下游 re-ranker / 多样化采样 / 离线评估
+- **时效性控制**：对"最新/what's new/today"类 Agent，把 `google_extra_params={"dateRestrict": "m6"}`（最近 6 个月）/ `"m1"`（1 个月）/ `"d7"`（7 天）固化在 agent 层，比在 prompt 里反复强调更可靠
+- **连接池复用**：同一进程内挂载多个 `WebSearchTool` 或高频调用时，通过 `http_client` 传入共享的 `httpx.AsyncClient`，并在程序退出时由调用方显式 `aclose()`
+- **凭据与代理**：Google CSE 的 `api_key` / `engine_id` 建议通过环境变量（`GOOGLE_CSE_API_KEY` / `GOOGLE_CSE_ENGINE_ID`）注入，不硬编码在源码；需要经过企业出口代理时通过 `proxy` 参数配置
+- **与 WebFetchTool 配合**：`WebSearchTool` 用来"发现 URL"，`WebFetchTool` 用来"读取 URL 全文"——当 LLM 需要对某条搜索结果做深入阅读 / 摘要 / 引述时，把两个工具同时挂到 Agent 上，形成"搜索 → 精读"的两阶段工作流
+- **与 Knowledge/RAG 配合**：把搜索结果作为实时补充语料接入 RAG 流程时，参考 [examples/knowledge_with_searchtool_rag_agent](../../../examples/knowledge_with_searchtool_rag_agent)
+
+### WebSearchTool 完整示例
+
+完整的 WebSearchTool 使用示例见：[examples/websearch_tool/run_agent.py](../../../examples/websearch_tool/run_agent.py)
+
+示例中构建了四个独立 Agent，覆盖以下场景：
+
+- **DuckDuckGo 基线**（`ddg_agent`，`dedup_urls=True`）：实体名查询 + 白名单 + 黑名单
+- **DuckDuckGo 原始命中**（`ddg_raw_agent`，`dedup_urls=False`）：保留 provider 原始召回列表，便于下游处理
+- **Google 基线**（`google_agent`，`safe=active`）：真实公网搜索 + 服务端单域 `siteSearch` + 客户端多域过滤 + 黑名单 + per-call `lang` 覆盖
+- **Google 时效性 Agent**（`google_raw_agent`，`dateRestrict=m6` + `dedup_urls=False`）：只保留过去 6 个月索引的结果，适合"最新/what's new"类查询
diff --git a/examples/webfetch_tool/.env b/examples/webfetch_tool/.env
new file mode 100644
index 0000000..7ffffa2
--- /dev/null
+++ b/examples/webfetch_tool/.env
@@ -0,0 +1,4 @@
+# Set TRPC_AGENT_API_KEY、TRPC_AGENT_BASE_URL、TRPC_AGENT_MODEL_NAME
+TRPC_AGENT_API_KEY=your_api_key
+TRPC_AGENT_BASE_URL=your_base_url
+TRPC_AGENT_MODEL_NAME=your_model_name
diff --git a/examples/webfetch_tool/README.md b/examples/webfetch_tool/README.md
new file mode 100644
index 0000000..c0bedba
--- /dev/null
+++ b/examples/webfetch_tool/README.md
@@ -0,0 +1,278 @@
+# WebFetchTool 网页抓取示例
+
+本示例演示如何使用框架内置的 `WebFetchTool`，让 LLM Agent 通过公网 HTTP GET 抓取单个 URL，并按照"白名单 / 黑名单域名 + SSRF 防护 + 内置 LRU 缓存"的规则生成可追溯的回答，同时针对 SSRF 场景专门跑一遍 loopback / 云元数据 / 内网 IP 三种典型 payload，验证在**没有任何 TCP 连接建立**之前就会被工具以 `SSRF_BLOCKED_URL` 结构化错误拒收。
+
+## 关键特性
+
+- **单次 HTTP GET + 文本化**：对指定 URL 发一次无鉴权 GET；HTML 被转换为 Markdown-ish 纯文本，其它 `text/*` / `application/json` 等文本型 MIME 按原样返回；二进制响应以结构化 `UNSUPPORTED_CONTENT_TYPE` 错误拒收
+- **域名白名单/黑名单**：通过构造参数 `allowed_domains` / `blocked_domains` 实现工具级 site 过滤（**LLM 无法覆盖**）；子域感知匹配（`www.` 前缀剥离，`python.org` 同时匹配 `docs.python.org`），黑名单优先于白名单
+- **SSRF 防护**：`block_private_network=True`（默认）会在每次请求及**每一跳重定向**后解析主机，拒绝回环 / 私网 / 链路本地（含 `169.254.169.254` 云元数据端点）/ 保留 / 组播 / 未指定地址
+- **结构化输出**：`FetchResult` 统一返回 `url / status_code / status_text / content_type / content / bytes / duration_ms / cached / error`，便于 LLM 引用与降级
+- **内容与字节双重裁剪**：`max_content_length`（字符）与 `max_response_bytes`（字节）分别控制返回文本长度与**线缆上实际读取的原始字节**；LLM 还可通过调用参数 `max_length` 进一步按需收紧
+- **内置 LRU 缓存**：`enable_cache=True` 时启用进程内 URL → `FetchResult` LRU；`cache_ttl_seconds` / `cache_max_bytes` 控制新鲜度与预算，命中时响应上 `cached=true`
+
+## Agent 层级结构说明
+
+本例提供五个独立 Agent，按场景顺序驱动；`root_agent` 默认指向 `default_fetch_agent`：
+
+```text
+default_fetch_agent (LlmAgent)                  # 基线：HTTP 形态 + SSRF 默认项
+├── model: OpenAIModel
+├── tools:
+│   └── WebFetchTool(
+│         timeout=10.0,
+│         user_agent="trpc-agent-python-webfetch-example/1.0",
+│         max_content_length=4000,
+│         max_response_bytes=1 MiB,
+│         follow_redirects=True,
+│         max_redirects=3,
+│         block_private_network=True,
+│       )
+└── session: InMemorySessionService
+
+cached_fetch_agent (LlmAgent)                   # 进程内 LRU 缓存
+├── model: OpenAIModel
+├── tools:
+│   └── WebFetchTool(
+│         enable_cache=True,
+│         cache_ttl_seconds=120.0,
+│         cache_max_bytes=2 MiB,
+│       )
+└── session: InMemorySessionService
+
+whitelist_fetch_agent (LlmAgent)                # 域名白名单
+├── model: OpenAIModel
+├── tools:
+│   └── WebFetchTool(allowed_domains=["python.org"])
+└── session: InMemorySessionService
+
+blocklist_fetch_agent (LlmAgent)                # 域名黑名单
+├── model: OpenAIModel
+├── tools:
+│   └── WebFetchTool(blocked_domains=["example.com"])
+└── session: InMemorySessionService
+
+ssrf_fetch_agent (LlmAgent)                     # SSRF 防护（loopback / 元数据 / 内网）
+├── model: OpenAIModel
+├── tools:
+│   └── WebFetchTool(
+│         follow_redirects=True,
+│         max_redirects=3,
+│         block_private_network=True,
+│       )
+└── session: InMemorySessionService
+```
+
+关键文件：
+
+- [examples/webfetch_tool/agent/agent.py](./agent/agent.py)：构建五个 `LlmAgent`，分别覆盖 HTTP 形态默认项、LRU 缓存、白名单、黑名单、SSRF 防护
+- [examples/webfetch_tool/agent/prompts.py](./agent/prompts.py)：网页阅读助手提示词，要求引用 URL、复述 `BLOCKED_URL` / `SSRF_BLOCKED_URL` / `HTTP_STATUS` 错误、并在命中缓存时告知用户
+- [examples/webfetch_tool/agent/config.py](./agent/config.py)：环境变量读取（LLM 凭据）
+- [examples/webfetch_tool/run_agent.py](./run_agent.py)：测试入口，依次执行基线抓取、`max_length` 按需裁剪、缓存命中、白名单拒绝、黑名单拒绝、SSRF 三类 payload 拒绝等场景
+
+## 关键代码解释
+
+这一节用于快速定位"HTTP 形态默认项、LRU 缓存、域名过滤、SSRF 防护"四条核心链路。
+
+### 1) HTTP 形态默认项（`agent/agent.py::create_default_fetch_agent`）
+
+- `timeout`：HTTP 读写超时，示例压到 10s 便于快速暴露网络异常
+- `user_agent`：线上日志可由此识别示例流量
+- `max_content_length`：返回 `content` 字符上限（示例 4000，便于屏显）；LLM 调用参数 `max_length` 可进一步**按调用覆盖**
+- `max_response_bytes`：线缆上允许读取的**原始字节**上限（示例 1 MiB）。流式读取遇到该上限即终止下载，避免大文件吃满解码/内存预算
+- `follow_redirects` / `max_redirects`：手动重定向循环，上限示例 3 跳
+- `block_private_network`：默认开启的 SSRF 边界，**每一跳**都会重新做 DNS 解析校验
+
+### 2) LRU 缓存（`agent/agent.py::create_cached_fetch_agent`）
+
+- `enable_cache=True`：打开进程内 URL → `FetchResult` LRU（默认关闭，需显式 opt-in）
+- `cache_ttl_seconds`：单条新鲜度，超时后下一次读触发穿透 + 淘汰
+- `cache_max_bytes`：总字节预算，满后按 LRU 淘汰；**单条体积超过预算时会被静默跳过**
+- 缓存键会做 URL 归一化（统一 scheme 大小写、剥离 `www.`、忽略默认端口、忽略尾 `/`），`https://example.com` 与 `https://www.example.com/` 共享同一条缓存项
+- 命中时 `FetchResult.cached = True`，便于下游判断新鲜度
+
+### 3) 域名白/黑名单（`agent/agent.py::create_whitelist_fetch_agent` / `create_blocklist_fetch_agent`）
+
+- `allowed_domains` / `blocked_domains` 为**工具级**配置，**LLM 无法在调用参数里覆盖**；这是与 `WebSearchTool`（LLM 可逐调用传入名单）的主要差别
+- 匹配规则：`www.` 前缀剥离，子域感知（`python.org` 同时匹配 `docs.python.org`）
+- **黑名单优先**：同一主机同时命中两张名单时仍被拒绝，返回错误 `BLOCKED_URL: '<host>' is not permitted by the tool's domain policy`
+- 每一跳重定向都会重新套一遍名单校验，防止"合法首跳 → 跳到被禁主机"的绕过
+
+### 4) SSRF 防护（`agent/agent.py::create_ssrf_fetch_agent`）
+
+- `block_private_network=True` 为默认值，示例里显式固定以便明确意图
+- 在发起请求**和每一跳重定向**时对目标主机做 DNS 解析，命中以下任一即以结构化错误 `SSRF_BLOCKED_URL: <host> is a private/reserved address` 拒绝，**不会建立任何 TCP 连接**：
+  - 回环（`127.0.0.0/8`，包含 `localhost`）
+  - 链路本地（`169.254.0.0/16`，含 `169.254.169.254` AWS / GCP / Aliyun / 腾讯云通用元数据端点）
+  - 私网（RFC 1918：`10/8`、`172.16/12`、`192.168/16`，以及 IPv6 ULA `fc00::/7`）
+  - 保留 / 组播 / 未指定（`0.0.0.0`、`::`）地址
+- 纯 IP 字面量会直接走 `ipaddress` 判定；域名则通过 `socket.getaddrinfo` 解析出的**每一条 A/AAAA 记录**都要求是公网地址，任意一条命中私网即整体拒绝，有效阻断"DNS 结果是一条公网 IP + 一条 `127.0.0.1`"这类 DNS Rebinding 变种
+- 本示例专门用 `ssrf_fetch_agent` 驱动三类经典 payload：
+  - `http://127.0.0.1/` — 本机 loopback，覆盖"让 Agent 打自己"的最短路径
+  - `http://169.254.169.254/latest/meta-data/` — 云实例元数据端点，历史上是最常见的 SSRF 数据外泄目标
+  - `http://10.0.0.1/` — RFC 1918 内网网段，覆盖"Agent 跑在 VPC / k8s 集群里被用来扫内网"
+- 仅当调用方已用外部白名单限定目标、并确信输入可信（如内网集群）时才考虑关闭该开关；关闭后示例 5 的三条 payload 会真的发起连接，生产环境请谨慎评估
+
+## 环境与运行
+
+### 环境要求
+
+- Python 3.12
+
+### 安装步骤
+
+```bash
+git clone https://github.com/trpc-group/trpc-agent-python.git
+cd trpc-agent-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip3 install -e .
+```
+
+### 环境变量要求
+
+在 [examples/webfetch_tool/.env](./.env) 中配置（或通过 `export`）：
+
+必填：
+
+- `TRPC_AGENT_API_KEY`
+- `TRPC_AGENT_BASE_URL`
+- `TRPC_AGENT_MODEL_NAME`
+
+### 运行命令
+
+```bash
+cd examples/webfetch_tool
+python3 run_agent.py
+```
+
+## 运行结果
+
+```text
+========== Default · plain fetch ==========
+🆔 Session ID: d422c00b...
+📝 User: Fetch https://example.com and summarise the page in one short paragraph.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://example.com', 'max_length': 500})]
+📊 [Tool Result: url='https://example.com' status=200 content_type='text/html' bytes=183 cached=False duration_ms=87 preview='Example Domain  # Example Domain  This domain is for use in documentation examples without needing permission. Avoid ...']
+The page at **Example Domain** is a placeholder used for documentation purposes. It states that the domain is intended for examples and should not be used in actual operations. A link is provided to learn more about such domains.
+
+Source: [https://example.com](https://example.com)
+----------------------------------------
+
+========== Default · per-call max_length override ==========
+🆔 Session ID: 47afb4e2...
+📝 User: Fetch https://example.com but only return the first ~200 characters of the body. Use max_length=200 on the tool call.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://example.com', 'max_length': 200})]
+📊 [Tool Result: url='https://example.com' status=200 content_type='text/html' bytes=183 cached=False duration_ms=75 preview='Example Domain  # Example Domain  This domain is for use in documentation examples without needing permission. Avoid ...']
+Here is the first ~200 characters of the content from https://example.com:
+
+Example Domain
+
+# Example Domain
+
+This domain is for use in documentation examples without needing permission. Avoid use in operations.
+
+[Learn more](https://iana.org/domains/example)
+
+Source: [https://example.com](https://example.com)
+----------------------------------------
+
+========== Cache · first fetch (network) ==========
+🆔 Session ID: 64dbc485...
+📝 User: Fetch https://example.com and summarise the page in one short paragraph.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://example.com', 'max_length': 500})]
+[INFO] WebFetchTool put result for https://example.com in LRU cache
+📊 [Tool Result: url='https://example.com' status=200 content_type='text/html' bytes=183 cached=False duration_ms=79 preview='Example Domain  # Example Domain  This domain is for use in documentation examples without needing permission. Avoid ...']
+The page at **Example Domain** is a placeholder used for documentation purposes. It states that this domain is intended for examples and should not be used in actual operations. A link is provided to learn more about such domains.
+
+Source: [https://example.com](https://example.com)
+----------------------------------------
+
+========== Cache · second fetch (cache hit) ==========
+🆔 Session ID: 857e415e...
+📝 User: Fetch https://example.com again and summarise the page in one short paragraph. Tell me whether the tool served the response from the cache.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://example.com', 'max_length': 500})]
+[INFO] WebFetchTool got cached result for https://example.com in LRU cache
+📊 [Tool Result: url='https://example.com' status=200 content_type='text/html' bytes=183 cached=True duration_ms=79 preview='Example Domain  # Example Domain  This domain is for use in documentation examples without needing permission. Avoid ...']
+The page at **Example Domain** is a placeholder used for documentation purposes, advising users to avoid operational use. It provides a link to learn more about such domains.
+
+The response was served from the in-process cache, so the content may be slightly stale (up to the tool's configured TTL).
+
+Source: [https://example.com](https://example.com)
+----------------------------------------
+
+========== Whitelist · allowed host (python.org) ==========
+🆔 Session ID: d56de0e1...
+📝 User: Fetch https://www.python.org/ and summarise the landing page in one short paragraph.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://www.python.org/', 'max_length': 500})]
+📊 [Tool Result: url='https://www.python.org/' status=200 content_type='text/html' bytes=505 cached=False duration_ms=413 preview='Welcome to Python.org  **Notice:** This page displays a fallback because interactive scripts did not run. Possible ca...']
+The Python.org landing page welcomes visitors to the official site of the Python programming language. It provides quick links to essential resources like the Python Software Foundation (PSF), documentation, the Python Package Index (PyPI), and more. The page also includes navigation options for exploring Python further.
+
+Source: [Python.org](https://www.python.org/)
+----------------------------------------
+
+========== Whitelist · rejected host (example.com) ==========
+🆔 Session ID: 980ff5ad...
+📝 User: Fetch https://example.com and summarise the page. If the tool refuses the URL, explain why.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://example.com'})]
+📊 [Tool Result: error="BLOCKED_URL: 'example.com' is not permitted by the tool's domain policy" url='https://example.com' status=None]
+The tool refused to fetch the URL `https://example.com` because the domain `example.com` is not permitted by the tool's domain policy. This means the tool has a blocklist or allowlist in place that restricts access to certain domains, and `example.com` is one of them.
+
+If you need information from a different domain, please provide a URL that is allowed by the tool's policy.
+----------------------------------------
+
+========== Blacklist · rejected host (example.com) ==========
+🆔 Session ID: a58386ba...
+📝 User: Fetch https://example.com and summarise the page. If the tool refuses the URL, explain why.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'https://example.com'})]
+📊 [Tool Result: error="BLOCKED_URL: 'example.com' is not permitted by the tool's domain policy" url='https://example.com' status=None]
+The tool refused to fetch the URL `https://example.com` because the domain `example.com` is blocked by the tool's domain policy. This means the tool is configured to disallow requests to this specific domain.
+
+If you need information from this domain, you may need to use an alternative method or tool to access it.
+----------------------------------------
+
+========== SSRF · loopback (127.0.0.1) ==========
+🆔 Session ID: 0b0503e6...
+📝 User: Fetch http://127.0.0.1/ and summarise the page. If the tool refuses the URL, explain why in one or two sentences.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'http://127.0.0.1/'})]
+📊 [Tool Result: error='SSRF_BLOCKED_URL: 127.0.0.1 is a private/reserved address' url='http://127.0.0.1/' status=0]
+The tool refused to fetch the URL `http://127.0.0.1/` because it resolves to a loopback (private/reserved) address (`127.0.0.1`), which is blocked by the SSRF guard to prevent potential security risks.
+----------------------------------------
+
+========== SSRF · cloud metadata (169.254.169.254) ==========
+🆔 Session ID: a370e17b...
+📝 User: Fetch http://169.254.169.254/latest/meta-data/ and summarise what it returns. If the tool refuses the URL, explain why in one or two sentences.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'http://169.254.169.254/latest/meta-data/'})]
+📊 [Tool Result: error='SSRF_BLOCKED_URL: 169.254.169.254 is a private/reserved address' url='http://169.254.169.254/latest/meta-data/' status=0]
+The tool refused to fetch the URL `http://169.254.169.254/latest/meta-data/` because the IP address `169.254.169.254` is a private/reserved address, and accessing such addresses is blocked by the SSRF (Server-Side Request Forgery) guard to prevent security risks. 
+
+Source: [http://169.254.169.254/latest/meta-data/](http://169.254.169.254/latest/meta-data/)
+----------------------------------------
+
+========== SSRF · RFC 1918 intranet (10.0.0.1) ==========
+🆔 Session ID: 9a667a8d...
+📝 User: Fetch http://10.0.0.1/ and summarise the page. If the tool refuses the URL, explain why in one or two sentences.
+🤖 Assistant: 
+🔧 [Invoke Tool: webfetch({'url': 'http://10.0.0.1/'})]
+📊 [Tool Result: error='SSRF_BLOCKED_URL: 10.0.0.1 is a private/reserved address' url='http://10.0.0.1/' status=0]
+The tool refused to fetch the URL `http://10.0.0.1/` because the target address `10.0.0.1` is a private/reserved IP address, which is blocked by the SSRF (Server-Side Request Forgery) guard to prevent unauthorized access to internal networks.
+----------------------------------------
+```
+
+## 适用场景建议
+
+- 需要 LLM 阅读 **指定网页并引用 URL** 的场景：适合直接复用本示例 `WebFetchTool` + 提示词约定
+- 对 **公网 SSRF 风险敏感**（例如 Agent 跑在云实例、能访问内网元数据端点）：保留 `block_private_network=True` 默认值，并参考 `ssrf_fetch_agent` 用 loopback / `169.254.169.254` / RFC 1918 三条 payload 固化回归测试
+- 存在 **热点页面反复读取**（文档、changelog、status page）：打开 `enable_cache=True` 并按请求体量调整 `cache_max_bytes`
+- 需要把抓取工具限定在一小组可信站点（白名单）或屏蔽已知噪声站点（黑名单）：通过 `allowed_domains` / `blocked_domains` 配置，**这两个参数 LLM 无法覆盖**
+- 需要在工具调用前后插入日志、审计、参数校验：参考 [examples/filter_with_tool](../filter_with_tool)，把 `WebFetchTool(filters_name=[...])` 与 `before_tool_callback` / `after_tool_callback` 组合使用
+- 需要自定义 HTTP 形态（公司代理、mTLS、连接池复用）：通过构造参数 `proxy` 或 `http_client` 注入
diff --git a/examples/webfetch_tool/agent/__init__.py b/examples/webfetch_tool/agent/__init__.py
new file mode 100644
index 0000000..bc6e483
--- /dev/null
+++ b/examples/webfetch_tool/agent/__init__.py
@@ -0,0 +1,5 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
diff --git a/examples/webfetch_tool/agent/agent.py b/examples/webfetch_tool/agent/agent.py
new file mode 100644
index 0000000..d87e427
--- /dev/null
+++ b/examples/webfetch_tool/agent/agent.py
@@ -0,0 +1,166 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" Agent module for WebFetchTool"""
+
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel
+from trpc_agent_sdk.models import OpenAIModel
+from trpc_agent_sdk.tools import WebFetchTool
+
+from .config import get_model_config
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """Create the LLM model used by every demo agent."""
+    api_key, url, model_name = get_model_config()
+    return OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+
+
+def create_default_fetch_agent() -> LlmAgent:
+    """Build the baseline webfetch agent.
+
+    The construction below pins every HTTP-shape knob explicitly so the
+    example doubles as inline documentation:
+
+    - ``timeout`` — lower than the 30s default so transient network
+      hiccups surface quickly in the demo.
+    - ``user_agent`` — identifies the demo on the wire so downstream
+      logs can tell example traffic apart from real deployments.
+    - ``max_content_length`` — cap returned ``content`` text so the
+      demo output stays readable even for long pages.
+    - ``max_response_bytes`` — hard byte budget on the raw wire read
+      (~1 MiB here) that protects decode / memory budgets before the
+      char cap kicks in.
+    - ``follow_redirects`` / ``max_redirects`` — keep the redirect
+      loop bounded while still handling ``http`` → ``https`` hops.
+    - ``block_private_network`` — default-on SSRF boundary; pinned
+      here to make the intent explicit.
+    """
+    web_fetch = WebFetchTool(
+        timeout=10.0,
+        user_agent="trpc-agent-python-webfetch-example/1.0",
+        max_content_length=4000,
+        max_response_bytes=1 * 1024 * 1024,
+        follow_redirects=True,
+        max_redirects=3,
+        block_private_network=True,
+    )
+    return LlmAgent(
+        name="default_webfetch_assistant",
+        description="Web-reading assistant that fetches a single URL and summarises its textual content.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+
+
+def create_cached_fetch_agent() -> LlmAgent:
+    """Build a webfetch agent that enables the in-process LRU cache.
+
+    Cache knobs covered:
+
+    - ``enable_cache=True`` — opt in to the URL → ``FetchResult`` LRU.
+    - ``cache_ttl_seconds`` — how long an entry is considered fresh.
+    - ``cache_max_bytes`` — total byte budget for the cache; entries
+      larger than this limit are silently skipped.
+
+    The demo fetches the same URL twice in a row so the second call
+    comes back with ``cached=true`` on the tool response.
+    """
+    web_fetch = WebFetchTool(
+        timeout=10.0,
+        user_agent="trpc-agent-python-webfetch-example/1.0",
+        max_content_length=4000,
+        max_response_bytes=1 * 1024 * 1024,
+        enable_cache=True,
+        cache_ttl_seconds=120.0,
+        cache_max_bytes=2 * 1024 * 1024,
+    )
+    return LlmAgent(
+        name="cached_webfetch_assistant",
+        description=("Web-reading assistant with an in-process LRU cache so repeated "
+                     "fetches of the same URL skip the network."),
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+
+
+def create_whitelist_fetch_agent() -> LlmAgent:
+    """Build a webfetch agent that only permits a closed set of hosts.
+
+    Configures ``allowed_domains`` so every non-whitelisted URL is
+    rejected with ``BLOCKED_URL`` before the HTTP GET is issued. The
+    matching is subdomain-aware (``www.`` stripped), so ``python.org``
+    also lets ``docs.python.org`` through.
+    """
+    web_fetch = WebFetchTool(
+        timeout=10.0,
+        user_agent="trpc-agent-python-webfetch-example/1.0",
+        max_content_length=4000,
+        allowed_domains=["python.org"],
+    )
+    return LlmAgent(
+        name="whitelist_webfetch_assistant",
+        description=("Web-reading assistant restricted to a domain whitelist; "
+                     "off-list URLs are rejected with BLOCKED_URL."),
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+
+
+def create_ssrf_fetch_agent() -> LlmAgent:
+    """Build a webfetch agent that focuses on the SSRF guard."""
+    web_fetch = WebFetchTool(
+        timeout=10.0,
+        user_agent="trpc-agent-python-webfetch-example/1.0",
+        max_content_length=4000,
+        follow_redirects=True,
+        max_redirects=3,
+        block_private_network=True,
+    )
+    return LlmAgent(
+        name="ssrf_webfetch_assistant",
+        description=("Web-reading assistant with an SSRF guard that rejects loopback / private / "
+                     "link-local / reserved / multicast / unspecified targets on every hop."),
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+
+
+def create_blocklist_fetch_agent() -> LlmAgent:
+    """Build a webfetch agent that rejects a named set of hosts.
+
+    Configures ``blocked_domains`` so any URL whose host matches
+    (subdomain-aware, ``www.`` stripped) is rejected with
+    ``BLOCKED_URL``. Blocks are evaluated *before* the allow list, so a
+    host present in both lists is still rejected.
+    """
+    web_fetch = WebFetchTool(
+        timeout=10.0,
+        user_agent="trpc-agent-python-webfetch-example/1.0",
+        max_content_length=4000,
+        blocked_domains=["example.com"],
+    )
+    return LlmAgent(
+        name="blocklist_webfetch_assistant",
+        description=("Web-reading assistant with a domain blacklist; "
+                     "blacklisted URLs are rejected with BLOCKED_URL."),
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_fetch],
+    )
+
+
+default_fetch_agent = create_default_fetch_agent()
+cached_fetch_agent = create_cached_fetch_agent()
+whitelist_fetch_agent = create_whitelist_fetch_agent()
+blocklist_fetch_agent = create_blocklist_fetch_agent()
+ssrf_fetch_agent = create_ssrf_fetch_agent()
+root_agent = default_fetch_agent
diff --git a/examples/webfetch_tool/agent/config.py b/examples/webfetch_tool/agent/config.py
new file mode 100644
index 0000000..7f60e29
--- /dev/null
+++ b/examples/webfetch_tool/agent/config.py
@@ -0,0 +1,19 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" Agent config module"""
+
+import os
+
+
+def get_model_config() -> tuple[str, str, str]:
+    """Get LLM model config from environment variables."""
+    api_key = os.getenv('TRPC_AGENT_API_KEY', '')
+    url = os.getenv('TRPC_AGENT_BASE_URL', '')
+    model_name = os.getenv('TRPC_AGENT_MODEL_NAME', '')
+    if not api_key or not url or not model_name:
+        raise ValueError('''TRPC_AGENT_API_KEY, TRPC_AGENT_BASE_URL,
+                         and TRPC_AGENT_MODEL_NAME must be set in environment variables''')
+    return api_key, url, model_name
diff --git a/examples/webfetch_tool/agent/prompts.py b/examples/webfetch_tool/agent/prompts.py
new file mode 100644
index 0000000..2d88679
--- /dev/null
+++ b/examples/webfetch_tool/agent/prompts.py
@@ -0,0 +1,28 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" prompts for agent"""
+
+INSTRUCTION = ("You are a web-reading assistant that answers user questions using the `webfetch` tool.\n"
+               "\n"
+               "Workflow:\n"
+               "  1. When the user gives you an absolute http(s) URL and asks you to read, summarise, or\n"
+               "     quote from it, call `webfetch` ONCE with that exact URL. Do not invent or rewrite the URL.\n"
+               "  2. If the user asks for only a short excerpt / headline, pass a smaller `max_length`\n"
+               "     (e.g. 500 or 1000) so the tool truncates the response early and keeps the context tight.\n"
+               "     Otherwise omit `max_length` and let the tool-level default apply.\n"
+               "  3. Use the returned `content` field verbatim to compose your answer; quote short phrases\n"
+               "     directly and summarise the rest in your own words.\n"
+               "  4. If the tool returns an `error` field (e.g. `BLOCKED_URL`, `SSRF_BLOCKED_URL`, `HTTP_STATUS`,\n"
+               "     `UNSUPPORTED_CONTENT_TYPE`), do NOT guess the page contents — explain the failure briefly.\n"
+               "     - For `BLOCKED_URL`, tell the user which domain allow/block policy rejected the host.\n"
+               "     - For `SSRF_BLOCKED_URL`, tell the user the target resolved to a loopback / private /\n"
+               "       link-local / reserved / multicast / unspecified address and was refused by the SSRF\n"
+               "       guard before any connection was opened.\n"
+               "  5. If `cached=true` is set on the tool response, mention at the end of your reply that the\n"
+               "     page was served from the in-process cache so the user knows the content may be slightly\n"
+               "     stale (up to the tool's configured TTL).\n"
+               "  6. After answering, append a `Source:` line with the final `url` from the tool response as a\n"
+               "     markdown link (redirects may have rewritten the URL you were given). Never fabricate URLs.")
diff --git a/examples/webfetch_tool/run_agent.py b/examples/webfetch_tool/run_agent.py
new file mode 100644
index 0000000..d4b9b48
--- /dev/null
+++ b/examples/webfetch_tool/run_agent.py
@@ -0,0 +1,213 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Demo entry point for the WebFetchTool example.
+
+The script drives several agents back-to-back so a single ``python3
+run_agent.py`` invocation exercises the most common ``WebFetchTool``
+constructor knobs:
+
+1. Default fetch — plain HTTP GET + Markdown conversion against a
+   small, stable public page. Exercises the default ``timeout`` /
+   ``user_agent`` / ``max_content_length`` / ``max_response_bytes`` /
+   ``follow_redirects`` / ``max_redirects`` / ``block_private_network``
+   settings configured on :data:`default_fetch_agent`.
+2. Per-call ``max_length`` override — the LLM passes a smaller
+   per-call cap so the response `content` is truncated early without
+   changing the tool-level ``max_content_length`` default.
+3. Cache miss → cache hit — two back-to-back fetches of the same URL
+   against :data:`cached_fetch_agent`; the second response is served
+   from the in-process LRU with ``cached=true``, exercising
+   ``enable_cache`` / ``cache_ttl_seconds`` / ``cache_max_bytes``.
+4. Whitelist rejection — :data:`whitelist_fetch_agent` pins
+   ``allowed_domains=["python.org"]``; a non-whitelisted URL comes back
+   with ``BLOCKED_URL`` before any HTTP traffic is issued.
+5. Blacklist rejection — :data:`blocklist_fetch_agent` pins
+   ``blocked_domains=["example.com"]``; a URL on that list is rejected
+   with ``BLOCKED_URL`` (blocks win over allow lists).
+6. SSRF rejection — :data:`ssrf_fetch_agent` keeps
+   ``block_private_network=True`` and is driven against the three
+   canonical SSRF payloads (loopback ``127.0.0.1``, the AWS
+   cloud-metadata endpoint ``169.254.169.254``, and an RFC 1918 intranet
+   IP ``10.0.0.1``). Every attempt is rejected with
+   ``SSRF_BLOCKED_URL`` *before* any TCP connection is opened, so the
+   demo is safe to run from any network.
+
+The public URLs used below (``https://example.com``,
+``https://www.python.org/``) are intentionally small, stable, and
+unauthenticated so the example stays reproducible.
+
+Each scenario uses a fresh session so the agents do not lean on prior
+context — this makes the tool-call flow easy to read in the output.
+"""
+
+import asyncio
+import uuid
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content
+from trpc_agent_sdk.types import Part
+
+load_dotenv()
+
+APP_NAME = "webfetch_agent_demo"
+USER_ID = "demo_user"
+
+
+async def _run_one_query(runner: Runner, *, label: str, query: str) -> None:
+    """Drive a single user query through ``runner`` and pretty-print events."""
+    session_id = str(uuid.uuid4())
+    await runner.session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+        session_id=session_id,
+        state={"user_name": USER_ID},
+    )
+
+    print(f"\n========== {label} ==========")
+    print(f"🆔 Session ID: {session_id[:8]}...")
+    print(f"📝 User: {query}")
+    print("🤖 Assistant: ", end="", flush=True)
+
+    user_content = Content(parts=[Part.from_text(text=query)])
+    async for event in runner.run_async(
+            user_id=USER_ID,
+            session_id=session_id,
+            new_message=user_content,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text, end="", flush=True)
+            continue
+
+        for part in event.content.parts:
+            if part.thought:
+                continue
+            if part.function_call:
+                print(f"\n🔧 [Invoke Tool: {part.function_call.name}({part.function_call.args})]")
+            elif part.function_response:
+                resp = part.function_response.response
+                preview = _summarise_tool_response(resp)
+                print(f"📊 [Tool Result: {preview}]")
+
+    print("\n" + "-" * 40)
+
+
+def _summarise_tool_response(resp) -> str:
+    """Compact a ``FetchResult`` dict so the demo output stays readable."""
+    if not isinstance(resp, dict):
+        return str(resp)
+    if resp.get("error"):
+        return (f"error={resp.get('error')!r} url={resp.get('url')!r} "
+                f"status={resp.get('status_code')}")
+    content = (resp.get("content") or "").strip().replace("\n", " ")
+    if len(content) > 120:
+        content = content[:117] + "..."
+    return (f"url={resp.get('url')!r} status={resp.get('status_code')} "
+            f"content_type={resp.get('content_type')!r} bytes={resp.get('bytes')} "
+            f"cached={resp.get('cached')} duration_ms={resp.get('duration_ms')} "
+            f"preview={content!r}")
+
+
+async def _drive_agent(agent: LlmAgent, *, scenarios: list[tuple[str, str]]) -> None:
+    """Spin up a ``Runner`` for ``agent`` and run each ``(label, query)`` pair.
+
+    The runner — and therefore the cached agent's in-process LRU — is
+    shared across every scenario in ``scenarios`` so back-to-back
+    fetches of the same URL can actually hit the cache.
+    """
+    runner = Runner(
+        app_name=APP_NAME,
+        agent=agent,
+        session_service=InMemorySessionService(),
+    )
+    for label, query in scenarios:
+        await _run_one_query(runner, label=label, query=query)
+
+
+async def main() -> None:
+    from agent.agent import (
+        blocklist_fetch_agent,
+        cached_fetch_agent,
+        default_fetch_agent,
+        ssrf_fetch_agent,
+        whitelist_fetch_agent,
+    )
+
+    default_scenarios = [
+        (
+            "Default · plain fetch",
+            "Fetch https://example.com and summarise the page in one short paragraph.",
+        ),
+        (
+            "Default · per-call max_length override",
+            "Fetch https://example.com but only return the first ~200 characters of the body. "
+            "Use max_length=200 on the tool call.",
+        ),
+    ]
+    await _drive_agent(default_fetch_agent, scenarios=default_scenarios)
+
+    cached_scenarios = [
+        (
+            "Cache · first fetch (network)",
+            "Fetch https://example.com and summarise the page in one short paragraph.",
+        ),
+        (
+            "Cache · second fetch (cache hit)",
+            "Fetch https://example.com again and summarise the page in one short paragraph. "
+            "Tell me whether the tool served the response from the cache.",
+        ),
+    ]
+    await _drive_agent(cached_fetch_agent, scenarios=cached_scenarios)
+
+    whitelist_scenarios = [
+        (
+            "Whitelist · allowed host (python.org)",
+            "Fetch https://www.python.org/ and summarise the landing page in one short paragraph.",
+        ),
+        (
+            "Whitelist · rejected host (example.com)",
+            "Fetch https://example.com and summarise the page. If the tool refuses the URL, explain why.",
+        ),
+    ]
+    await _drive_agent(whitelist_fetch_agent, scenarios=whitelist_scenarios)
+
+    blocklist_scenarios = [
+        (
+            "Blacklist · rejected host (example.com)",
+            "Fetch https://example.com and summarise the page. If the tool refuses the URL, explain why.",
+        ),
+    ]
+    await _drive_agent(blocklist_fetch_agent, scenarios=blocklist_scenarios)
+
+    ssrf_scenarios = [
+        (
+            "SSRF · loopback (127.0.0.1)",
+            "Fetch http://127.0.0.1/ and summarise the page. If the tool refuses the URL, "
+            "explain why in one or two sentences.",
+        ),
+        (
+            "SSRF · cloud metadata (169.254.169.254)",
+            "Fetch http://169.254.169.254/latest/meta-data/ and summarise what it returns. "
+            "If the tool refuses the URL, explain why in one or two sentences.",
+        ),
+        (
+            "SSRF · RFC 1918 intranet (10.0.0.1)",
+            "Fetch http://10.0.0.1/ and summarise the page. If the tool refuses the URL, "
+            "explain why in one or two sentences.",
+        ),
+    ]
+    await _drive_agent(ssrf_fetch_agent, scenarios=ssrf_scenarios)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/websearch_tool/.env b/examples/websearch_tool/.env
new file mode 100644
index 0000000..0745ca5
--- /dev/null
+++ b/examples/websearch_tool/.env
@@ -0,0 +1,12 @@
+# Set TRPC_AGENT_API_KEY、TRPC_AGENT_BASE_URL、TRPC_AGENT_MODEL_NAME
+TRPC_AGENT_API_KEY=your_api_key
+TRPC_AGENT_BASE_URL=your_base_url
+TRPC_AGENT_MODEL_NAME=your_model_name
+
+# Google Custom Search — required ONLY when driving the google_agent /
+# google_raw_agent scenarios. Obtain credentials from
+#   https://developers.google.com/custom-search/v1/overview
+# If either variable is missing the Google scenarios will short-circuit
+# with a friendly "provider not configured" summary instead of crashing.
+GOOGLE_CSE_API_KEY=your_google_cse_api_key
+GOOGLE_CSE_ENGINE_ID=your_google_cse_engine_id
diff --git a/examples/websearch_tool/README.md b/examples/websearch_tool/README.md
new file mode 100644
index 0000000..e582316
--- /dev/null
+++ b/examples/websearch_tool/README.md
@@ -0,0 +1,346 @@
+# WebSearchTool 联网检索示例
+
+本示例演示如何使用框架内置的 `WebSearchTool`，让 LLM Agent 通过公网搜索引擎获取实时信息，并按照"白名单 / 黑名单域名 + 必须引用 URL"的规则生成可追溯的回答，同时覆盖 **DuckDuckGo** 与 **Google Custom Search** 两个 provider。
+
+## 关键特性
+
+- **双 Provider 支持**：
+  - `duckduckgo`：DuckDuckGo Instant Answer API，**无需 API Key**，适合事实/定义/百科类检索
+  - `google`：Google Custom Search（CSE），需要 `api_key` + `engine_id`，提供真正的公网搜索结果，支持 `siteSearch`、`hl`、`safe`、`dateRestrict` 等 CSE 原生参数
+- **域名白名单/黑名单**：通过工具调用参数 `allowed_domains` / `blocked_domains` 实现 site 级过滤，二者互斥；DDG 做客户端子域感知过滤，Google 在单域名时使用服务端 `siteSearch` 快速路径，多域名自动回退到客户端过滤
+- **结构化输出**：`WebSearchResult` 统一返回 `query / provider / results[{title, url, snippet}] / summary`，便于 LLM 引用与拼装 `Sources:` 段落
+- **强制引用规范**：`WebSearchTool.process_request` 自动向 LLM 追加"必须以 markdown 链接形式列出来源 URL"和"使用当前年份"的指令
+- **结果裁剪与去重**：`results_num / snippet_len / title_len` 控制返回体大小；`dedup_urls`（默认 `True`）按 scheme/host/path 归一化后自动合并同一 URL 的重复命中，避免 LLM 在 `Sources:` 段里重复引用同一来源。若需要把原始结果交给下游 re-ranker / 多样化采样等流程处理，可显式传入 `dedup_urls=False` 保留每一条命中
+- **共享 httpx 连接池**：Google 演示把 `http_client` 传给 `WebSearchTool`，在多个 agent / 多次调用之间复用连接，并演示外部负责 `aclose` 生命周期管理
+- **Provider 原生参数透传**：`ddg_extra_params` / `google_extra_params` 让用户把 provider 专属的高级参数（如 Google CSE 的 `safe`、`dateRestrict`）封装在 agent 层，无需每次工具调用重复指定
+
+## Agent 层级结构说明
+
+本例提供四个独立 Agent，按场景顺序驱动；`root_agent` 默认指向 `ddg_agent`：
+
+```text
+ddg_agent (LlmAgent)                   # 默认 dedup_urls=True
+├── model: OpenAIModel
+├── tools:
+│   └── WebSearchTool(provider="duckduckgo", results_num=3, snippet_len=300)
+└── session: InMemorySessionService
+
+ddg_raw_agent (LlmAgent)               # dedup_urls=False，保留原始命中
+├── model: OpenAIModel
+├── tools:
+│   └── WebSearchTool(provider="duckduckgo", results_num=5, dedup_urls=False)
+└── session: InMemorySessionService
+
+google_agent (LlmAgent)                # 基线 Google CSE，覆盖大部分构造参数
+├── model: OpenAIModel
+├── tools:
+│   └── WebSearchTool(
+│         provider="google",
+│         api_key=<GOOGLE_CSE_API_KEY>,
+│         engine_id=<GOOGLE_CSE_ENGINE_ID>,
+│         user_agent="trpc-agent-python-websearch-demo/1.0 (+google-cse)",
+│         proxy=<HTTPS_PROXY/HTTP_PROXY>,
+│         lang="en",
+│         http_client=<shared httpx.AsyncClient>,
+│         results_num=3, snippet_len=240, title_len=80, timeout=15.0,
+│         dedup_urls=True,
+│         google_extra_params={"safe": "active"},
+│       )
+└── session: InMemorySessionService
+
+google_raw_agent (LlmAgent)            # dedup_urls=False + 6 个月时效性
+├── model: OpenAIModel
+├── tools:
+│   └── WebSearchTool(
+│         provider="google", ...,
+│         results_num=5, snippet_len=320, title_len=100, timeout=20.0,
+│         dedup_urls=False,
+│         google_extra_params={"dateRestrict": "m6"},
+│       )
+└── session: InMemorySessionService
+```
+
+关键文件：
+
+- [examples/websearch_tool/agent/agent.py](./agent/agent.py)：构建四个 `LlmAgent`，分别挂载默认去重/关闭去重的 DuckDuckGo 与 Google CSE 版本 `WebSearchTool`
+- [examples/websearch_tool/agent/prompts.py](./agent/prompts.py)：两套 instruction —— DuckDuckGo 版（实体名查询）与 Google 版（自然语言 + 年份 + 可选 `lang` 覆盖）
+- [examples/websearch_tool/agent/config.py](./agent/config.py)：环境变量读取（LLM 凭据 + Google CSE 凭据 + 可选 HTTP 代理）
+- [examples/websearch_tool/run_agent.py](./run_agent.py)：测试入口，先跑 DuckDuckGo 的白名单/黑名单/`dedup_urls=False` 场景，再跑 Google 的服务端 `siteSearch` / 客户端多域名过滤 / 黑名单 / 语言覆盖 / 时效性 bias 场景
+
+## 关键代码解释
+
+这一节用于快速定位 "Provider 切换、域名过滤、引用规范注入、URL 去重、共享连接池、Google 原生参数" 六条核心链路。
+
+### 1) Provider 配置（`agent/agent.py`）
+
+- `WebSearchTool(provider="duckduckgo", ...)`：使用 DuckDuckGo Instant Answer API，**无需 API Key**，适合定义/百科/事实型查询
+- `WebSearchTool(provider="google", api_key=..., engine_id=..., ...)`：使用 Google Custom Search JSON API，需要 API Key 和 Programmable Search engine id（即 CSE 的 `cx`）
+- `results_num / snippet_len / title_len` 控制单次调用返回体大小；`timeout` 控制 HTTP 超时；每个参数在构造时都会按 `[1, _MAX_*]` 做 clamp，避免误配置打爆上下文
+
+### 2) 黑/白名单域名过滤（`run_agent.py` 的提示词驱动）
+
+- 用户在请求中明确"只用 wikipedia.org"或"排除 duckduckgo.com"，LLM 会按工具 `FunctionDeclaration` 自动把对应的字符串数组放进 `allowed_domains` / `blocked_domains`
+- `WebSearchTool._run_async_impl` 会：
+  - 把 `allowed_domains` 与 `blocked_domains` 同时传入时返回 `INVALID_ARGS`（互斥校验）
+  - 对 DuckDuckGo 结果做客户端域名过滤
+  - 对 Google 结果：
+    - **单个域名**时优先使用服务端 `siteSearch` + `siteSearchFilter=i/e`（更少流量、更快）
+    - **多个域名**时跳过服务端过滤，回退到客户端 `_is_blocked` —— 因为 Google CSE 的 `siteSearch` 只接受一个值
+  - 把 `www.` 前缀剥离并按子域匹配（如 `wikipedia.org` 同时匹配 `en.wikipedia.org`）
+
+### 3) 引用规范与时间感知指令注入（`WebSearchTool.process_request`）
+
+- 工具在每次请求前会自动 `append_instructions`，强制要求：
+  - 回答末尾追加 `Sources:` 段并以 `[Title](URL)` 列出工具返回的 URL
+  - 不允许编造 URL，只能引用工具实际返回的 URL
+  - 在涉及"最新/recent/current"类查询时使用 _当前月份与年份_ 入参（避免 LLM 幻觉旧年份）
+- 这部分逻辑无需例子代码额外配置，只要挂载 `WebSearchTool` 就会生效
+
+### 4) URL 去重开关（`dedup_urls`）
+
+- `WebSearchTool` 构造参数 `dedup_urls`（默认 `True`）控制是否合并"形态不同但语义相同"的 URL：
+  - 归一化时会统一 `scheme` 大小写、剥离 `www.` 前缀、忽略末尾 `/`、忽略 http/https 默认端口
+  - 例如 `https://docs.python.org/3/` 与 `https://www.docs.python.org/3` 会被视为同一来源，仅保留首次出现
+- `ddg_agent` / `google_agent` 使用默认值 `True`，避免 `Sources:` 段里出现重复链接
+- `ddg_raw_agent` / `google_raw_agent` 显式传入 `dedup_urls=False`，把每一条原始 provider 命中都透出给调用方，适配：
+  - 外置 **re-ranker**（如 Cross-Encoder / Cohere Rerank）需要更多候选以挑出最相关项
+  - **多样化采样 / MMR** 等希望看到重复变体以评估置信度的流水线
+  - 需要做**链路可观测性**、记录原始召回列表用于离线评估的场景
+
+### 5) 共享 httpx.AsyncClient（`http_client` + `user_agent` + `proxy` + `timeout`）
+
+`google_agent` 与 `google_raw_agent` 共用一个由 `_get_shared_google_http_client()` 创建的 `httpx.AsyncClient`，通过构造参数传入 `WebSearchTool`：
+
+- **连接复用**：多次搜索复用同一连接池，对连续调用明显更快；`httpx.Limits` 的上限由创建方决定（本例 `max_connections=16, max_keepalive_connections=8`）
+- **生命周期归属**：传入外部 `http_client` 后，`WebSearchTool` **不会**帮你 `aclose()`，需要调用方显式关闭。示例在 `run_agent.py` 的 `main()` 结尾通过 `aclose_shared_google_http_client()` 在 **同一个事件循环** 内关闭，避免 `Unclosed client` 警告
+- **强制生效的 `timeout` / `user_agent`**：即使传了外部 client，`WebSearchTool._get_json` 仍会在每次 `GET` 时把构造器里的 `timeout` 与 `user_agent` 覆盖到当次请求上，保证 agent 层的这些约束始终有效
+- **可选 `proxy`**：demo 从 `HTTPS_PROXY` / `HTTP_PROXY` 读取；需要经过企业出口代理访问 Google 时填上即可，无需改代码
+
+### 6) Provider 原生参数透传（`google_extra_params` / `ddg_extra_params`）
+
+- `google_extra_params` / `ddg_extra_params` 允许把 provider 专属的高级参数固定在 agent 层，每次工具调用都自动带上
+- 本 demo 演示两种典型用法：
+  - `google_agent` 使用 `google_extra_params={"safe": "active"}` —— 打开 Google 的 SafeSearch
+  - `google_raw_agent` 使用 `google_extra_params={"dateRestrict": "m6"}` —— 只保留过去 6 个月内被 Google 索引的结果，适合"最新/what's new"类查询
+- 其他常见透传包括 Google CSE 的 `gl`（地理偏向）、`cr`（国家限制）、`filter`、`sort` 等
+
+## 环境与运行
+
+### 环境要求
+
+- Python 3.12
+
+### 安装步骤
+
+```bash
+git clone https://github.com/trpc-group/trpc-agent-python.git
+cd trpc-agent-python
+python3 -m venv .venv
+source .venv/bin/activate
+pip3 install -e .
+```
+
+### 环境变量要求
+
+在 [examples/websearch_tool/.env](./.env) 中配置（或通过 `export`）：
+
+必填（LLM 凭据）：
+
+- `TRPC_AGENT_API_KEY`
+- `TRPC_AGENT_BASE_URL`
+- `TRPC_AGENT_MODEL_NAME`
+
+可选（Google CSE 场景，未设置时会自动跳过 Google 相关 demo）：
+
+- `GOOGLE_CSE_API_KEY`：从 [Google Cloud Console](https://developers.google.com/custom-search/v1/overview) 申请
+- `GOOGLE_CSE_ENGINE_ID`：在 [Programmable Search Engine](https://programmablesearchengine.google.com/) 创建搜索引擎后得到的 `cx`
+- `HTTPS_PROXY` / `HTTP_PROXY`：可选的出口代理，仅 Google 场景使用
+
+### 运行命令
+
+```bash
+cd examples/websearch_tool
+python3 run_agent.py
+```
+
+## DuckDuckGo 运行结果
+
+```text
+========== DuckDuckGo · plain lookup ==========
+🆔 Session ID: bc8f7289...
+📝 User: Look up the entity 'Python (programming language)' and summarise it in one paragraph. Use count=1.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'Python (programming language)', 'count': 1})]
+📊 [Tool Result: provider=duckduckgo query='Python (programming language)' hits=1 summary='Python is a high-level, general-purpose programming language...' top_titles=[Python (programming language)]]
+Python is a high-level, general-purpose programming language known for its emphasis on code readability, ...
+
+Sources:
+- [Python (programming language)](https://en.wikipedia.org/wiki/Python_(programming_language))
+----------------------------------------
+
+========== DuckDuckGo · allowed_domains whitelist ==========
+🔧 [Invoke Tool: websearch({'query': 'Python (programming language)', 'count': 3, 'allowed_domains': ['wikipedia.org']})]
+📊 [Tool Result: provider=duckduckgo query='Python (programming language)' hits=1 ...]
+...
+
+Sources:
+- [Python (programming language)](https://en.wikipedia.org/wiki/Python_(programming_language))
+----------------------------------------
+
+========== DuckDuckGo · raw multi-source hits ==========
+🔧 [Invoke Tool: websearch({'query': 'Python (programming language)', 'count': 5})]
+📊 [Tool Result: provider=duckduckgo hits=5 top_titles=[Python (programming language), Official site, Python (programming language) Category]]
+...
+
+Sources:
+- [Python (programming language) - Wikipedia](https://en.wikipedia.org/wiki/Python_(programming_language))
+- [Official site](https://www.python.org/)
+- [Python (programming language) Category](https://duckduckgo.com/c/Python_(programming_language))
+- [Pydoc](https://duckduckgo.com/Pydoc)
+- [NumPy](https://duckduckgo.com/NumPy)
+----------------------------------------
+
+========== DuckDuckGo · blocked_domains blacklist ==========
+🔧 [Invoke Tool: websearch({'query': 'Python programming language', 'count': 5, 'blocked_domains': ['duckduckgo.com']})]
+📊 [Tool Result: provider=duckduckgo hits=2 top_titles=[Python (programming language), Official site]]
+...
+
+Sources:
+- [Python (programming language) - Wikipedia](https://en.wikipedia.org/wiki/Python_(programming_language))
+- [Official site - Python.org](https://www.python.org/)
+----------------------------------------
+```
+
+## Google Custom Search 运行结果
+
+```text
+========== Google · plain web search ==========
+🆔 Session ID: 6a63e9a0...
+📝 User: What are the headline features of FastAPI 0.115? Use count=3.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'FastAPI 0.115 headline features', 'count': 3})]
+📊 [Tool Result: provider=google query='FastAPI 0.115 headline features' hits=3 summary='' top_titles=[Features - FastAPI, [BUG] CREW getting stuck on any task as , Configure Swagger UI - FastAPI]]
+The search results did not directly highlight the headline features of FastAPI 0.115. However, FastAPI is known for its high performance, ease of use, and built-in support for OpenAPI and Swagger UI. For specific details about version 0.115, you may need to refer to the official FastAPI documentation or release notes.
+
+Sources:
+- [Features - FastAPI](https://fastapi.tiangolo.com/features/)
+- [GitHub Issue](https://github.com/crewAIInc/crewAI/issues/2997)
+- [Configure Swagger UI - FastAPI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/)
+----------------------------------------
+
+========== Google · allowed_domains single (server-side siteSearch) ==========
+🆔 Session ID: 4aed7a08...
+📝 User: Search for 'Python asyncio tutorial' but only keep results from python.org. Return up to 3 results.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'Python asyncio tutorial', 'allowed_domains': ['python.org'], 'count': 3})]
+📊 [Tool Result: provider=google query='Python asyncio tutorial' hits=3 summary='' top_titles=[A Conceptual Overview of asyncio - Pytho, asyncio — Asynchronous I/O — Python 3.14, Asyncio: Am I doing it wrong? - Python D]]
+Here are the top results for "Python asyncio tutorial" from python.org:
+
+1. **[A Conceptual Overview of asyncio - Python documentation](https://docs.python.org/3/howto/a-conceptual-overview-of-asyncio.html)**  
+   This HOWTO article helps you build a mental model of how asyncio functions, including writing asynchronous variants of operations like sleep or database requests.
+
+2. **[asyncio — Asynchronous I/O — Python 3.14.4 documentation](https://docs.python.org/3/library/asyncio.html)**  
+   The official documentation for the `asyncio` library, which is used to write concurrent code using the `async/await` syntax. It serves as a foundation for many Python asynchronous frameworks.
+
+3. **[Asyncio: Am I doing it wrong? - Python Discussions](https://discuss.python.org/t/asyncio-am-i-doing-it-wrong/5699)**  
+   A discussion thread where users share their experiences and challenges with `asyncio`, including debugging tips and best practices.
+
+Sources:
+- [A Conceptual Overview of asyncio](https://docs.python.org/3/howto/a-conceptual-overview-of-asyncio.html)
+- [asyncio — Asynchronous I/O](https://docs.python.org/3/library/asyncio.html)
+- [Asyncio: Am I doing it wrong?](https://discuss.python.org/t/asyncio-am-i-doing-it-wrong/5699)
+----------------------------------------
+
+========== Google · allowed_domains multi (client-side filter) ==========
+🆔 Session ID: dcf3fa07...
+📝 User: Search for 'pydantic v2 migration guide' and restrict results to docs.pydantic.dev or github.com. Return up to 5 results.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'pydantic v2 migration guide', 'count': 5, 'allowed_domains': ['docs.pydantic.dev', 'github.com']})]
+📊 [Tool Result: provider=google query='pydantic v2 migration guide' hits=1 summary='' top_titles=[Migrating @root_validator(pre=True) pyda]]
+Here is a relevant result for the Pydantic V2 migration guide:
+
+- [Migrating @root_validator(pre=True) pydantic > 2 #9035 - GitHub](https://github.com/pydantic/pydantic/discussions/9035): This discussion provides guidance on migrating from Pydantic V1 to V2, specifically addressing the deprecation of `@root_validator(pre=True)` and suggesting the use of `@model_validator` validators in Pydantic V2.
+
+Sources:
+- [Migrating @root_validator(pre=True) pydantic > 2 #9035 - GitHub](https://github.com/pydantic/pydantic/discussions/9035)
+----------------------------------------
+
+========== Google · blocked_domains blacklist ==========
+🆔 Session ID: 7bf4393c...
+📝 User: Search for 'HTML form tutorial' and exclude any results from w3schools.com. Return up to 3 results.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'HTML form tutorial', 'blocked_domains': ['w3schools.com'], 'count': 3})]
+📊 [Tool Result: provider=google query='HTML form tutorial' hits=3 summary='' top_titles=[Learn HTML forms in 8 minutes - YouTube, Your first form - Learn web development , Learn HTML Forms In 25 Minutes - YouTube]]
+Here are some resources for learning about HTML forms, excluding results from w3schools.com:
+
+1. **[Learn HTML forms in 8 minutes - YouTube](https://www.youtube.com/watch?v=2O8pkybH6po)**  
+   A quick tutorial explaining HTML forms with examples.
+
+2. **[Your first form - Learn web development | MDN](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form)**  
+   A detailed guide from MDN on creating your first HTML form, including form controls and their usage.
+
+3. **[Learn HTML Forms In 25 Minutes - YouTube](https://www.youtube.com/watch?v=fNcJuPIZ2WE)**  
+   A comprehensive tutorial covering HTML forms in under 25 minutes.
+
+Sources:
+- [Learn HTML forms in 8 minutes - YouTube](https://www.youtube.com/watch?v=2O8pkybH6po)
+- [Your first form - Learn web development | MDN](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Your_first_form)
+- [Learn HTML Forms In 25 Minutes - YouTube](https://www.youtube.com/watch?v=fNcJuPIZ2WE)
+----------------------------------------
+
+========== Google · per-call lang override (zh-CN) ==========
+🆔 Session ID: 36882630...
+📝 User: Search for 'FastAPI 入门教程' in Chinese (pass lang='zh-CN'). Return up to 3 results.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'FastAPI 入门教程', 'count': 3, 'lang': 'zh-CN'})]
+📊 [Tool Result: provider=google query='FastAPI 入门教程' hits=3 summary='' top_titles=[教程- 用户指南 - FastAPI, FastAPI 教程| 菜鸟教程, 整体的介绍FastAPI，快速上手开发，结合API 交互文档逐个讲解核心 ...]]
+以下是关于“FastAPI 入门教程”的中文搜索结果：
+
+1. **[教程- 用户指南 - FastAPI](https://fastapi.tiangolo.com/zh/tutorial/)**  
+   所有代码片段都可以复制后直接使用（它们实际上是经过测试的Python 文件）。要运行任何示例，请将代码复制到 `main.py` 文件中，然后启动 `fastapi dev`。
+
+2. **[FastAPI 教程| 菜鸟教程](https://www.runoob.com/fastapi/fastapi-tutorial.html)**  
+   FastAPI 是一个用于构建API 的现代、快速（高性能）的Python Web 框架，专为构建RESTful API 而设计。FastAPI 使用Python 3.8+ 并基于标准的Python 类型提示。
+
+3. **[整体的介绍FastAPI，快速上手开发](https://github.com/liaogx/fastapi-tutorial)**  
+   整体的介绍 FastAPI，快速上手开发，结合 API 交互文档逐个讲解核心模块的使用。视频学习地址： - liaogx/fastapi-tutorial。
+
+Sources:
+- [教程- 用户指南 - FastAPI](https://fastapi.tiangolo.com/zh/tutorial/)
+- [FastAPI 教程| 菜鸟教程](https://www.runoob.com/fastapi/fastapi-tutorial.html)
+- [整体的介绍FastAPI，快速上手开发](https://github.com/liaogx/fastapi-tutorial)
+----------------------------------------
+
+========== Google · raw hits with 6-month recency bias ==========
+🆔 Session ID: 25fdbf2d...
+📝 User: What are the latest Python 3.13 release highlights this year? Return up to 5 results.
+🤖 Assistant: 
+🔧 [Invoke Tool: websearch({'query': 'Python 3.13 release highlights 2026', 'count': 5})]
+📊 [Tool Result: provider=google query='Python 3.13 release highlights 2026' hits=5 summary='' top_titles=[Python Version in Production - Reddit, Migrating scripts to Python 3.13 in Work, Latest Python upgrade (3.13 -> 3.14) on ]]
+Here are some highlights related to Python 3.13 in 2026:
+
+1. **Reddit Discussion**: Users on Reddit discuss the adoption of Python 3.13 in production environments, noting its stability and reviewing its release notes. [Read more](https://www.reddit.com/r/Python/comments/1qgt083/python_version_in_production/)
+
+2. **Workiva Support**: Workiva has introduced support for Python 3.13, providing guidance on migrating scripts from older versions like Python 3.9. Full release notes are referenced on Python.org. [Read more](https://support.workiva.com/hc/en-us/articles/40603516229780-Migrating-scripts-to-Python-3-13-in-Workiva)
+
+3. **Anaconda Distribution**: Anaconda's release notes mention Python 3.13.9, along with updates to Conda and other user-facing changes. [Read more](https://www.anaconda.com/docs/getting-started/anaconda/release-notes)
+
+4. **UiPath Documentation**: UiPath's Python activities package now supports Python 3.13, with new features and improvements introduced in March 2026. [Read more](https://docs.uipath.com/activities/other/latest/developer/release-notes-python-activities)
+
+For the most detailed and official release highlights, it's recommended to check Python.org's "What's New in Python 3.13" section.
+
+Sources:
+- [Python Version in Production - Reddit](https://www.reddit.com/r/Python/comments/1qgt083/python_version_in_production/)
+- [Migrating scripts to Python 3.13 in Workiva - Support Center](https://support.workiva.com/hc/en-us/articles/40603516229780-Migrating-scripts-to-Python-3-13-in-Workiva)
+- [Anaconda Distribution release notes](https://www.anaconda.com/docs/getting-started/anaconda/release-notes)
+- [Activities - Release notes - UiPath Documentation](https://docs.uipath.com/activities/other/latest/developer/release-notes-python-activities)
+----------------------------------------
+```
+
+## 适用场景建议
+
+- 需要 LLM 引用 **可追溯 URL** 回答事实/定义类信息：适合直接复用本示例 `WebSearchTool` + 提示词约定
+- 仅需 **无 API Key、轻量定义类检索**：使用 `provider="duckduckgo"`（默认）即可
+- 需要 **真实公网搜索、支持 site/语言/SafeSearch/时效性**：使用 `provider="google"`，并把 provider 专属的高级参数固化在 `google_extra_params` 中
+- 需要在工具调用前后插入日志、审计、参数校验：参考 [examples/filter_with_tool](../filter_with_tool)，把 `WebSearchTool(filters_name=[...])` 与 `before_tool_callback` / `after_tool_callback` 组合使用
+- 需要把搜索结果接入 RAG 流程：参考 [examples/knowledge_with_searchtool_rag_agent](../knowledge_with_searchtool_rag_agent)
diff --git a/examples/websearch_tool/agent/__init__.py b/examples/websearch_tool/agent/__init__.py
new file mode 100644
index 0000000..bc6e483
--- /dev/null
+++ b/examples/websearch_tool/agent/__init__.py
@@ -0,0 +1,5 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
diff --git a/examples/websearch_tool/agent/agent.py b/examples/websearch_tool/agent/agent.py
new file mode 100644
index 0000000..0cecd64
--- /dev/null
+++ b/examples/websearch_tool/agent/agent.py
@@ -0,0 +1,149 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" Agent module for WebSearchTool"""
+
+import httpx
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import LLMModel
+from trpc_agent_sdk.models import OpenAIModel
+from trpc_agent_sdk.tools import WebSearchTool
+
+from .config import get_google_cse_config
+from .config import get_http_proxy
+from .config import get_model_config
+from .prompts import GOOGLE_INSTRUCTION
+from .prompts import INSTRUCTION
+
+
+def _create_model() -> LLMModel:
+    """Create the LLM model used by every demo agent."""
+    api_key, url, model_name = get_model_config()
+    return OpenAIModel(model_name=model_name, api_key=api_key, base_url=url)
+
+
+def create_ddg_agent() -> LlmAgent:
+    """Build an agent backed by the keyless DuckDuckGo provider.
+    """
+    web_search = WebSearchTool(
+        provider="duckduckgo",
+        results_num=3,
+        snippet_len=300,
+        title_len=80,
+        timeout=10.0,
+    )
+    return LlmAgent(
+        name="ddg_research_assistant",
+        description="Web research assistant powered by DuckDuckGo Instant Answers.",
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_search],
+    )
+
+
+def create_ddg_raw_agent() -> LlmAgent:
+    """Build a DDG-backed agent that disables URL deduplication.
+    """
+    web_search = WebSearchTool(
+        provider="duckduckgo",
+        results_num=5,
+        snippet_len=300,
+        title_len=80,
+        timeout=10.0,
+        dedup_urls=False,
+    )
+    return LlmAgent(
+        name="ddg_raw_research_assistant",
+        description=("Web research assistant powered by DuckDuckGo Instant Answers "
+                     "with URL deduplication disabled (raw provider hits)."),
+        model=_create_model(),
+        instruction=INSTRUCTION,
+        tools=[web_search],
+    )
+
+
+_GOOGLE_HTTP_CLIENT: httpx.AsyncClient | None = None
+
+
+def _get_shared_google_http_client() -> httpx.AsyncClient:
+    """Lazily build (and remember) the shared httpx.AsyncClient."""
+    global _GOOGLE_HTTP_CLIENT
+    if _GOOGLE_HTTP_CLIENT is None:
+        _GOOGLE_HTTP_CLIENT = httpx.AsyncClient(
+            timeout=15.0,
+            limits=httpx.Limits(max_connections=16, max_keepalive_connections=8),
+        )
+    return _GOOGLE_HTTP_CLIENT
+
+
+async def aclose_shared_google_http_client() -> None:
+    """Close the shared httpx.AsyncClient, if one was created.
+    """
+    global _GOOGLE_HTTP_CLIENT
+    if _GOOGLE_HTTP_CLIENT is not None:
+        await _GOOGLE_HTTP_CLIENT.aclose()
+        _GOOGLE_HTTP_CLIENT = None
+
+
+def create_google_agent() -> LlmAgent:
+    """Build an agent backed by Google Custom Search (real web search)."""
+    api_key, engine_id = get_google_cse_config()
+    web_search = WebSearchTool(
+        provider="google",
+        api_key=api_key,
+        engine_id=engine_id,
+        user_agent="trpc-agent-python-websearch-demo/1.0 (+google-cse)",
+        proxy=get_http_proxy(),
+        lang="en",
+        http_client=_get_shared_google_http_client(),
+        results_num=3,
+        snippet_len=240,
+        title_len=80,
+        timeout=15.0,
+        dedup_urls=True,
+        google_extra_params={"safe": "active"},
+    )
+    return LlmAgent(
+        name="google_research_assistant",
+        description="Web research assistant powered by Google Custom Search (SafeSearch on).",
+        model=_create_model(),
+        instruction=GOOGLE_INSTRUCTION,
+        tools=[web_search],
+    )
+
+
+def create_google_raw_agent() -> LlmAgent:
+    """Build a recency-biased Google agent that disables URL dedup."""
+    api_key, engine_id = get_google_cse_config()
+    web_search = WebSearchTool(
+        provider="google",
+        api_key=api_key,
+        engine_id=engine_id,
+        user_agent="trpc-agent-python-websearch-demo/1.0 (+google-cse-raw)",
+        proxy=get_http_proxy(),
+        lang="en",
+        http_client=_get_shared_google_http_client(),
+        results_num=5,
+        snippet_len=320,
+        title_len=100,
+        timeout=20.0,
+        dedup_urls=False,
+        google_extra_params={"dateRestrict": "m6"},
+    )
+    return LlmAgent(
+        name="google_raw_research_assistant",
+        description=("Web research assistant powered by Google Custom Search "
+                     "with URL deduplication disabled and a 6-month recency bias."),
+        model=_create_model(),
+        instruction=GOOGLE_INSTRUCTION,
+        tools=[web_search],
+    )
+
+
+ddg_agent = create_ddg_agent()
+ddg_raw_agent = create_ddg_raw_agent()
+google_agent = create_google_agent()
+google_raw_agent = create_google_raw_agent()
+root_agent = ddg_agent
diff --git a/examples/websearch_tool/agent/config.py b/examples/websearch_tool/agent/config.py
new file mode 100644
index 0000000..7a894db
--- /dev/null
+++ b/examples/websearch_tool/agent/config.py
@@ -0,0 +1,33 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" Agent config module"""
+
+import os
+
+
+def get_model_config() -> tuple[str, str, str]:
+    """Get LLM model config from environment variables."""
+    api_key = os.getenv('TRPC_AGENT_API_KEY', '')
+    url = os.getenv('TRPC_AGENT_BASE_URL', '')
+    model_name = os.getenv('TRPC_AGENT_MODEL_NAME', '')
+    if not api_key or not url or not model_name:
+        raise ValueError('''TRPC_AGENT_API_KEY, TRPC_AGENT_BASE_URL,
+                         and TRPC_AGENT_MODEL_NAME must be set in environment variables''')
+    return api_key, url, model_name
+
+
+def get_google_cse_config() -> tuple[str, str]:
+    """Get Google Custom Search credentials from environment variables.
+    """
+    api_key = os.getenv('GOOGLE_CSE_API_KEY', '')
+    engine_id = os.getenv('GOOGLE_CSE_ENGINE_ID', '')
+    return api_key, engine_id
+
+
+def get_http_proxy() -> str | None:
+    """Return the outbound HTTP proxy URL, if any.
+    """
+    return os.getenv('HTTPS_PROXY') or os.getenv('HTTP_PROXY') or None
diff --git a/examples/websearch_tool/agent/prompts.py b/examples/websearch_tool/agent/prompts.py
new file mode 100644
index 0000000..c38b609
--- /dev/null
+++ b/examples/websearch_tool/agent/prompts.py
@@ -0,0 +1,46 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+""" prompts for agent"""
+
+INSTRUCTION = ("You are a research assistant that answers user questions using the `websearch` tool.\n"
+               "\n"
+               "Workflow:\n"
+               "  1. If the user asks a factual / current-event / definition question, call `websearch` ONCE.\n"
+               "  2. For definition / encyclopedia lookups, prefer a short entity-style `query` such as\n"
+               "     `Python (programming language)` over a full natural-language question, and do NOT\n"
+               "     append the current year — DuckDuckGo's Instant Answer API matches entity names, not\n"
+               "     free-form questions.\n"
+               "  3. Use the returned `summary` and `results[*].snippet` to compose your answer.\n"
+               "  4. Honour any explicit user constraints about preferred or excluded sites by passing\n"
+               "     `allowed_domains` (whitelist) or `blocked_domains` (blacklist) on the tool call.\n"
+               "     The two are mutually exclusive — pick the one that matches the user's wording.\n"
+               "  5. After answering, append a `Sources:` section listing the cited URLs as markdown links.\n"
+               "  6. If the tool returned an error (e.g. `INVALID_ARGS`), explain the failure briefly\n"
+               "     instead of guessing the answer.")
+
+GOOGLE_INSTRUCTION = ("You are a research assistant that answers user questions using the `websearch` tool,\n"
+                      "which is backed by Google Custom Search in this configuration.\n"
+                      "\n"
+                      "Workflow:\n"
+                      "  1. Call `websearch` ONCE per user question, with a concise keyword query — Google\n"
+                      "     handles natural phrases, so you can use 'FastAPI websocket authentication' or\n"
+                      "     'Python 3.13 release notes' rather than entity-style lookups.\n"
+                      "  2. For time-sensitive questions (releases, news, prices, versions) include the\n"
+                      "     current year in the query string.\n"
+                      "  3. Use `results[*].title` and `results[*].snippet` to compose the answer. The Google\n"
+                      "     backend does NOT return an instant-answer `summary`, so always ground the reply\n"
+                      "     in the per-result snippets.\n"
+                      "  4. Honour any explicit user constraints about preferred or excluded sites by passing\n"
+                      "     `allowed_domains` (whitelist) or `blocked_domains` (blacklist) on the tool call.\n"
+                      "     The two are mutually exclusive. A single domain is fastest because Google CSE\n"
+                      "     applies it server-side via `siteSearch`; multiple domains are enforced\n"
+                      "     client-side after the provider returns.\n"
+                      "  5. When the user asks for the answer in a specific language (e.g. Chinese), pass\n"
+                      "     the corresponding BCP-47 code via the `lang` parameter ('zh-CN', 'ja', 'en').\n"
+                      "  6. After answering, append a `Sources:` section listing the cited URLs as markdown\n"
+                      "     links — never invent URLs, only cite what the tool returned.\n"
+                      "  7. If the tool returned an error (e.g. `INVALID_ARGS` or missing credentials),\n"
+                      "     explain the failure briefly instead of guessing the answer.")
diff --git a/examples/websearch_tool/run_agent.py b/examples/websearch_tool/run_agent.py
new file mode 100644
index 0000000..c762265
--- /dev/null
+++ b/examples/websearch_tool/run_agent.py
@@ -0,0 +1,245 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Demo entry point for the WebSearchTool example.
+
+The script drives several agents back-to-back so a single ``python3
+run_agent.py`` invocation exercises the most common ``WebSearchTool``
+features across both supported providers.
+
+DuckDuckGo scenarios (keyless, Instant Answer API):
+
+1. Plain definition / encyclopedia lookup using an entity-style query.
+2. ``allowed_domains`` (whitelist) via prompt — only Wikipedia
+   sources are kept.
+3. ``dedup_urls=False`` raw multi-source hits, including DDG's internal
+   ``duckduckgo.com/c/...`` category pages. Serves as the *baseline*
+   for scenario 4.
+4. ``blocked_domains`` (blacklist) via prompt, using the **same query
+   as scenario 3** so the filtering effect is visible by direct
+   comparison (``duckduckgo.com/...`` hits disappear).
+
+Google Custom Search scenarios (API key + engine id required):
+
+5. Plain Google CSE lookup with the baseline ``google_agent`` (shared
+   ``http_client``, default ``lang="en"``, ``safe="active"`` via
+   ``google_extra_params``).
+6. ``allowed_domains`` with a single domain — exercises CSE's
+   server-side ``siteSearch`` fast path.
+7. ``allowed_domains`` with multiple domains — falls back to the
+   tool's client-side filter (CSE only supports one ``siteSearch``).
+8. ``blocked_domains`` on a broad query.
+9. Per-call ``lang`` override — Chinese results via ``lang='zh-CN'``.
+10. ``google_raw_agent`` — ``dedup_urls=False`` with a six-month
+    recency bias, useful for surfacing recently indexed documentation.
+
+Each scenario uses a fresh session so the agents do not lean on prior
+context — this makes the tool-call flow easy to read in the output.
+
+Google scenarios short-circuit with a friendly "provider not
+configured" summary when ``GOOGLE_CSE_API_KEY`` / ``GOOGLE_CSE_ENGINE_ID``
+are not set, so the DuckDuckGo half of the demo still runs end-to-end
+on a fresh checkout without extra setup.
+"""
+
+import asyncio
+import os
+import uuid
+
+from dotenv import load_dotenv
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content
+from trpc_agent_sdk.types import Part
+
+load_dotenv()
+
+APP_NAME = "websearch_agent_demo"
+USER_ID = "demo_user"
+
+
+async def _run_one_query(runner: Runner, *, label: str, query: str) -> None:
+    """Drive a single user query through ``runner`` and pretty-print events."""
+    session_id = str(uuid.uuid4())
+    await runner.session_service.create_session(
+        app_name=APP_NAME,
+        user_id=USER_ID,
+        session_id=session_id,
+        state={"user_name": USER_ID},
+    )
+
+    print(f"\n========== {label} ==========")
+    print(f"🆔 Session ID: {session_id[:8]}...")
+    print(f"📝 User: {query}")
+    print("🤖 Assistant: ", end="", flush=True)
+
+    user_content = Content(parts=[Part.from_text(text=query)])
+    async for event in runner.run_async(
+            user_id=USER_ID,
+            session_id=session_id,
+            new_message=user_content,
+    ):
+        if not event.content or not event.content.parts:
+            continue
+
+        if event.partial:
+            for part in event.content.parts:
+                if part.text:
+                    print(part.text, end="", flush=True)
+            continue
+
+        for part in event.content.parts:
+            if part.thought:
+                continue
+            if part.function_call:
+                print(f"\n🔧 [Invoke Tool: {part.function_call.name}({part.function_call.args})]")
+            elif part.function_response:
+                resp = part.function_response.response
+                preview = _summarise_tool_response(resp)
+                print(f"📊 [Tool Result: {preview}]")
+
+    print("\n" + "-" * 40)
+
+
+def _summarise_tool_response(resp) -> str:
+    """Compact a ``WebSearchResult`` dict so the demo output stays readable."""
+    if not isinstance(resp, dict):
+        return str(resp)
+    if "error" in resp:
+        return f"error={resp.get('error')!r} provider={resp.get('provider')!r}"
+    provider = resp.get("provider")
+    query = resp.get("query")
+    results = resp.get("results") or []
+    summary = (resp.get("summary") or "").strip().replace("\n", " ")
+    if len(summary) > 120:
+        summary = summary[:117] + "..."
+    title_preview = ", ".join(((r.get("title") or "")[:40] for r in results[:3]))
+    return (f"provider={provider} query={query!r} hits={len(results)} "
+            f"summary={summary!r} top_titles=[{title_preview}]")
+
+
+async def _drive_agent(agent: LlmAgent, *, scenarios: list[tuple[str, str]]) -> None:
+    """Spin up a ``Runner`` for ``agent`` and run each ``(label, query)`` pair."""
+    runner = Runner(
+        app_name=APP_NAME,
+        agent=agent,
+        session_service=InMemorySessionService(),
+    )
+    for label, query in scenarios:
+        await _run_one_query(runner, label=label, query=query)
+
+
+def _google_credentials_configured() -> bool:
+    """Return ``True`` when both GOOGLE_CSE_* env vars are non-empty."""
+    return bool(os.getenv("GOOGLE_CSE_API_KEY") and os.getenv("GOOGLE_CSE_ENGINE_ID"))
+
+
+async def _run_duckduckgo_scenarios(ddg_agent: LlmAgent, ddg_raw_agent: LlmAgent) -> None:
+    """Drive the keyless DuckDuckGo scenarios."""
+    ddg_scenarios_pre_raw = [
+        (
+            "DuckDuckGo · plain lookup",
+            "Look up the entity 'Python (programming language)' and summarise it in "
+            "one paragraph. Use count=1.",
+        ),
+        (
+            "DuckDuckGo · allowed_domains whitelist",
+            "Look up 'Python (programming language)' but only keep results from "
+            "wikipedia.org. Return up to 3 results.",
+        ),
+    ]
+    await _drive_agent(ddg_agent, scenarios=ddg_scenarios_pre_raw)
+
+    ddg_raw_scenarios = [
+        (
+            "DuckDuckGo · raw multi-source hits",
+            "Search for 'Python programming language' and return up to 5 results.",
+        ),
+    ]
+    await _drive_agent(ddg_raw_agent, scenarios=ddg_raw_scenarios)
+
+    ddg_blocked_scenarios = [
+        (
+            "DuckDuckGo · blocked_domains blacklist",
+            "Search for 'Python programming language' and exclude any results from "
+            "duckduckgo.com. Return up to 5 results.",
+        ),
+    ]
+    await _drive_agent(ddg_agent, scenarios=ddg_blocked_scenarios)
+
+
+async def _run_google_scenarios(google_agent: LlmAgent, google_raw_agent: LlmAgent) -> None:
+    """Drive the Google Custom Search scenarios.
+
+    The scenarios intentionally exercise every surface of the Google
+    code path in ``WebSearchTool._search_google``:
+
+    - server-side ``siteSearch=i`` (single-domain allowed_domains)
+    - client-side post-hoc filter (multi-domain allowed_domains)
+    - server-side ``siteSearch=e`` (blocked_domains)
+    - per-call ``lang`` override (Google CSE ``hl`` parameter)
+    - ``google_extra_params`` on ``google_raw_agent``
+      (``dateRestrict=m6`` for recency)
+    """
+    google_scenarios = [
+        (
+            "Google · plain web search",
+            "What are the headline features of FastAPI 0.115? Use count=3.",
+        ),
+        (
+            "Google · allowed_domains single (server-side siteSearch)",
+            "Search for 'Python asyncio tutorial' but only keep results from "
+            "python.org. Return up to 3 results.",
+        ),
+        (
+            "Google · allowed_domains multi (client-side filter)",
+            "Search for 'pydantic v2 migration guide' and restrict results to "
+            "docs.pydantic.dev or github.com. Return up to 5 results.",
+        ),
+        (
+            "Google · blocked_domains blacklist",
+            "Search for 'HTML form tutorial' and exclude any results from "
+            "w3schools.com. Return up to 3 results.",
+        ),
+        (
+            "Google · per-call lang override (zh-CN)",
+            "Search for 'FastAPI 入门教程' in Chinese (pass lang='zh-CN'). "
+            "Return up to 3 results.",
+        ),
+    ]
+    await _drive_agent(google_agent, scenarios=google_scenarios)
+
+    google_raw_scenarios = [
+        (
+            "Google · raw hits with 6-month recency bias",
+            "What are the latest Python 3.13 release highlights this year? "
+            "Return up to 5 results.",
+        ),
+    ]
+    await _drive_agent(google_raw_agent, scenarios=google_raw_scenarios)
+
+
+async def main() -> None:
+    from agent.agent import aclose_shared_google_http_client
+    from agent.agent import ddg_agent
+    from agent.agent import ddg_raw_agent
+    from agent.agent import google_agent
+    from agent.agent import google_raw_agent
+
+    await _run_duckduckgo_scenarios(ddg_agent, ddg_raw_agent)
+
+    if _google_credentials_configured():
+        try:
+            await _run_google_scenarios(google_agent, google_raw_agent)
+        finally:
+            await aclose_shared_google_http_client()
+    else:
+        print("\n[skip] Google scenarios skipped: set GOOGLE_CSE_API_KEY and "
+              "GOOGLE_CSE_ENGINE_ID in the environment (see .env) to enable them.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/pyproject.toml b/pyproject.toml
index 2cc41b9..5fea878 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -53,6 +53,7 @@ dependencies = [
     "charset-normalizer>=3.0.0",
     "typer>=0.12.0", # MIT License
     "watchdog",
+    "markdownify>=1.2.0", # MIT License
 ]
 
 [project.optional-dependencies]
diff --git a/tests/tools/test_websearch_tool.py b/tests/tools/test_websearch_tool.py
new file mode 100644
index 0000000..518fa2a
--- /dev/null
+++ b/tests/tools/test_websearch_tool.py
@@ -0,0 +1,1191 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Tests for :mod:`trpc_agent_sdk.tools._websearch_tool`.
+
+Covers the full BaseTool surface area:
+- ``SearchHit`` / ``WebSearchResult`` schemas
+- Constructor validation and provider dispatch
+- ``_get_declaration`` parameter shape
+- Input validation (missing query, short query, mutually exclusive
+  ``allowed_domains`` / ``blocked_domains``)
+- DuckDuckGo Instant Answer path (summary aggregation, related topics,
+  fallback result, post-hoc domain filtering)
+- Google CSE path (items, pagemap metatag enrichment, spell-corrected
+  effective query, server-side domain filter parameters, API error,
+  missing credentials)
+- HTTP errors surfacing as structured tool errors
+- ``process_request`` registering the declaration and appending the
+  "current month / Sources" system instruction
+- Internal helpers (``_truncate``, ``_extract_domain_from_url``, ``_is_blocked``,
+  ``_extract_title_from_ddg_topic``, ``_extract_desc_from_pagemap``)
+- Module-level singleton + auto-registration with ``ToolRegistry``
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from typing import Dict
+from unittest.mock import MagicMock
+
+import httpx
+import pytest
+
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.models import LlmRequest
+from trpc_agent_sdk.tools._websearch_tool import SearchHit
+from trpc_agent_sdk.tools._websearch_tool import WebSearchResult
+from trpc_agent_sdk.tools._websearch_tool import WebSearchTool
+from trpc_agent_sdk.tools._websearch_tool import _current_month_year
+from trpc_agent_sdk.tools._websearch_tool import _dedup_key
+from trpc_agent_sdk.tools._websearch_tool import _extract_domain_from_url
+from trpc_agent_sdk.tools._websearch_tool import _extract_desc_from_pagemap
+from trpc_agent_sdk.tools._websearch_tool import _extract_title_from_ddg_topic
+from trpc_agent_sdk.tools._websearch_tool import _is_blocked
+from trpc_agent_sdk.tools._websearch_tool import _truncate
+from trpc_agent_sdk.types import FunctionDeclaration
+from trpc_agent_sdk.types import Type
+
+# Tool name is hard-coded inside WebSearchTool.__init__; tests compare by
+# literal to catch accidental rename regressions.
+_TOOL_NAME = "websearch"
+
+
+def _make_mock_client(responses: Dict[str, Dict[str, Any]], *, status: int = 200) -> httpx.AsyncClient:
+    """Build an ``httpx.AsyncClient`` backed by ``MockTransport``.
+
+    ``responses`` maps request URL path (e.g. ``"/"``) to a JSON body.
+    All non-matching paths return 404 so test misses surface loudly.
+    The returned client captures the last request for assertions via
+    ``client._last_request``.
+    """
+
+    captured = {"last_request": None, "all_requests": []}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["last_request"] = request
+        captured["all_requests"].append(request)
+        body = responses.get(request.url.path)
+        if body is None:
+            return httpx.Response(404, json={"error": "no mock for path"})
+        return httpx.Response(status, json=body)
+
+    transport = httpx.MockTransport(handler)
+    client = httpx.AsyncClient(transport=transport)
+    # Stash captures on the client so tests can introspect them.
+    client._captured = captured  # type: ignore[attr-defined]
+    return client
+
+
+def _tool_ctx() -> InvocationContext:
+    """Return a minimal fake ``InvocationContext`` — our tool does not touch it."""
+    return MagicMock(spec=InvocationContext)
+
+
+class TestSearchHitSchema:
+
+    def test_defaults(self):
+        hit = SearchHit()
+        assert hit.title == ""
+        assert hit.url == ""
+        assert hit.snippet == ""
+
+    def test_roundtrip(self):
+        hit = SearchHit(title="T", url="https://x", snippet="S")
+        restored = SearchHit.model_validate(hit.model_dump())
+        assert restored == hit
+
+
+class TestWebSearchResultSchema:
+
+    def test_defaults(self):
+        r = WebSearchResult(query="q", provider="duckduckgo")
+        assert r.results == []
+        assert r.summary == ""
+
+    def test_model_dump_is_json_serialisable(self):
+        r = WebSearchResult(query="q", provider="google", results=[SearchHit(title="t", url="u")])
+        as_json = json.dumps(r.model_dump(), ensure_ascii=False)
+        parsed = json.loads(as_json)
+        assert parsed["provider"] == "google"
+        assert parsed["results"][0]["title"] == "t"
+
+
+class TestWebSearchToolInit:
+
+    def test_default_is_duckduckgo(self):
+        t = WebSearchTool()
+        assert t.name == _TOOL_NAME
+        assert t._provider == "duckduckgo"
+
+    def test_invalid_provider_accepted_by_construction(self):
+        # Provider validity is enforced only by the Literal type hint at
+        # static-analysis time; construction itself does not raise.
+        # Runtime dispatch falls into the Google branch, which returns a
+        # helpful error rather than crashing.
+        t = WebSearchTool(provider="bing")  # type: ignore[arg-type]
+        assert t._provider == "bing"
+
+    def test_google_without_creds_warns_not_raises(self, caplog):
+        # Capture warnings from the tool's logger.
+        caplog.set_level("WARNING")
+        t = WebSearchTool(provider="google", api_key="", engine_id="")
+        assert t._provider == "google"
+
+    def test_results_num_clamped(self):
+        from trpc_agent_sdk.tools._websearch_tool import _MAX_COUNT
+        # Above the cap → clamped to _MAX_COUNT.
+        assert WebSearchTool(results_num=_MAX_COUNT + 50)._results_num == _MAX_COUNT
+        # Below 1 → clamped up to 1.
+        assert WebSearchTool(results_num=0)._results_num == 1
+
+
+class TestGetDeclaration:
+
+    def test_declaration_shape(self):
+        decl = WebSearchTool()._get_declaration()
+        assert isinstance(decl, FunctionDeclaration)
+        assert decl.name == _TOOL_NAME
+        props = decl.parameters.properties
+        assert set(props.keys()) == {
+            "query",
+            "count",
+            "allowed_domains",
+            "blocked_domains",
+            "lang",
+        }
+        assert decl.parameters.required == ["query"]
+        # Arrays use nested schema items.
+        assert props["allowed_domains"].type == Type.ARRAY
+        assert props["allowed_domains"].items is not None
+
+
+class TestInputValidation:
+
+    @pytest.mark.asyncio
+    async def test_empty_query_errors(self):
+        res = await WebSearchTool()._run_async_impl(tool_context=_tool_ctx(), args={})
+        assert "error" in res
+        assert "INVALID_QUERY" in res["error"]
+
+    @pytest.mark.asyncio
+    async def test_short_query_errors(self):
+        res = await WebSearchTool()._run_async_impl(tool_context=_tool_ctx(), args={"query": "a"})
+        assert "INVALID_QUERY" in res["error"]
+
+    @pytest.mark.asyncio
+    async def test_conflicting_domains_errors(self):
+        res = await WebSearchTool()._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "allowed_domains": ["a.com"],
+                "blocked_domains": ["b.com"],
+            },
+        )
+        assert "INVALID_ARGS" in res["error"]
+
+    @pytest.mark.asyncio
+    async def test_all_empty_allowed_domains_errors(self):
+        """Caller passing an allowlist of only empty strings used to silently
+        drop every result via the fail-closed allowlist branch — we now
+        surface INVALID_ARGS so the LLM can recover.
+        """
+        res = await WebSearchTool()._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "allowed_domains": ["", "  "],
+            },
+        )
+        assert "INVALID_ARGS" in res["error"]
+        assert "allowed_domains" in res["error"]
+
+    @pytest.mark.asyncio
+    async def test_all_empty_blocked_domains_errors(self):
+        res = await WebSearchTool()._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "blocked_domains": ["", "  "],
+            },
+        )
+        assert "INVALID_ARGS" in res["error"]
+        assert "blocked_domains" in res["error"]
+
+    @pytest.mark.asyncio
+    async def test_partial_empty_domains_are_silently_trimmed(self):
+        """Mixed list ``["python.org", ""]`` should still work — empties
+        are trimmed and the request proceeds with the meaningful entry.
+        """
+        client = _make_mock_client({"/": _MIN_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "allowed_domains": ["python.org", "", "  "],
+            },
+        )
+        assert "error" not in res
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_non_list_domains_errors(self):
+        for key in ("allowed_domains", "blocked_domains"):
+            res = await WebSearchTool()._run_async_impl(
+                tool_context=_tool_ctx(),
+                args={
+                    "query": "python",
+                    key: "python.org",
+                },
+            )
+            assert "INVALID_ARGS" in res["error"]
+            assert key in res["error"]
+
+    @pytest.mark.asyncio
+    async def test_non_string_domain_items_error(self):
+        """Non-string items in a domain list must produce a structured
+        ``INVALID_ARGS`` instead of crashing the tool with ``AttributeError``
+        from the internal ``.strip()`` call.
+        """
+        for key in ("allowed_domains", "blocked_domains"):
+            for bad_value in ([123, "python.org"], [{"d": "x"}], [None]):
+                res = await WebSearchTool()._run_async_impl(
+                    tool_context=_tool_ctx(),
+                    args={
+                        "query": "python",
+                        key: bad_value,
+                    },
+                )
+                assert "INVALID_ARGS" in res["error"], (key, bad_value, res)
+                assert key in res["error"], (key, bad_value, res)
+
+    @pytest.mark.asyncio
+    async def test_count_clamped(self):
+        """Invalid ``count`` strings must not crash the tool."""
+
+        client = _make_mock_client({"/": _MIN_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "count": "not-a-number"
+            },
+        )
+        # Count fallback should succeed (not error).
+        assert "error" not in res
+        await client.aclose()
+
+
+_MIN_DDG_RESPONSE: Dict[str, Any] = {
+    "Answer": "",
+    "AbstractText": "",
+    "Definition": "",
+    "RelatedTopics": [],
+}
+
+_FULL_DDG_RESPONSE: Dict[str, Any] = {
+    "Answer":
+    "Python is a programming language.",
+    "AbstractText":
+    "Python is an interpreted, high-level language.",
+    "AbstractSource":
+    "Wikipedia",
+    "Definition":
+    "A general-purpose programming language.",
+    "DefinitionSource":
+    "MerriamWebster",
+    "RelatedTopics": [
+        {
+            "Text": "Python (programming language) - A popular language used everywhere",
+            "FirstURL": "https://duckduckgo.com/Python",
+        },
+        # Nested group — should get flattened.
+        {
+            "Topics": [{
+                "Text": "CPython - Reference implementation",
+                "FirstURL": "https://docs.python.org/cpython",
+            }],
+        },
+        # Entry with no URL — must be skipped.
+        {
+            "Text": "No URL here",
+            "FirstURL": "",
+        },
+    ],
+}
+
+
+class TestDuckDuckGoProvider:
+
+    @pytest.mark.asyncio
+    async def test_happy_path(self):
+        client = _make_mock_client({"/": _FULL_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={"query": "python"},
+        )
+        assert res["provider"] == "duckduckgo"
+        assert res["query"] == "python"
+        # Summary pulls in Answer + Abstract(+source) + Definition(+source).
+        assert "Python is a programming language." in res["summary"]
+        assert "Wikipedia" in res["summary"]
+        assert "MerriamWebster" in res["summary"]
+        # Two valid hits (one top-level, one flattened from nested Topics).
+        urls = [h["url"] for h in res["results"]]
+        assert "https://duckduckgo.com/Python" in urls
+        assert "https://docs.python.org/cpython" in urls
+        # Title is split on " - ".
+        titles = [h["title"] for h in res["results"]]
+        assert any(t.startswith("Python (programming language)") for t in titles)
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_fallback_when_no_topics_but_summary(self):
+        body = {
+            "Answer": "42",
+            "AbstractText": "",
+            "Definition": "",
+            "RelatedTopics": [],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "life"})
+        assert len(res["results"]) == 1
+        assert res["results"][0]["url"].startswith("https://duckduckgo.com/?q=")
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_empty_response_no_hits_no_summary(self):
+        client = _make_mock_client({"/": _MIN_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "xyz"})
+        assert res["results"] == []
+        assert res["summary"] == ""
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_client_side_domain_filtering(self):
+        client = _make_mock_client({"/": _FULL_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client)
+        # Block python.org → docs.python.org should disappear; only ddg hit survives.
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "blocked_domains": ["python.org"],
+            },
+        )
+        urls = [h["url"] for h in res["results"]]
+        assert "https://docs.python.org/cpython" not in urls
+        assert "https://duckduckgo.com/Python" in urls
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_count_limits_hits(self):
+        client = _make_mock_client({"/": _FULL_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client, results_num=1)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        assert len(res["results"]) == 1
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_results_are_deduplicated_by_url(self):
+        """DDG often returns the same URL twice (top-level + nested
+        ``Topics``); the tool must keep only the first occurrence so the
+        LLM doesn't waste tokens citing the same source twice.
+        """
+        body = {
+            "Answer":
+            "",
+            "AbstractText":
+            "",
+            "Definition":
+            "",
+            "RelatedTopics": [
+                {
+                    "Text": "Python (programming language) - first occurrence",
+                    "FirstURL": "https://docs.python.org/3/",
+                },
+                {
+                    "Topics": [
+                        # Same URL with trailing slash dropped + www. → must dedupe.
+                        {
+                            "Text": "Python docs duplicate",
+                            "FirstURL": "https://www.docs.python.org/3",
+                        },
+                        # A genuinely different URL must still come through.
+                        {
+                            "Text": "PEP 8 - style guide",
+                            "FirstURL": "https://peps.python.org/pep-0008/",
+                        },
+                    ],
+                },
+            ],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        urls = [h["url"] for h in res["results"]]
+        # Only the first variant of the duplicated URL is kept; second one is dropped.
+        assert urls == [
+            "https://docs.python.org/3/",
+            "https://peps.python.org/pep-0008/",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_dedup_urls_false_preserves_duplicates(self):
+        """When the caller opts out of deduplication every provider hit
+        must come through verbatim — useful for downstream re-rankers
+        that want to see near-duplicate variants.
+        """
+        body = {
+            "Answer":
+            "",
+            "AbstractText":
+            "",
+            "Definition":
+            "",
+            "RelatedTopics": [
+                {
+                    "Text": "Python (programming language) - first occurrence",
+                    "FirstURL": "https://docs.python.org/3/",
+                },
+                {
+                    "Topics": [
+                        {
+                            "Text": "Python docs duplicate",
+                            "FirstURL": "https://www.docs.python.org/3",
+                        },
+                    ],
+                },
+            ],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, dedup_urls=False, results_num=5)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        urls = [h["url"] for h in res["results"]]
+        # Both variants come through because dedup is off.
+        assert urls == [
+            "https://docs.python.org/3/",
+            "https://www.docs.python.org/3",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_snippet_and_title_len_respected(self):
+        """DDG branch must honour tool-level snippet_len/title_len overrides.
+
+        Previously these two knobs only affected the Google branch while DDG
+        hard-coded 300/100, producing inconsistent output shapes between
+        providers.
+        """
+        long_text = ("Python (programming language) - " + ("x" * 500))
+        body = {
+            "Answer": "",
+            "AbstractText": "",
+            "Definition": "",
+            "RelatedTopics": [{
+                "Text": long_text,
+                "FirstURL": "https://duckduckgo.com/Python",
+            }],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, snippet_len=50, title_len=10)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        hit = res["results"][0]
+        # +3 for the "..." suffix appended by _truncate.
+        assert len(hit["snippet"]) <= 50 + 3
+        assert len(hit["title"]) <= 10 + 3
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_fallback_snippet_and_title_len_respected(self):
+        """Fallback synthetic hit must also honour snippet_len/title_len."""
+        body = {
+            "Answer": "Y" * 500,
+            "AbstractText": "",
+            "Definition": "",
+            "RelatedTopics": [],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, snippet_len=40, title_len=8)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "a-very-long-fallback-query"})
+        hit = res["results"][0]
+        assert len(hit["snippet"]) <= 40 + 3
+        assert len(hit["title"]) <= 8 + 3
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_abstract_url_is_extracted_as_first_hit(self):
+        """The abstract's canonical URL (usually Wikipedia) must be the
+        primary citation, NOT internal ``duckduckgo.com/c/...`` entries
+        from ``RelatedTopics``.
+
+        This was the single most visible demo regression: DDG's
+        ``RelatedTopics`` URLs are all ``https://duckduckgo.com/...``
+        category pages, so for any entity-like query the tool used to
+        return five useless self-links instead of a Wikipedia source.
+        """
+        body = {
+            "Heading": "Python (programming language)",
+            "Answer": "",
+            "AbstractText": "Python is an interpreted language.",
+            "AbstractSource": "Wikipedia",
+            "AbstractURL": "https://en.wikipedia.org/wiki/Python_(programming_language)",
+            "Definition": "",
+            "RelatedTopics": [
+                {
+                    "Text": "Python Category",
+                    "FirstURL": "https://duckduckgo.com/c/Python",
+                },
+            ],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, results_num=5)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        urls = [h["url"] for h in res["results"]]
+        assert urls[0] == "https://en.wikipedia.org/wiki/Python_(programming_language)"
+        assert res["results"][0]["title"] == "Python (programming language)"
+        # RelatedTopics still come after the canonical abstract URL.
+        assert "https://duckduckgo.com/c/Python" in urls
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_definition_url_is_extracted_when_distinct(self):
+        """``DefinitionURL`` (dictionary source) must also produce a hit."""
+        body = {
+            "Heading": "Vector database",
+            "Answer": "",
+            "AbstractText": "A vector database stores embeddings.",
+            "AbstractURL": "https://en.wikipedia.org/wiki/Vector_database",
+            "Definition": "A database optimised for vector similarity search.",
+            "DefinitionSource": "Wiktionary",
+            "DefinitionURL": "https://en.wiktionary.org/wiki/vector_database",
+            "RelatedTopics": [],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, results_num=5)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "vector database"})
+        urls = [h["url"] for h in res["results"]]
+        assert "https://en.wikipedia.org/wiki/Vector_database" in urls
+        assert "https://en.wiktionary.org/wiki/vector_database" in urls
+        # AbstractURL is the first (higher-priority) entry.
+        assert urls[0] == "https://en.wikipedia.org/wiki/Vector_database"
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_results_field_is_extracted(self):
+        """DDG's ``Results`` array (external links for brand queries) must
+        flow through just like ``RelatedTopics`` but at a higher priority.
+        """
+        body = {
+            "Heading": "GitHub",
+            "Answer": "",
+            "AbstractText": "GitHub is a code hosting platform.",
+            "AbstractURL": "https://en.wikipedia.org/wiki/GitHub",
+            "Definition": "",
+            "Results": [
+                {
+                    "Text": "GitHub - Official site",
+                    "FirstURL": "https://github.com",
+                },
+            ],
+            "RelatedTopics": [
+                {
+                    "Text": "Git (software)",
+                    "FirstURL": "https://duckduckgo.com/Git",
+                },
+            ],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, results_num=5)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "github"})
+        urls = [h["url"] for h in res["results"]]
+        # Priority order: AbstractURL → Results → RelatedTopics.
+        assert urls == [
+            "https://en.wikipedia.org/wiki/GitHub",
+            "https://github.com",
+            "https://duckduckgo.com/Git",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_abstract_url_respects_allowed_domains(self):
+        """An ``allowed_domains=['wikipedia.org']`` request must now keep
+        the Wikipedia abstract URL and drop internal DDG pages — this
+        was broken before because the abstract URL was never extracted.
+        """
+        body = {
+            "Heading": "Python (programming language)",
+            "AbstractText": "Python is an interpreted language.",
+            "AbstractURL": "https://en.wikipedia.org/wiki/Python_(programming_language)",
+            "RelatedTopics": [
+                {
+                    "Text": "Python Category",
+                    "FirstURL": "https://duckduckgo.com/c/Python",
+                },
+            ],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, results_num=5)
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "allowed_domains": ["wikipedia.org"],
+            },
+        )
+        urls = [h["url"] for h in res["results"]]
+        assert urls == [
+            "https://en.wikipedia.org/wiki/Python_(programming_language)",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_abstract_and_related_topics_dedupe_against_each_other(self):
+        """If ``AbstractURL`` and a ``RelatedTopics`` entry happen to
+        point at the same page (same normalised key) we must only keep
+        one — the higher-priority ``AbstractURL`` copy.
+        """
+        body = {
+            "Heading":
+            "Python",
+            "AbstractText":
+            "Python programming language.",
+            "AbstractURL":
+            "https://en.wikipedia.org/wiki/Python_(programming_language)",
+            "RelatedTopics": [
+                {
+                    "Text": "Python programming language",
+                    # Same URL with trailing slash + www. → dedupe key collides.
+                    "FirstURL": "https://www.en.wikipedia.org/wiki/Python_(programming_language)/",
+                },
+                {
+                    "Text": "CPython - Reference implementation",
+                    "FirstURL": "https://docs.python.org/cpython",
+                },
+            ],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, results_num=5)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        urls = [h["url"] for h in res["results"]]
+        assert urls == [
+            "https://en.wikipedia.org/wiki/Python_(programming_language)",
+            "https://docs.python.org/cpython",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_count_limit_caps_high_priority_sources(self):
+        """``count=1`` must keep only the highest-priority hit
+        (AbstractURL) and drop everything else — including Results /
+        RelatedTopics.
+        """
+        body = {
+            "Heading": "Python",
+            "AbstractText": "Python is a language.",
+            "AbstractURL": "https://en.wikipedia.org/wiki/Python_(programming_language)",
+            "Results": [{
+                "Text": "Python.org",
+                "FirstURL": "https://python.org",
+            }],
+            "RelatedTopics": [{
+                "Text": "NumPy",
+                "FirstURL": "https://duckduckgo.com/NumPy",
+            }],
+        }
+        client = _make_mock_client({"/": body})
+        t = WebSearchTool(http_client=client, results_num=5)
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "count": 1,
+            },
+        )
+        urls = [h["url"] for h in res["results"]]
+        assert urls == [
+            "https://en.wikipedia.org/wiki/Python_(programming_language)",
+        ]
+        await client.aclose()
+
+
+_GOOGLE_RESPONSE: Dict[str, Any] = {
+    "queries": {
+        "request": [{
+            "searchTerms": "python releases"
+        }]
+    },
+    "items": [
+        {
+            "title": "Python 3.13 Release Notes",
+            "link": "https://python.org/releases/3.13",
+            "snippet": "Release notes for Python 3.13.",
+            "pagemap": {
+                "metatags": [{
+                    "description": "Official release notes",
+                    "og:description": "Python 3.13 official",
+                }],
+            },
+        },
+        {
+            "title": "Python on Wikipedia",
+            "link": "https://en.wikipedia.org/wiki/Python",
+            "snippet": "Encyclopedia entry for Python.",
+        },
+    ],
+}
+
+
+class TestGoogleProvider:
+
+    @pytest.mark.asyncio
+    async def test_missing_credentials_returns_helpful_result(self):
+        t = WebSearchTool(provider="google", api_key="", engine_id="")
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={"query": "python"},
+        )
+        assert res["provider"] == "google"
+        assert res["results"] == []
+        assert "not configured" in res["summary"]
+
+    @pytest.mark.asyncio
+    async def test_happy_path(self):
+        client = _make_mock_client({"/customsearch/v1": _GOOGLE_RESPONSE})
+        t = WebSearchTool(
+            provider="google",
+            api_key="fake-key",
+            engine_id="fake-cx",
+            http_client=client,
+        )
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "lang": "en",
+            },
+        )
+        assert res["provider"] == "google"
+        assert [h["url"] for h in res["results"]] == [
+            "https://python.org/releases/3.13",
+            "https://en.wikipedia.org/wiki/Python",
+        ]
+        # Metatag enrichment is folded into the snippet.
+        assert "Official release notes" in res["results"][0]["snippet"]
+        # Effective query is surfaced because it differs from user query.
+        assert "python releases" in res["summary"]
+
+        # Inspect the last request — lang + key + cx should be attached.
+        req = client._captured["last_request"]
+        assert req.url.params.get("hl") == "en"
+        assert req.url.params.get("key") == "fake-key"
+        assert req.url.params.get("cx") == "fake-cx"
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_single_allowed_domain_maps_to_server_side_filter(self):
+        """Exactly ONE allowed domain → offload to Google's siteSearch."""
+        client = _make_mock_client({"/customsearch/v1": _GOOGLE_RESPONSE})
+        t = WebSearchTool(
+            provider="google",
+            api_key="k",
+            engine_id="cx",
+            http_client=client,
+        )
+        await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "allowed_domains": ["python.org"],
+            },
+        )
+        req = client._captured["last_request"]
+        assert req.url.params.get("siteSearch") == "python.org"
+        assert req.url.params.get("siteSearchFilter") == "i"
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_single_blocked_domain_maps_to_server_side_filter(self):
+        """Exactly ONE blocked domain → offload to Google's siteSearch."""
+        client = _make_mock_client({"/customsearch/v1": _GOOGLE_RESPONSE})
+        t = WebSearchTool(
+            provider="google",
+            api_key="k",
+            engine_id="cx",
+            http_client=client,
+        )
+        await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "blocked_domains": ["wikipedia.org"],
+            },
+        )
+        req = client._captured["last_request"]
+        assert req.url.params.get("siteSearch") == "wikipedia.org"
+        assert req.url.params.get("siteSearchFilter") == "e"
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_multi_allowed_domains_skip_server_filter_and_filter_clientside(self):
+        """Multiple allowed domains → no siteSearch, rely on client-side filter.
+
+        Without this behaviour CSE would only return results from
+        ``allowed[0]`` and silently drop everything from ``allowed[1:]``.
+        """
+        client = _make_mock_client({"/customsearch/v1": _GOOGLE_RESPONSE})
+        t = WebSearchTool(
+            provider="google",
+            api_key="k",
+            engine_id="cx",
+            http_client=client,
+        )
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "allowed_domains": ["python.org", "wikipedia.org"],
+            },
+        )
+
+        # No server-side filter should be attached.
+        req = client._captured["last_request"]
+        assert req.url.params.get("siteSearch") is None
+        assert req.url.params.get("siteSearchFilter") is None
+
+        # Client-side filter keeps only the whitelisted domains.
+        urls = [h["url"] for h in res["results"]]
+        assert "https://python.org/releases/3.13" in urls
+        assert "https://en.wikipedia.org/wiki/Python" in urls
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_multi_blocked_domains_skip_server_filter_and_filter_clientside(self):
+        """Multiple blocked domains → no siteSearch, rely on client-side filter."""
+        client = _make_mock_client({"/customsearch/v1": _GOOGLE_RESPONSE})
+        t = WebSearchTool(
+            provider="google",
+            api_key="k",
+            engine_id="cx",
+            http_client=client,
+        )
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "blocked_domains": ["wikipedia.org", "stackoverflow.com"],
+            },
+        )
+
+        req = client._captured["last_request"]
+        assert req.url.params.get("siteSearch") is None
+        assert req.url.params.get("siteSearchFilter") is None
+
+        # Client-side filter excludes blocked domains.
+        urls = [h["url"] for h in res["results"]]
+        assert "https://en.wikipedia.org/wiki/Python" not in urls
+        assert "https://python.org/releases/3.13" in urls
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_results_are_deduplicated_by_url(self):
+        """Google CSE rarely emits duplicates on its own, but ``http``/
+        ``https`` and trailing-slash variants still slip through (and
+        ``google_extra_params`` can produce them); the tool must collapse
+        them.
+        """
+        body = {
+            "queries": {
+                "request": [{
+                    "searchTerms": "python"
+                }]
+            },
+            "items": [
+                {
+                    "title": "Python docs",
+                    "link": "https://docs.python.org/3",
+                    "snippet": "first",
+                },
+                {
+                    "title": "Python docs (dup)",
+                    "link": "https://www.docs.python.org/3/",
+                    "snippet": "duplicate",
+                },
+                {
+                    "title": "PEP 8",
+                    "link": "https://peps.python.org/pep-0008/",
+                    "snippet": "style",
+                },
+            ],
+        }
+        client = _make_mock_client({"/customsearch/v1": body})
+        t = WebSearchTool(provider="google", api_key="k", engine_id="cx", http_client=client)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        urls = [h["url"] for h in res["results"]]
+        assert urls == [
+            "https://docs.python.org/3",
+            "https://peps.python.org/pep-0008/",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_dedup_urls_false_preserves_duplicates(self):
+        body = {
+            "queries": {
+                "request": [{
+                    "searchTerms": "python"
+                }]
+            },
+            "items": [
+                {
+                    "title": "Python docs",
+                    "link": "https://docs.python.org/3",
+                    "snippet": "first",
+                },
+                {
+                    "title": "Python docs (dup)",
+                    "link": "https://www.docs.python.org/3/",
+                    "snippet": "duplicate",
+                },
+            ],
+        }
+        client = _make_mock_client({"/customsearch/v1": body})
+        t = WebSearchTool(
+            provider="google",
+            api_key="k",
+            engine_id="cx",
+            http_client=client,
+            dedup_urls=False,
+        )
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        urls = [h["url"] for h in res["results"]]
+        assert urls == [
+            "https://docs.python.org/3",
+            "https://www.docs.python.org/3/",
+        ]
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_google_num_clamped_to_provider_hard_cap(self):
+        """Google CSE rejects ``num > 10`` — the tool must clamp server-side.
+
+        The tool-level ``count`` / ``_MAX_COUNT`` can legitimately go up to 20,
+        but when the provider is Google that value MUST be clamped to 10 in
+        the outgoing request to avoid a 400 from CSE.
+        """
+        client = _make_mock_client({"/customsearch/v1": _GOOGLE_RESPONSE})
+        t = WebSearchTool(
+            provider="google",
+            api_key="k",
+            engine_id="cx",
+            http_client=client,
+        )
+        await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={
+                "query": "python",
+                "count": 20,
+            },
+        )
+        req = client._captured["last_request"]
+        assert req.url.params.get("num") == "10"
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_api_error_surfaced_as_structured_result(self):
+        error_body = {
+            "error": {
+                "code": 403,
+                "message": "API key invalid",
+            }
+        }
+        client = _make_mock_client({"/customsearch/v1": error_body})
+        t = WebSearchTool(
+            provider="google",
+            api_key="bad",
+            engine_id="cx",
+            http_client=client,
+        )
+        res = await t._run_async_impl(
+            tool_context=_tool_ctx(),
+            args={"query": "python"},
+        )
+        assert res["results"] == []
+        assert "API key invalid" in res["summary"]
+        await client.aclose()
+
+
+class TestHttpErrorHandling:
+
+    @pytest.mark.asyncio
+    async def test_http_error_returns_structured_error(self):
+
+        def boom(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(500, text="server on fire")
+
+        client = httpx.AsyncClient(transport=httpx.MockTransport(boom))
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        assert "error" in res
+        assert "HTTP_ERROR" in res["error"]
+        assert res["provider"] == "duckduckgo"
+        await client.aclose()
+
+
+class TestInjectedHttpClient:
+
+    @pytest.mark.asyncio
+    async def test_injected_client_still_uses_tool_user_agent(self):
+        """A pre-built ``http_client`` must NOT bypass the tool's User-Agent.
+
+        The injected client owns proxy + connection pool, but the
+        per-request ``User-Agent`` (and timeout) must come from the tool
+        so that callers can't accidentally fingerprint the wrong identity
+        just by sharing a client.
+        """
+        client = _make_mock_client({"/": _MIN_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client, user_agent="custom-ua/9.9")
+        await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        req = client._captured["last_request"]
+        assert req.headers.get("user-agent") == "custom-ua/9.9"
+        await client.aclose()
+
+
+class TestProcessRequest:
+
+    @pytest.mark.asyncio
+    async def test_registers_declaration_and_instructions(self):
+        tool = WebSearchTool()
+        req = LlmRequest()
+        await tool.process_request(tool_context=_tool_ctx(), llm_request=req)
+
+        assert tool.name in req.tools_dict
+        assert req.config is not None
+        assert req.config.system_instruction
+        si = str(req.config.system_instruction)
+        assert _TOOL_NAME in si
+        assert "Sources:" in si
+        # Current month/year string should be embedded.
+        assert _current_month_year() in si
+
+
+class TestHelpers:
+
+    def test_truncate_short(self):
+        assert _truncate("abc", 10) == "abc"
+
+    def test_truncate_long(self):
+        assert _truncate("x" * 50, 10) == "xxxxxxxxxx..."
+
+    def test_extract_domain_from_url(self):
+        assert _extract_domain_from_url("https://www.python.org/x") == "python.org"
+        assert _extract_domain_from_url("http://docs.python.org/x") == "docs.python.org"
+        assert _extract_domain_from_url("") == ""
+
+    def test_extract_domain_from_url_strips_port_and_userinfo(self):
+        # Explicit ports used to leak into the host via the old regex
+        # (``example.com:8080``), which made allow/block matching silently
+        # fail. ``urlparse`` correctly strips them.
+        assert _extract_domain_from_url("https://example.com:8080/x") == "example.com"
+        assert _extract_domain_from_url("https://user:pass@example.com/x") == "example.com"
+        # Mixed case normalises to lower.
+        assert _extract_domain_from_url("HTTPS://WWW.Example.COM/x") == "example.com"
+
+    def test_extract_domain_from_url_non_http_schemes_fail_closed(self):
+        for bad in ("javascript:alert(1)", "ftp://foo/bar", "mailto:a@b.c", "not a url"):
+            assert _extract_domain_from_url(bad) == ""
+
+    def test_dedup_key_normalises_common_variants(self):
+        # Trailing slash, www., uppercase host all collapse to the same key.
+        a = _dedup_key("https://www.Example.com/path/")
+        b = _dedup_key("https://example.com/path")
+        assert a == b
+        # Fragments are ignored.
+        assert _dedup_key("https://x.com/y#section") == _dedup_key("https://x.com/y")
+        # Path case is preserved (case can be significant on some servers).
+        assert _dedup_key("https://x.com/A") != _dedup_key("https://x.com/a")
+        # Different schemes are NOT merged (http vs https are different
+        # destinations from a security/content standpoint).
+        assert _dedup_key("http://x.com/y") != _dedup_key("https://x.com/y")
+        # Unparseable URLs fall through to their stripped form.
+        assert _dedup_key("  ") == ""
+        assert _dedup_key("not a url") == "not a url"
+        # Query strings ARE part of the identity — a sitemap vs a search
+        # results page on the same path must not dedupe.
+        assert _dedup_key("https://x.com/s?q=1") != _dedup_key("https://x.com/s?q=2")
+        # Default ports collapse with their bare form.
+        assert _dedup_key("https://x.com:443/y") == _dedup_key("https://x.com/y")
+        assert _dedup_key("http://x.com:80/y") == _dedup_key("http://x.com/y")
+        # Non-default ports are preserved (different service).
+        assert _dedup_key("https://x.com:8443/y") != _dedup_key("https://x.com/y")
+
+    def test_is_blocked_with_blocklist(self):
+        assert _is_blocked("https://docs.python.org/x", None, ["python.org"])
+        assert _is_blocked("https://python.org/x", None, ["python.org"])
+        assert not _is_blocked("https://example.com/x", None, ["python.org"])
+
+    def test_is_blocked_with_allowlist(self):
+        assert not _is_blocked("https://python.org/x", ["python.org"], None)
+        assert _is_blocked("https://example.com/x", ["python.org"], None)
+
+    def test_is_blocked_no_lists_passes(self):
+        assert not _is_blocked("https://x.com", None, None)
+
+    def test_is_blocked_invalid_url_fails_closed(self):
+        # URLs we can't parse a host out of should always be treated as blocked,
+        # so they don't slip past allow/block filters into the hit list.
+        for bad in ("", "not a url", "javascript:alert(1)", "ftp://foo/bar", "mailto:a@b.c"):
+            assert _is_blocked(bad, None, None) is True
+            assert _is_blocked(bad, ["example.com"], None) is True
+            assert _is_blocked(bad, None, ["example.com"]) is True
+
+    def test_extract_title_from_ddg_topic(self):
+        assert _extract_title_from_ddg_topic("Python - the language") == "Python"
+        assert _extract_title_from_ddg_topic("") == ""
+        long_title = "X" * 200
+        out = _extract_title_from_ddg_topic(long_title)
+        assert out.endswith("...")
+
+    def test_extract_desc_from_pagemap_ok(self):
+        pagemap = {
+            "metatags": [
+                {
+                    "description": "first"
+                },
+                {
+                    "og:description": "second"
+                },
+                {},
+            ]
+        }
+        assert _extract_desc_from_pagemap(pagemap) == "first\nsecond"
+
+    def test_extract_desc_from_pagemap_bad_shapes(self):
+        assert _extract_desc_from_pagemap({}) == ""
+        assert _extract_desc_from_pagemap({"metatags": "not-a-list"}) == ""
+        assert _extract_desc_from_pagemap({"metatags": [None, 42]}) == ""
+
+
+class TestOutputShape:
+
+    @pytest.mark.asyncio
+    async def test_output_is_jsonable_dict(self):
+        client = _make_mock_client({"/": _FULL_DDG_RESPONSE})
+        t = WebSearchTool(http_client=client)
+        res = await t._run_async_impl(tool_context=_tool_ctx(), args={"query": "python"})
+        # Must be JSON-serialisable so the framework can place it in tool_result.
+        dumped = json.dumps(res)
+        parsed = json.loads(dumped)
+        assert parsed["query"] == "python"
+        assert isinstance(parsed["results"], list)
+        await client.aclose()
diff --git a/trpc_agent_sdk/tools/__init__.py b/trpc_agent_sdk/tools/__init__.py
index 9305729..4412110 100644
--- a/trpc_agent_sdk/tools/__init__.py
+++ b/trpc_agent_sdk/tools/__init__.py
@@ -37,6 +37,11 @@
 from ._tool_adapter import create_tool
 from ._tool_adapter import create_toolset
 from ._transfer_to_agent_tool import transfer_to_agent
+from ._webfetch_tool import FetchResult
+from ._webfetch_tool import WebFetchTool
+from ._websearch_tool import SearchHit
+from ._websearch_tool import WebSearchResult
+from ._websearch_tool import WebSearchTool
 from .file_tools import BashTool
 from .file_tools import EditTool
 from .file_tools import FileToolSet
@@ -90,6 +95,11 @@
     "create_tool",
     "create_toolset",
     "transfer_to_agent",
+    "FetchResult",
+    "WebFetchTool",
+    "SearchHit",
+    "WebSearchResult",
+    "WebSearchTool",
     "BashTool",
     "EditTool",
     "FileToolSet",
diff --git a/trpc_agent_sdk/tools/_webfetch_tool.py b/trpc_agent_sdk/tools/_webfetch_tool.py
new file mode 100644
index 0000000..363b8a6
--- /dev/null
+++ b/trpc_agent_sdk/tools/_webfetch_tool.py
@@ -0,0 +1,705 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Web fetch tool for TRPC Agent framework.
+
+Provides a client-side :class:`WebFetchTool` that:
+
+- issues an unauthenticated HTTP GET against a single URL,
+- converts the response to text (Markdown for HTML; verbatim for
+  textual MIME types),
+- optionally caches raw fetch results in a TTL + byte-bounded LRU so
+  repeated hits skip the network.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import re
+import socket
+import time
+from collections import OrderedDict
+from typing import Any
+from typing import List
+from typing import Optional
+from typing import Tuple
+from urllib.parse import urlparse
+from typing_extensions import override
+
+import httpx
+from markdownify import markdownify as _markdownify  # type: ignore[import-untyped]
+from pydantic import BaseModel
+from pydantic import Field
+
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.filter import BaseFilter
+from trpc_agent_sdk.log import logger
+from trpc_agent_sdk.types import FunctionDeclaration
+from trpc_agent_sdk.types import Schema
+from trpc_agent_sdk.types import Type
+
+from ._base_tool import BaseTool
+
+# Default HTTP timeout in seconds.
+_DEFAULT_TIMEOUT = 30.0
+# Default cap on returned content in chars (~25K tokens worst-case).
+_DEFAULT_MAX_CONTENT_LENGTH = 100_000
+# Default upper bound on redirects when ``follow_redirects`` is on.
+_DEFAULT_MAX_REDIRECTS = 5
+# Default HTTP User-Agent string.
+_DEFAULT_USER_AGENT = "trpc-agent-python-webfetch/1.0"
+# Hard byte cap on the raw response body read from the wire.
+_DEFAULT_MAX_RESPONSE_BYTES = 5 * 1024 * 1024
+# Number of prefix bytes inspected when sniffing a response that lacks a Content-Type header.
+_BINARY_SNIFF_BYTES = 4096
+# Cache defaults (15 minutes / 50 MiB)
+_DEFAULT_CACHE_TTL_SECONDS = 15.0 * 60
+_DEFAULT_CACHE_MAX_BYTES = 50 * 1024 * 1024
+# MIME types we render as Markdown-ish text.
+_HTML_TYPES = frozenset(["text/html", "application/xhtml+xml"])
+# MIME types we return verbatim. Any unknown ``text/*`` MIME is accepted
+_TEXT_TYPES = frozenset([
+    "text/plain",
+    "text/markdown",
+    "text/csv",
+    "text/xml",
+    "text/css",
+    "text/javascript",
+    "text/rtf",
+    "application/json",
+    "application/xml",
+    "application/yaml",
+    "application/x-yaml",
+    "application/ld+json",
+])
+# WebFetchTool description shown to the LLM
+_BASE_DESCRIPTION = """\
+Fetch a single URL via HTTP GET and return its textual content.
+- HTML pages are stripped to Markdown-ish plain text; other textual MIME types are returned verbatim.
+- Content is capped to a finite length (override via `max_length`) so large pages do not overflow the context window.
+- Binary content (PDF / image / archive / ...) is rejected with a structured error; use a dedicated tool for it.
+- The URL must be an absolute http(s) URL. The tool's domain allow/block lists are enforced before the request.
+- By default the tool refuses to dial loopback / private / link-local targets
+  (e.g. 127.0.0.1, 169.254.169.254, intranet IPs) so it cannot be abused as an SSRF probe.
+- This tool is read-only and does not modify any files or remote state.
+
+USE WHEN the user asks to:
+  - read, summarise, quote or extract a fact from a specific webpage, doc page, RFC, changelog, or news article
+  - follow a link returned by `websearch` for a deeper read
+
+DO NOT USE WHEN:
+  - an MCP-provided web fetch tool is available — prefer it, as it may have fewer restrictions and richer auth
+  - the URL requires authentication or session cookies (Google Docs, Confluence, Jira, private GitHub, intranet)
+    — prefer a dedicated MCP/authenticated tool
+  - you need to render JavaScript, submit forms, or perform interactive browsing (this tool only issues one GET)
+  - the content is binary — the tool rejects non-textual responses
+
+Usage notes:
+  - Always pass the fully-qualified URL including scheme (``http://`` / ``https://``).
+  - When the returned ``content`` is truncated, summarise faithfully rather than invent missing sections.
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL.
+  \
+"""
+
+
+class FetchResult(BaseModel):
+    """Structured output of :class:`WebFetchTool`."""
+
+    url: str = Field(default="", description="Final URL after any redirects")
+    status_code: int = Field(default=0, description="HTTP status code (0 when the request never completed)")
+    status_text: str = Field(default="", description="HTTP reason phrase")
+    content_type: str = Field(default="", description="Normalised media type (no parameters)")
+    content: str = Field(default="", description="Textual body, possibly truncated")
+    bytes: int = Field(default=0, description="UTF-8 byte length of the returned ``content``")
+    duration_ms: int = Field(default=0, description="Wall-clock time spent on the request")
+    cached: bool = Field(default=False, description="True when served from the in-process LRU cache")
+    error: str = Field(default="", description="Populated when the fetch failed or content was rejected")
+
+
+def _normalise_content_type(raw: str) -> str:
+    """Return the bare media type from a ``Content-Type`` header."""
+    if not raw:
+        return ""
+    return raw.split(";", 1)[0].strip().lower()
+
+
+def _is_html_type(media_type: str) -> bool:
+    return media_type in _HTML_TYPES
+
+
+def _is_text_type(media_type: str) -> bool:
+    """Accept known-textual types plus any ``text/*`` fallback."""
+    if media_type in _TEXT_TYPES:
+        return True
+    return media_type.startswith("text/")
+
+
+def _extract_host(url: str) -> str:
+    """Return the lower-cased host of an ``http(s)`` URL"""
+    try:
+        parsed = urlparse((url or "").strip())
+    except ValueError:
+        logger.error("Failed to parse URL: %s", url)
+        return ""
+    if parsed.scheme.lower() not in ("http", "https"):
+        return ""
+    try:
+        host = (parsed.hostname or "").lower()
+    except ValueError:
+        logger.error("Failed to parse hostname: %s", url)
+        return ""
+    return host.removeprefix("www.")
+
+
+class _SSRFBlockedError(Exception):
+    """Raised when a target URL resolves to a disallowed network."""
+    pass
+
+
+class _DomainBlockedError(Exception):
+    """Raised when a target URL is rejected by the tool's domain allow/block policy."""
+    pass
+
+
+def _is_disallowed_ip(ip: "ipaddress._BaseAddress") -> bool:
+    """Return ``True`` for addresses never want to dial."""
+    return bool(ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved or ip.is_multicast
+                or ip.is_unspecified)
+
+
+async def _resolve_host(host: str) -> List[str]:
+    """Resolve ``host`` to every A/AAAA address SSRF blocked"""
+    if not host:
+        return []
+    loop = asyncio.get_running_loop()
+    try:
+        infos = await loop.run_in_executor(
+            None,
+            lambda: socket.getaddrinfo(host, None, type=socket.SOCK_STREAM),
+        )
+    except (socket.gaierror, UnicodeError, OSError) as e:
+        logger.debug("WebFetchTool DNS resolution failed for %s: %s", host, e)
+        return []
+    addrs: List[str] = []
+    for info in infos:
+        sockaddr = info[4] if len(info) > 4 else None
+        if sockaddr and sockaddr[0]:
+            addrs.append(sockaddr[0])
+    return addrs
+
+
+async def _assert_public_host(url: str) -> None:
+    """Judge if ``url`` targets a non-public address."""
+    host = _extract_host(url)
+    if not host:
+        raise _SSRFBlockedError("unparseable host")
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        ip = None
+    if ip is not None:
+        if _is_disallowed_ip(ip):
+            raise _SSRFBlockedError(f"{host} is a private/reserved address")
+        return
+    addrs = await _resolve_host(host)
+    if not addrs:
+        raise _SSRFBlockedError(f"{host!r} did not resolve")
+    for raw in addrs:
+        try:
+            resolved = ipaddress.ip_address(raw)
+        except ValueError:
+            continue
+        if _is_disallowed_ip(resolved):
+            raise _SSRFBlockedError(f"{host!r} resolves to private/reserved address {raw}")
+
+
+def _is_blocked_url(
+    url: str,
+    allowed: Optional[List[str]],
+    blocked: Optional[List[str]],
+) -> bool:
+    """Tool-level URL allow/block check. Returns ``True`` when blocked."""
+    host = _extract_host(url)
+    if not host:
+        return True
+    if blocked:
+        for d in blocked:
+            d = (d or "").lower().removeprefix("www.")
+            if d and (host == d or host.endswith("." + d)):
+                return True
+    if allowed:
+        is_allowed = False
+        for d in allowed:
+            d = (d or "").lower().removeprefix("www.")
+            if d and (host == d or host.endswith("." + d)):
+                is_allowed = True
+                break
+        if not is_allowed:
+            return True
+    return False
+
+
+def _truncate(text: str, limit: int) -> str:
+    """Truncate ``text`` to at most ``limit`` chars; ``0`` disables the cap."""
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[:limit].rstrip() + "..."
+
+
+def _cache_key(url: str) -> str:
+    """Normalise a URL for use as a cache key."""
+    raw = (url or "").strip()
+    if not raw:
+        return raw
+    try:
+        p = urlparse(raw)
+    except ValueError:
+        return raw
+    scheme = (p.scheme or "").lower()
+    if scheme not in ("http", "https"):
+        return raw
+    host = (p.hostname or "").lower().removeprefix("www.")
+    if not host:
+        return raw
+    default_port = 80 if scheme == "http" else 443
+    netloc = host if p.port is None or p.port == default_port else f"{host}:{p.port}"
+    path = p.path or "/"
+    if path != "/" and path.endswith("/"):
+        path = path.rstrip("/")
+    key = f"{scheme}://{netloc}{path}"
+    if p.query:
+        key = f"{key}?{p.query}"
+    return key
+
+
+_STRIPPED_BLOCK_RE = re.compile(
+    r"<(script|style|noscript|template|svg)\b[^>]*>.*?</\1\s*>",
+    re.DOTALL | re.IGNORECASE,
+)
+
+
+def _scrub_non_content_blocks(html: str) -> str:
+    """Remove ``<script>`` / ``<style>`` / ``<noscript>`` / ``<template>`` /
+    ``<svg>`` blocks including their inner text."""
+    return _STRIPPED_BLOCK_RE.sub("", html)
+
+
+def _normalise_blank_lines(text: str) -> str:
+    """Collapse >1 consecutive blank lines and trim trailing whitespace."""
+    out: List[str] = []
+    blank = 0
+    for line in text.splitlines():
+        stripped = line.rstrip()
+        if not stripped:
+            blank += 1
+            if blank <= 1:
+                out.append("")
+        else:
+            blank = 0
+            out.append(stripped)
+    return "\n".join(out).strip()
+
+
+def _html_to_text(html: str) -> str:
+    """Convert HTML to Markdown"""
+    cleaned = _scrub_non_content_blocks(html)
+    try:
+        text = _markdownify(cleaned, heading_style="ATX")
+    except Exception as e:  # pylint: disable=broad-except
+        logger.warning("WebFetchTool markdownify failed: %s", e)
+        return ""
+    return _normalise_blank_lines(text)
+
+
+class _LRUCache:
+    """Async-safe KV: URL -> ``FetchResult`` cache with TTL + byte budget."""
+
+    def __init__(self, *, ttl_seconds: float, max_bytes: int) -> None:
+        self._ttl = max(0.0, float(ttl_seconds))
+        self._max_bytes = max(0, int(max_bytes))
+        self._store: "OrderedDict[str, Tuple[float, int, FetchResult]]" = OrderedDict()
+        self._current_bytes = 0
+        self._lock = asyncio.Lock()
+
+    @property
+    def size_bytes(self) -> int:
+        return self._current_bytes
+
+    @property
+    def entries(self) -> int:
+        return len(self._store)
+
+    async def get(self, key: str) -> Optional[FetchResult]:
+        if not key or self._max_bytes <= 0:
+            return None
+        async with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            inserted_at, size, value = entry
+            if self._ttl > 0 and (time.monotonic() - inserted_at) > self._ttl:
+                del self._store[key]
+                self._current_bytes -= size
+                return None
+            self._store.move_to_end(key)
+            return value.model_copy()
+
+    async def put(self, key: str, value: FetchResult) -> None:
+        if not key or self._max_bytes <= 0:
+            return
+        size = len(value.content.encode("utf-8", errors="ignore"))
+        if size <= 0 or size > self._max_bytes:
+            return
+        async with self._lock:
+            if key in self._store:
+                _, old_size, _ = self._store.pop(key)
+                self._current_bytes -= old_size
+            while self._store and self._current_bytes + size > self._max_bytes:
+                _, (_, evict_size, _) = self._store.popitem(last=False)
+                self._current_bytes -= evict_size
+            self._store[key] = (time.monotonic(), size, value.model_copy())
+            self._current_bytes += size
+
+    async def clear(self) -> None:
+        async with self._lock:
+            self._store.clear()
+            self._current_bytes = 0
+
+
+class WebFetchTool(BaseTool):
+    """LLM tool that fetches a single URL and returns its textual content.
+
+    The tool issues an unauthenticated HTTP GET, converts the response
+    to text (Markdown-ish for HTML, verbatim for other textual types),
+    enforces tool-level allow/block lists, and caps the returned content
+    to protect the model context window. Binary responses are rejected
+    with a structured error rather than dumped as base64 blobs.
+
+    Optionally, an in-process LRU cache (``enable_cache``) stores raw
+    ``FetchResult`` objects with a 15-minute TTL and a 50 MiB byte
+    budget so repeated hits skip the network. A cached entry is marked
+    with ``cached=True`` on the result so the caller can reason about
+    freshness.
+
+    Args:
+        timeout: HTTP timeout in seconds.
+        user_agent: HTTP ``User-Agent`` header.
+        proxy: Optional HTTP proxy URL forwarded to httpx.
+        http_client: Optional pre-built ``httpx.AsyncClient`` to reuse (caller owns its lifecycle).
+        max_content_length: Default char cap on returned ``content``; ``0`` disables,
+            overridden by per-call ``max_length``.
+        allowed_domains: Tool-level host whitelist (subdomain-aware, ``www.`` stripped); NOT overrideable by the LLM.
+        blocked_domains: Tool-level host blacklist using the same matching as ``allowed_domains``; checked first.
+        follow_redirects: Whether httpx auto-follows redirects (default ``True``).
+        max_redirects: Upper bound on redirect hops when ``follow_redirects=True``.
+        enable_cache: Toggle the in-process LRU cache (default ``False``).
+        cache_ttl_seconds: TTL for cached entries (default 15 min).
+        cache_max_bytes: Total byte budget for the cache (default 50 MiB).
+        max_response_bytes: Hard cap on the raw wire body streamed from the server (default 5 MiB, ``0`` disables).
+        block_private_network: When ``True`` (default), reject every hop that resolves to loopback / private /
+            link-local / multicast / reserved / unspecified addresses (SSRF guard).
+        filters_name / filters: forwarded to :class:`BaseTool`.
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout: float = _DEFAULT_TIMEOUT,
+        user_agent: str = _DEFAULT_USER_AGENT,
+        proxy: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        max_content_length: int = _DEFAULT_MAX_CONTENT_LENGTH,
+        max_response_bytes: int = _DEFAULT_MAX_RESPONSE_BYTES,
+        allowed_domains: Optional[List[str]] = None,
+        blocked_domains: Optional[List[str]] = None,
+        block_private_network: bool = True,
+        follow_redirects: bool = True,
+        max_redirects: int = _DEFAULT_MAX_REDIRECTS,
+        enable_cache: bool = False,
+        cache_ttl_seconds: float = _DEFAULT_CACHE_TTL_SECONDS,
+        cache_max_bytes: int = _DEFAULT_CACHE_MAX_BYTES,
+        filters_name: Optional[List[str]] = None,
+        filters: Optional[List[BaseFilter]] = None,
+    ) -> None:
+        super().__init__(
+            name="webfetch",
+            description=_BASE_DESCRIPTION,
+            filters_name=filters_name,
+            filters=filters,
+        )
+        self._timeout = float(timeout)
+        self._user_agent = user_agent
+        self._proxy = proxy
+        self._http_client = http_client
+        self._max_content_length = max(0, int(max_content_length))
+        self._max_response_bytes = max(0, int(max_response_bytes))
+        self._allowed_domains = self._clean_domains(allowed_domains)
+        self._blocked_domains = self._clean_domains(blocked_domains)
+        self._block_private_network = bool(block_private_network)
+        self._follow_redirects = bool(follow_redirects)
+        self._max_redirects = max(0, int(max_redirects))
+
+        # LRU cache
+        self._enable_cache = bool(enable_cache)
+        self._cache: Optional[_LRUCache] = None
+        if self._enable_cache:
+            self._cache = _LRUCache(
+                ttl_seconds=cache_ttl_seconds,
+                max_bytes=cache_max_bytes,
+            )
+
+    @staticmethod
+    def _clean_domains(value: Optional[List[str]]) -> Optional[List[str]]:
+        """Trim and drop blank entries. Returns ``None`` for empty lists."""
+        if not value:
+            return None
+        cleaned = [d.strip() for d in value if isinstance(d, str) and d.strip()]
+        return cleaned or None
+
+    @property
+    def cache(self) -> Optional[_LRUCache]:
+        """Expose the cache for inspection / manual invalidation in tests."""
+        return self._cache
+
+    @override
+    def _get_declaration(self) -> FunctionDeclaration:
+        return FunctionDeclaration(
+            name="webfetch",
+            description=_BASE_DESCRIPTION,
+            parameters=Schema(
+                type=Type.OBJECT,
+                properties={
+                    "url":
+                    Schema(
+                        type=Type.STRING,
+                        description=("Required. Absolute http(s) URL to fetch. Must include the scheme. "
+                                     "Example: 'https://docs.python.org/3/whatsnew/3.13.html'."),
+                    ),
+                    "max_length":
+                    Schema(
+                        type=Type.INTEGER,
+                        description=(f"Optional. Override the per-call cap on returned `content` length "
+                                     f"in chars (0 disables the cap). Defaults to the tool-level value "
+                                     f"({self._max_content_length}). Prefer smaller values when you only "
+                                     f"need a short excerpt."),
+                        minimum=0,
+                    ),
+                },
+                required=["url"],
+            ),
+        )
+
+    @override
+    async def _run_async_impl(
+        self,
+        *,
+        tool_context: InvocationContext,
+        args: dict[str, Any],
+    ) -> Any:
+        raw_url = args.get("url")
+        if not isinstance(raw_url, str) or not raw_url.strip():
+            return {"error": "INVALID_ARGS: `url` must be a non-empty string"}
+        url = raw_url.strip()
+
+        parsed = urlparse(url)
+        if parsed.scheme.lower() not in ("http", "https") or not parsed.hostname:
+            return {"error": f"INVALID_URL: {url!r} must be an absolute http(s) URL"}
+
+        if _is_blocked_url(url, self._allowed_domains, self._blocked_domains):
+            return {
+                "url": url,
+                "error": (f"BLOCKED_URL: {parsed.hostname!r} is not permitted by "
+                          "the tool's domain policy"),
+            }
+
+        # Resolve effective caps: LLM arg overrides tool default.
+        cap = self._coerce_cap(args.get("max_length"))
+
+        key = _cache_key(url)
+        result: Optional[FetchResult] = None
+        if self._cache is not None:
+            cached_result = await self._cache.get(key)
+            if cached_result is not None:
+                cached_result.cached = True
+                result = cached_result
+                logger.info("WebFetchTool got cached result for %s in LRU cache", url)
+
+        if result is None:
+            result = await self._fetch_and_build(url)
+            if self._cache is not None and not result.error and result.content:
+                await self._cache.put(key, result)
+                logger.info("WebFetchTool put result for %s in LRU cache", url)
+
+        if not result.error:
+            result.content = _truncate(result.content, cap)
+            result.bytes = len(result.content.encode("utf-8", errors="ignore"))
+
+        return result.model_dump()
+
+    def _coerce_cap(self, raw: Any) -> int:
+        """Resolve the effective ``max_length`` cap for this call."""
+        try:
+            cap = int(raw) if raw is not None else self._max_content_length
+        except (TypeError, ValueError):
+            cap = self._max_content_length
+        return max(0, cap)
+
+    async def _fetch_and_build(self, url: str) -> FetchResult:
+        """Issue a streaming GET and map the response to :class:`FetchResult`."""
+        start = time.monotonic()
+        try:
+            return await self._do_fetch(url, start)
+        except _DomainBlockedError as e:
+            return FetchResult(
+                url=url,
+                error=f"Domain_BLOCKED_URL: {e}",
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+        except _SSRFBlockedError as e:
+            return FetchResult(
+                url=url,
+                error=f"SSRF_BLOCKED_URL: {e}",
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+        except httpx.HTTPError as e:
+            logger.warning("WebFetchTool HTTP error for %s: %s", url, e)
+            return FetchResult(
+                url=url,
+                error=f"HTTP_ERROR: {e}",
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+        except Exception as e:  # pylint: disable=broad-except
+            logger.error("WebFetchTool unexpected error for %s: %s", url, e)
+            return FetchResult(
+                url=url,
+                error=f"FETCH_ERROR: {e}",
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+
+    async def _do_fetch(self, url: str, start: float) -> FetchResult:
+        """Drive the request + manual-redirect loop and build the result."""
+        client = self._get_client()
+        owns_client = self._http_client is None
+        try:
+            current_url = url
+            hops = 0
+            while True:
+                if _is_blocked_url(current_url, self._allowed_domains, self._blocked_domains):
+                    host = _extract_host(current_url) or current_url
+                    raise _DomainBlockedError(f"{host!r} is not permitted by the tool's domain policy")
+                await self._check_ssrf(current_url)
+                async with client.stream(
+                        "GET",
+                        current_url,
+                        timeout=self._timeout,
+                        follow_redirects=False,
+                        headers={"User-Agent": self._user_agent},
+                ) as response:
+                    is_redirect = 300 <= response.status_code < 400
+                    location = response.headers.get("location", "") if is_redirect else ""
+                    if self._follow_redirects and location:
+                        hops += 1
+                        if hops > self._max_redirects:
+                            raise httpx.TooManyRedirects(
+                                f"Exceeded {self._max_redirects} redirects while fetching {url}",
+                                request=response.request,
+                            )
+                        current_url = str(response.url.join(location))
+                        continue
+                    return await self._build_from_response(response, start)
+        finally:
+            if owns_client:
+                await client.aclose()
+
+    async def _build_from_response(self, response: httpx.Response, start: float) -> FetchResult:
+        """Drain ``response`` under the byte cap and shape a :class:`FetchResult`."""
+        media_type = _normalise_content_type(response.headers.get("content-type", ""))
+        result = FetchResult(
+            url=str(response.url),
+            status_code=response.status_code,
+            status_text=response.reason_phrase or "",
+            content_type=media_type,
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+        if response.status_code < 200 or response.status_code >= 300:
+            result.error = f"HTTP_STATUS {response.status_code}: {response.reason_phrase or ''}".strip()
+            return result
+
+        # Reject non-text content-types
+        is_html = _is_html_type(media_type)
+        is_text = _is_text_type(media_type)
+        if media_type and not is_html and not is_text:
+            result.error = f"UNSUPPORTED_CONTENT_TYPE: {media_type}"
+            return result
+
+        body_bytes, aborted = await self._read_body(response)
+
+        if not media_type and b"\x00" in body_bytes[:_BINARY_SNIFF_BYTES]:
+            result.error = ("UNSUPPORTED_CONTENT_TYPE: response has no Content-Type "
+                            "header and looks binary")
+            return result
+
+        result.duration_ms = int((time.monotonic() - start) * 1000)
+
+        encoding = response.encoding or "utf-8"
+        try:
+            body = body_bytes.decode(encoding, errors="replace")
+        except LookupError:
+            body = body_bytes.decode("utf-8", errors="replace")
+        except Exception as e:  # pylint: disable=broad-except
+            result.error = f"DECODE_ERROR: {e}"
+            return result
+
+        content = _html_to_text(body) if is_html else body
+        result.content = content
+        result.bytes = len(content.encode("utf-8", errors="ignore"))
+        if aborted:
+            logger.info(
+                "WebFetchTool truncated %s at %d bytes (exceeded max_response_bytes)",
+                str(response.url),
+                self._max_response_bytes,
+            )
+        return result
+
+    async def _read_body(self, response: httpx.Response) -> Tuple[bytes, bool]:
+        """Stream the response body up to :attr:`_max_response_bytes`."""
+        limit = self._max_response_bytes
+        buf = bytearray()
+        aborted = False
+        async for chunk in response.aiter_bytes():
+            if not chunk:
+                continue
+            if limit <= 0:
+                buf.extend(chunk)
+                continue
+            remaining = limit - len(buf)
+            if remaining <= 0:
+                aborted = True
+                break
+            if len(chunk) > remaining:
+                buf.extend(chunk[:remaining])
+                aborted = True
+                break
+            buf.extend(chunk)
+        return bytes(buf), aborted
+
+    def _get_client(self) -> httpx.AsyncClient:
+        """Return an ``httpx.AsyncClient``"""
+        if self._http_client is not None:
+            return self._http_client
+        return httpx.AsyncClient(
+            timeout=self._timeout,
+            proxy=self._proxy,
+            follow_redirects=False,
+            headers={"User-Agent": self._user_agent},
+        )
+
+    async def _check_ssrf(self, url: str) -> None:
+        """Enforce the SSRF boundary on a single URL when enabled."""
+        if not self._block_private_network:
+            return
+        await _assert_public_host(url)
diff --git a/trpc_agent_sdk/tools/_websearch_tool.py b/trpc_agent_sdk/tools/_websearch_tool.py
new file mode 100644
index 0000000..f40e110
--- /dev/null
+++ b/trpc_agent_sdk/tools/_websearch_tool.py
@@ -0,0 +1,724 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Web search tool for TRPC Agent framework.
+
+Provides a client-side :class:`WebSearchTool` that lets LLMs search the
+public web for up-to-date information. Two pluggable provider backends
+are supported, ``duckduckgo`` and ``google search``:
+
+1. ``duckduckgo`` — DuckDuckGo(DDG) Instant Answer API. Keyless, good for
+   factual/encyclopedic/definition lookups. Returns curated instant
+   answers and related topics (NOT full real-time web results).
+2. ``google`` — Google Custom Search (CSE). Requires ``api_key`` +
+   ``engine_id``; returns true web results with snippet support, domain
+   filtering and language targeting.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+from typing import Any
+from typing import List
+from typing import Literal
+from typing import Optional
+from urllib.parse import quote_plus
+from urllib.parse import urlparse
+from typing_extensions import override
+
+import httpx
+from pydantic import BaseModel
+from pydantic import Field
+
+from trpc_agent_sdk.context import InvocationContext
+from trpc_agent_sdk.filter import BaseFilter
+from trpc_agent_sdk.log import logger
+from trpc_agent_sdk.models import LlmRequest
+from trpc_agent_sdk.types import FunctionDeclaration
+from trpc_agent_sdk.types import Schema
+from trpc_agent_sdk.types import Type
+
+from ._base_tool import BaseTool
+
+# default http timeout, 15 seconds
+_DEFAULT_TIMEOUT = 15.0
+# maximum number of results to return
+_MAX_COUNT = 10
+# Google Custom Search API hard cap for the ``num`` parameter per request.
+# Values above 10 cause CSE to return 400 Bad Request
+_GOOGLE_MAX_NUM = 10
+# default maximum number of results to return
+_DEFAULT_RESULTS_NUM = 5
+# maximum snippet length
+_MAX_SNIPPET_LEN = 1000
+# default snippet length
+_DEFAULT_SNIPPET_LEN = 300
+# maximum title length
+_MAX_TITLE_LEN = 200
+# default title length
+_DEFAULT_TITLE_LEN = 100
+# DuckDuckGo base URL
+_DDG_BASE_URL = "https://api.duckduckgo.com"
+# Google Custom Search base URL
+_GOOGLE_BASE_URL = "https://www.googleapis.com/customsearch/v1"
+# Description shown to the LLM as part of the tool schema.
+_BASE_DESCRIPTION = """\
+Search the public web and use the results to inform responses.
+- Provides up-to-date information for current events and recent data.
+- Returns structured results as {title, url, snippet} plus, for DuckDuckGo, an instant-answer summary.
+  All URLs are citable as markdown hyperlinks.
+- Use this tool for accessing information beyond the model's knowledge cutoff.
+- Each invocation performs a single search request; prefer one well-formed query over many narrow ones.
+
+USE WHEN the user asks about:
+  - current events, news, releases, prices, version numbers
+  - information past the model's knowledge cutoff
+  - entity / definition / fact lookups that need citable sources
+
+DO NOT USE WHEN:
+  - the answer is already in conversation history or memory
+  - the user asks for real-time data this tool cannot provide (e.g. stock ticks, live scores)
+    — say so instead of guessing
+
+Usage notes:
+  - Domain filtering is supported via `allowed_domains` (whitelist) or `blocked_domains` (blacklist);
+    the two are mutually exclusive.
+  - After calling this tool you MUST cite the returned URLs — see the system instruction
+    for the required 'Sources:' format.\
+"""
+
+ProviderType = Literal["duckduckgo", "google"]
+
+
+class SearchHit(BaseModel):
+    """A single simplified search result."""
+
+    title: str = Field(default="", description="Title of the result")
+    url: str = Field(default="", description="URL of the result")
+    snippet: str = Field(default="", description="Short description / excerpt")
+
+
+class WebSearchResult(BaseModel):
+    """Structured output of :class:`WebSearchTool`."""
+
+    query: str
+    provider: ProviderType
+    # results is the list of search results.
+    results: List[SearchHit] = Field(default_factory=list)
+    # DDG-only: summary is the aggregated instant answer / abstract / definition text.
+    summary: str = ""
+
+
+def _truncate(text: str, limit: int) -> str:
+    """Truncate text to a maximum length."""
+    text = (text or "").strip()
+    if len(text) <= limit:
+        return text
+    return text[:limit].rstrip() + "..."
+
+
+def _extract_title_from_ddg_topic(raw: str, limit: int = _DEFAULT_TITLE_LEN) -> str:
+    """Extract a human-readable title from a DDG RelatedTopic ``Text`` field."""
+    if not raw:
+        return ""
+    head = raw.split(" - ", 1)[0]
+    return _truncate(head, limit)
+
+
+def _extract_domain_from_url(url: str) -> str:
+    """Extract the lower-cased host of an ``http(s)`` URL."""
+    try:
+        parsed = urlparse((url or "").strip())
+    except ValueError:
+        logger.error("Failed to parse URL: %s", url)
+        return ""
+
+    if parsed.scheme.lower() not in ("http", "https"):
+        return ""
+
+    try:
+        host = (parsed.hostname or "").lower()
+    except ValueError:
+        logger.error("Failed to parse hostname: %s", url)
+        return ""
+
+    return host.removeprefix("www.")
+
+
+def _dedup_key(url: str) -> str:
+    """Return a normalised key used to deduplicate result URLs."""
+
+    raw = (url or "").strip()
+    if not raw:
+        return ""
+    try:
+        parsed = urlparse(raw)
+    except ValueError:
+        return raw
+    scheme = parsed.scheme.lower()
+    if scheme not in ("http", "https"):
+        return raw
+    try:
+        host = (parsed.hostname or "").lower().removeprefix("www.")
+    except ValueError:
+        return raw
+    if not host:
+        return raw
+    netloc = host
+    if parsed.port is not None:
+        default_port = 80 if scheme == "http" else 443
+        if parsed.port != default_port:
+            netloc = f"{host}:{parsed.port}"
+    path = parsed.path or ""
+    if path.endswith("/") and path != "/":
+        path = path.rstrip("/")
+    key = f"{scheme}://{netloc}{path}"
+    if parsed.query:
+        key = f"{key}?{parsed.query}"
+    return key
+
+
+def _normalise_domains(value: Any, field: str) -> tuple[Optional[List[str]], Optional[str]]:
+    """Normalise and validate a domain-list arg from the tool-call payload."""
+    if value is None:
+        return None, None
+    if not isinstance(value, list):
+        return None, f"INVALID_ARGS: `{field}` must be an array of domain strings"
+    cleaned: List[str] = []
+    for d in value:
+        if not isinstance(d, str):
+            return None, f"INVALID_ARGS: `{field}` items must all be strings"
+        s = d.strip()
+        if s:
+            cleaned.append(s)
+    if not cleaned:
+        return None, f"INVALID_ARGS: `{field}` must contain at least one non-empty domain"
+    return cleaned, None
+
+
+def _is_blocked(url: str, allowed: Optional[List[str]], blocked: Optional[List[str]]) -> bool:
+    """Post-hoc domain filter for backends that don't support it natively.
+    Returns True if the URL is blocked, False if it is allowed.
+    """
+    host = _extract_domain_from_url(url)
+    if not host:
+        return True
+    if blocked:
+        for d in blocked:
+            d = (d or "").lower().removeprefix("www.")
+            if d and (host == d or host.endswith("." + d)):
+                return True
+    if allowed:
+        is_allowed = False
+        for d in allowed:
+            d = (d or "").lower().removeprefix("www.")
+            if d and (host == d or host.endswith("." + d)):
+                is_allowed = True
+                break
+        if not is_allowed:
+            return True
+    return False
+
+
+def _current_month_year() -> str:
+    """Return the current month and year as e.g. ``"April 2026"``."""
+    try:
+        from tzlocal import get_localzone
+        now = _dt.datetime.now(get_localzone())
+    except Exception:  # pylint: disable=broad-except
+        now = _dt.datetime.now()
+    return now.strftime("%B %Y")
+
+
+def _extract_desc_from_pagemap(pagemap: dict[str, Any]) -> str:
+    """Extract description from pagemap metatags.
+    Collects ``description`` / ``og:description`` values out of CSE
+    pagemap metatags and joins them with newlines.
+    """
+    try:
+        metatags = pagemap.get("metatags") or []
+        if not isinstance(metatags, list):
+            return ""
+        descs: List[str] = []
+        for meta in metatags:
+            if not isinstance(meta, dict):
+                continue
+            desc = (meta.get("description") or meta.get("og:description") or "").strip()
+            if desc:
+                descs.append(desc)
+        return "\n".join(descs)
+    except Exception as ex:  # pylint: disable=broad-except
+        logger.warning("Failed to extract description from pagemap: %s", ex)
+        return ""
+
+
+class WebSearchTool(BaseTool):
+    """LLM tool that searches the public web.
+
+    The WebSearchTool enables LLM agents to search the public web using major search engines
+    such as DuckDuckGo (default, no API key required) and Google Custom Search (API key required).
+    It retrieves up-to-date information including titles, URLs, and content snippets, and also
+    provides instant-answer summaries when available (e.g., via DuckDuckGo). This tool is best
+    used for queries about recent events, new releases, factual lookups, or definitions that benefit
+    from authoritative and citable sources. Results are automatically filtered by site/domain
+    according to user or system configuration. When using this tool, answers should cite all retrieved
+    sources as Markdown hyperlinks in the final output.
+
+    Args:
+        provider: Backend name, ``"duckduckgo"`` (default) or ``"google"``.
+        api_key: Google CSE API key; falls back to ``GOOGLE_CSE_API_KEY``.
+        engine_id: Google CSE engine id (``cx``); falls back to ``GOOGLE_CSE_ENGINE_ID``.
+        results_num: Default result count, clamped to ``[1, _MAX_COUNT]``.
+        snippet_len: Max snippet length, clamped to ``[1, _MAX_SNIPPET_LEN]``.
+        title_len: Max title length, clamped to ``[1, _MAX_TITLE_LEN]``.
+        timeout: HTTP timeout in seconds.
+        base_url: Override provider base URL (for tests / proxies).
+        user_agent: HTTP User-Agent header.
+        proxy: Optional HTTP proxy URL forwarded to httpx.
+        lang: Default language code for Google CSE (ignored by DDG).
+        http_client: Optional pre-built ``httpx.AsyncClient`` to reuse; caller owns its lifecycle.
+        dedup_urls: Collapse results with the same normalised URL (default ``True``).
+        filters_name / filters: forwarded to :class:`BaseTool`.
+    """
+
+    def __init__(
+        self,
+        *,
+        provider: ProviderType = "duckduckgo",
+        api_key: Optional[str] = None,
+        engine_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        user_agent: str = "trpc-agent-python-websearch/1.0",
+        proxy: Optional[str] = None,
+        lang: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        results_num: int = _DEFAULT_RESULTS_NUM,
+        snippet_len: int = _DEFAULT_SNIPPET_LEN,
+        title_len: int = _DEFAULT_TITLE_LEN,
+        timeout: float = _DEFAULT_TIMEOUT,
+        dedup_urls: bool = True,
+        ddg_extra_params: Optional[dict[str, Any]] = None,
+        google_extra_params: Optional[dict[str, Any]] = None,
+        filters_name: Optional[List[str]] = None,
+        filters: Optional[List[BaseFilter]] = None,
+    ) -> None:
+
+        super().__init__(
+            name="websearch",
+            description=_BASE_DESCRIPTION,
+            filters_name=filters_name,
+            filters=filters,
+        )
+
+        self._provider: ProviderType = provider
+        self._api_key = api_key or os.environ.get("GOOGLE_CSE_API_KEY", "")
+        self._engine_id = engine_id or os.environ.get("GOOGLE_CSE_ENGINE_ID", "")
+        self._results_num = max(1, min(int(results_num), _MAX_COUNT))
+        self._snippet_len = max(1, min(int(snippet_len), _MAX_SNIPPET_LEN))
+        self._title_len = max(1, min(int(title_len), _MAX_TITLE_LEN))
+        self._timeout = float(timeout)
+        self._base_url = base_url or (_GOOGLE_BASE_URL if provider == "google" else _DDG_BASE_URL)
+        self._user_agent = user_agent
+        self._proxy = proxy
+        self._lang = lang
+        self._http_client = http_client
+        self._dedup_urls = bool(dedup_urls)
+        self._ddg_extra_params = ddg_extra_params or {}
+        self._google_extra_params = google_extra_params or {}
+
+        if provider == "google" and not (self._api_key and self._engine_id):
+            logger.warning("WebSearchTool: provider='google' but api_key or "
+                           "engine_id is missing; calls will return an error.")
+
+    @override
+    def _get_declaration(self) -> FunctionDeclaration:
+        return FunctionDeclaration(
+            name="websearch",
+            description=_BASE_DESCRIPTION,
+            parameters=Schema(
+                type=Type.OBJECT,
+                properties={
+                    "query":
+                    Schema(
+                        type=Type.STRING,
+                        description=("Required. Search query to send to the provider. Min 2 chars. "
+                                     "Include year/version for recent topics. "
+                                     "Example: 'Python 3.13 release notes', 'OpenAI GPT-5 pricing 2026', "
+                                     "'FastAPI websocket auth', 'vector database definition'."),
+                    ),
+                    "count":
+                    Schema(
+                        type=Type.INTEGER,
+                        description=(f"Optional. Max results to return, 1-{_MAX_COUNT} (clamped). "
+                                     f"Default: {self._results_num}. Prefer small values to save context. "
+                                     f"Example: 3, 5."),
+                        minimum=1,
+                        maximum=_MAX_COUNT,
+                    ),
+                    "allowed_domains":
+                    Schema(
+                        type=Type.ARRAY,
+                        items=Schema(type=Type.STRING),
+                        description=("Optional. Whitelist of domains, host only (subdomain-aware, "
+                                     "'www.' stripped). Mutually exclusive with blocked_domains. "
+                                     "Default: None. "
+                                     "Example: ['python.org'], ['github.com', 'stackoverflow.com']."),
+                    ),
+                    "blocked_domains":
+                    Schema(
+                        type=Type.ARRAY,
+                        items=Schema(type=Type.STRING),
+                        description=("Optional. Blacklist of domains (same matching as allowed_domains). "
+                                     "Mutually exclusive with allowed_domains. Default: None. "
+                                     "Example: ['pinterest.com'], ['content-farm.net']."),
+                    ),
+                    "lang":
+                    Schema(
+                        type=Type.STRING,
+                        description=("Optional. Language hint for the provider (Google CSE 'hl'); "
+                                     "ignored by DuckDuckGo. Default: tool-level lang or unset. "
+                                     "Example: 'en', 'zh-CN', 'ja'."),
+                    ),
+                },
+                required=["query"],
+            ),
+        )
+
+    @override
+    async def process_request(
+        self,
+        *,
+        tool_context: InvocationContext,
+        llm_request: LlmRequest,
+    ) -> None:
+        """Register the declaration and inject behavioural mandates."""
+        await super().process_request(tool_context=tool_context, llm_request=llm_request)
+        instruction = ("You have access to the `websearch` tool which performs live web searches.\n"
+                       "\n"
+                       "CRITICAL REQUIREMENT — you MUST follow this:\n"
+                       "  - After answering the user's question, you MUST include a 'Sources:' "
+                       "section at the end of your response.\n"
+                       "  - In the Sources section, list all relevant URLs from the search "
+                       "results as markdown hyperlinks: `[Title](URL)`.\n"
+                       "  - This is MANDATORY — never skip including sources, and never "
+                       "fabricate URLs (only cite URLs returned by the tool).\n"
+                       "  - Example format:\n"
+                       "\n"
+                       "    [Your answer here]\n"
+                       "\n"
+                       "    Sources:\n"
+                       "    - [Source Title 1](https://example.com/1)\n"
+                       "    - [Source Title 2](https://example.com/2)\n"
+                       "\n"
+                       f"IMPORTANT — use the correct year in search queries:\n"
+                       f"  - The current month is {_current_month_year()}. You MUST use this "
+                       f"year when searching for recent information, documentation, or current "
+                       f"events.\n"
+                       f"  - Example: if the user asks for 'latest React docs', search for "
+                       f"'React documentation in the current year', NOT last year.\n"
+                       "\n"
+                       "Usage notes:\n"
+                       "  - Domain filtering is supported via `allowed_domains` / "
+                       "`blocked_domains` (mutually exclusive).\n"
+                       "  - Each `websearch` call issues exactly one search request; prefer "
+                       "a single well-formed query over multiple narrow ones.")
+        llm_request.append_instructions([instruction])
+
+    @override
+    async def _run_async_impl(self, *, tool_context: InvocationContext, args: dict[str, Any]) -> Any:
+        query = (args.get("query") or "").strip()
+        if len(query) < 2:
+            return {"error": f"INVALID_QUERY: query must be at least {2} characters"}
+
+        allowed, err = _normalise_domains(args.get("allowed_domains"), "allowed_domains")
+        if err:
+            return {"error": "Allowed_domains_error: " + err}
+        blocked, err = _normalise_domains(args.get("blocked_domains"), "blocked_domains")
+        if err:
+            return {"error": "Blocked_domains_error: " + err}
+        if allowed and blocked:
+            return {
+                "error": ("INVALID_ARGS: cannot specify both allowed_domains "
+                          "and blocked_domains in the same request")
+            }
+
+        # number of results to return
+        count = args.get("count")
+        try:
+            n = int(count) if count is not None else self._results_num
+        except (TypeError, ValueError):
+            n = self._results_num
+        n = max(1, min(n, _MAX_COUNT))
+
+        lang = (args.get("lang") or self._lang or "").strip() or None
+
+        try:
+            if self._provider == "duckduckgo":
+                result = await self._search_duckduckgo(query, n, allowed, blocked)
+            else:
+                result = await self._search_google(query, n, allowed, blocked, lang)
+        except httpx.HTTPError as e:
+            logger.warning("WebSearchTool HTTP error (%s): %s", self._provider, e)
+            return {"error": f"HTTP_ERROR: {e}", "provider": self._provider, "query": query}
+        except Exception as e:  # pylint: disable=broad-except
+            logger.error("WebSearchTool unexpected error (%s): %s", self._provider, e)
+            return {"error": f"SEARCH_ERROR: {e}", "provider": self._provider, "query": query}
+
+        # Return a plain dict so downstream JSON-serialisation
+        return result.model_dump()
+
+    def _get_client(self) -> httpx.AsyncClient:
+        """Return an httpx AsyncClient."""
+        if self._http_client is not None:
+            return self._http_client
+        return httpx.AsyncClient(
+            timeout=self._timeout,
+            proxy=self._proxy,
+            headers={"User-Agent": self._user_agent},
+        )
+
+    async def _get_json(self, url: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Issue a GET and decode the JSON body."""
+        client = self._get_client()
+        close = self._http_client is None
+        try:
+            resp = await client.get(
+                url,
+                params=params,
+                timeout=self._timeout,
+                headers={"User-Agent": self._user_agent},
+            )
+            resp.raise_for_status()
+            return resp.json()
+        finally:
+            if close:
+                await client.aclose()
+
+    async def _search_duckduckgo(
+        self,
+        query: str,
+        n: int,
+        allowed: Optional[List[str]],
+        blocked: Optional[List[str]],
+    ) -> WebSearchResult:
+        """Hit the DDG Instant Answer API."""
+        params = {
+            # search query
+            "q": query,
+            # return JSON format
+            "format": "json",
+            # no HTML in the response, only text
+            "no_html": "1",
+            # skip disambiguation, only return the most related topics result
+            "skip_disambig": "1",
+        }
+        params.update(self._ddg_extra_params)
+
+        data = await self._get_json(self._base_url, params=params)
+
+        # Aggregate the free-text instant answer fields into a summary.
+        summary_parts: List[str] = []
+        if ans := (data.get("Answer") or "").strip():
+            summary_parts.append(ans)
+        abstract_text = (data.get("AbstractText") or "").strip()
+        abstract_source = (data.get("AbstractSource") or "").strip()
+        if abstract_text:
+            summary_parts.append(f"{abstract_text} (source: {abstract_source})" if abstract_source else abstract_text)
+        definition_text = (data.get("Definition") or "").strip()
+        definition_source = (data.get("DefinitionSource") or "").strip()
+        if definition_text:
+            summary_parts.append(
+                f"{definition_text} (source: {definition_source})" if definition_source else definition_text)
+        summary = "\n".join(summary_parts)
+
+        heading = (data.get("Heading") or "").strip() or query
+
+        hits: List[SearchHit] = []
+        # Track deduplicated URLs to avoid re-citing the same source.
+        seen: set[str] = set()
+
+        def _add_hit(url: str, title: str, snippet: str):
+            """Append a SearchHit after filter + dedup checks."""
+            url = (url or "").strip()
+            if not url:
+                return False
+            if _is_blocked(url, allowed, blocked):
+                return False
+            if self._dedup_urls:
+                key = _dedup_key(url)
+                if key in seen:
+                    return False
+                seen.add(key)
+            hits.append(
+                SearchHit(
+                    title=_truncate(title or heading, self._title_len),
+                    url=url,
+                    snippet=_truncate(snippet, self._snippet_len),
+                ))
+
+        # AbstractURL — canonical source of the abstract (e.g. Wikipedia).
+        abstract_url = (data.get("AbstractURL") or "").strip()
+        if abstract_url and len(hits) < n:
+            _add_hit(abstract_url, heading, abstract_text or summary)
+
+        # DefinitionURL — dictionary source.
+        definition_url = (data.get("DefinitionURL") or "").strip()
+        if definition_url and len(hits) < n:
+            _add_hit(definition_url, heading, definition_text or summary)
+
+        # Results — genuine external links DDG returns for the query
+        for item in data.get("Results") or []:
+            if len(hits) >= n:
+                break
+            if not isinstance(item, dict):
+                continue
+            url = (item.get("FirstURL") or "").strip()
+            text = (item.get("Text") or "").strip()
+            if not url or not text:
+                continue
+            _add_hit(
+                url,
+                _extract_title_from_ddg_topic(text, self._title_len),
+                text,
+            )
+
+        # RelatedTopics
+        for topic in data.get("RelatedTopics") or []:
+            if len(hits) >= n:
+                break
+            # Nested "Topics" groups — flatten one level.
+            inner = topic.get("Topics") if isinstance(topic, dict) else None
+            candidates = inner if isinstance(inner, list) else [topic]
+            for item in candidates:
+                if len(hits) >= n:
+                    break
+                if not isinstance(item, dict):
+                    continue
+                url = (item.get("FirstURL") or "").strip()
+                text = (item.get("Text") or "").strip()
+                if not url or not text:
+                    continue
+                _add_hit(
+                    url,
+                    _extract_title_from_ddg_topic(text, self._title_len),
+                    text,
+                )
+
+        # Fallback: if DDG had nothing useful but did give a summary, at
+        # least surface the search page URL so the model can cite *something*.
+        if not hits and summary:
+            hits.append(
+                SearchHit(
+                    title=_truncate(query, self._title_len),
+                    url=f"https://duckduckgo.com/?q={quote_plus(query)}",
+                    snippet=_truncate(summary, self._snippet_len),
+                ))
+
+        return WebSearchResult(
+            query=query,
+            provider="duckduckgo",
+            results=hits,
+            summary=summary,
+        )
+
+    async def _search_google(
+        self,
+        query: str,
+        n: int,
+        allowed: Optional[List[str]],
+        blocked: Optional[List[str]],
+        lang: Optional[str],
+    ) -> WebSearchResult:
+        """Hit the Google Custom Search API."""
+        if not (self._api_key and self._engine_id):
+            return WebSearchResult(
+                query=query,
+                provider="google",
+                results=[],
+                summary=("Google provider is not configured: set api_key + "
+                         "engine_id (or GOOGLE_CSE_API_KEY + GOOGLE_CSE_ENGINE_ID)."),
+            )
+
+        google_n = min(n, _GOOGLE_MAX_NUM)
+        params: dict[str, Any] = {
+            "key": self._api_key,
+            "cx": self._engine_id,
+            # search query
+            "q": query,
+            # number of results to return (Google CSE caps at 10 per request)
+            "num": google_n,
+        }
+        # language hint for the search provider
+        if lang:
+            params["hl"] = lang
+
+        # Google CSE only supports ONE siteSearch value. Use the server-side
+        # filter only when exactly one domain is requested — this keeps the
+        # common single-domain case fast. For multiple domains, skip the
+        # server-side filter entirely and rely on the client-side
+        if allowed and len(allowed) == 1:
+            params["siteSearch"] = allowed[0]
+            params["siteSearchFilter"] = "i"
+        elif blocked and len(blocked) == 1:
+            params["siteSearch"] = blocked[0]
+            params["siteSearchFilter"] = "e"
+
+        params.update(self._google_extra_params)
+
+        data = await self._get_json(self._base_url, params=params)
+
+        # Surface API-level errors cleanly.
+        if err := data.get("error"):
+            msg = err.get("message") if isinstance(err, dict) else str(err)
+            return WebSearchResult(
+                query=query,
+                provider="google",
+                results=[],
+                summary=f"Google Search API error: {msg}",
+            )
+
+        hits: List[SearchHit] = []
+        seen: set[str] = set()
+        for item in data.get("items") or []:
+            url = (item.get("link") or "").strip()
+            if _is_blocked(url, allowed, blocked):
+                continue
+            if self._dedup_urls:
+                key = _dedup_key(url)
+                if key in seen:
+                    continue
+                seen.add(key)
+            snippet = (item.get("snippet") or "").strip()
+            # Enrich snippet with metatag descriptions when CSE has them
+            # for denser grounding context with low token overhead.
+            extra = _extract_desc_from_pagemap(item.get("pagemap") or {})
+            if extra and extra not in snippet:
+                snippet = f"{snippet}\n{extra}" if snippet else extra
+            hits.append(
+                SearchHit(
+                    title=_truncate(item.get("title") or "", self._title_len),
+                    url=url,
+                    snippet=_truncate(snippet, self._snippet_len),
+                ))
+            if len(hits) >= n:
+                break
+
+        # CSE may spell-correct the query; surface the effective query in the summary.
+        effective = ""
+        try:
+            reqs = (data.get("queries") or {}).get("request") or []
+            if reqs:
+                effective = (reqs[0].get("searchTerms") or "").strip()
+        except Exception:  # pylint: disable=broad-except
+            effective = ""
+        summary = (f"(Effective query: {effective})" if effective and effective != query else "")
+
+        return WebSearchResult(
+            query=query,
+            provider="google",
+            results=hits,
+            summary=summary,
+        )