Skip to content

armgit / LEANN

Public Imported from GitHub
0

[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.

feat: add web search and acting capabilities to ReAct agent

ArshadJafri3a1345ac8d90
diff --git a/docs/react_agent.md b/docs/react_agent.md
index 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 context
This 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 page
3. **Observation**: The agent reviews the search results
4. **Iteration**: The process repeats until the agent has enough information or reaches the maximum iteration limit
5. **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 enabled
agent = 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 used
if 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 Documentation
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index 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 command
subparsers.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.py
index 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 Any
from .api import LeannSearcher, SearchResult
from .chat import LLMInterface, get_llm
+from .web_search import WebSearcher
logger = 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 = llm
self.max_iterations = max_iterations
self.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 = None
elif "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 correctly
import 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 history
self.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.py
new file mode 100644
index 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}"