Skip to content

Instantly share code, notes, and snippets.

@ai-christianson

ai-christianson/gist:43447275d5cc0966b1b6f90ce3035794

Created February 4, 2025 20:35
Show Gist options
  • Save ai-christianson/43447275d5cc0966b1b6f90ce3035794 to your computer and use it in GitHub Desktop.
Save ai-christianson/43447275d5cc0966b1b6f90ce3035794 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
gistfile1.txt
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│🔎 Research Stage │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📊 Project Status ──────────────────────────────────────────────────────────────────────────────╮
│ Existing project with 122 file(s) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 🤖 Assistant ────────────────────────────────────────────────────────────────────────────────╮
│ Let me explore the open deep research example code. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📂 Directory Tree ──────────────────────────────────────────────────────────────────────────────╮
│ │
│ 📁 /home/user/workspace/smolagents/examples/open_deep_research/ │
│ ├── 📁 scripts/ │
│ │ ├── cookies.py │
│ │ ├── gaia_scorer.py │
│ │ ├── mdconvert.py │
│ │ ├── reformulator.py │
│ │ ├── run_agents.py │
│ │ ├── text_inspector_tool.py │
│ │ ├── text_web_browser.py │
│ │ └── visual_qa.py │
│ ├── analysis.ipynb │
│ ├── requirements.txt │
│ ├── run.py │
│ └── visual_vs_text_browser.ipynb │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 300 lines (10283 bytes) from examples/open_deep_research/run.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #1 ───────────────────────────────────────────────────────────────────────────────╮
│ Open Deep Research is an example project in the smolagents library that performs research tasks using web browsing and file inspection tools │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #2 ───────────────────────────────────────────────────────────────────────────────╮
│ It uses a hierarchical agent system with a manager agent (CodeAgent) and a web browser agent (ToolCallingAgent) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #3 ───────────────────────────────────────────────────────────────────────────────╮
│ The system includes tools for text inspection, web browsing, visual inspection, and file analysis │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #4 ───────────────────────────────────────────────────────────────────────────────╮
│ Key tools include: TextInspectorTool, SimpleTextBrowser with various navigation tools (SearchInformation, Visit, PageUp/Down, Finder, etc.) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #5 ───────────────────────────────────────────────────────────────────────────────╮
│ Uses the GAIA benchmark dataset for evaluation │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #6 ───────────────────────────────────────────────────────────────────────────────╮
│ Can handle various file types including PDFs, text files, and zip archives │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #7 ───────────────────────────────────────────────────────────────────────────────╮
│ Runs tasks concurrently with ThreadPoolExecutor │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #8 ───────────────────────────────────────────────────────────────────────────────╮
│ Saves results to JSONL files with metrics like start/end time and intermediate steps │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────── 📁 Related Files Noted ───────────────────────────────────────────────────────────────────────────╮
│ Files Noted: │
│ │
│ • examples/open_deep_research/run.py │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #1 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/run.py │
│ • Line: 82 │
│ │
│ Code: │
│ │
│ │
│ def create_agent_hierarchy(model: Model): │
│ text_limit = 100000 │
│ ti_tool = TextInspectorTool(model, text_limit) │
│ │
│ browser = SimpleTextBrowser(**BROWSER_CONFIG) │
│ │
│ WEB_TOOLS = [ │
│ SearchInformationTool(browser), │
│ VisitTool(browser), │
│ PageUpTool(browser), │
│ PageDownTool(browser), │
│ FinderTool(browser), │
│ FindNextTool(browser), │
│ ArchiveSearchTool(browser), │
│ TextInspectorTool(model, text_limit), │
│ ] │
│ │
│ │
│ Description: Core setup of the agent hierarchy and web tools │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #2 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/run.py │
│ • Line: 132 │
│ │
│ Code: │
│ │
│ │
│ manager_agent = CodeAgent( │
│ model=model, │
│ tools=[visualizer, ti_tool], │
│ max_steps=12, │
│ verbosity_level=2, │
│ additional_authorized_imports=AUTHORIZED_IMPORTS, │
│ planning_interval=4, │
│ managed_agents=[text_webbrowser_agent], │
│ ) │
│ │
│ │
│ Description: Creation of the manager agent that oversees the research process │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 563 lines (23379 bytes) from examples/open_deep_research/scripts/text_web_browser.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #9 ───────────────────────────────────────────────────────────────────────────────╮
│ The browser component provides text-based web browsing functionality with tools like search, navigation, and content inspection │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #10 ───────────────────────────────────────────────────────────────────────────────╮
│ Browser tools include: web search, page visit, page navigation (up/down), text find, and archive lookup │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #11 ───────────────────────────────────────────────────────────────────────────────╮
│ Supports downloading and processing various file types including PDFs and text files │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #12 ───────────────────────────────────────────────────────────────────────────────╮
│ Uses SerpAPI for Google search functionality │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #13 ───────────────────────────────────────────────────────────────────────────────╮
│ Can visit both web URLs and local files │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #14 ───────────────────────────────────────────────────────────────────────────────╮
│ Handles page content in viewports for manageable chunks of text │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 122 lines (4589 bytes) from examples/open_deep_research/scripts/text_inspector_tool.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #15 ───────────────────────────────────────────────────────────────────────────────╮
│ TextInspectorTool provides functionality to read and analyze various file types including PDFs, text files, Office documents, etc │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #16 ───────────────────────────────────────────────────────────────────────────────╮
│ Can process file contents and answer specific questions about them using an LLM │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #17 ───────────────────────────────────────────────────────────────────────────────╮
│ Handles file conversion to markdown text format │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #18 ───────────────────────────────────────────────────────────────────────────────╮
│ Does not handle images (directs to use visualizer tool instead) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #19 ───────────────────────────────────────────────────────────────────────────────╮
│ Has two modes: direct content return and question-answering with detailed responses │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 187 lines (6032 bytes) from examples/open_deep_research/scripts/visual_qa.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #20 ───────────────────────────────────────────────────────────────────────────────╮
│ Visual QA tool provides image analysis capabilities using IDEFICS and GPT-4 vision models │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #21 ───────────────────────────────────────────────────────────────────────────────╮
│ Can process both local and web-hosted images │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #22 ───────────────────────────────────────────────────────────────────────────────╮
│ Handles image resizing if needed for large images │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #23 ───────────────────────────────────────────────────────────────────────────────╮
│ Can provide detailed image captions or answer specific questions about images │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #24 ───────────────────────────────────────────────────────────────────────────────╮
│ Supports multiple image formats and handles base64 encoding of images │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 86 lines (4440 bytes) from examples/open_deep_research/scripts/reformulator.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #25 ───────────────────────────────────────────────────────────────────────────────╮
│ Reformulator tool processes conversation history to generate final answers │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #26 ───────────────────────────────────────────────────────────────────────────────╮
│ Formats responses according to specific templates and rules │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #27 ───────────────────────────────────────────────────────────────────────────────╮
│ Handles different types of answers (numbers, strings, lists) with appropriate formatting │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #28 ───────────────────────────────────────────────────────────────────────────────╮
│ Enforces consistent output formatting and unit handling │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #29 ───────────────────────────────────────────────────────────────────────────────╮
│ Can handle fallback to educated guesses when definitive answers can't be determined │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
^C^C^C^C^C
👋 Bye!
~/workspace/smolagents main $ ~/workspace/ra-aid/.venv/bin/ra-aid --expert-model o3-mini -m 'tell me how the open deep research works. consult with the expert to get a really good understanding of it.'
/home/user/workspace/ra-aid/.venv/lib/python3.12/site-packages/pydantic/_internal/_config.py:345: UserWarning: Valid config keys have changed in V2:
* 'fields' has been removed
warnings.warn(message, UserWarning)
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│🔎 Research Stage │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📊 Project Status ──────────────────────────────────────────────────────────────────────────────╮
│ Existing project with 122 file(s) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 🤖 Assistant ────────────────────────────────────────────────────────────────────────────────╮
│ Let me start by examining the relevant files and directory structure for open deep research. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📂 Directory Tree ──────────────────────────────────────────────────────────────────────────────╮
│ │
│ 📁 /home/user/workspace/smolagents/examples/open_deep_research/ │
│ ├── 📁 scripts/ │
│ │ ├── cookies.py │
│ │ ├── gaia_scorer.py │
│ │ ├── mdconvert.py │
│ │ ├── reformulator.py │
│ │ ├── run_agents.py │
│ │ ├── text_inspector_tool.py │
│ │ ├── text_web_browser.py │
│ │ └── visual_qa.py │
│ ├── analysis.ipynb │
│ ├── requirements.txt │
│ ├── run.py │
│ └── visual_vs_text_browser.ipynb │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 300 lines (10283 bytes) from examples/open_deep_research/run.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 87 lines (3703 bytes) from examples/open_deep_research/scripts/run_agents.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #1 ───────────────────────────────────────────────────────────────────────────────╮
│ Open Deep Research is a research agent system that can analyze both text and visual content │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #2 ───────────────────────────────────────────────────────────────────────────────╮
│ The system uses a hierarchical agent structure with a manager agent and specialized sub-agents │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #3 ───────────────────────────────────────────────────────────────────────────────╮
│ It includes tools for web browsing, text inspection, and visual analysis │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #4 ───────────────────────────────────────────────────────────────────────────────╮
│ The system can process multiple file types including images, PDFs, documents and audio files │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #5 ───────────────────────────────────────────────────────────────────────────────╮
│ The architecture uses ThreadPoolExecutor for concurrent task processing │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #6 ───────────────────────────────────────────────────────────────────────────────╮
│ The system integrates with language models through LiteLLMModel interface │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #7 ───────────────────────────────────────────────────────────────────────────────╮
│ Core components include TextInspectorTool, SimpleTextBrowser, and various web tools (Search, Visit, PageUp/Down, etc.) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #8 ───────────────────────────────────────────────────────────────────────────────╮
│ The system maintains a memory of intermediate steps and can provide run summaries │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #9 ───────────────────────────────────────────────────────────────────────────────╮
│ Includes ability to process questions with attached files/documents with specialized handling per file type │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #10 ───────────────────────────────────────────────────────────────────────────────╮
│ Uses a custom browser configuration with viewport size and user agent settings │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────── 📁 Related Files Noted ───────────────────────────────────────────────────────────────────────────╮
│ Files Noted: │
│ │
│ • examples/open_deep_research/run.py │
│ • examples/open_deep_research/scripts/run_agents.py │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #1 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/run.py │
│ • Line: 71 │
│ │
│ Code: │
│ │
│ │
│ def create_agent_hierarchy(model: Model): │
│ text_limit = 100000 │
│ ti_tool = TextInspectorTool(model, text_limit) │
│ │
│ browser = SimpleTextBrowser(**BROWSER_CONFIG) │
│ │
│ WEB_TOOLS = [ │
│ SearchInformationTool(browser), │
│ VisitTool(browser), │
│ PageUpTool(browser), │
│ PageDownTool(browser), │
│ FinderTool(browser), │
│ FindNextTool(browser), │
│ ArchiveSearchTool(browser), │
│ TextInspectorTool(model, text_limit), │
│ ] │
│ │
│ │
│ Description: Core agent hierarchy creation showing main tools │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #2 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/scripts/run_agents.py │
│ • Line: 13 │
│ │
│ Code: │
│ │
│ │
│ def get_image_description(file_name: str, question: str, visual_inspection_tool) -> str: │
│ prompt = f"""Write a caption of 5 sentences for this image. Pay special attention to any details that might be useful for someone answering the following question: │
│ {question}. But do not try to answer the question directly! │
│ Do not add any information that is not present in the image.""" │
│ return visual_inspection_tool(image_path=file_name, question=prompt) │
│ │
│ │
│ Description: Image analysis functionality │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── Expert Context ───────────────────────────────────────────────────────────────────────────────╮
│ Added expert context (1053 characters) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 🤔 Expert Query ───────────────────────────────────────────────────────────────────────────────╮
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ Question ┃ │
│ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
│ │
│ Can you explain how the hierarchical agent structure in this system works, particularly how the manager agent coordinates with sub-agents and specialized tools to handle │
│ different types of analysis (text, web, visual)? I'm especially interested in understanding the interaction flow between components. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── Expert Response ───────────────────────────────────────────────────────────────────────────────╮
│ The system’s hierarchical agent structure is organized around a primary manager agent that delegates specialized analysis tasks to sub‐agents and dedicated tools. Here’s │
│ how it works: │
│ │
│ 1 Manager Agent as the Coordinator │
│  • The manager agent (implemented as a CodeAgent) is in charge of processing the overall query. │
│  • It receives an augmented question that may contain both the description of the task and attached files or URLs. │
│  • Holding responsibility for synthesizing information, it collects intermediate steps, remembers context, and eventually produces the final answer. │
│ 2 Delegation to Sub‐Agents │
│  • The manager agent creates and embeds a sub‐agent (a ToolCallingAgent) that is specifically configured for web-related tasks. │
│  • This sub-agent comes equipped with a suite of web tools (such as search, navigation, and page inspection tools) that are used when the question requires browsing or │
│ online information retrieval. │
│ 3 Specialized Tools for Different Analyses │
│  • Web analysis: Within its sub-agent, a set of specialized tools (like SearchInformationTool, VisitTool, and PageUp/PageDown tools) handle browsing tasks. The manager │
│ agent can delegate parts of the question that require real-time or focused web searches to this team member. │
│  • Text and visual analysis: In parallel, the manager agent incorporates tools such as the TextInspectorTool for text content inspection and a visual analysis tool │
│ (visualizer) for handling images or scanned documents. For example, when a question involves an attached image, a dedicated function wraps the visual tool’s │
│ functionality into a coherent caption or description.  • Document processing: If the query includes documents (PDFs, Word files, etc.), appropriate tools inspect and │
│ extract summaries or captions to support the answer. │
│ 4 Interaction Flow Between Components │
│  • The manager agent begins by formulating the problem and augmenting the query based on any file descriptions (using functions like get_single_file_description or │
│ get_zip_description). │
│  • When the query signals a need for external or visual data, it delegates those subtasks: the web agent uses its integrated browsing tools to fetch and process web │
│ results, while the text and visual tools analyze the provided documents or images. │
│  • The results from these specialized tasks are passed back to the manager agent. It then integrates and verifies all intermediate steps stored in its memory (with │
│ details on each tool’s contribution) to produce a coherent final answer.  • Finally, the system logs all the intermediate steps and final results, ensuring that the │
│ entire process (from sub-agent delegation to final synthesis) is transparent and traceable. │
│ │
│ Overall, the hierarchical design allows the system to split the work—letting a dedicated sub-agent focus on web searches and relying on specialized tools for text or image │
│ analysis—while the manager agent coordinates the overall inquiry, integrates the results, and ensures that all necessary verification steps are performed before answering. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 563 lines (23379 bytes) from examples/open_deep_research/scripts/text_web_browser.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 187 lines (6032 bytes) from examples/open_deep_research/scripts/visual_qa.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────── 📁 Related Files Noted ───────────────────────────────────────────────────────────────────────────╮
│ Files Noted: │
│ │
│ • examples/open_deep_research/scripts/text_web_browser.py │
│ • examples/open_deep_research/scripts/visual_qa.py │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #3 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/scripts/text_web_browser.py │
│ • Line: 15 │
│ │
│ Code: │
│ │
│ │
│ class SimpleTextBrowser: │
│ """(In preview) An extremely simple text-based web browser comparable to Lynx. Suitable for Agentic use.""" │
│ │
│ def __init__( │
│ self, │
│ start_page: Optional[str] = None, │
│ viewport_size: Optional[int] = 1024 * 8, │
│ downloads_folder: Optional[Union[str, None]] = None, │
│ serpapi_key: Optional[Union[str, None]] = None, │
│ request_kwargs: Optional[Union[Dict[str, Any], None]] = None, │
│ ): │
│ │
│ │
│ Description: Text browser implementation for web navigation │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #4 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/scripts/visual_qa.py │
│ • Line: 125 │
│ │
│ Code: │
│ │
│ │
│ class VisualQATool(Tool): │
│ name = "visualizer" │
│ description = "A tool that can answer questions about attached images." │
│ inputs = { │
│ "image_path": { │
│ "description": "The path to the image on which to answer the question", │
│ "type": "string", │
│ }, │
│ "question": {"description": "the question to answer", "type": "string", "nullable": True}, │
│ } │
│ output_type = "string" │
│ │
│ client = InferenceClient("HuggingFaceM4/idefics2-8b-chatty") │
│ │
│ │
│ Description: Visual QA tool implementation for image analysis │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #11 ───────────────────────────────────────────────────────────────────────────────╮
│ Text browser component implements SERP API integration for web searches │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #12 ───────────────────────────────────────────────────────────────────────────────╮
│ Visual QA tool uses IDEFICS and GPT-4 models for image analysis │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #13 ───────────────────────────────────────────────────────────────────────────────╮
│ Browser includes tools for page navigation (up/down), text search (find/find next) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #14 ───────────────────────────────────────────────────────────────────────────────╮
│ System handles multiple file types including images, PDFs, documents with specialized converters │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #15 ───────────────────────────────────────────────────────────────────────────────╮
│ Text browser maintains viewport and page state for incremental content viewing │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #16 ───────────────────────────────────────────────────────────────────────────────╮
│ Visual analysis supports both local and URL-based image processing │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #17 ───────────────────────────────────────────────────────────────────────────────╮
│ Web tools include archive search capability through Wayback Machine │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #18 ───────────────────────────────────────────────────────────────────────────────╮
│ System integrates with HuggingFace for model inference │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── Expert Context ───────────────────────────────────────────────────────────────────────────────╮
│ Added expert context (823 characters) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 🤔 Expert Query ───────────────────────────────────────────────────────────────────────────────╮
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ Question ┃ │
│ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
│ │
│ How do the text browser tools and visual analysis components interact and coordinate in this system? I'm particularly interested in understanding the flow of data between │
│ them and how they handle different types of content. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── Expert Response ───────────────────────────────────────────────────────────────────────────────╮
│ The system is built around a hierarchical agent that orchestrates both text navigation and visual analysis tools. In essence, the text browser tools and visual analysis │
│ components serve complementary roles and feed their outputs into the manager agent’s overall reasoning process. │
│ │
│ 1 Text Browser Tools:  • The SimpleTextBrowser provides a text‐only rendering of web pages. Tools built on top of it (like SearchInformationTool, VisitTool, │
│ PageUp/PageDown, FinderTool, etc.) let the agent perform actions such as conducting a Google‐like search, navigating to URLs, scrolling through large pages, and finding │
│ specific text on a page. These tools are designed to extract, segment, and present textual content. For example, when a search is performed, the browser retrieves search │
│ results (including webpage titles, links, snippets, and timestamps) and splits the resulting content into “viewports” that the agent can inspect incrementally. │
│ 2 Visual Analysis Components:  • The visual qa tools (specifically VisualQATool and its decorator “visualizer”) handle the analysis of images. When an attached file (or an │
│ image extracted from a document) is encountered, a dedicated function (such as get_image_description) uses the visual qa tool to generate a detailed caption. This │
│ caption highlights key details for answering the task—all without trying to answer the question directly.  • The visual analysis process involves reading the local │
│ image, encoding it (as Base64 for instance), and passing it, along with an appropriate prompt, to an external inference client or a transformer model. The output is a │
│ textual description that is then integrated into the augmented question. │
│ 3 Coordination and Data Flow:  • When a task is being processed, the main agent first augments the prompt with any relevant file information. For instance, if an image is │
│ attached, the system calls get_single_file_description (which in turn calls the visual qa tool) to generate a caption.  • If a task requires browsing the web, the text │
│ browser tools gather and return text-based information. This information might include search result snippets, excerpts from web pages, or the text content of downloaded │
│ files.  • Both types of outputs—text from browsing and captions or descriptions from image analysis—are incorporated into the agent’s memory. The memory, which stores │
│ intermediate steps, becomes a shared context that the manager agent uses to verify, plan, and generate a final answer.  • In sum, while the text browser tools │
│ predominantly handle the extraction and navigation of text-based content from the web (or local documents), the visual qa tools focus on converting visual content into │
│ descriptive text. Their outputs are then coalesced within the agent’s reasoning loop, ensuring that the system can handle questions that mix different modalities without │
│ losing context. │
│ │
│ By designing these components as modular tools that the manager agent can call as needed, the system effectively coordinates across different types of content while keeping │
│ the data flow straightforward: attach relevant descriptions to the original query, process them via specialized tools, and use the aggregated insights to generate a │
│ comprehensive response. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────────── 📄 File Read ────────────────────────────────────────────────────────────────────────────────╮
│ Read 122 lines (4589 bytes) from examples/open_deep_research/scripts/text_inspector_tool.py in 0.00s │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────── 📁 Related Files Noted ───────────────────────────────────────────────────────────────────────────╮
│ Files Noted: │
│ │
│ • examples/open_deep_research/scripts/text_inspector_tool.py │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 📝 Key Snippet #5 ──────────────────────────────────────────────────────────────────────────────╮
│ Source Location: │
│ │
│ • File: examples/open_deep_research/scripts/text_inspector_tool.py │
│ • Line: 10 │
│ │
│ Code: │
│ │
│ │
│ class TextInspectorTool(Tool): │
│ name = "inspect_file_as_text" │
│ description = """ │
│ You cannot load files yourself: instead call this tool to read a file as markdown text and ask questions about it. │
│ This tool handles the following file extensions: [".html", ".htm", ".xlsx", ".pptx", ".wav", ".mp3", ".flac", ".pdf", ".docx"], and all other types of text files. IT DOES │
│ NOT HANDLE IMAGES.""" │
│ │
│ inputs = { │
│ "file_path": { │
│ "description": "The path to the file you want to read as text. Must be a '.something' file, like '.pdf'. If it is an image, use the visualizer tool instead! D │
│ NOT use this tool for an HTML webpage: use the web_search tool instead!", │
│ "type": "string", │
│ }, │
│ "question": { │
│ "description": "[Optional]: Your question, as a natural language sentence. Provide as much context as possible. Do not pass this parameter if you just want to │
│ directly return the content of the file.", │
│ "type": "string", │
│ "nullable": True, │
│ }, │
│ } │
│ │
│ │
│ Description: Text inspection tool implementation showing supported file types and functionality │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #19 ───────────────────────────────────────────────────────────────────────────────╮
│ TextInspectorTool provides file content analysis with optional question-answering capabilities │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #20 ───────────────────────────────────────────────────────────────────────────────╮
│ System supports a wide range of file types including HTML, XLSX, PPTX, WAV, MP3, PDF, and DOCX │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #21 ───────────────────────────────────────────────────────────────────────────────╮
│ Text inspection can generate both direct content and structured responses with short/detailed answers │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #22 ───────────────────────────────────────────────────────────────────────────────╮
│ Implementation includes special handling for large documents by limiting text content │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #23 ───────────────────────────────────────────────────────────────────────────────╮
│ Tool uses markdown conversion for consistent text formatting across file types │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #24 ───────────────────────────────────────────────────────────────────────────────╮
│ System maintains separation between text inspection and image analysis tools │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 💡 Key Fact #25 ───────────────────────────────────────────────────────────────────────────────╮
│ Each tool provides detailed error messages when used with unsupported file types │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─────────────────────────────────────────────────────────────────────────────── Expert Context ───────────────────────────────────────────────────────────────────────────────╮
│ Added expert context (548 characters) │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── 🤔 Expert Query ───────────────────────────────────────────────────────────────────────────────╮
│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
│ ┃ Question ┃ │
│ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │
│ │
│ How does the TextInspectorTool integrate with the broader system architecture, particularly in terms of its interaction with the web browser and visual components? I'm │
│ interested in understanding how these components work together to handle different types of content and questions. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────── Expert Response ───────────────────────────────────────────────────────────────────────────────╮
│ The TextInspectorTool is one of the specialized tools that the system incorporates to handle and process non-image file content. It is integrated into the broader agent │
│ hierarchy alongside components that can navigate the web and process visual content. Here’s how they work together: │
│ │
│ 1 In the agent hierarchy (as seen in the create_agent_hierarchy function), the TextInspectorTool is instantiated alongside a web browser instance (the SimpleTextBrowser) │
│ and a collection of web navigation tools (such as search, visit, page up/down, etc.). This means that while the browser tools fetch and render web content or downloaded │
│ pages for navigation and text extraction, the TextInspectorTool is available to “inspect” file contents that aren’t directly viewable as HTML (for instance, PDFs or DOCX │
│ files). │
│ 2 When a task includes attached files or documents, the system decides how to process the attachment based on its type. If the file is a visual asset (like an image), it │
│ is handled by the visual components (e.g. VisualQATool or visualizer) to generate detailed captions. If the file is a document (or any text-based file), │
│ TextInspectorTool steps in. It converts the file into markdown text (using a markdown converter) and, when provided with a question, it may generate a short caption or a │
│ fully detailed answer that assists the agent in understanding the content. │
│ 3 In scenarios where a question requires information drawn both from web searches and file content, the agent uses the web browser tools to retrieve and navigate online │
│ content while relying on TextInspectorTool to process any documents it has to inspect. This separation ensures that the system uses the best-suited tool for each content │
│ type:   • Web navigation and page extraction are handled by the SimpleTextBrowser and related tools.   • Detailed file content analysis (for a variety of document │
│ formats) is managed by the TextInspectorTool.   • Visual questions about images are processed by dedicated visual tools. │
│ │
│ By integrating these components, the system can dynamically decide, based on the type of content and the nature of the question, whether to fetch data from the web, inspect │
│ a document as text, or analyze an image visually. This coordination among tools enables the agent to provide appropriate levels of detail and context, whether it needs to │
│ inspect, convert, and summarize complex documents or capture and describe visual details from images. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── 🔍 Research Notes ──────────────────────────────────────────────────────────────────────────────╮
│ The Open Deep Research system implements a sophisticated multi-agent architecture for handling both textual and visual content through several key components: │
│ │
│ 1 Agent Hierarchy: │
│ │
│ • Manager agent (CodeAgent) coordinates overall task processing │
│ • Specialized sub-agents handle specific types of tasks │
│ • Web browser agent with tools for searching and navigation │
│ • All agents maintain memory of intermediate steps │
│ │
│ 2 Core Components: │
│ │
│ • SimpleTextBrowser: Text-based web browser with viewport management │
│ • TextInspectorTool: Handles document content analysis │
│ • VisualQATool: Processes image analysis and captions │
│ • Various web tools for search, navigation, and content inspection │
│ │
│ 3 Key Features: │
│ │
│ • Multi-modal processing supporting text, web, and visual content │
│ • Hierarchical delegation of tasks to specialized components │
│ • Integrated memory management for tracking steps │
│ • Support for multiple file types with specialized handlers │
│ • Web search capabilities through SERP API │
│ • Visual analysis using IDEFICS and GPT-4 models │
│ • Markdown conversion for consistent text formatting │
│ │
│ 4 Tool Integration: │
│ │
│ • Clear separation of responsibilities between tools │
│ • Coordinated processing of different content types │
│ • Structured response formatting │
│ • Error handling for unsupported operations │
│ • Memory maintenance across operations │
│ │
│ 5 Content Processing: │
│ │
│ • Web content handled by browser tools │
│ • Documents processed by text inspector │
│ • Images analyzed by visual QA tools │
│ • File type-specific conversion and handling │
│ • Support for large document processing │
│ │
│ This architecture enables systematic processing of complex queries involving multiple types of content while maintaining clear separation of concerns and coordinated │
│ information flow between components. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────── ✅ Task Completed ──────────────────────────────────────────────────────────────────────────────╮
│ Completed explanation of Open Deep Research system architecture and functionality │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment