How dawnjo123/ai-agent-builder works
What this project is (type + purpose)
This is a small backend-only REST API (single service) that acts as an “AI Agent Builder”:
• Clients call POST /generate_agent with a natural-language “query”.
• The service uses an LLM provider (Groq or OpenRouter) to generate an agent definition (custom system prompt + chosen tools).
• Clients then call GET /run_agent/<agent_id> to execute the agent, which invokes a set of tools (scrape web, summarize PDFs, send email, post to Twitter, log to file).
• Agent configs are retrievable via GET /all_agents.
• API layer (Flask app)
• Agent generation / orchestration
• LLM provider integration
• Tool plugins (and which ones are real vs mocked)
• State/storage for agent definitions + log file output
• External systems (websites, LLM APIs)
File structure → architectural components
From the tree:
• app.py
• Main entry point: defines REST endpoints, initializes the LLM client, builds/executes agents, routes requests.
• tools/ package
• web_scraper.py: real network calls (requests + BeautifulSoup)
• pdf_summarizer.py: reads PDFs from uploads/ path (not in tree, but described)
• email_sender.py: mocked (prints)
• twitter_tool.py: mocked (prints)
• file_logger.py: real filesystem write (e.g., agent_logs.txt)
• requirements.txt
• Agent Builder APIs.postman_collection.json
• .env (implied by README)
• Runtime config: API keys and base URL.
Key architectural implication: monolith service with a tool-plugin style module layout.
README → runtime interactions and boundaries
Important details to reflect:
• Dual LLM support
• Groq is “primary”, OpenRouter is optional toggle in app.py.
• Both are external SaaS dependencies.
• Tools differ by integration fidelity
• Real: Web Scraper, File Logger, LLM calls
• Mocked: Email Sender, Twitter Tool
• PDF summarizer is “real-ish” locally (reads from uploads path), but no external storage service is shown.
• No explicit database
• Shows the API service as a container and its external dependencies.
• This is what stakeholders use to understand the system at a glance.
• Shows app.py split into logical components: routing/controllers, agent factory, execution engine, tool interfaces, tool implementations.
• This is what engineers use to reason about change impact, testing, and extensibility.
Main components
External Actors / Clients
• “API Client” (Postman, frontend, other service)
API Service (single process)
• Flask API / Router (endpoints)
• Agent Builder (LLM prompt construction + tool selection)
• Agent Registry (in-memory store of agents: id → {name, query, prompt, tools})
• Agent Runner / Orchestrator (executes tool calls in a workflow)
• Tool Interface / Dispatcher (maps tool names to implementations)
**Tool Implementations (tools/*)**
• Web Scraper (HTTP GET → parse HTML)
• PDF Summarizer (read PDFs from local uploads/ → summarize via LLM or internal logic; depends on code)
• Email Sender (mock; console output)
• Twitter Tool (mock; console output)
• File Logger (write to agent_logs.txt)
External Services
• Groq API (LLM)
• OpenRouter API (LLM)
• Target Websites (for scraping)
Data Stores / Artifacts
• Local filesystem:
• agent_logs.txt
• uploads/ directory (PDF inputs)
• Environment variables / .env (configuration source)
API → Client (agent_id, tools, prompt)
• “Natural language query”
• “LLM prompt → tool selection”
• “Agent config persisted (in-memory)”
Tools may call
• Web Scraper → External Website (HTTP)
• PDF Summarizer → Local uploads/ (read) and possibly → LLM Provider (if it summarizes via LLM)
• File Logger → Local filesystem write
Get all agents (GET /all_agents)
• Client → /all_agents
• Flask → Agent Registry → returns list
Architectural patterns/design principles to highlight (project-specific)
• State management: no DB present → likely in-memory registry. Mark as a limitation and a replaceable component (future: Redis/Postgres).
Required elements
• e.g., “Flask API (app.py)”, “Agent Registry (in-memory)”, “Groq LLM API”
• Blue rectangles: internal components (within your service boundary)
• Orange clouds: external services (Groq/OpenRouter, websites)
• “AI Agent Builder Service (Python/Flask)” boundary containing:
• Router, Builder, Runner, Registry, Tools
• Outside boundary:
• Clients
• LLM providers
• Websites
• (Optional) Console/Stdout as a sink for mocked tools
Don’t overthink it: maximize component separation
For this project, “best and most accurate” means you split the monolith into explicit logical components even if they live in one file:
• Routes/Controllers
• Agent lifecycle management (create/store/list)
• Execution engine
• Tool interface + concrete tools
• External provider adapters (Groq/OpenRouter)
• Storage artifacts (uploads, logs)