Architectural Overview

While the codebase is compact, the call chain involves complex interdependencies. Central to this system are two primary components:

• MindSearchAgent: Acts as the central coordinator or supervisor managing all subordinate agents.
• WebSearchGraph: Responsible for orchestrating the search path generated by the LLM.

The workflow initiates when a client sends a query via a FastAPI endpoint. The system initializes the agent, creating instances for the language model, action executors, and the protocol layer. Once active, the agent streams responses through the protocol layer to the LLM. When an action is detected—typically a request to execute code—the WebSearchGraph takes over. It spawns temporary SearcherAgents to handle specific sub-questions, feeds prompts to the LLM, and manages tool invocations via an ActionExecutor (such as BingBrowser). Results are queued and processed sequentially before being yielded back to the client as an SSE stream. The final return payload includes the tree structure nodes, adjacency lists, inner processing steps, and references.

Dependency Configuration and API Selection

The framework relies on a proprietary LLM invocation library named lagent. Notably, integration with services like Siliconflow for Qwen models requires modification, as out-of-the-box support may be lacking. Depending on your infrastructure needs, you may exclude heavy local inference dependencies such as lmdeploy and transformers from requirements.txt if utilizing remote APIs exclusively.

Four distinct search engine integrations are available: Google, DuckDuckGo, Brave, and Bing. Recommendations vary based on cost and throughput:

• GoogleSearch: Offers free trial credits via serper.dev registration; recommended for performance.
• DuckDuckGoSearch: Cost-free but requires proxy configuration.
• BingSearch: Requires Azure subscription and Visa card binding.
• BraveSearch: Provides monthly free quotas but enforces a concurrency limit of one.

Prompt Engineering for Model Compatibility

Out-of-the-box performance is optimized for models like GPT-4o and InternLM2.5. Supporting alternative models such as Qwen or DeepSeek necessitates adjustments to the prompt template file, specifically mindsearch_prompt.py. By modifying the GRAPH_PROMPT_CN variable, developers can inject examples that guide the LLM toward valid output formats.

Key constraints enforced via prompting include:

1. Singular Focus: Each search node must address exactly one question to avoid ambiguity.
2. No Hallucination: Agents must await code execution results rather than fabricating outcomes.
3. No Redundancy: Avoid repeating questions; iterate on existing context instead.
4. Single Block Output: Emit only one code block per message cycle.
5. Tagging Protocol: Enclose code within interpreter tags followed by <|action_end|>.
6. Node Linking: Every code segment must link a node to an edge and conclude by retrieving the result.
7. Termination Condition: The final node must be named 'response' and must be added independently of other operations.

An implementation example demonstrates the sequential building of the graph:

## Example Graph Construction Flow

# 1. Initialize the graph and root node
graph = WebSearchGraph()
graph.add_root_node(node_content="AI Advancements?", node_name="root")

# 2. Define intermediate queries
graph.add_node(node_name="key_areas", node_content="Key AI Research Domains?")
graph.add_edge(start_node="key_areas", end_node="trends")

# 3. Retrieve data explicitly
graph.node("key_areas")

# 4. Finalize with response node
graph.add_response_node(node_name="response")
graph.add_edge(start_node="trends", end_node="response")

A critical finding is that omitting graph.node() prevents the LLM from accessing agent-derived information, leading to hallucinated answers. Additionally, certain models like InternLM2.5 appear to have hard-coded imports for WebSearchGraph internally, which explains their seamless integration compared to external models.

Debugging Initialization Race Conditions

A known issue involves premature termination where the search stops before reaching the final response node, despite valid code generation. This behavior stems from asynchronous threads completing before the graph object is fully initialized in the local dictionary. To resolve this, the initialization logic in mindsearch_agent.py must enforce a wait state for the graph object.

The following patch introduces a retry mechanism to ensure thread safety before proceeding with node processing:

import time
from collections import defaultdict

class MindSearchAgent(BaseAgent):
    # ... existing initialization code ...

    def run_code(self, command):
        # Existing threading logic here
        producer_thread.start()

        # Ensure the graph instance is ready before continuing
        graph_obj = None
        attempts = 0
        max_retries = 10
        
        while attempts < max_retries:
            graph_obj = self.local_dict.get('graph')
            if graph_obj:
                break
            time.sleep(0.1)
            attempts += 1
        
        if not graph_obj:
            raise RuntimeError("Initialization failed: graph object not created in time")

        # Continue with response parsing logic
        responses = defaultdict(list)
        ordered_nodes = []
        active_node = None