Skip to main content

00 - Architecture Overview

Welcome to the core architecture documentation of the Aegis Agent Platform. This document provides an accurate overview of the system architecture based on the actual codebase and design of the project.

Vision​

To build a financial-grade AI Gateway and Agent management platform that provides high-strength governance, observability, and security for enterprise Large Language Model (LLM) ecosystems.

Core Principles​

  • Security & Governance First: Provides multi-tenant isolation based on IAM / RBAC, supporting quota and safety guardrail policies at the Organization and Team levels via VirtualKeys (API credentials).
  • Real-Time Observability: Combines PostgreSQL and ClickHouse to balance administrative data reliability with sub-second aggregate query performance for high-concurrency, massive trace streams (conversation chains and invocation chains).
  • Standardized Agent Lifecycles: Through the runtime registration mechanism (Taimoe Runtime SDK), engineers define the Agent backbone (Code-first), while operations teams can override Prompts, models, parameters, and tools in real-time via the Console interface (Hybrid-mode).
  • Vertex AI Native & ADK Core: Deeply integrates with the Google Cloud ecosystem, directly connecting to Vertex AI (Gemini 1.5/2.0 models), fusing with Google ADK (Agent Development Kit), and integrating Microsoft Teams Bot and Google Cloud Storage (GCS).

High-Level System Architecture​

The Aegis platform consists of the following key components:

  1. User Facing (Console & Chat UI):

    • Aegis Console (aegis-console): The administrative dashboard for managers and operations teams. Built on Vite + React 19, it uses Material UI (MUI) as the UI component library, manages routes with React Router Dom, and integrates with Google OAuth. It uses XYFlow/Dagre to render Agent topologies and workflow graphs, and ECharts for observability dashboards.
    • Aegis Chat (aegis-chat): A lightweight dialog client for sandbox testing and direct conversations. Also built on Vite + React 19, utilizing MUI, google-oauth, react-markdown, and highlight.js.
    • Dashboard (dashboard.py): A rapid operational dashboard powered by Streamlit for development debugging and metric inspection.

  2. Backend Services (Core Services):

    • FastAPI API Engine (app/main.py): The unified core API written in Python FastAPI. It includes IAM/RBAC, Runtime Registry, Agent configuration, Knowledge Base registry, observability/audit centers, and connects directly to Redis and databases.
    • Microsoft Teams Bot: A Teams bot adapter integrated with the FastAPI backend to bring platform Agents directly into Teams workspaces.

  3. Storage Tier (Multi-Dimensional Storage):

    • PostgreSQL: Stores strong-consistency data such as organization, team, user, IAM roles, Agent attributes, Runtime records, Prompt library, and API keys.
    • ClickHouse: Dedicated to high-throughput trace spans and Audit Logs, linking to large text payloads in GCS for sub-second analytical querying.
    • GCS (Google Cloud Storage): Backs up System Prompt versions and stores large conversation JSON payloads and ADK artifacts.
    • Redis: Caches frequently accessed Agent configurations, RBAC entries, VirtualKey validation states, and distributed IP/Key-based rate limiting.

  4. Runtime & SDK (Agent Execution & Taimoe SDK):

    • Taimoe Python SDK (taimoe-python): Provides Agent registration, auto-introspection, 5-minute polling for dynamic prompt updates, and distributed tracing span injection.
    • Agent Runtime: Runs in GKE, Cloud Run, or local containers, executing ADK-driven Agent logic and establishing unidirectional or bidirectional communication with the platform.

  5. AI Core & Grounding:

    • Vertex AI SDK: Directly communicates with Google Cloud Vertex AI (e.g., gemini-1.5-flash-001 models).
    • Grounding Integration: Supports Google Search Grounding and Vertex AI Search datastore grounding, applying PII Redaction and Model Armor safety policies.

System Diagram​

flowchart TB
  %% Actors
  user[End User / Client App]
  admin[Platform Admin / Console]
  runtime[Agent Runtime<br/>ADK / Cloud Run / Agent Engine]
  sdk[taimoe-python SDK<br/>Registry / Sync / Trace]

  %% Platform
  subgraph aegis[Aegis / Taimoe Platform]
    api[FastAPI API Engine]
    auth[Auth / IAM / RBAC<br/>User, Team, VirtualKey]
    gateway[AI Gateway<br/>Model Alias, Key Validation, Rate Limit]
    registry[Runtime Registry<br/>Discovery, Health Check, Agent Import]
    config[Agent Config<br/>Model, Prompt, Tools, KB bindings]
    kbapi[Knowledge Base API<br/>Credentials, KB Registry, Test Query]
    obs[Observability<br/>Trace / Span Ingestion]
    audit[Audit Logs<br/>Request, Token, Latency, Status]
    policy[Policy Guard<br/>PII, Quota, Model Armor]
  end

  %% Storage
  subgraph storage[Platform Storage]
    pg[(PostgreSQL<br/>Org, Team, Agent, Runtime,<br/>Prompt, KB, Provider, Key)]
    ch[(ClickHouse<br/>Spans / Trace Analytics)]
    gcs[(GCS<br/>Prompt Sync / Payload Artifacts)]
    redis[(Redis<br/>Cache / Rate Limit)]
  end

  %% External providers
  subgraph google[Google / External Providers]
    gemini[Gemini / Vertex AI Models]
    aisearch[Vertex AI Search / Agent Search]
    googlesearch[Google Search Grounding]
  end

  teams[Microsoft Teams Bot]

  %% Main user paths
  user --> runtime
  user --> gateway
  admin --> api
  teams --> api

  %% Runtime + SDK
  runtime --> sdk
  sdk -->|GET /health /agents /.well-known| registry
  sdk -->|GET /runtimes/:id/agents/sync| config
  sdk -->|POST /observability/spans/batch| obs

  %% Platform internal
  api --> auth
  api --> registry
  api --> config
  api --> kbapi
  api --> obs
  api --> audit
  gateway --> auth
  gateway --> policy
  gateway --> audit

  %% Governed LLM path
  runtime -->|LLM call through Gateway<br/>Gemini generateContent body| gateway
  gateway -->|provider call| gemini
  gemini -->|response + usage + groundingMetadata| gateway

  %% Grounding through Gemini body
  gateway -. parses tools[].google_search .-> googlesearch
  gateway -. parses tools[].retrieval.vertexAiSearch.datastore .-> aisearch

  %% KB governed path
  runtime -->|preferred: platform-mediated KB query| kbapi
  kbapi -->|platform-owned credential| aisearch

  %% Storage links
  auth --> pg
  registry --> pg
  config --> pg
  kbapi --> pg
  gateway --> pg
  gateway --> redis
  obs --> ch
  audit --> pg
  config --> gcs

  %% Bypass path
  runtime -. bypass if runtime owns credential<br/>direct AI Search call .-> aisearch

  classDef governed fill:#dff3e4,stroke:#2f855a,color:#123524;
  classDef platform fill:#e8f1ff,stroke:#2563eb,color:#102a43;
  classDef storage fill:#fff7db,stroke:#b7791f,color:#3d2b00;
  classDef external fill:#f3e8ff,stroke:#7e22ce,color:#2e1065;

  class api,auth,gateway,registry,config,kbapi,obs,audit,policy platform;
  class pg,ch,gcs,redis storage;
  class gemini,aisearch,googlesearch external;
  class runtime,sdk governed;

Core Data Flow​

  1. Administration & Config Lowering:

    • Admins modify Agent configuration or System Prompts via the aegis-console.
    • FastAPI API Engine saves the changes to PostgreSQL, writes backups to GCS, and purges corresponding caches in Redis.
    • The taimoe-python SDK background thread running in the Runtime polls (/sync endpoint) every X seconds, fetching the latest config and caching it in Runtime memory for subsequent conversations.

  2. Conversation & LLM Invocation (Governed Path):

    • An end user sends a request to the Runtime.
    • The ADK Agent loads the latest Prompt. When an LLM call is needed, it sends the request to Aegis's AI Gateway.
    • AI Gateway performs API Key authentication and checks Team quotas.
    • The Gateway resolves the model_alias (e.g., gemini-flash) to the actual Vertex AI project/model, applying PII / Model Armor safety guardrails.
    • The Gateway directly calls Vertex AI to fetch generation results, parsing the response body, token usage, and grounding metadata.
    • Observation spans are written to ClickHouse, and operational event details are logged to PostgreSQL audit tables.
    • The Gateway returns standardized results to the Runtime, which is ultimately presented back to the user.