update quick start and add tool searching serper, config logging for single task

BinWang28 · BinWang28 · commit b2ff201a63aa · 2025-10-11T12:49:01.000+08:00
diff --git a/README.md b/README.md
@@ -88,7 +88,7 @@ cp .env.template .env
 # Edit .env and add your OPENROUTER_API_KEY
 
 # 3. Run your first agent
-uv run main.py trace --config_file_name=agent_quickstart_1 --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
+uv run main.py trace --config_file_name=agent_quickstart_reading --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
 ```
 
 🎉 **Expected Output:** Your agent should return **\boxed{Congo Democratic Republic}** 😊
diff --git a/README_ja.md b/README_ja.md
@@ -86,7 +86,7 @@ cp .env.template .env
 # .env を編集して OPENROUTER_API_KEY を追加
 
 # 3. 最初のエージェントを実行
-uv run main.py trace --config_file_name=agent_quickstart_1 --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
+uv run main.py trace --config_file_name=agent_quickstart_reading --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
 ```
 
 🎉 **想定出力**: エージェントは **\boxed{Congo Democratic Republic}** を返すはずです 😊
diff --git a/README_zh.md b/README_zh.md
@@ -86,7 +86,7 @@ cp .env.template .env
 # 编辑 .env 并添加您的 OPENROUTER_API_KEY
 
 # 3. 运行您的第一个智能体
-uv run main.py trace --config_file_name=agent_quickstart_1 --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
+uv run main.py trace --config_file_name=agent_quickstart_reading --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
 ```
 
 🎉 **预期输出**: 您的智能体应该返回 **\boxed{Congo Democratic Republic}** 😊
diff --git a/config/agent_quickstart_reading.yaml b/config/agent_quickstart_reading.yaml
@@ -22,7 +22,8 @@ main_agent:
     keep_tool_result: -1
     oai_tool_thinking: false
   
-  tool_config: []
+  tool_config:
+    - tool-reading
 
   max_turns: -1  # Maximum number of turns for main agent execution
   max_tool_calls_per_turn: 10  # Maximum number of tool calls per turn
@@ -40,30 +41,7 @@ main_agent:
   chinese_context: "${oc.env:CHINESE_CONTEXT,false}"
 
 
-sub_agents:
-  agent-worker:
-    prompt_class: SubAgentWorkerPrompt
-    llm: 
-      provider_class: "ClaudeOpenRouterClient"
-      model_name: "anthropic/claude-3.7-sonnet"
-      async_client: true
-      temperature: 0.3
-      top_p: 0.95
-      min_p: 0.0
-      top_k: -1
-      max_tokens: 32000
-      openrouter_api_key: "${oc.env:OPENROUTER_API_KEY,???}"
-      openrouter_base_url: "${oc.env:OPENROUTER_BASE_URL,https://openrouter.ai/api/v1}"
-      openrouter_provider: "anthropic"
-      disable_cache_control: false
-      keep_tool_result: -1
-      oai_tool_thinking: false
-    
-    tool_config:
-      - tool-reading
-
-    max_turns: -1  # Maximum number of turns for main agent execution
-    max_tool_calls_per_turn: 10  # Maximum number of tool calls per turn
+sub_agents: null
 
 
 # Can define some top-level or default parameters here
diff --git a/config/agent_quickstart_search.yaml b/config/agent_quickstart_search.yaml
@@ -0,0 +1,50 @@
+defaults:
+  - benchmark: gaia-validation
+  - override hydra/job_logging: none
+  - _self_  # Allow defining variables at the top of this file
+
+
+main_agent:
+  prompt_class: MainAgentPromptBoxedAnswer
+  llm: 
+    provider_class: "ClaudeOpenRouterClient"
+    model_name: "anthropic/claude-3.7-sonnet"
+    async_client: true
+    temperature: 0.3
+    top_p: 0.95
+    min_p: 0.0
+    top_k: -1
+    max_tokens: 32000
+    openrouter_api_key: "${oc.env:OPENROUTER_API_KEY,???}"
+    openrouter_base_url: "${oc.env:OPENROUTER_BASE_URL,https://openrouter.ai/api/v1}"
+    openrouter_provider: "anthropic"
+    disable_cache_control: false
+    keep_tool_result: -1
+    oai_tool_thinking: false
+  
+  tool_config:
+    - tool-searching-serper
+
+  max_turns: -1  # Maximum number of turns for main agent execution
+  max_tool_calls_per_turn: 10  # Maximum number of tool calls per turn
+  
+  input_process:
+    hint_generation: false
+    hint_llm_base_url: "${oc.env:HINT_LLM_BASE_URL,https://api.openai.com/v1}"
+  output_process:
+    final_answer_extraction: false
+    final_answer_llm_base_url: "${oc.env:FINAL_ANSWER_LLM_BASE_URL,https://api.openai.com/v1}"
+
+  openai_api_key: "${oc.env:OPENAI_API_KEY,???}" # used for hint generation and final answer extraction
+  add_message_id: true
+  keep_tool_result: -1
+  chinese_context: "${oc.env:CHINESE_CONTEXT,false}"
+
+
+sub_agents: null
+
+
+# Can define some top-level or default parameters here
+output_dir: logs/
+data_dir: "${oc.env:DATA_DIR,data}"  # Points to where data is stored
+
diff --git a/config/tool/tool-searching-serper.yaml b/config/tool/tool-searching-serper.yaml
@@ -1,8 +1,8 @@
-name: "tool-serper-search"
+name: "tool-searching-serper"
 tool_command: "npx"
 args:
   - "-y"
   - "serper-search-scrape-mcp-server"
 env:
 # Search API key - this value will be loaded from the .env file at runtime
-  SERPER_API_KEY: "${oc.env:SERPER_API_KEY}"
+  SERPER_API_KEY: "${oc.env:SERPER_API_KEY}"
diff --git a/docs/mkdocs/docs/contribute_benchmarks.md b/docs/mkdocs/docs/contribute_benchmarks.md
@@ -148,7 +148,7 @@ Start with a small subset to verify everything works correctly:
 
 ```bash title="Test Benchmark Integration"
 uv run main.py common-benchmark \
-  --config_file_name=agent_quickstart_1 \
+  --config_file_name=agent_quickstart_reading \
   benchmark=your-benchmark \
   benchmark.execution.max_tasks=3 \
   output_dir="logs/test-your-benchmark/$(date +"%Y%m%d_%H%M")"
@@ -160,7 +160,7 @@ Once testing passes, run the complete benchmark:
 
 ```bash title="Run Full Benchmark"
 uv run main.py common-benchmark \
-  --config_file_name=agent_quickstart_1 \
+  --config_file_name=agent_quickstart_reading \
   benchmark=your-benchmark \
   output_dir="logs/your-benchmark/$(date +"%Y%m%d_%H%M")"
 ```
diff --git a/docs/mkdocs/docs/futurex.md b/docs/mkdocs/docs/futurex.md
@@ -72,10 +72,10 @@ OPENAI_BASE_URL="https://api.openai.com/v1"
 ### Step 3: Run the Evaluation
 
 !!! example "Evaluation Execution"
-    Execute the following command to run evaluation on the Futurex-Online dataset. This uses the basic `agent_quickstart_1` configuration for quick start purposes.
+    Execute the following command to run evaluation on the Futurex-Online dataset. This uses the basic `agent_quickstart_reading` configuration for quick start purposes.
 
 ```bash title="Run Futurex-Online Evaluation"
-uv run main.py common-benchmark --config_file_name=agent_quickstart_1 benchmark=futurex output_dir="logs/futurex/$(date +"%Y%m%d_%H%M")"
+uv run main.py common-benchmark --config_file_name=agent_quickstart_reading benchmark=futurex output_dir="logs/futurex/$(date +"%Y%m%d_%H%M")"
 ```
 
 !!! tip "Progress Monitoring and Resume"
@@ -88,7 +88,7 @@ uv run main.py common-benchmark --config_file_name=agent_quickstart_1 benchmark=
     If you need to resume an interrupted evaluation, specify the same output directory to continue from where you left off.
 
     ```bash title="Resume Evaluation, e.g."
-    uv run main.py common-benchmark --config_file_name=agent_quickstart_1 benchmark=futurex output_dir="logs/futurex/20250918_1010"
+    uv run main.py common-benchmark --config_file_name=agent_quickstart_reading benchmark=futurex output_dir="logs/futurex/20250918_1010"
     ```
 
 ### Step 4: Extract Results
@@ -184,13 +184,13 @@ Check the generated files for voting analysis:
 
 ```bash title="Check Voting Results"
 # View submission file with voting results
-cat logs/futurex/agent_quickstart_1_*/futurex_submission.jsonl
+cat logs/futurex/agent_quickstart_reading_*/futurex_submission.jsonl
 
 # Check individual run results
-ls logs/futurex/agent_quickstart_1_*/run_*/
+ls logs/futurex/agent_quickstart_reading_*/run_*/
 
 # Check progress and voting statistics
-uv run python utils/progress_check/check_futurex_progress.py logs/futurex/agent_quickstart_1_*
+uv run python utils/progress_check/check_futurex_progress.py logs/futurex/agent_quickstart_reading_*
 ```
 
 ### Manual Voting Aggregation
@@ -199,13 +199,13 @@ You can also manually run the voting aggregation:
 
 ```bash title="Manual Voting Aggregation"
 # Aggregate multiple runs with majority voting
-uv run python utils/extract_futurex_results.py logs/futurex/agent_quickstart_1_* --aggregate
+uv run python utils/extract_futurex_results.py logs/futurex/agent_quickstart_reading_* --aggregate
 
 # Force single run mode (if needed)
-uv run python utils/extract_futurex_results.py logs/futurex/agent_quickstart_1_*/run_1 --single
+uv run python utils/extract_futurex_results.py logs/futurex/agent_quickstart_reading_*/run_1 --single
 
 # Specify custom output file
-uv run python utils/extract_futurex_results.py logs/futurex/agent_quickstart_1_* -o my_voted_predictions.jsonl
+uv run python utils/extract_futurex_results.py logs/futurex/agent_quickstart_reading_* -o my_voted_predictions.jsonl
 ```
 
 ### Voting Output Format
@@ -249,7 +249,7 @@ For example, `"vote_counts": {"No": 2}` means 2 out of 2 runs predicted "No", in
 After running multiple evaluations, you'll find the following structure:
 
 ```
-logs/futurex/agent_quickstart_1_YYYYMMDD_HHMM/
+logs/futurex/agent_quickstart_reading_YYYYMMDD_HHMM/
 ├── futurex_submission.jsonl          # Final voted predictions
 ├── run_1/                            # First run results
 │   ├── benchmark_results.jsonl       # Individual task results
diff --git a/docs/mkdocs/docs/quickstart.md b/docs/mkdocs/docs/quickstart.md
@@ -1,7 +1,6 @@
-
 # 🚀 Get Started in Under 5 Minutes
 
-Clone the repository, configure your API key, and run your first intelligent agent. You'll just need one `OPENROUTER_API_KEY`.
+Clone the repository, configure your API keys, and run your first intelligent agent. MiroFlow provides multiple pre-configured agents for different use cases.
 
 ---
 
@@ -14,52 +13,139 @@ Clone the repository, configure your API key, and run your first intelligent age
 
 ---
 
-## ⚡ Quick Setup
-
-### Example 1: Intelligent document analysis with file processing capabilities
+## 🎯 Example 1: Document Analysis
 
 !!! example "File Processing Demo"
-    This example demonstrates MiroFlow's document analysis capabilities.
+    Analyze structured data files (Excel, CSV, PDF, etc.) with intelligent document processing.
+    
+    **Required:** [OPENROUTER_API_KEY](https://openrouter.ai/): to access Claude 3.7 Sonnet
 
-```bash title="Setup Commands"
+```bash title="Setup and Run Document Analysis"
 # 1. Clone and setup
 git clone https://github.com/MiroMindAI/MiroFlow && cd MiroFlow
 uv sync
 
-# 2. Configure API key
+# 2. Configure API key (REQUIRED for LLM access)
 cp .env.template .env
 # Edit .env and add your OPENROUTER_API_KEY
+# This key is necessary to access Claude 3.7 Sonnet for document analysis
 
-# 3. Run your first agent
-uv run main.py trace --config_file_name=agent_quickstart_1 --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
+# 3. Run document analysis
+uv run main.py trace --config_file_name=agent_quickstart_reading --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"
 ```
 
+**What this does:**
+
+- Uses the `tool-reading` capability to process Excel files
+- Leverages Claude 3.7 Sonnet (via OpenRouter API) for intelligent analysis
+- Finds countries starting with "Co" and returns the first one
+
 !!! success "Expected Output"
-    🎉 **Expected Output:** Your agent should return **\boxed{Congo Democratic Republic}** 😊
+    🎉 **Expected Output:** Your agent should return **\boxed{Congo Democratic Republic}**
+
+---
+
+## 🎯 Example 2: Web Search Analysis
+
+!!! example "Real-time Web Research"
+    Search the web for current information and get intelligent analysis of the results.
+
+    **Required:** [OPENROUTER_API_KEY](https://openrouter.ai/) and [SERPER_API_KEY](https://serper.dev/)
 
-!!! tip "Troubleshooting"
-    **💡 Tip:** If you encounter issues, check that your API key is correctly set in the `.env` file and that all dependencies are installed.
+```bash title="Setup and Run Web Search"
+# 1. Clone and setup (if not done already)
+git clone https://github.com/MiroMindAI/MiroFlow && cd MiroFlow
+uv sync
 
-!!! note "Coming Soon"
-    **Coming Soon:** We will add a video demo for this example
+# 2. Configure API keys (if not done already)
+cp .env.template .env
+# Edit .env and add your OPENROUTER_API_KEY and SERPER_API_KEY
+# These keys are necessary to access Claude 3.7 Sonnet and web search capabilities
+
+# 3. Run web search analysis
+uv run main.py trace --config_file_name=agent_quickstart_search --task="What is the current NASDAQ index price and what are the main factors affecting it today?"
+```
+
+**What this does:**
+
+- Uses the `tool-searching-serper` capability to search the web
+- Leverages Claude 3.7 Sonnet (via OpenRouter API) for intelligent analysis
+- Searches for current NASDAQ index information and market factors
+- Provides real-time financial data analysis
+
+!!! success "Expected Output"
+    🎉 **Expected Output:** Current NASDAQ index price with analysis of key market factors affecting it
 
 ---
 
-### Example 2: Web research and multi-agent orchestration
+## 🔧 Configuration Options
 
-!!! warning "Work in Progress"
-    The example is not complete yet, to be completed
+### Available Agent Configurations
 
-```bash title="Web Research Command"
-uv run main.py trace --config_file_name=agent_quickstart_2 --task="What is the Nasdaq Composite Index at today?"
+| Agent | Tools | Use Case |
+|-------|-------|----------|
+| `agent_quickstart_reading` | Document reading | File analysis, data extraction, document summarization |
+| `agent_quickstart_search` | Web search | Real-time information, market data, current events |
+
+### Customizing Tasks
+
+You can customize any task by modifying the `--task` parameter:
+
+```bash
+# Analyze different files
+uv run main.py trace --config_file_name=agent_quickstart_reading \
+  --task="Summarize the main findings in this document" \
+  --task_file_name="path/to/your/document.pdf"
+
+# Search for different information
+uv run main.py trace --config_file_name=agent_quickstart_search \
+  --task="What are the latest developments in AI technology?"
 ```
 
-!!! note "Coming Soon"
-    **Coming Soon:** Web research and multi-agent orchestration example
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+!!! warning "API Key Issues"
+    **Problem:** Agent fails to start or returns errors
+    **Solution:** Ensure your API keys are correctly set in the `.env` file:
+    ```bash
+    OPENROUTER_API_KEY=your_key_here
+    SERPER_API_KEY=your_key_here  # For web search examples
+    ```
+
+
+!!! warning "Tool Execution Errors"
+    **Problem:** Tools fail to execute
+    **Solution:** Check that all dependencies are installed:
+    ```bash
+    uv sync  # Reinstall dependencies
+    ```
+
+### Getting Help
+
+- Check the [FAQ section](faqs.md) for common questions
+- Review the [YAML Configuration Guide](yaml_config.md) for advanced setup
+- Explore [Tool Documentation](tool_overview.md) for available capabilities
 
 ---
 
-!!! info "Documentation Info"
-    **Last Updated:** Sep 2025 · **Doc Contributor:** Team @ MiroMind AI
+## 🚀 Next Steps
+
+Once you've tried the examples above, explore more advanced features:
 
+1. **Custom Agent Configuration**: Create your own agent setups
+   ```bash
+   # Copy and modify existing configs
+   cp config/agent_quickstart_reading.yaml config/my_custom_agent.yaml
+   ```
 
+2. **Tool Development**: Add custom tools for your specific needs
+   - See [Contributing Tools](contribute_tools.md) guide
+
+---
+
+!!! info "Documentation Info"
+    **Last Updated:** October 2025 · **Doc Contributor:** Team @ MiroMind AI
diff --git a/docs/mkdocs/docs/yaml_config.md b/docs/mkdocs/docs/yaml_config.md
diff --git a/scripts/run_evaluate_multiple_runs_futurex.sh b/scripts/run_evaluate_multiple_runs_futurex.sh
diff --git a/utils/trace_single_task.py b/utils/trace_single_task.py
