Incomex AI Portal
KB-6B9B

Prefect Orchestration — SSOT

3 min read Revision 1
prefectorchestrationai-councilssot

Prefect Orchestration — SSOT

Version: 1.1
Date: 2026-02-27
Scope: AI Council Macro Orchestration Layer
Status: Draft (Pre-Install Phase)

I. MỤC ĐÍCH

Prefect được chuẩn hóa là Macro Orchestration Layer cho hệ AI Council.

Vai trò:

  • Điều phối workflow AI nhiều giai đoạn
  • Retry / Timeout / Failure recovery
  • Parallel execution
  • Conditional branching
  • Theo dõi long-running processes
  • Monitoring & logging cấp hệ thống

Prefect KHÔNG thay thế:

  • Agent Data (Shared Memory Layer)
  • Directus (Governance UI)
  • MCP (Transport Layer)
  • Langroid A2A (Micro reasoning loop)

II. KIẾN TRÚC TRIỂN KHAI

Deployment Model

Prefect chạy trên VPS (Dockerized).

Bắt buộc có:

  • prefect-server (container)
  • prefect-worker (container)
  • PostgreSQL (shared instance — xem SSOT PostgreSQL)

Không được:

  • Dùng SQLite production
  • Dùng chung MySQL chính (Directus)
  • Dùng Firestore làm metadata DB

III. DATABASE DESIGN

Prefect sử dụng PostgreSQL làm metadata database.

Yêu cầu:

  • Schema riêng: prefect
  • Không trộn với schema khác
  • Không truy cập trực tiếp ngoài Prefect service

PostgreSQL instance này sẽ được chuẩn hóa để dùng chung với Kestra.

IV. TẦNG LOGIC

Macro Layer — Prefect

  • Workflow lifecycle
  • State transitions
  • Failure handling
  • Parallelization
  • Governance enforcement

Durable Memory — Agent Data

  • Shared memory
  • Reports
  • Decisions
  • Vector integrity

Micro Layer — A2A (Langroid)

  • AI Council debate
  • Planner vs Critic
  • Voting & synthesis

A2A chỉ tồn tại trong phạm vi một workflow step.

V. STORAGE

Metadata

  • PostgreSQL
  • Schema: prefect

Artifacts

  • Google Cloud Storage (GCS) — khuyến nghị
  • Hoặc Docker volume

VI. NGUYÊN TẮC VẬN HÀNH

  1. Không hardcode credentials
  2. Mọi config qua environment variables
  3. Không bypass MCP khi truy cập Agent Data
  4. Không async hóa write gây orphan vector
  5. CI phải GREEN trước khi deploy

VII. TƯƠNG QUAN VỚI CI/CD

  • Repo agent-data-test → build qua GitHub → deploy Google Artifact
  • Repo web-test → build qua GitHub → deploy trực tiếp VPS

Prefect sẽ:

  • Deploy trực tiếp trên VPS
  • Không qua Google Artifact
  • Được quản lý bằng Docker Compose

VIII. THAM SỐ TRIỂN KHAI (SẼ CHI TIẾT HÓA)

Ports (Proposed)

  • Prefect UI: 4200
  • PostgreSQL: 5432 (internal)

Env Vars (Draft)

  • PREFECT_API_URL
  • PREFECT_DB_HOST
  • PREFECT_DB_NAME
  • PREFECT_DB_USER
  • PREFECT_DB_PASSWORD

(Chi tiết sẽ bổ sung trong tài liệu triển khai riêng.)

IX. KẾT LUẬN

Prefect được chuẩn hóa là lớp điều phối AI cấp hệ thống.

Nó phụ thuộc PostgreSQL và không thay thế Agent Data.

Prefect + Agent Data + A2A tạo thành 3 tầng AI Council.