How t-majumder/agentgo works
This repo is a single-service Python application that exposes an AI agent via:
• Web UI + REST API (Flask in app.py, UI in index.html)
• CLI (main.py)
Core purpose: an LLM-driven tool-using agent. The LLM (via Groq API) decides which tools to call (web search, Wikipedia, scraper, calculator, time), the app executes those tool calls, then the LLM synthesizes a final response.
File-structure-driven decomposition (map files → components)
Use the file tree as the canonical “module boundary” guide:
• Entry points / Interfaces
• app.py → Flask server, routes (notably POST /chat), serves index.html
• index.html → Browser UI (calls backend /chat)
• main.py → CLI loop (calls agent directly; no HTTP)
• Core orchestration
• agent.py → the “brain”: prompt + tool schemas + iteration loop + tool dispatch
• tools.py → tool implementations (wikipedia_search, web_search, web_scraper, calculator, current_time)
• llm_call.py → LLM client wrappers for various models (gpt-oss-120b, qwen-32b, etc.), calling Groq
• Packaging/Runtime
• requirements.txt → deps
• Dockerfile → container runtime
• LICENSE, README.md
This naturally becomes: Client(s) → Flask/CLI → Agent Orchestrator → (LLM + Tools) → External Services.
Flask App / API Layer (app.py)
• Route: POST /chat
• Also static serving of index.html
Agent Orchestrator (agent.py)
• Conversation state/messages
• Tool schemas (function-calling spec)
• Iteration loop (max iterations)
• Tool selection + tool execution + final synthesis
LLM Adapter (llm_call.py)
• Model selection
• Groq API call
• Returns function-call requests or final text
Tooling Layer (tools.py)
• Individual tool functions
• Any parsing/normalization/summarization done inside tools
Flow 1: Web UI → API
• Browser UI (index.html) → HTTP POST /chat → Flask (app.py)
• Flask passes the message to Agent Orchestrator (agent.py)
• Agent uses LLM Adapter (llm_call.py) → Groq API
• Groq response may contain:
• Tool calls → Agent dispatches to tools.py → external services (Wikipedia/DDG/Websites) → returns tool results
• Or a final answer
• Agent returns final answer → Flask returns JSON → UI renders response
Flow 2: CLI → Agent
• CLI (main.py) → directly calls Agent Orchestrator (agent.py)
• Then same loop: Agent ↔ LLM ↔ Tools ↔ External services
LLM returns either
• function_call(s) with arguments, or
• final answer
If tool calls
• execute tool(s) in tools.py
• append tool outputs to conversation
• repeat until done or max iterations
Architectural patterns/design principles present
Call these out visually (labels/notes) because they guide correct diagramming:
• Function-calling / Tool-augmented LLM (ReAct-like): LLM chooses tools; system executes them; LLM synthesizes.
• Single-service modular monolith: everything runs in one Python process; separation is by module, not microservices.
• Ports & adapters style (informally):
• Ports: agent interface invoked by Flask/CLI
• Adapters: llm_call.py for Groq; tools.py for external info sources
• Pluggable tools: add function in tools.py, add schema + registry mapping in agent.py.
What to label explicitly (tech + interfaces)
• Protocols
• Browser → Flask: HTTP (JSON)
• Flask → Agent: Python function call
• LLM Adapter → Groq: HTTPS API
• Tools → Wikipedia/DDG/Websites: HTTPS requests
• Key API endpoint
• POST /chat (request {message} → response {response})
• Configuration
• GROQ_API_KEY (env var)
• Optional: FLASK_DEBUG, FLASK_PORT
• Runtime options
• “Run as CLI” vs “Run as Web server”
• “Dockerized deployment” boundary