Astraea ADK (LegionADK)

Enterprise-Grade Mixture-of-Agents (MoA) Orchestration & Autonomous Agent Development Kit

Astraea ADK (LegionADK) adalah framework dan runtime tingkat enterprise untuk perancangan, orkestrasi, tata kelola keamanan (governance), memori graf lokal, serta komunikasi sistem multi-agen berbasis Mixture-of-Agents (MoA). ADK ini dirancang dari nol dengan fokus pada determinisme matematis, pencegahan balapan data (race condition), efisiensi biaya inferensi token LLM, dan keandalan tingkat produksi (production-grade resilience).

📑 Daftar Isi

• 📖 Panduan Lengkap API (documentation.md)
• Arsitektur Sistem (Layer Breakdown)
• Fitur Utama (Core Features)
• Konfigurasi Lingkungan (.env)
• Panduan Penggunaan Cepat (Quickstart)
  • A. Membangun Roster Agen Dinamis
  • B. Cara 1: Diskusi Multi-Putaran Eksplisit (run_moa_debate)
  • C. Cara 2: Triase Otonom & Pendelegasian Mandiri (run_autonomous_triage)
  • D. Fasad Tingkat Atas: Router Otomatis (dispatch_envelope)
  • E. Strict Chain-of-Command Rekursif (Hierarki Berjenjang)
• Verifikasi & Checkpoint Test Suite
• Lisensi

🏗 Arsitektur Sistem (Layer Breakdown)

Astraea ADK dibangun dengan arsitektur berlapis (layered architecture) yang modular, deterministik, dan terisolasi dengan batas tanggung jawab (separation of concerns) yang jelas. Setiap lapisan saling berkolaborasi melalui protokol komunikasi yang terstandarisasi:

1. Protocol Layer (MoA Orchestration Engine)

Lapisan orkestrasi tingkat tinggi yang mengendalikan interaksi, kolaborasi, dan alur kerja antar-agen:

• MoA Orchestration: Mengelola eksekusi Mixture-of-Agents secara adaptif. Agen koordinator dapat menganalisis persoalan secara mandiri, menentukan pembagian peran, dan membagi tugas ke berbagai spesialis terkait.
• Multi-Agent Debate: Memfasilitasi pertukaran ide, sintesis kompromi, dan evaluasi silang (cross-critique) multi-putaran antar-spesialis sebelum draf akhir disatukan kembali oleh peran agregator.
• Strict Chain-of-Command: Mengatur hierarki delegasi berjenjang (atasan ke bawahan) dengan batas kedalaman eksekusi terkontrol, pelacakan tumpukan panggilan (call stack tracking), serta pencegahan siklus delegasi (anti-cycle protection).

2. Runtime Layer (10-Phase Agent Turn Engine)

Mesin eksekusi inti yang memandu siklus hidup giliran (turn lifecycle) setiap agen secara deterministik dan terukur:

• 10-Phase Execution Pipeline: Menjalankan setiap giliran interaksi melalui tahapan terstandarisasi—mulai dari audit tata kelola awal (preflight), perakitan prompt dinamis, pemanggilan model terawasi (watchdog invocation), eksekusi aksi, evaluasi keamanan pasca-eksekusi, hingga finalisasi status.
• Context Compaction & Token Budgeting: Pengelolaan kuota token proaktif dengan strategi reduksi riwayat dua tingkat (summarization & eviction), menjaga relevansi konteks percakapan panjang tanpa melampaui jendela konteks model.
• Immutable State Transitions: Menjamin seluruh manipulasi status percakapan bersifat beku (immutable frozen state), mencegah mutasi data yang tidak terduga antar-giliran.

3. Gateway Layer (Resilient I/O & Routing)

Gerbang komunikasi berkecepatan tinggi yang menjembatani runtime agen dengan berbagai penyedia model LLM (foundation models):

• Model Router & Load Balancer: Manajemen lalu lintas inferensi multi-penyedia dengan isolasi kuota RPM/TPM, failover cascade otomatis, dan pemulihan mandiri (auto-cooldown) saat terjadi batasan laju (rate-limiting).
• Byte-Stable Cache Boundary: Segmentasi prompt statis dan dinamis dengan verifikasi hash deterministik untuk memastikan efisiensi biaya tertinggi dan retensi prompt caching penyedia LLM (>90% Cache HIT).
• Multi-LLM Adapters: Abstraksi konektor universal untuk penyedia model cloud terkemuka maupun model lokal (self-hosted / private inference).
• Self-Healing Tool Repair: Mekanisme penanganan anomali otomatis yang mampu memperbaiki payload JSON yang terpotong atau mengalami inkonsistensi sintaks sebelum diproses lebih lanjut.

4. Governance Layer (Security & Safety Guardrails)

Sistem pertahanan berlapis (defense-in-depth) yang menjamin keamanan dan kepatuhan eksekusi di lingkungan produksi:

• Deterministic Verifier: Validasi parametrik ketat terhadap seluruh aksi agen sebelum dieksekusi, mencegah manipulasi batas direktori kerja (path traversal) dan akses resource ilegal.
• Smart Guardian: Mesin audit perilaku agen secara real-time untuk mengevaluasi risiko eksekusi kode berbahaya, manipulasi instruksi (prompt injection), dan pola loop anomali.
• Circuit Breakers: Sakelar proteksi otomatis yang memutus rantai eksekusi saat layanan hilir mengalami kegagalan berulang, mencegah pemborosan kuota dan kelelahan sistem.
• Parallel Execution Guards: Pembatasan hak akses operasi mutasi bagi agen yang berjalan serentak, menjamin integritas data dan eliminasi total terhadap kondisi balapan (race condition).

5. Memory Layer (Local Knowledge Graph & Vault)

Infrastruktur memori graf pengetahuan lokal tanpa ketergantungan pada database eksternal yang rumit:

• Knowledge Graph Vault: Penyimpanan dokumen pengetahuan berbasis format terbuka dengan metadata terstruktur dan transaksi berkas atomik yang aman (atomic file-locking).
• Wiki-Links & Semantic Relations: Pengindeksan otomatis relasi dua arah (bidirectional links) dan penelusuran relasi dokumen secara deterministik untuk menemukan konteks yang relevan secara instan.

🌟 Fitur Utama (Core Features)

Astraea ADK dirancang untuk memenuhi standar keandalan, keamanan, dan efisiensi tingkat produksi (enterprise-grade) bagi ekosistem multi-agen modern:

• 100% Role-Agnostic Multi-Agent Ecosystem Tidak ada peran atau persona yang di-hardcode. Pengembang memiliki kebebasan penuh merancang struktur tim agen, persona (soul), SOP operasional, serta wewenang alat secara dinamis sesuai kebutuhan spesifik domain industri.

• Advanced Mixture-of-Agents (MoA) Collaboration Mendukung kolaborasi multi-agen canggih melalui dua pola operasional: konsensus debat multi-putaran untuk eksplorasi dan sintesis ide, serta triase otonom di mana koordinator memecah dan mendelegasikan tugas ke sub-tim spesialis secara mandiri.

• Strict Chain-of-Command & Anti-Cycle Hierarchies Mendukung pendelegasian hierarkis berjenjang (atasan ke bawahan) dengan batas kedalaman terkontrol, jaminan zero double-call pada LLM untuk efisiensi token, serta perlindungan tumpukan panggilan (call stack guard) yang mencegah siklus delegasi tanpa akhir.

• Byte-Stable Prompt Caching & Cost Optimizer Optimalisasi biaya inferensi tingkat lanjut dengan memisahkan identitas agen statis dari konteks dinamis secara deterministik. Memaksimalkan rasio Cache HIT hingga >90% pada penyedia LLM modern, memangkas latensi dan biaya operasional secara signifikan.

• Multi-Provider Resilience & Auto-Failover Konektivitas terintegrasi ke berbagai penyedia model cloud terkemuka serta infrastruktur self-hosted / private proxy. Dilengkapi isolasi kuota RPM/TPM mandiri, mekanisme failover cascade, serta pemulihan otonom saat terkena batas laju (HTTP 429/5xx).

• Self-Healing Tool Calling & JSON Repair Mesin perbaikan otomatis yang secara mandiri menambal keluaran model yang terpotong oleh batasan token (max_tokens), menyeimbangkan tanda kurung, membersihkan format data, dan menjamin keberhasilan pemanggilan fungsi tanpa crash.

• Enterprise-Grade Governance & Multi-Layer Guardrails Validasi deterministik sebelum aksi (pre-execution verifier), audit keamanan perilaku dan analisis risiko kode secara real-time, sakelar pemutus sirkuit (circuit breaker), serta isolasi ketat terhadap sistem operasi dan direktori berkas.

• Concurrency & Race-Condition Immunity Eksekusi multi-agen paralel yang kebal terhadap konflik data berkat mekanisme isolasi hak akses mutasi pada agen paralel serta transaksi berkas atomik (deadlock-free file locking).

• Local Knowledge Graph Memory Engine Penyimpanan memori jangka panjang berbasis graf pengetahuan lokal dengan penautan semantik dua arah (Wiki-Links) dan penelusuran jalur keterkaitan dokumen yang cepat, sepenuhnya mandiri tanpa dependensi database eksternal yang kompleks.

⚙️ Konfigurasi Lingkungan (.env)

Buat berkas .env pada direktori root proyek untuk menghubungkan penyedia LLM Anda:

# ============================================================================
# Universal Custom Provider (Aggregator / Private Proxy / Self-hosted vLLM)
# ============================================================================
CUSTOM_PROVIDER_API_KEY=your_api_key_here
CUSTOM_PROVIDER_BASE_URL=https://api.your-provider.com/v1

# Parameter Model Utama
TEST_PRIMARY_PROVIDER=custom
TEST_PRIMARY_MODEL=deepseek-v4.1-flash

# ============================================================================
# Official Providers (Opsional - Sesuai Kebutuhan)
# ============================================================================
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIzaSy...
OLLAMA_BASE_URL=http://localhost:11434/v1
VLLM_BASE_URL=http://localhost:8000/v1

# Matikan mode live pada test suite jika hanya ingin menguji algoritma offline:
# LEGION_SKIP_LIVE=1

🚀 Panduan Penggunaan Cepat (Quickstart)

A. Membangun Roster Agen Dinamis

LegionADK bersifat role-agnostic. Anda bebas menentukan nama peran, persona soul, dan batasan SOP:

from LegionADK.core.llm_spec import LLMSpec
from LegionADK.protocol import AgentRoster

roster = AgentRoster([
    LLMSpec(
        handle="@coordinator",
        agent_name="Koordinator Utama",
        soul_prompt="Kamu adalah koordinator tim yang analitis dan cermat.",
        system_prompt="Analisis topik dan delegasikan tugas ke spesialis terkait.",
        tool_permissions=["comm:delegate"],
    ),
    LLMSpec(
        handle="@architect",
        agent_name="Software Architect",
        soul_prompt="Kamu mengutamakan modularitas, skalabilitas, dan keandalan sistem.",
        system_prompt="Berikan rekomendasi arsitektur sistem yang konkret.",
        tool_permissions=["comm:delegate"],
    ),
    LLMSpec(
        handle="@security",
        agent_name="Security Specialist",
        soul_prompt="Kamu fokus pada keamanan memori, enkripsi, dan audit risiko.",
        system_prompt="Identifikasi kerentanan dan rekomendasikan kontrol pengamanan.",
    ),
])

B. Cara 1: Diskusi Multi-Putaran Eksplisit (run_moa_debate)

Gunakan saat pengguna meminta beberapa agen berdiskusi mencari titik kompromi:

import asyncio
from LegionADK.core.llm_spec import contract_message
from LegionADK.protocol import OrchestrationPolicy, run_moa_debate

async def main():
    env = contract_message(
        sender="@user",
        target="@coordinator",
        content="Silakan @architect berdiskusi dengan @security untuk merancang sistem autentikasi perbankan.",
    )

    policy = OrchestrationPolicy(max_discussion_rounds=2)
    result = await run_moa_debate(
        envelope=env,
        roster=roster,
        aggregator_handle="@coordinator",
        policy=policy,
    )

    print(f"Status Orkestrasi: {result.status}")
    print(f"Sintesis Akhir:\n{result.final_content}")

asyncio.run(main())

C. Cara 2: Triase Otonom & Pendelegasian Mandiri (run_autonomous_triage)

Koordinator mengevaluasi topik. Jika sederhana, koordinator langsung menjawab (jalur cepat STANDALONE). Jika membutuhkan masukan tim, koordinator memanggil spesialis secara mandiri lalu menyintesiskan hasilnya:

from LegionADK.protocol import run_autonomous_triage

async def main():
    env = contract_message(
        sender="@user",
        target="@coordinator",
        content="Kita mengalami lonjakan trafik transaksi 500% malam ini. Analisis dan buat rencana mitigasi.",
    )

    result = await run_autonomous_triage(
        envelope=env,
        roster=roster,
        coordinator_handle="@coordinator",
    )

    print(f"Mode Terpilih : {result.mode}") # AUTONOMOUS_TRIAGE atau STANDALONE
    print(f"Agen Spesialis: {result.proposer_handles}")
    print(f"Keputusan Akhir:\n{result.final_content}")

asyncio.run(main())

D. Fasad Tingkat Atas: Router Otomatis (dispatch_envelope)

Pintu masuk terpadu yang otomatis menganalisis amplop dan memilih alur eksekusi terbaik:

from LegionADK.protocol import dispatch_envelope

async def handle_incoming_message(envelope):
    # Otomatis mendeteksi:
    # 1. AUTONOMOUS_TRIAGE (jika target adalah koordinator)
    # 2. EXPLICIT_MOA (jika target >= 2 agen atau menyebut banyak @handle)
    # 3. STANDALONE (jika target 1 agen biasa)
    return await dispatch_envelope(envelope=envelope, roster=roster)

E. Strict Chain-of-Command Rekursif (Hierarki Berjenjang)

Mendukung pendelegasian hierarkis berlapis: User $\to$ @coordinator $\to$ @architect $\to$ @security $\to$ @architect $\to$ @coordinator $\to$ User.

policy = OrchestrationPolicy(
    max_delegation_depth=3,      # Batas kedalaman hierarki (mencegah runaway recursion)
    max_discussion_rounds=1,     # Putaran debat per level
)

result = await dispatch_envelope(
    envelope=env,
    roster=roster,
    policy=policy,
    triage_handles=["@coordinator"],
)

# Seluruh prompt, cached, dan completion tokens dari @security terakumulasi ke @architect
# dan teragregasi secara presisi ke dalam total @coordinator.
print(f"Total Token Tim: {result.total_prompt_tokens} prompt, {result.total_completion_tokens} completion")

🧪 Verifikasi & Checkpoint Test Suite

Seluruh kapabilitas LegionADK diverifikasi melalui rangkaian pengujian komprehensif dari Checkpoint 1 hingga Checkpoint 4.

Menjalankan Seluruh Pengujian Checkpoint 4

# Jalankan seluruh pengujian (O1 - O12) termasuk live LLM test:
$env:PYTHONPATH="."
python checkpoint_4_orchestrator.py

# Atau jalankan mode offline murni (melewati live LLM):
$env:LEGION_SKIP_LIVE="1"
python checkpoint_4_orchestrator.py

Hasil Ringkasan Checkpoint 4 (100% PASS)

🔒 Lisensi

Proyek ini dilindungi di bawah lisensi Proprietary and Confidential License. Hak Cipta © 2025 Astraea ADK Contributors. Seluruh hak cipta dilindungi undang-undang.

Dilarang keras menyebarluaskan, mendistribusikan ulang, atau mereproduksi kode sumber ini tanpa izin tertulis eksplisit dari pemilik hak cipta.