# agno-agi/agent-api architecture

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

- Interactive diagram: https://gitdiagram.com/agno-agi/agent-api
- Repository: https://github.com/agno-agi/agent-api

## Overview

##### Project type and purpose
- This is a backend‐only, containerized API service (“Simple Agent API”) whose sole responsibility is to host and expose conversational “Agents” (chatbots) over HTTP.
- It uses FastAPI as the web framework, PostgreSQL for persistence, and a suite of Python “Agents” that delegate to external AI services (e.g., OpenAI’s GPT).

##### File structure
- Top level:
- Dockerfile & compose.yaml – container image build and multi‐container orchestration (FastAPI + PostgreSQL).
- scripts/ – build, validate, format, entrypoint, and dev setup helpers.
- providers of environment config: example.env, .env, pyproject.toml, requirements.txt.
- agents/ – individual agent implementations (agno_assist, finance_agent, web_agent) plus a selector module.
- api/ – FastAPI entrypoint (main.py), router definitions (routes/), settings module.
- db/ – database URL and session setup.

##### README for additional insights
- Confirms FastAPI on port 8000, PostgreSQL on port 5432.
- Explains prebuilt agents that combine local logic with external APIs (web search, finance, Agno knowledge base).
- Describes local development (uv + scripts/dev_setup.sh) and Docker Compose for deployment, plus production workflows (build_image.sh, push to registry, deploy to Cloud Run/ECS/GKE, etc.).

a. Main components:
- Client(s): Swagger UI (localhost:8000/docs), Agno Playground or any HTTP client.
- FastAPI Application:
– Routers: /agents, /health, /playground, /v1_router
– Settings loader
– Uvicorn ASGI server
- Agents Layer:
– agno_assist, finance_agent, web_agent (and selector logic)
– Each agent may call: OpenAI API, YFinance API, Web search API, or internal knowledge‐base loader.
- Database Layer: PostgreSQL
– db.session for ORM sessions (likely SQLAlchemy)
– db.url for connection strings
- External Services:
– OpenAI (or other LLM provider)
– YFinance, Web Search endpoints
- Container Orchestration: Docker Compose (FastAPI container + Postgres container)

b. Relationships and data flows:
1. Client → FastAPI (HTTP)
2. FastAPI routes dispatch to agent selector → specific agent module
3. Agent module:
– May read/write state to PostgreSQL via db.session
– May call external endpoints (OpenAI, YFinance, Web Search)
4. FastAPI returns HTTP response to Client

c. Architectural patterns and principles:
- Layered architecture: Presentation (HTTP/Routers), Domain/Business (Agent logic), Persistence (DB), Integration (External APIs).
- Dependency Injection: FastAPI’s settings and DB session in request scope.
- Containerized micro-service: single service with its own DB container.

d. Key technologies and frameworks:
- Python 3.x, FastAPI, Uvicorn
- SQLAlchemy or similar via db.session
- Docker & Docker Compose
- External APIs: OpenAI, YFinance, Web Search

##### Detail to capture
- Api/routes sub‐system under “FastAPI” to indicate modular endpoints.
- How /agents routes use a Selector to pick which agent implementation to run.
- Session lifecycle: client request → new DB session → commit/close.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        Swagger["Swagger UI"]:::client
        Playground["Agno Playground\n(HTTP Client)"]:::client
    end

    %% Container Orchestration
    subgraph "Docker Compose" 
        direction TB
        Compose["FastAPI Container\n+ PostgreSQL Container\n(Ports: 8000, 5432)"]:::orchestration
    end

    %% FastAPI Application Container
    subgraph "FastAPI Service" 
        direction TB
        Main["api/main.py\n(Uvicorn ASGI Server)"]:::backend
        Routers["api/routes"]:::backend
        Health["api/routes/health.py"]:::backend
        AgentsRoute["api/routes/agents.py"]:::backend
        PlaygroundRoute["api/routes/playground.py"]:::backend
        V1Route["api/routes/v1_router.py"]:::backend
        Settings["api/settings.py"]:::backend
    end

    %% Agents Layer
    subgraph "Agents Layer" 
        direction TB
        Selector["agents/selector.py"]:::agent
        AgnoAssist["agents/agno_assist.py"]:::agent
        FinanceAgent["agents/finance_agent.py"]:::agent
        WebAgent["agents/web_agent.py"]:::agent
    end

    %% Persistence Layer
    subgraph "Database Layer" 
        direction TB
        URL["db/url.py"]:::db
        Session["db/session.py"]:::db
        Postgres["PostgreSQL"]:::db
    end

    %% External Services
    subgraph "External APIs" 
        direction TB
        OpenAI["OpenAI"]:::external
        YFinance["YFinance API"]:::external
        WebSearch["Web Search API"]:::external
    end

    %% Dev & CI/CD
    subgraph "Dev & CI/CD" 
        direction TB
        ExampleEnv["example.env"]:::config
        Pyproject["pyproject.toml"]:::config
        Requirements["requirements.txt"]:::config
        Dockerfile["Dockerfile"]:::config
        ComposeFile["compose.yaml"]:::config
        DevSetup["scripts/dev_setup.sh"]:::script
        BuildImage["scripts/build_image.sh"]:::script
        Entrypoint["scripts/entrypoint.sh"]:::script
        Validate["scripts/validate.sh"]:::script
        Format["scripts/format.sh"]:::script
        Utils["scripts/_utils.sh"]:::script
        GenReq["scripts/generate_requirements.sh"]:::script
        Workflow[".github/workflows/validate.yml"]:::script
    end

    %% Connections
    Swagger -->|"HTTP Request"| Main
    Playground -->|"HTTP Request"| Main
    Main -->|"includes routers"| Routers
    Routers -->|"/health"| Health
    Routers -->|"/agents"| AgentsRoute
    Routers -->|"/playground"| PlaygroundRoute
    Routers -->|"/v1"| V1Route
    Main -->|"loads config"| Settings
    AgentsRoute -->|"uses"| Selector
    Selector -->|"dispatch to"| AgnoAssist
    Selector -->|"dispatch to"| FinanceAgent
    Selector -->|"dispatch to"| WebAgent
    AgnoAssist -->|"LLM call: chat.completions"| OpenAI
    FinanceAgent -->|"finance data"| YFinance
    WebAgent -->|"search data"| WebSearch
    AgnoAssist -->|"DB read/write"| Session
    FinanceAgent -->|"DB read/write"| Session
    WebAgent -->|"DB read/write"| Session
    Session -->|"connect using"| URL
    Session -->|"ORM Session"| Postgres
    Main -->|"DB session injection"| Session

    Compose -->|"orchestrates"| Main
    Compose -->|"orchestrates"| Postgres

    %% Click Events
    click Main "https://github.com/agno-agi/agent-api/blob/main/api/main.py"
    click Health "https://github.com/agno-agi/agent-api/blob/main/api/routes/health.py"
    click AgentsRoute "https://github.com/agno-agi/agent-api/blob/main/api/routes/agents.py"
    click PlaygroundRoute "https://github.com/agno-agi/agent-api/blob/main/api/routes/playground.py"
    click V1Route "https://github.com/agno-agi/agent-api/blob/main/api/routes/v1_router.py"
    click Settings "https://github.com/agno-agi/agent-api/blob/main/api/settings.py"
    click Selector "https://github.com/agno-agi/agent-api/blob/main/agents/selector.py"
    click AgnoAssist "https://github.com/agno-agi/agent-api/blob/main/agents/agno_assist.py"
    click FinanceAgent "https://github.com/agno-agi/agent-api/blob/main/agents/finance_agent.py"
    click WebAgent "https://github.com/agno-agi/agent-api/blob/main/agents/web_agent.py"
    click Session "https://github.com/agno-agi/agent-api/blob/main/db/session.py"
    click URL "https://github.com/agno-agi/agent-api/blob/main/db/url.py"
    click Dockerfile "https://github.com/agno-agi/agent-api/tree/main/Dockerfile"
    click ComposeFile "https://github.com/agno-agi/agent-api/blob/main/compose.yaml"
    click ExampleEnv "https://github.com/agno-agi/agent-api/blob/main/example.env"
    click Pyproject "https://github.com/agno-agi/agent-api/blob/main/pyproject.toml"
    click Requirements "https://github.com/agno-agi/agent-api/blob/main/requirements.txt"
    click DevSetup "https://github.com/agno-agi/agent-api/blob/main/scripts/dev_setup.sh"
    click BuildImage "https://github.com/agno-agi/agent-api/blob/main/scripts/build_image.sh"
    click Entrypoint "https://github.com/agno-agi/agent-api/blob/main/scripts/entrypoint.sh"
    click Validate "https://github.com/agno-agi/agent-api/blob/main/scripts/validate.sh"
    click Format "https://github.com/agno-agi/agent-api/blob/main/scripts/format.sh"
    click Utils "https://github.com/agno-agi/agent-api/blob/main/scripts/_utils.sh"
    click GenReq "https://github.com/agno-agi/agent-api/blob/main/scripts/generate_requirements.sh"
    click Workflow "https://github.com/agno-agi/agent-api/blob/main/.github/workflows/validate.yml"

    %% Styles
    classDef client fill:#cccccc,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:1px,shape:rect
    classDef agent fill:#FFA500,stroke:#333,stroke-width:1px,shape:rect,rx:5,ry:5
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px,shape:cloud
    classDef orchestration fill:#FFE4B5,stroke:#333,stroke-width:1px,shape:rect
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef script fill:#E0E0E0,stroke:#333,stroke-width:1px,shape:parallelogram
```
