How calvhobbes/ai-agents works
Project Type and Purpose
• This is a small demo project (“sample AI agent code”) that implements Retrieval-Augmented Generation (RAG) agents using LlamaIndex for vector indexing plus Google’s Gemini-Flash model (via the google.generativeai client) in place of the paid Vertex AI API.
• It consists of two Jupyter notebooks showing two flavors of an “agent” (one with a RAG pipeline, one illustrating pure Gemini-Flash agent patterns), plus the requirements file.
High-Level Architecture
A. Data & Indexing Layer
– Source documents or data you want to query (PDFs, text, etc.)
– LlamaIndex component that ingests those documents and builds/stores a vector store.
B. Agent Orchestration Layer
– A Python “controller” (the notebook code) that:
• Accepts a user query
• Fetches relevant context from the vector store via LlamaIndex
• Packages the context + query into a prompt template
• Invokes the Gemini-Flash model through google.generativeai
C. LLM Service Layer
– External Gemini-Flash API endpoint (hosted by Google) that returns model completions.
Main Components
1. “Data Sources” node (local files, external corpus)
2. “LlamaIndex” node (vector store & index builder)
3. “Agent Controller” node (the notebook code split into: ingestion module, query handler, prompt builder)
4. “Google Gemini-Flash” node (external service)
5. “User / Client” node (the user or upstream service sending queries)
Relationships & Data Flows
• User → Agent Controller: submits a query
• Agent Controller → LlamaIndex: “retrieve top-k relevant documents”
• LlamaIndex → Agent Controller: returns document embeddings + metadata
• Agent Controller → Gemini-Flash API: submits prompt (query + context)
• Gemini-Flash → Agent Controller: returns text completion
• Agent Controller → User: returns the final answer
Architectural Patterns & Design Principles
• Layered separation: keep data ingestion/indexing separate from “agent logic.”
• Modular notebook code: split into functions or classes for ingestion, retrieval, prompt-templating, and external calls.
• Dependency management: capture all third-party libraries in agentic_rag_llamaindex_requirements.txt.
• Stateless orchestration: the notebooks themselves are stateless controllers that call out to the vector store and LLM service.