g1-agent-backend 🦾

PydanticAI streaming agent backend — multi-tenant chat API with conversation persistence, MCP tool access, and GPU infrastructure introspection.

---

✨ Overview

g1-agent-backend is the Python AI agent service for Generate One. Built on FastAPI and PydanticAI, it provides a streaming chat API that proxies through LiteLLM, persists multi-tenant conversations in PostgreSQL, and validates requests via Authentik OIDC JWT. It also exposes infrastructure introspection tools (Docker stats, GPU metrics via nvidia-smi) and an Excalidraw diagram generation tool — making it the primary AI gateway for app.generate.one.

---

🏗️ Architecture

graph TD
    Client["app.generate.one\n(g1-frontend)"]
    
    subgraph "g1-agent-backend (agent.generate.one)"
        FastAPI["FastAPI\n:8000"]
        Agent["PydanticAI Agent\n(main.py)"]
        Auth["JWT Auth\n(Authentik JWKS)"]
        DB["asyncpg\n(conversation persistence)"]
        
        subgraph "Tools"
            InfraTools["infra.py\nDocker stats, GPU metrics\nCoolify API"]
            ExcalidrawTool["excalidraw.py\nDiagram generation"]
        end
        
        FastAPI --> Auth
        FastAPI --> Agent
        Agent --> InfraTools
        Agent --> ExcalidrawTool
        Agent --> DB
    end

    subgraph "External Services"
        LiteLLM["g1-llm / LiteLLM\nllm.generate.one"]
        MetaMCP["g1-mcp / MetaMCP\nmcp.generate.one"]
        PG["g1-core / PostgreSQL\ng1_agent DB"]
        Authentik["g1-auth / Authentik\nauth.generate.one"]
    end

    Client --> FastAPI
    Agent --> LiteLLM
    Agent --> MetaMCP
    DB --> PG
    Auth --> Authentik

---

📦 Services

Service	Image	Port	Description
g1-agent-backend	g1-agent-backend:latest (local build)	8200→8000	FastAPI agent with SSE streaming

The container mounts the Docker socket (read-only) and nvidia-smi for infrastructure introspection.

---

🔗 API Endpoints

Method	Path	Auth	Description
GET	/health	Public	Health check
POST	/api/chat	JWT	Streaming chat — proxies to LiteLLM, persists conversation
POST	/api/ag-ui	JWT (admin)	AG-UI adapter endpoint

Streaming Response

/api/chat returns text/event-stream (SSE) with real-time token streaming. The X-Conversation-ID header in the response carries the persisted conversation ID for follow-up requests.

---

🔧 Configuration

Variable	Description
DATABASE_URL	PostgreSQL connection string (g1_agent DB on shared PG)
AUTHENTIK_JWKS_URL	Authentik OIDC JWKS endpoint for JWT validation
LITELLM_BASE_URL	LiteLLM proxy URL (internal Docker network)
LITELLM_API_KEY	LiteLLM API key
METAMCP_BASE_URL	MetaMCP base URL for MCP tool access
METAMCP_API_KEY	MetaMCP API key
CORS_ORIGINS	Comma-separated allowed origins

CORS is configured for app.generate.one and admin.generate.one by default.

---

🛠️ Key Capabilities

• Multi-tenant isolation — Tenant context extracted from JWT, conversations scoped by tenant_id
• Conversation persistence — Messages stored in PostgreSQL (conversations + messages tables)
• SSE streaming — Real-time token streaming via text/event-stream
• Infrastructure tools — Docker container stats, GPU VRAM usage via nvidia-smi mount
• Diagram generation — Excalidraw tool (tools/excalidraw.py) for AI-generated diagrams
• MCP bridge — Connects to MetaMCP to expose all 195+ platform tools to the agent
• Role-based namespace access — Admin/user/viewer roles gate which MCP namespaces are accessible

---

🚀 Quick Start

# Local development
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Docker build
docker build -t g1-agent-backend:latest .

# Docker run (with GPU + Docker socket access)
docker compose up -d

Dependencies (Python)

pydantic-ai[vercel,ag-ui]>=1.67.0
fastapi>=0.115
uvicorn[standard]>=0.30
asyncpg>=0.30
PyJWT[crypto]>=2.8
httpx>=0.27
boto3>=1.34

---

📂 Code Structure

File	Description
main.py	FastAPI app, SSE streaming, conversation management (31K)
agent.py	PydanticAI agent definition, JWT auth, MCP server cache, role-based namespace access
infra.py	Infrastructure introspection tools (Docker, GPU, Coolify API)
db.py	PostgreSQL async connection and schema management
models.py	Pydantic request/response models
tools/excalidraw.py	Excalidraw diagram generation tool
Dockerfile	Python 3.12-slim multi-stage build

---

🔗 Dependencies

Depends on:

• g1-llm — LiteLLM proxy for all LLM completions
• g1-mcp — MetaMCP for platform tool access
• g1-auth — Authentik OIDC JWKS for JWT validation
• g1-core — PostgreSQL g1_agent database

Depended on by:

• g1-frontend (apps/app) — Primary AI API consumer

---

🔗 Related Repos

Repo	Relationship
g1-frontend	Frontend apps that consume this API
g1-llm	LiteLLM for all model completions
g1-mcp	MetaMCP tools exposed to the agent
g1-auth	Authentik SSO provider

---

🛡️ Part of Generate One

Generate One — AI infrastructure that answers to you.

Self-hosted, sovereign AI platform. generate.one

Licensed under AGPL-3.0.