# sjtu-sai-agents/browse-master architecture

> Architecture diagram of the GitHub repository sjtu-sai-agents/browse-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sjtu-sai-agents/browse-master
- Repository: https://github.com/sjtu-sai-agents/browse-master

## Overview

##### Project Type and Purpose
- BrowseMaster is an open-source, LLM-based “Planner–Executor” web-browsing agent.
- Purpose: Given a user query, it uses a planner LLM to create a high-level search strategy, then an executor LLM plus code-based search primitives to run thousands of page queries, decide when to replan, and produce a final answer.

##### File Structure
- Entry point: `agent.py` orchestrates the end-to-end pipeline.
- Configuration:
- `config/model_config.yaml` holds model endpoint URLs (DeepSeek-R1, etc.).
- `config/r1_tool.jinja` is a Jinja template for wrapping tool calls.
- Core package: `llm_agent/`
- `base_agent.py`: LLM invocation wrapper.
- `context.py`: Maintains conversation state, memory, and confidence scores.
- `tools/tool_manager.py`: Exposes primitives (`batch_search`, `generate_keywords`, `check_condition`) to the executor.
- `utils.py`: Shared helpers (parsing, logging, metrics).
- Prompts: `prompts/*.txt` define planner & executor system messages and prefixes.
- Logs: `logs/examples.jsonl` captures sample runs.

##### README for Additional Insights
- Emphasizes a two-phase architecture:
1) Planner – high-level strategy generation
2) Executor – code-driven search primitives + confidence-guided replanning
- Mentions external dependencies: local “mcp_sandbox” for safe code execution, and a Toolbox service (toolbox URL).

##### Planner Module Deep Dive
- Inputs: user query, context (history, previous plans)
- Process: load `prompts/planner_prefix.txt` + `prompts/planner_prompt.txt`, fill in context via Jinja
- Invoke base_agent to call LLM endpoint (DeepSeek-R1-0528)
- Parse LLM response into a structured “plan” (steps with keywords, browse actions)
- Emit plan back to orchestrator

##### Executor Module Deep Dive
- Inputs: plan (sequence of sub-tasks), context, confidence threshold
- Process loop:
1) Load executor prompts (`executor_prefix.txt`, `executor_prompt.txt`)
2) For each step, invoke `tool_manager.batch_search` or `generate_keywords` or `check_condition`
3) Collect results, update context, compute confidence
5) Otherwise, continue until plan completion
- Output: final synthesized answer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Client["Client/CLI"]:::external
    DeepSeek["DeepSeek-R1 Endpoint"]:::external
    Toolbox["Toolbox Service"]:::external
    Sandbox["MCP Sandbox"]:::external

    %% Configuration and Data Stores
    ConfigYAML["model_config.yaml"]:::config
    ConfigJinja["r1_tool.jinja"]:::config
    PromptsDir["Prompts Directory"]:::config
    Logs["logs/examples.jsonl"]:::datastore
    Assets["assets/"]:::config

    %% Orchestrator
    Orchestrator["agent.py"]:::orchestrator

    %% Planner Module
    subgraph "Planner Module"
        direction TB
        BaseAgent["base_agent.py"]:::orchestrator
        PlannerProm1["prompts/planner_prefix.txt"]:::config
        PlannerProm2["prompts/planner_prompt.txt"]:::config
        PlannerProc["Plan Generation"]:::compute
    end

    %% Executor Module
    subgraph "Executor Module"
        direction TB
        Context["context.py"]:::orchestrator
        Utils["utils.py"]:::orchestrator
        ExecProm1["prompts/executor_prefix.txt"]:::config
        ExecProm2["prompts/executor_prompt.txt"]:::config
        ToolMan["tools/tool_manager.py"]:::compute
        ExecProc["Execution Loop"]:::compute
    end

    %% Main Flow
    Client -->|"query"| Orchestrator
    Orchestrator -->|"load prompts"| PlannerProm1
    Orchestrator -->|"load prompts"| PlannerProm2
    Orchestrator -->|invoke| BaseAgent
    BaseAgent -->|"call LLM"| DeepSeek
    DeepSeek -->|"response"| PlannerProc
    PlannerProm1 --> PlannerProc
    PlannerProm2 --> PlannerProc
    PlannerProc -->|plan| Orchestrator

    Orchestrator -->|"load context"| Context
    Orchestrator -->|"load prompts"| ExecProm1
    Orchestrator -->|"load prompts"| ExecProm2
    Orchestrator -->|pass plan| ExecProc
    Context --> ExecProc
    ExecProm1 --> ExecProc
    ExecProm2 --> ExecProc

    ExecProc -->|use primitives| ToolMan
    ToolMan -->|"HTTP/REST"| Toolbox
    ToolMan -->|"sandbox exec"| Sandbox
    Toolbox --> ExecProc
    Sandbox --> ExecProc

    ExecProc -->|final answer| Orchestrator
    Orchestrator -->|output| Client
    Orchestrator -->|write log| Logs

    ExecProc -->|confidence < threshold| PlannerProc
    class ExecProc,PlannerProc compute

    %% Click Events
    click Orchestrator "https://github.com/sjtu-sai-agents/browse-master/blob/main/agent.py"
    click BaseAgent "https://github.com/sjtu-sai-agents/browse-master/blob/main/llm_agent/base_agent.py"
    click PlannerProm1 "https://github.com/sjtu-sai-agents/browse-master/blob/main/prompts/planner_prefix.txt"
    click PlannerProm2 "https://github.com/sjtu-sai-agents/browse-master/blob/main/prompts/planner_prompt.txt"
    click ExecProm1 "https://github.com/sjtu-sai-agents/browse-master/blob/main/prompts/executor_prefix.txt"
    click ExecProm2 "https://github.com/sjtu-sai-agents/browse-master/blob/main/prompts/executor_prompt.txt"
    click ToolMan "https://github.com/sjtu-sai-agents/browse-master/blob/main/llm_agent/tools/tool_manager.py"
    click Context "https://github.com/sjtu-sai-agents/browse-master/blob/main/llm_agent/context.py"
    click Utils "https://github.com/sjtu-sai-agents/browse-master/blob/main/llm_agent/utils.py"
    click ConfigYAML "https://github.com/sjtu-sai-agents/browse-master/blob/main/config/model_config.yaml"
    click ConfigJinja "https://github.com/sjtu-sai-agents/browse-master/blob/main/config/r1_tool.jinja"
    click Logs "https://github.com/sjtu-sai-agents/browse-master/blob/main/logs/examples.jsonl"
    click PromptsDir "https://github.com/sjtu-sai-agents/browse-master/tree/main/prompts/"
    click Assets "https://github.com/sjtu-sai-agents/browse-master/tree/main/assets/"

    %% Styles
    classDef compute fill:#D0E6FF,stroke:#004EAA,color:#004EAA
    classDef orchestrator fill:#E8DAFF,stroke:#7D3C98,color:#7D3C98
    classDef config fill:#D6F5D6,stroke:#1E7F1E,color:#1E7F1E
    classDef datastore fill:#EAFAD4,stroke:#8CBF26,color:#8CBF26
    classDef external fill:#F0F0F0,stroke:#999999,color:#555555
```
