# gurezende/agno-ai-labs architecture

> Architecture diagram of the GitHub repository gurezende/agno-ai-labs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gurezende/agno-ai-labs
- Repository: https://github.com/gurezende/agno-ai-labs

## Overview

##### Project Type and Purpose
- This is an open-source Python toolkit and sample repository for building AI agents.
- Its focus is on orchestrating LLMs (e.g. Gemini, OpenAI, Groq) with external “tools” (web search, YouTube, Wikipedia), plus a local vector-search store (LanceDB + Tantivy).

##### File Structure
- Top-level:
– README.md, pyproject.toml, scripts/, scripts2/ — entry-point examples
– tmp/lancedb/ — local LanceDB vector store, with Tantivy FTS indices
– img/, output/ — documentation and demo outputs
- scripts/ & scripts2/: each contains Python scripts that import from the Agno core (Agent, Model classes) plus tool modules (e.g. file_handling.py, wiki.py).
- Dependencies/config: pyproject.toml lists agno, google-generativeai, groq, lancedb, sentence-transformers, tantivy, youtube-transcript-api.

##### Extract Architectural Insights from README
- Single core “Agent” class orchestrates the pipeline:
– Model layer (Gemini, other LLMs)
– Tool layer (web search, YouTube transcript, file IO, memory)
– Memory layer (LanceDB as a vector store with filtering/full-text search via Tantivy)

##### Main Components
a. Entry-point Scripts
– scripts/*.py, scripts2/*.py
– CLI or programmatic invocations of Agent.run()
b. Agent Core
– Agent class (agno.agent)
– Instruction & prompt construction
c. Model Layer
– Gemini (agno.models.google)
– Other LLM connectors (OpenAI, Groq)
d. Tool/Utility Modules
– file_handling, agent_memory, agent_news, wiki, YouTube, reasoning, etc.
– Each encapsulates a “tool” the agent can call
e. Memory & Index Store
– LanceDB on local file system (tmp/lancedb)
– Underlying Tantivy full-text index
– Memory retrieval & storage interface
f. External Services
– Gemini API
– Other LLM APIs
– YouTube Transcript API
– Web/internet search (if Firecrawl or custom)

##### Component Relationships & Interactions
– Scripts invoke Agent.run() → Agent orchestrates:
1. Prompt & instruction builder
2. Calls Model API → receives LLM output
3. Based on the output, dispatches one or more Tool modules
4. Tools may:
- Call external APIs (YouTube, web search)
- Read/write to local file system
- Query/update LanceDB memory store
5. Aggregates results and returns to script
– Memory store (LanceDB) persists embeddings and metadata; Tantivy layer enables FTS.
– Agent can chain multiple tool calls—represent as feedback loops or pipelines.

##### Architectural Patterns & Design Principles
- Modular “Tool” pattern—each capability is an isolated module with a well-defined interface.
- Pipeline/chain-of-thought orchestration—Agent sequences tool invocations based on LLM guidance.
- Separation of concerns—prompting logic, model invocation, tool execution, and memory are distinct layers.
- Extensibility—new tools or models can be added by conforming to the Agent’s tool interface.

##### Technologies & Frameworks to Annotate
- Python 3.x, Agno library (Agent, Model abstractions)
- Google Gemini, OpenAI, Groq model connectors
- LanceDB (vector store) + Tantivy (FTS)
- Sentence-Transformers (embedding generation)
- youtube-transcript-api, requests or custom web-scraping (Firecrawl)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry-point Scripts
    subgraph "Entry-point Scripts"
        direction TB
        HelloWorld["hello_world.py"]:::internal
        AgentNews["agent_news.py"]:::internal
        FileHandlingScript["file_handling.py"]:::internal
        WikiScript["wiki.py"]:::internal
        FirecrawlScript["Firecrawl.py"]:::internal
        ReasoningScript["reasoning.py"]:::internal
        ContentWriter["content_writer.py"]:::internal
        Guardrails["agent_on_guardrails.py"]:::internal
        DataDocs["data_docs.py"]:::internal
    end

    %% Core
    AgentCore["Agent Class (agno.agent)"]:::internal

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        Gemini["Gemini Adapter"]:::internal
        OpenAI["OpenAI Adapter"]:::internal
        Groq["Groq Adapter"]:::internal
    end

    %% Tools
    subgraph "Tools"
        direction TB
        FileIO["File I/O Tool"]:::internal
        Wikipedia["Wikipedia Tool"]:::internal
        WikiEval["Wiki Eval Tool"]:::internal
        YouTubeTrans["YouTube Transcript Tool"]:::internal
        AgentMemory["Agent Memory Interface"]:::internal
        NewsTool["News Tool"]:::internal
        WebSearch["Web Search Tool"]:::internal
        Reasoning["Reasoning Tool"]:::internal
        Marketer["Marketer Example"]:::internal
    end

    %% Memory Store
    subgraph "Memory Store"
        direction TB
        LanceDB["LanceDB Store"]:::storage
        Tantivy["Tantivy FTS Index"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GeminiAPI["Gemini API"]:::external
        OpenAIAPI["OpenAI API"]:::external
        GroqAPI["Groq API"]:::external
        YouTubeAPI["YouTube Transcript API"]:::external
        WebSearchSvc["Web Search Service"]:::external
    end

    %% Documentation & Config
    README["README.md"]:::external
    PyProject["pyproject.toml"]:::external
    OutputDir["output/"]:::external
    ImgDir["img/"]:::external

    %% Connections
    HelloWorld -->|runs| AgentCore
    AgentNews -->|runs| AgentCore
    FileHandlingScript -->|runs| AgentCore
    WikiScript -->|runs| AgentCore
    FirecrawlScript -->|runs| AgentCore
    ReasoningScript -->|runs| AgentCore
    ContentWriter -->|runs| AgentCore
    Guardrails -->|runs| AgentCore
    DataDocs -->|runs| AgentCore

    AgentCore -->|invokes| Gemini
    AgentCore -->|invokes| OpenAI
    AgentCore -->|invokes| Groq

    AgentCore -->|dispatches| FileIO
    AgentCore -->|dispatches| Wikipedia
    AgentCore -->|dispatches| WikiEval
    AgentCore -->|dispatches| YouTubeTrans
    AgentCore -->|dispatches| AgentMemory
    AgentCore -->|dispatches| NewsTool
    AgentCore -->|dispatches| WebSearch
    AgentCore -->|dispatches| Reasoning
    AgentCore -->|dispatches| Marketer

    FileIO <-->|read/write| LanceDB
    Wikipedia <-->|query/update| LanceDB
    WikiEval <-->|query/update| LanceDB
    YouTubeTrans <-->|query/update| LanceDB
    AgentMemory <-->|embed/query| LanceDB
    NewsTool <-->|query/update| LanceDB
    WebSearch <-->|embed/query| LanceDB
    Reasoning <-->|query/update| LanceDB
    Marketer <-->|query/update| LanceDB

    FileIO <-->|FTS search| Tantivy
    Wikipedia <-->|FTS search| Tantivy
    WikiEval <-->|FTS search| Tantivy
    YouTubeTrans <-->|FTS search| Tantivy
    AgentMemory <-->|FTS search| Tantivy
    NewsTool <-->|FTS search| Tantivy
    WebSearch <-->|FTS search| Tantivy
    Reasoning <-->|FTS search| Tantivy
    Marketer <-->|FTS search| Tantivy

    Gemini -->|API call| GeminiAPI
    OpenAI -->|API call| OpenAIAPI
    Groq -->|API call| GroqAPI
    YouTubeTrans -->|HTTP request| YouTubeAPI
    WebSearch -->|HTTP request| WebSearchSvc

    README --- AgentCore
    PyProject --- AgentCore
    OutputDir --- AgentCore
    ImgDir --- AgentCore

    %% Click Events
    click HelloWorld "https://github.com/gurezende/agno-ai-labs/blob/main/scripts/hello_world.py"
    click AgentNews "https://github.com/gurezende/agno-ai-labs/blob/main/scripts/agent_news.py"
    click FileHandlingScript "https://github.com/gurezende/agno-ai-labs/blob/main/scripts/file_handling.py"
    click WikiScript "https://github.com/gurezende/agno-ai-labs/blob/main/scripts/wiki.py"
    click FirecrawlScript "https://github.com/gurezende/agno-ai-labs/blob/main/scripts/Firecrawl.py"
    click ReasoningScript "https://github.com/gurezende/agno-ai-labs/blob/main/scripts/reasoning.py"
    click ContentWriter "https://github.com/gurezende/agno-ai-labs/blob/main/scripts2/content_writer.py"
    click Guardrails "https://github.com/gurezende/agno-ai-labs/blob/main/scripts2/agent_on_guardrails.py"
    click DataDocs "https://github.com/gurezende/agno-ai-labs/blob/main/scripts2/data_docs.py"
    click README "https://github.com/gurezende/agno-ai-labs/blob/main/README.md"
    click PyProject "https://github.com/gurezende/agno-ai-labs/blob/main/pyproject.toml"
    click OutputDir "https://github.com/gurezende/agno-ai-labs/tree/main/output/"
    click ImgDir "https://github.com/gurezende/agno-ai-labs/tree/main/img/"
    click LanceDB "https://github.com/gurezende/agno-ai-labs/tree/main/tmp/lancedb/"
    click Tantivy "https://github.com/gurezende/agno-ai-labs/tree/main/tmp/lancedb/projects.lance/_indices/fts/"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#6fa8dc
    classDef storage fill:#f9cb9c,stroke:#e69138
    classDef external fill:#b6d7a8,stroke:#38761d
```
