How It Works

Every time you call agent.ask(), Mango runs a structured loop that combines memory retrieval, LLM reasoning, and tool execution.

The agent loop

User question
      │
      ▼
┌─────────────────────────────────────────────┐
│               MANGO AGENT                    │
│                                              │
│  1. Inject training examples (gold-standard) │
│  2. Pre-inject memory examples into prompt   │
│  3. Select relevant schema (per-query)       │
│  4. LLM decides which tools to call          │
│  5. Auto-inject schema before run_mql (*)    │
│  6. Validate MQL before execution            │
│  7. Execute tools against MongoDB            │
│  8. Auto-retry on fixable errors (max 2x)    │
│  9. Stream natural language answer           │
│ 10. Auto-save successful queries to memory   │
└─────────────────────────────────────────────┘
      │
      ▼
SSE stream → your frontend

(*) Schema is injected automatically before each run_mql call so the LLM always has accurate field names and types at query time, even if the prompt was built earlier.

The loop runs until the LLM produces a final answer with no further tool calls, or until max_iterations is reached (safety cap, default: 8).

Memory retrieval

Before the first LLM call, Mango searches the vector store for questions semantically similar to the current one. Matches above the similarity threshold are injected into the system prompt as examples:

## Relevant past interactions

Q: How many users signed up last month?
Tool: run_mql | Args: {"operation": "count", "collection": "users", ...}
Result: 1,247 users signed up in February 2026.

This gives the LLM concrete examples of correct queries for your specific database, dramatically improving accuracy on repeated or similar questions.

Schema context

agent.setup() introspects your database once and builds a system prompt that includes:

• Collection names and document counts
• Field names, types, and presence frequencies
• Index information
• Detected cross-collection references

The LLM uses this context to generate queries with the correct field names and operators — without guessing.

Tools available

Mango ships with a set of read-only tools the LLM can call:

Safety

• Read-only by design. run_mql only accepts find, aggregate, count, and distinct. Any attempt to run write operations is rejected at the tool level with a ValidationError.
• Allowlist, not blocklist. The permitted operations are explicitly whitelisted, not everything-except-writes.
• No raw query passthrough. The LLM cannot execute arbitrary strings — all queries go through the QueryRequest dataclass.

AgentResponse

ask() returns an AgentResponse with everything you need:

@dataclass
class AgentResponse:
    answer: str               # the natural language answer
    tool_calls_made: list[str] # which tools were called
    input_tokens: int          # total input tokens used
    output_tokens: int         # total output tokens used
    iterations: int            # number of LLM calls in this turn
    memory_hits: int           # how many memory examples were injected