Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JasonHonKL/spy-search/llms.txt

Use this file to discover all available pages before exploring further.

Spy Search is built around a multi-agent pipeline. The agents array in config.json controls which agents are activated for each query. You list only the processing and output agents you want — the Planner is always created internally and coordinates the rest.
config.json
{
    "agents": ["searcher", "reporter"]
}

​
Available Agents

Reporter

Agent ID: reporterClass: ReporterSynthesizes a long-form, structured report from all data gathered during a pipeline run. This is the primary output agent — it takes the Planner’s collected context and produces the final answer streamed back to the user.Status: ✅ Active

Searcher

Agent ID: searcherClass: Quick_searcherPerforms live web searches using DuckDuckGo. The Planner delegates search sub-tasks to this agent, which fetches and extracts content from relevant pages before passing results back into the pipeline.Status: ✅ Active

Local Retrieval

Agent ID: local-retrievalClass: RAG_agentQueries a local ChromaDB vector store built from files in the directory specified by db in config.json. Use this agent to ground answers in your own documents without an internet connection.Status: ✅ Active

Executor

Agent ID: (not yet assigned)Class: Executor (planned)A future agent designed to run tool calls and take programmatic actions on behalf of the user. The UI already exposes the checkbox for this agent, but it is disabled and not implemented in factory.py.Status: 🚧 Disabled

​
The Planner Agent

The Planner (src/agent/planner.py) is the pipeline orchestrator. It is always instantiated internally by the backend — you do not include "planner" in the agents array, and the UI intentionally hides it from the agent selection checkboxes. The Planner is responsible for:
  • Decomposing the user’s query into sub-tasks
  • Dispatching those sub-tasks to the configured agents (Searcher, Local Retrieval, etc.)
  • Aggregating results and handing them to the Reporter
Even if you run with "agents": ["reporter"] only, the Planner is still created — it simply has no search delegates to call.

​
Common Configurations

Skips all search steps. The LLM answers directly from its training data. Fastest option, no external calls made.
config.json
{
    "provider": "openai",
    "model": "gpt-4o",
    "agents": ["reporter"],
    "language": "en"
}

​
Changing Agents at Runtime

You can update the active agent list without restarting the server by calling the POST /agents_selection endpoint. The backend writes the new configuration to config.json immediately. 
curl -X POST http://localhost:8000/agents_selection \
  -H "Content-Type: application/json" \
  -d '{
    "agents": ["searcher", "reporter"],
    "provider": "openai",
    "model": "gpt-4o"
  }'
See the API — Agents reference for the full request/response schema.

​
UI Configuration

The Settings page in the React frontend exposes the same configuration through the AgentConfig panel. It:
  • Fetches the current config on load via GET /get_config
  • Renders checkboxes for each agent (searcher, local-retrieval, reporter; disabled agents are shown greyed-out)
  • Provides a provider dropdown and a free-text model name input
  • Exposes a Manage Database/Folders button for selecting the RAG source directory
  • Saves the new config via onAgentConfigSave, which calls POST /agents_selection
The UI enforces that reporter is always included — if you deselect it, the Save action re-adds it automatically before submitting. This mirrors the backend behaviour where reporter is the required output agent.
The provider value in config.json must match one of the strings recognised by Factory.get_model(): openai, gpt, deepseek, google, gemini, ollama, xAI, or gork. Using any other string will cause the factory to return None and the pipeline will fail to start.

Build docs developers (and LLMs) love

Get started for freeTalk to us