How shameendra/mrkl_agent works
This repository is a Python MRKL-style reasoning agent that can be run:
• as an interactive CLI or single-shot CLI (main.py)
• as an HTTP API server with JSON endpoints and a streaming endpoint (main.py)
Core behavior:
• Accept a user question
• (Optionally) generate a plan
• Execute a reasoning loop that repeatedly:
1) calls an LLM for “thought/action”
2) dispatches to a selected tool
3) feeds the observation back into the next step
• Produces a final answer (and optionally emits streaming events)
The architectural center is the MRKLAgent (agent.py) + tool registry/implementations (tools.py) + runtime config (config.py). local_mrkl_agent.py likely represents a variant/alternate implementation (e.g., local-only execution or simplified agent).
/query/stream (streaming events)
Participants:
• Client (CLI or HTTP Client)
• API/CLI handler (main.py)
• MRKLAgent (agent.py)
• LLM API
• Tool Dispatcher
• Specific Tool (e.g., web_search, then calculator)
• External service (SerpAPI/Web, etc.)
Key loop:
• LLM decides tool → tool executes → observation → back to LLM → repeat until final answer or max iteration/timeouts.
Control flow (orchestration)
• main.py orchestrates request lifecycle (HTTP/CLI).
• agent.py orchestrates reasoning iterations and decides when to stop.
Data flow (artifacts)
• Input: question, with_planning
• Intermediate: plan[], thought, action, action_input, observation
• Output: answer, plus optionally plan and step trace
• Streaming: events per step (thought/action/observation/final)
Constraints (very important in agent systems)
From config.py / README:
• MAX_ITERATIONS (loop guard)
• MAX_EXECUTION_TIME (timeout guard)
• error handling & fallback tool attempts
As annotations on the reasoning loop component.
• MRKL architecture: “LLM-as-controller + modular tools”
• Plugin/Registry pattern for tools (tools.py as a registry; tools are replaceable)
• Strategy selection (dynamic tool selection)
• Event streaming (server → client incremental output)
• Fail-soft execution (tool failure → retry/alternate path)
Clients
• CLI User
• HTTP Client
Your App (Python Process)
• main.py (CLI + API)
• agent.py (Planner, Reasoning Loop, Tool Dispatcher, Streaming)
• tools.py (Tool Registry + Tools)
• config.py
External Services / Stores
• OpenAI (LLM)
• SerpAPI/Web, News, Wolfram
• SQL DB
• Knowledge Base store
• Python Execution Sandbox/Subprocess
Even without overthinking, quickly confirm in the code:
• What web framework is used for API mode (FastAPI/Flask) in main.py
• How streaming is implemented (SSE vs websockets vs chunked responses)
• Whether python_executor is sandboxed or uses exec/subprocess
• Where tool definitions live (LangChain tools vs custom functions)
• How the tool registry is constructed (get_all_tools() signature)
• Whether local_mrkl_agent.py is an alternative runtime path that should be shown as “optional/variant”