[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.
Python aifaissgpt-osslangchainllama-indexllmlocalstorageoffline-firstollamaprivacypythonragretrieval-augmented-generationvector-databasevector-searchvectors
feat: add web search and acting capabilities to ReAct agent
ArshadJafri3a1345ac8d90
diff --git a/docs/react_agent.md b/docs/react_agent.mdindex 671b362..483ff11 100644--- a/docs/react_agent.md+++ b/docs/react_agent.md@@ -5,12 +5,14 @@The LEANN ReAct (Reasoning + Acting) Agent enables **multiturn retrieval and reasoning** for complex queries that require multiple search iterations. Unlike the standard `leann ask` command which performs a single search and answer, the ReAct agent can:- **Reason** about what information is needed-- **Act** by performing targeted searches+- **Act** by performing targeted searches (both local and web)- **Observe** the results and iterate- **Answer** based on all gathered contextThis is particularly useful for questions that require:- Multiple pieces of information from different parts of your index+- **Combining local knowledge with current web information**+- **Accessing external documentation or latest updates**- Iterative refinement of search queries- Complex reasoning that builds on previous findings@@ -19,7 +21,10 @@ This is particularly useful for questions that require:The ReAct agent follows a **Thought → Action → Observation** loop:1. **Thought**: The agent analyzes the question and determines what information is needed-2. **Action**: The agent performs a search query based on its reasoning+2. **Action**: The agent performs a search based on its reasoning, choosing from:+ - `leann_search("query")` - Search your local private knowledge base+ - `web_search("query")` - Search the public internet for current information+ - `visit_page("url")` - Fetch and read the full content of a specific web page3. **Observation**: The agent reviews the search results4. **Iteration**: The process repeats until the agent has enough information or reaches the maximum iteration limit5. **Final Answer**: The agent synthesizes all gathered information into a comprehensive answer@@ -51,16 +56,16 @@ leann react my-index "What are the main features discussed?" \- `--max-iterations`: Maximum number of search iterations (default: `5`)- `--api-base`: Base URL for OpenAI-compatible APIs- `--api-key`: API key for cloud LLM providers+- `--serper-api-key`: Serper API key for web search (enables web_search action)+- `--jina-api-key`: Jina AI API key for enhanced page content fetching (optional)### Python API```python-from leann import create_react_agent, LeannSearcher+from leann import create_react_agent+import os-# Create a searcher-searcher = LeannSearcher(index_path="path/to/index.leann")--# Create the ReAct agent+# Create the ReAct agent with web search enabledagent = create_react_agent(index_path="path/to/index.leann",llm_config={@@ -68,18 +73,125 @@ agent = create_react_agent("model": "qwen3:8b","host": "http://localhost:11434" # optional},- max_iterations=5+ max_iterations=5,+ serper_api_key=os.getenv("SERPER_API_KEY") # Enable web search)-# Run the agent-answer = agent.run("What are the main topics covered in the documentation?", top_k=5)+# Run the agent - it will automatically choose between local and web search+answer = agent.run("What are the latest Python 3.13 features?", top_k=5)print(answer)-# Access search history+# Access search history to see which actions were usedif agent.search_history:print(f"\nSearch History ({len(agent.search_history)} iterations):")for entry in agent.search_history:- print(f" {entry['iteration']}. {entry['action']} ({entry['results_count']} results)")+ action_type = "Web" if "web_search" in entry['action'] else "Local"+ print(f" {entry['iteration']}. [{action_type}] {entry['action']} ({entry['results_count']} results)")+```++## Web Search Integration++The ReAct agent can seamlessly combine searches from your local knowledge base with real-time web searches, enabling it to answer questions that require both private and public information.++### Enabling Web Search++**Get a Serper API Key:**+1. Visit https://serper.dev/+2. Sign up for a free account (2,500 queries/month free)+3. Copy your API key++**Use web search via CLI:**+```bash+# Set API key as environment variable+export SERPER_API_KEY="your-api-key-here"++# Run with web search enabled+leann react my-index "What are the latest AI developments?" \+ --llm ollama \+ --model qwen3:8b \+ --serper-api-key $SERPER_API_KEY+```++**Or pass the key directly:**+```bash+leann react my-index "question" \+ --llm ollama \+ --serper-api-key sk-your-key-here+```++### How the Agent Chooses Actions++The agent intelligently decides which action to use based on the question:++- **`leann_search("query")`** - For questions about your private data:+ - Code in your repository+ - Internal documentation+ - Chat history, notes, or private files+ - Project-specific details++- **`web_search("query")`** - For questions requiring current/public information:+ - Latest news or updates+ - Current best practices+ - Public documentation+ - General knowledge or concepts++- **`visit_page("url")`** - To read specific web pages:+ - When a URL is mentioned in the question+ - When search results contain a relevant link+ - To get detailed information from a specific source++### Web Search Examples++**Example 1: Pure Web Search**+```bash+leann react my-index "What are the latest features in Python 3.13?" \+ --serper-api-key $SERPER_API_KEY+```+Agent actions:+1. `web_search("Python 3.13 features latest")` → Gets current information from the web+2. Returns answer based on web results++**Example 2: Combining Local + Web**+```bash+leann react my-index "Compare our authentication implementation with current security best practices" \+ --serper-api-key $SERPER_API_KEY \+ --max-iterations 8+```+Agent actions:+1. `leann_search("authentication implementation")` → Finds your code+2. `web_search("authentication security best practices 2025")` → Gets current standards+3. Compares and provides recommendations++**Example 3: Following Web Links**+```bash+leann react my-index "What does the official Python async documentation say about event loops?" \+ --serper-api-key $SERPER_API_KEY \+ --jina-api-key $JINA_API_KEY+```+Agent actions:+1. `web_search("Python async event loop documentation")` → Finds official docs link+2. `visit_page("https://docs.python.org/3/library/asyncio-eventloop.html")` → Reads full page+3. Answers based on official documentation++### Web Search Output++When using web search, you'll see indicators in the output:++```+🤖 Starting ReAct agent with index 'my-index'...++--- Iteration 1/5 ---+💭 Thought: I need current information about Python 3.13+🔍 Action: web_search("Python 3.13 new features")++[Web Result 1]+Title: Python 3.13 Release Highlights+Link: https://docs.python.org/3.13/whatsnew/3.13.html+Snippet: Python 3.13 introduces a new interactive interpreter...++--- Iteration 2/5 ---+💭 Thought: I have enough information+✅ Final Answer: Python 3.13 introduces several key features...```## Example Use Cases@@ -222,11 +334,17 @@ LEANN is a vector database with several key features:## Future Enhancements-This is the first implementation (1/N) of Deep-Research integration. Future enhancements may include:-- Web search integration for external information+This is part of ongoing Deep-Research integration. Current capabilities:+- ✅ Web search integration for external information (via Serper API)+- ✅ Page content fetching (via Jina AI Reader)+- ✅ Intelligent action selection between local and web search++Potential future enhancements:- More sophisticated reasoning strategies- Parallel search execution- Better query optimization+- Additional web search backends (Tavily, Bing, etc.)+- Caching of web search results## Related Documentationdiff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.pyindex 6d56669..e762f6c 100644--- a/packages/leann-core/src/leann/cli.py+++ b/packages/leann-core/src/leann/cli.py@@ -440,6 +440,12 @@ Examples:default=None,help="API key for cloud LLM providers (OpenAI, Anthropic)",)+ react_parser.add_argument(+ "--serper-api-key", type=str, default=None, help="Serper API key for web search"+ )+ react_parser.add_argument(+ "--jina-api-key", type=str, default=None, help="Jina API key for content parsing"+ )# List commandsubparsers.add_parser("list", help="List all indexes")@@ -1830,6 +1836,8 @@ Examples:index_path=index_path,llm_config=llm_config,max_iterations=args.max_iterations,+ serper_api_key=args.serper_api_key,+ jina_api_key=args.jina_api_key,)print(f"\n🔍 Question: {query}\n")diff --git a/packages/leann-core/src/leann/react_agent.py b/packages/leann-core/src/leann/react_agent.pyindex 1a63876..2544002 100644--- a/packages/leann-core/src/leann/react_agent.py+++ b/packages/leann-core/src/leann/react_agent.py@@ -17,6 +17,7 @@ from typing import Anyfrom .api import LeannSearcher, SearchResultfrom .chat import LLMInterface, get_llm+from .web_search import WebSearcherlogger = logging.getLogger(__name__)@@ -38,6 +39,8 @@ class ReActAgent:llm: LLMInterface | None = None,llm_config: dict[str, Any] | None = None,max_iterations: int = 5,+ serper_api_key: str | None = None,+ jina_api_key: str | None = None,):"""Initialize the ReAct agent.@@ -55,6 +58,7 @@ class ReActAgent:self.llm = llmself.max_iterations = max_iterationsself.search_history: list[dict[str, Any]] = []+ self.web_searcher = WebSearcher(api_key=serper_api_key, jina_api_key=jina_api_key)def _format_search_results(self, results: list[SearchResult]) -> str:"""Format search results as a string for the LLM."""@@ -71,11 +75,20 @@ class ReActAgent:self, question: str, iteration: int, previous_observations: list[str]) -> str:"""Create the ReAct prompt for the LLM."""- prompt = f"""You are a helpful assistant that answers questions by searching through a knowledge base.+ prompt = f"""You are a helpful assistant that answers questions by searching through a knowledge base AND the internet.Question: {question}-You can search the knowledge base by using the action: search("query")+You have access to two tools:+1. leann_search("query"): Search the local private knowledge base (code, docs, history).+2. web_search("query"): Search the public internet for up-to-date information.+3. visit_page("url"): Read the full content of a specific URL.++Strategies:+- Use `leann_search` for internal project details, code implementation, or private history.+- Use `web_search` for public documentation, latest news, or general concepts.+- Use `visit_page` if you found a relevant link but need the full details.+- You can Combine both!Previous observations:"""@@ -88,13 +101,23 @@ Previous observations:prompt += f"""Current iteration: {iteration}/{self.max_iterations}-Think step by step:-1. If you need more information, use search("your search query")-2. If you have enough information, provide your final answer+Think step by step.+Format your response EXACTLY like this:-Format your response as:Thought: [your reasoning]-Action: search("query") OR Final Answer: [your answer]+Action: web_search("your query")++OR++Thought: [your reasoning]+Action: leann_search("your query")++OR++Thought: [your reasoning]+Action: Final Answer: [your answer]++IMPORTANT: You MUST start a new line with "Action:" to trigger a tool."""return prompt@@ -131,30 +154,17 @@ Action: search("query") OR Final Answer: [your answer]action = Noneelif "Action:" in response:action_part = response.split("Action:")[1].strip()- # Try to extract search query- if 'search("' in action_part:- start = action_part.find('search("') + 7- end = action_part.find('")', start)- if end != -1:- action = action_part[start:end]- else:- # Try with single quote- end = action_part.find('")', start)- if end != -1:- action = action_part[start:end]- elif "search(" in action_part:- # Handle without quotes- start = action_part.find("search(") + 7- end = action_part.find(")", start)- if end != -1:- action = action_part[start:end].strip('"').strip("'")- elif "search(" in response.lower():- # Try to extract search query even if format is slightly different++ # Use regex to extract action - handles all cases correctlyimport re- match = re.search(r'search\(["\']([^"\']+)["\']\)', response, re.IGNORECASE)+ # Try to match web_search, leann_search, search, or visit_page+ match = re.search(+ r'(web_search|leann_search|visit_page|search)\(["\']([^"\']+)["\']\)',+ action_part,+ )if match:- action = match.group(1)+ action = f"{match.group(1)}:{match.group(2)}"return thought, action@@ -218,13 +228,42 @@ Action: search("query") OR Final Answer: [your answer]return final_answer# Perform search action- logger.info(f'🔍 Action: search("{action}")')- results = self.search(action, top_k=top_k)+ logger.info(f"🔍 Action: {action}")++ results_count = 0++ if action.startswith("web_search:"):+ query = action.split(":", 1)[1]+ # Perform web search directly to get objects and count+ web_results = self.web_searcher.search(query, top_k=top_k)+ results_count = len(web_results)++ if not web_results:+ observation = "No web results found."+ else:+ formatted = []+ for i, res in enumerate(web_results, 1):+ formatted.append(+ f"[Web Result {i}]\nTitle: {res['title']}\nLink: {res['link']}\nSnippet: {res['snippet']}"+ )+ observation = "\n\n".join(formatted)++ elif action.startswith("visit_page:"):+ url = action.split(":", 1)[1]+ content = self.web_searcher.get_page_content(url)+ results_count = 1+ # Truncate content to avoid token limit overflow (adjust limit as needed)+ observation = f"Content of {url}:\n{content[:15000]}"++ else:+ # Default to local search+ query = action.split(":", 1)[1] if ":" in action else action+ results = self.search(query, top_k=top_k)+ results_count = len(results)+ observation = self._format_search_results(results)- # Format observation- observation = self._format_search_results(results)previous_observations.append(observation)- all_context.append(f"Search: {action}\n{observation}")+ all_context.append(f"Action: {action}\n{observation}")# Store in historyself.search_history.append(@@ -232,12 +271,12 @@ Action: search("query") OR Final Answer: [your answer]"iteration": iteration,"thought": thought,"action": action,- "results_count": len(results),+ "results_count": results_count,})# If no results, might want to stop early- if not results and iteration >= 2:+ if results_count == 0 and iteration >= 2:logger.warning("No results found, asking LLM for final answer...")final_prompt = f"""Based on the previous searches, provide your best answer to the question.@@ -270,6 +309,8 @@ def create_react_agent(index_path: str,llm_config: dict[str, Any] | None = None,max_iterations: int = 5,+ serper_api_key: str | None = None,+ jina_api_key: str | None = None,**searcher_kwargs,) -> ReActAgent:"""@@ -285,4 +326,10 @@ def create_react_agent(ReActAgent instance"""searcher = LeannSearcher(index_path, **searcher_kwargs)- return ReActAgent(searcher=searcher, llm_config=llm_config, max_iterations=max_iterations)+ return ReActAgent(+ searcher=searcher,+ llm_config=llm_config,+ max_iterations=max_iterations,+ serper_api_key=serper_api_key,+ jina_api_key=jina_api_key,+ )diff --git a/packages/leann-core/src/leann/web_search.py b/packages/leann-core/src/leann/web_search.pynew file mode 100644index 0000000..7b9b9b7--- /dev/null+++ b/packages/leann-core/src/leann/web_search.py@@ -0,0 +1,68 @@+import json+import logging+import os+from typing import Any++import requests++logger = logging.getLogger(__name__)+++class WebSearcher:+ """Helper class for performing web searches via Serper API."""++ def __init__(self, api_key: str | None = None, jina_api_key: str | None = None):+ self.api_key = api_key or os.getenv("SERPER_API_KEY")+ self.jina_api_key = jina_api_key or os.getenv("JINA_API_KEY")+ if not self.api_key:+ logger.warning("No SERPER_API_KEY found. Web seach will fail")++ def search(self, query: str, top_k: int = 5) -> list[dict[str, Any]]:+ if not self.api_key:+ return [{"title": "Error", "link": "", "snippet": "Missing SERPER_API_KEY env var"}]++ url = "https://google.serper.dev/search"+ payload = json.dumps({"q": query, "num": top_k})+ headers = {"X-API-KEY": self.api_key, "Content-Type": "application/json"}++ try:+ response = requests.request("POST", url, headers=headers, data=payload)+ response.raise_for_status()+ data = response.json()++ results = []++ if "organic" in data:+ for item in data["organic"][:top_k]:+ results.append(+ {+ "title": item.get("title", ""),+ "link": item.get("link", ""),+ "snippet": item.get("snippet", ""),+ }+ )++ return results+ except Exception as e:+ logger.error(f"Web search failed: {e}")+ return [{"title": "Error", "link": "", "snippet": f"Web Search failed:{e!s}"}]++ def get_page_content(self, url: str) -> str:+ """+ Fetch page content using Jina AI (https://jina.ai/reader).+ """+ jina_url = f"https://r.jina.ai/{url}"++ # Use Jina API key if available for higher limits, but works without it+ headers = {"X-Return-Format": "markdown"}+ if self.jina_api_key:+ headers["Authorization"] = f"Bearer {self.jina_api_key}"++ try:+ logger.info(f"Fetching content from: {url}")+ response = requests.get(jina_url, headers=headers)+ response.raise_for_status()+ return response.text+ except Exception as e:+ logger.error(f"Failed to fetch content from {url}: {e}")+ return f"Error fetching content: {e!s}"