diff --git a/backend/docs/CONFIGURATION.md b/backend/docs/CONFIGURATION.md index 60554608ad..1832c6801b 100644 --- a/backend/docs/CONFIGURATION.md +++ b/backend/docs/CONFIGURATION.md @@ -983,6 +983,8 @@ tools: # api_key: $TAVILY_API_KEY # Optional ``` +Tavily search and fetch initialize their HTTPS clients on a worker thread so TLS trust loading does not block other agent runs. A tool cancelled during initialization closes its client before returning without sending a request. + For Tavily, `include_domains` and `exclude_domains` are deployment-only options read from the `web_search` tool entry and passed directly to `TavilyClient.search`. For a non-empty `include_domains`, DeerFlow also sends `include_domains_mode: filter` diff --git a/backend/packages/harness/deerflow/community/tavily/AGENTS.md b/backend/packages/harness/deerflow/community/tavily/AGENTS.md index 4547721ffe..db2a13df45 100644 --- a/backend/packages/harness/deerflow/community/tavily/AGENTS.md +++ b/backend/packages/harness/deerflow/community/tavily/AGENTS.md @@ -8,8 +8,10 @@ cd backend && python -m pytest tests -q -k "tavily" - **When no key resolves, pass an empty string to the SDK.** The SDK then never reads the raw `TAVILY_API_KEY` variable on its own. -- **Each tool owns its client for one call and closes it in `finally`**, also on - a request failure and on cancellation. +- **Each tool owns its client for one call.** Shield the task that builds the + client in a worker thread. On cancellation, wait for construction to finish + and close any returned client on the event loop before propagating cancellation. + Once construction completes normally, the request's `finally` closes the client. - **Domain filters are deployment settings from the `web_search` tool config.** The model-visible signature stays `query` and `time_range`. An explicit empty list means no restriction of that kind and is preserved. An absent key is diff --git a/backend/packages/harness/deerflow/community/tavily/tools.py b/backend/packages/harness/deerflow/community/tavily/tools.py index 35d32094d8..5d6b3975d2 100644 --- a/backend/packages/harness/deerflow/community/tavily/tools.py +++ b/backend/packages/harness/deerflow/community/tavily/tools.py @@ -11,6 +11,7 @@ from deerflow.community.search_time_range import SearchTimeRange from deerflow.community.url_safety import safe_public_result_url from deerflow.config import get_app_config from deerflow.config.tool_config import ToolConfig +from deerflow.utils.file_io import await_drained logger = logging.getLogger(__name__) @@ -32,6 +33,24 @@ def _get_tavily_client(tool_name: str = "web_search", config: ToolConfig | None return AsyncTavilyClient(api_key=api_key or "") +async def _open_tavily_client(tool_name: str = "web_search", config: ToolConfig | None = _UNSET) -> AsyncTavilyClient: + """Build the client off-loop and close it if construction is cancelled.""" + construction = asyncio.create_task(asyncio.to_thread(_get_tavily_client, tool_name, config)) + try: + return await asyncio.shield(construction) + except asyncio.CancelledError: + + async def close_after_construction() -> None: + try: + client = await construction + await client.close() + except Exception as exc: + logger.error("Tavily client cleanup after cancellation failed (%s)", type(exc).__name__) + + await await_drained(close_after_construction()) + raise + + def _response_objects(data: object, container: str) -> list[dict] | None: """Return the object entries of a Tavily response container, or None if malformed. @@ -79,7 +98,7 @@ async def web_search_tool(query: str, time_range: SearchTimeRange | None = None) search_kwargs["include_domains_mode"] = "filter" if time_range is not None: search_kwargs["time_range"] = time_range - client = _get_tavily_client(config=config) + client = await _open_tavily_client(config=config) try: res = await client.search(query, **search_kwargs) finally: @@ -111,7 +130,7 @@ async def web_fetch_tool(url: str) -> str: url: The URL to fetch the contents of. """ # Config resolution stats and hashes the config files; keep it off the event loop. - client = await asyncio.to_thread(_get_tavily_client, "web_fetch") + client = await _open_tavily_client("web_fetch") try: res = await client.extract([url]) finally: diff --git a/backend/tests/blocking_io/test_tavily_client_ssl.py b/backend/tests/blocking_io/test_tavily_client_ssl.py new file mode 100644 index 0000000000..055508eac7 --- /dev/null +++ b/backend/tests/blocking_io/test_tavily_client_ssl.py @@ -0,0 +1,130 @@ +"""Keep Tavily's synchronous TLS setup off the tool event loop.""" + +import asyncio +import ssl +import threading +from types import SimpleNamespace + +import httpx +import pytest +from tavily import AsyncTavilyClient + +from deerflow.community.tavily import tools + +pytestmark = pytest.mark.asyncio + +_URL = "https://example.com/article" + + +@pytest.fixture(autouse=True) +def tavily_config(monkeypatch): + monkeypatch.setenv("TAVILY_API_KEY", "synthetic-test-key") + monkeypatch.setattr(tools, "get_app_config", lambda: SimpleNamespace(get_tool_config=lambda name: None)) + + +@pytest.mark.parametrize( + ("tool", "args", "route", "result"), + [ + (tools.web_search_tool, {"query": "example"}, "/search", {"title": "Example", "url": _URL, "content": "search snippet"}), + (tools.web_fetch_tool, {"url": _URL}, "/extract", {"url": _URL, "raw_content": "page body"}), + ], + ids=["search", "fetch"], +) +async def test_tavily_builds_tls_off_loop(tool, args, route, result, monkeypatch): + loop_thread = threading.get_ident() + create_context = ssl.create_default_context + context_threads = [] + requests = [] + + def record_context(*args, **kwargs): + context_threads.append(threading.get_ident()) + return create_context(*args, **kwargs) + + async def respond(request): + assert threading.get_ident() == loop_thread + requests.append(request.url.path) + return httpx.Response(200, json={"results": [result]}) + + monkeypatch.setattr(ssl, "create_default_context", record_context) + transport = httpx.MockTransport(respond) + monkeypatch.setattr(httpx.AsyncHTTPTransport, "handle_async_request", lambda self, request: transport.handle_async_request(request)) + + assert _URL in await tool.ainvoke(args) + assert requests == [route] + assert context_threads + assert loop_thread not in context_threads + + +@pytest.mark.parametrize(("tool", "args"), [(tools.web_search_tool, {"query": "example"}), (tools.web_fetch_tool, {"url": _URL})], ids=["search", "fetch"]) +@pytest.mark.parametrize("cancel_count", [1, 2]) +@pytest.mark.parametrize("construction_fails", [False, True], ids=["client-built", "construction-failed"]) +async def test_tavily_drains_cancelled_client_construction(tool, args, cancel_count, construction_fails, monkeypatch, caplog): + loop = asyncio.get_running_loop() + loop_thread = threading.get_ident() + started = asyncio.Event() + release = threading.Event() + finished = asyncio.Event() + clients = [] + closed = [] + requests = [] + original_init = AsyncTavilyClient.__init__ + original_close = AsyncTavilyClient.close + sensitive_detail = "synthetic-sensitive-value" + + def gated_init(self, *args, **kwargs): + assert threading.get_ident() != loop_thread, "client construction must run off the event loop" + loop.call_soon_threadsafe(started.set) + try: + assert release.wait(10), "the constructor was never released" + if construction_fails: + raise RuntimeError(sensitive_detail) + original_init(self, *args, **kwargs) + clients.append(self) + finally: + loop.call_soon_threadsafe(finished.set) + + async def record_close(self): + await original_close(self) + closed.append(self._client.is_closed) + + async def refuse(self, request, **kwargs): + requests.append(request.url) + raise AssertionError("cancelled construction must not send a request") + + monkeypatch.setattr(AsyncTavilyClient, "__init__", gated_init) + monkeypatch.setattr(AsyncTavilyClient, "close", record_close) + monkeypatch.setattr(httpx.AsyncClient, "send", refuse) + + pending = asyncio.create_task(tool.coroutine(**args)) + start_waiter = asyncio.create_task(started.wait()) + try: + done, _ = await asyncio.wait({pending, start_waiter}, timeout=10, return_when=asyncio.FIRST_COMPLETED) + if pending in done: + await pending + assert start_waiter in done, "the constructor never started" + for _ in range(cancel_count): + pending.cancel() + await asyncio.sleep(0) # Let cancellation reach the tool while the constructor is gated. + assert not pending.done(), "cancellation escaped before the constructor finished" + + release.set() + with pytest.raises(asyncio.CancelledError): + await asyncio.wait_for(pending, timeout=10) + + assert requests == [] + if construction_fails: + assert closed == [] + assert "Tavily client cleanup after cancellation failed (RuntimeError)" in caplog.text + assert sensitive_detail not in caplog.text + else: + assert closed == [True] + finally: + release.set() + pending.cancel() + start_waiter.cancel() + await asyncio.gather(pending, start_waiter, return_exceptions=True) + if started.is_set(): + await asyncio.wait_for(finished.wait(), timeout=10) + for client in clients: + if not client._client.is_closed: + await original_close(client)