Lewati ke konten
AggregaAggrega
Pilih Bahasa: Bahasa Indonesia
Halaman ini diterjemahkan oleh mesin. Baca versi asli dalam bahasa Inggris.

Resolusi dependensi

Resolusi dependensi Aggrega & pilar topologi struktural

Dalam arsitektur Aggrega, dependensi topologis dipetakan secara eksplisit melalui pilar skema uses untuk mempertahankan payload values yang sepenuhnya buram. Menyelesaikan “siapa berbicara dengan siapa” menghadirkan tantangan tertentu: topologi aplikasi multi-node yang kompleks harus dipetakan tanpa memaksa pengembang menulis perutean jaringan eksplisit, urutan eksekusi tingkat orkestrator, atau dependensi infrastruktur.

1. Filosofi inti: Mengapa uses?

Blok uses mendeklarasikan dependensi lintas komponen sebagai topologi murni: Component A bergantung pada kontrak publik provides milik Component B, bukan pada alamat fisik atau detail koneksi Component B. Topologi berada di uses; konfigurasi berada di values. Pemisahan ini memungkinkan kompiler melihat semua edge lintas komponen secara eksplisit tanpa menyimpulkannya dari isi values.

Aggrega mengatasi hal ini dengan mengangkat topologi menjadi pilar skema kelas satu bernama uses.

  • Argumen proxy semantik: Kata kunci uses merepresentasikan niat semantik L7. Jika sebuah agen uses sebuah database, hal itu tetap benar secara semantik meskipun Platform Ops menyisipkan mesh proxy Wasm transparan di antara keduanya.
  • Netralitas matematis: Kompiler Go mengurai struct uses secara bawaan untuk menggambar graf representasi perantara (IR). Kompiler tidak pernah mencoba mengurai atau mengkueri logika aplikasi pengembang (values).
  • Atomisitas Feature: Pilar uses berlaku secara identik untuk Components dan Features (termasuk Features kredensial). Hal ini memungkinkan proxy sidecar (sebuah Feature) atau pengambil kredensial untuk secara mandiri mendeklarasikan dependensi jaringannya sendiri tanpa mencemari konfigurasi Component induknya.

2. Mekanika kontrak skema terpadu

Untuk mengekstrak instruksi operasional tanpa mengurai payload aplikasi, sistem mengandalkan deklarasi JSON Schema 2020-12 yang ketat yang mengatur struktur YAML yang dipisahkan secara eksplisit.

Domain 2: Skema terpisah (usesSchema & schema) Untuk mencegah katalog platform terpecah menjadi file skema yang tidak terkelola, Aggrega menggunakan mesin skema terpisah. usesSchema YAML bawaan mendefinisikan dan memvalidasi topologi secara ketat, sementara schema: (JSON Schema 2020-12 — biasanya ditulis melalui singkatan bentuk ringkas) memvalidasi isi pilar values dan infra serta mendeklarasikan bentuk pilar provides. values yang ditulis pengembang dan infra yang ditetapkan operator diperiksa terhadap tipe yang dideklarasikan; subskema provides mendeklarasikan nama kunci dan tipe dari kontrak hilir yang dihasilkan sebuah Recipe, dan kompiler memeriksa bahwa setiap referensi inject menyebut kunci provides yang dideklarasikan — tetapi nilai provides yang dihasilkan itu sendiri bergerak ke hilir sebagai string buram yang disalurkan kompiler tanpa interpretasi, bukan sebagai nilai yang tipenya ia periksa, karena inti tidak menafsirkan arti nilai yang disalurkan. usesSchema adalah tempat soket dideklarasikan, dan deklarasilah yang memberinya kontrak. Soket yang dideklarasikan oleh entitas katalog membawa batasan entitas tersebut: selektor yang menyatakan target mana yang dapat dijangkaunya, allowlist inject, serta valueSchema / infraSchema per edge. Di dalam usesSchema, arsitek platform menggunakan bidang selector: — dibaca sebagai string yang ditulis arsitek, tidak disalin ke skema yang dihasilkan mana pun — dan mesin selektor Go bawaan mengevaluasinya untuk menegakkan keamanan tipe lintas node atas soket yang dideklarasikan. Hal ini memastikan bahwa jika soket memerlukan database, pengembang tidak dapat mencolokkan server web.

Selektor dikenai tata bahasanya pada saat dievaluasi, yaitu sekali untuk setiap edge yang disambungkan melalui soket. Selektor yang tidak dapat dibaca mesin sebagai salah satu dari enam bentuk persyaratannya — persyaratan kosong akibat koma yang tersesat, kunci yang mengandung spasi atau salah satu karakter yang digunakan tata bahasa untuk membedakan bentuk-bentuknya (=, !, (, ) dan koma), atau himpunan tanpa tanda kurung penutup — menghentikan build pada edge tersebut sambil menyebut persyaratannya, alih-alih dibaca sebagai selektor lain. Ketegasan inilah yang menjaga pemeriksaan tetap jujur: jika dibaca secara longgar, !tier=frontend, yang ditulis untuk menyingkirkan frontend, hanya akan meminta agar tidak ada label yang bernama tier=frontend, dan setiap target — termasuk frontend — akan lolos. Tata bahasa yang sama mengatur selektor slot lampiran dan appliesTo milik Feature; tata bahasa selektor mencantumkan setiap bentuk dan setiap penolakan. Build tidak pernah mengevaluasi soket yang tidak dilalui edge mana pun, sehingga aggrega validate — atas seluruh katalog, atau atas Component atau Feature yang mendeklarasikan soket itu — membaca selektor setiap soket yang dideklarasikan dan menolak selektor yang salah bentuk di sana, dengan kode dan kata-kata yang digunakan oleh build yang menyambungkan soket tersebut.

Namun, mendeklarasikan soket bukanlah satu-satunya cara menarik edge. Penulis Aggregate dapat menyebut soket pada komponennya sendiri yang tidak dideklarasikan entitas katalog — termasuk pada tipe komponen yang sama sekali tidak mendeklarasikan usesSchema — dan edge tetap dibangun. Katalog yang tidak mendeklarasikan entri untuk sebuah soket belum mengantisipasi koneksi tersebut, yang tidak sama dengan melarangnya, dan topologi aplikasi adalah milik pengembang. Soket seperti ini disebut ad hoc, dan biayanya persis sama dengan apa yang diberikan deklarasi: tidak ada entri katalog, sehingga tidak ada selektor dan tidak ada kontrak per edge, dan keamanan tipe lintas node tidak memiliki apa pun untuk dievaluasi. Apa yang boleh dibawa edge tidak berubah — setiap kunci yang diinjeksinya tetap harus menyebut kunci yang dideklarasikan provides milik target, dan target tetap harus ada. Setiap edge dalam graf yang dihasilkan mencatat kasus mana dari keduanya, sehingga konsumen tidak perlu menebak; lihat governance-and-compliance untuk cara operator melarang soket ad hoc sepenuhnya.

Dua permukaan sengaja tidak dibuka dengan cara ini, karena keduanya tidak menulis topologi aplikasi. uses pada lampiran Feature hanya boleh menyebut soket yang dideklarasikan oleh Feature yang dilampirkan, dan uses per edge pada Release hanya boleh menyebut soket yang dideklarasikan entitas katalog milik komponen konsumen di usesSchema-nya, tidak pernah soket yang ditulis ad hoc oleh Aggregate — operator mengonfigurasi dan menyambungkan di dalam sebuah arsitektur, dan Feature berpartisipasi dalam topologi yang dideklarasikan entitas katalognya sendiri. Mendeklarasikan soket di katalog juga tetap merupakan jalan yang lebih baik dan itulah yang dilakukan katalog pustaka standar: soket ad hoc adalah jalan keluar, bukan default baru.

Domain 1: Pengalaman pengembang (polimorfisme) Pengembang menulis uses: sejajar dengan values: dan features:. Untuk memastikan UX tanpa hambatan, skema mendukung polimorfisme secara bawaan:

  • Array string: Digunakan untuk referensi komponen logis sederhana (mis. tools: ["search-api"]) ketika perutean standar sudah memadai.
  • Map objek: Digunakan ketika kontrak pengiriman yang ketat diperlukan (mis. databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • Tanpa wildcard: Tidak ada bentuk wildcard, yang mencegah “dependensi hantu” dan penyambungan otomatis tanpa izin: setiap entri menyebut satu komponen, sehingga ["*"] menghentikan build sebagai target yang tidak ada — tidak ada nama komponen yang dapat mengandung *.

Domain 3: Realitas Ops (normalisasi) Untuk menjaga templat Go tetap dapat diprediksi, kompiler Go menormalkan masukan polimorfik uses. Array referensi komponen logis dikonversi menjadi objek standar sebelum diteruskan ke kamus datar dan ketat yang dikenal sebagai .context.uses.


3. Contoh ujung ke ujung

Dua contoh berikut menunjukkan dua sifat berbeda dari pilar topologi eksplisit: Contoh A membuktikan apakah sebuah koneksi diotorisasi (keamanan tipe lintas node), dan Contoh B membuktikan bagaimana data koneksi dikirimkan secara fisik (polimorfisme & normalisasi).

Contoh A: Validasi topologis dan keamanan tipe lintas node

Skenario ini menelusuri bagaimana selektor pada soket yang dideklarasikan mendeteksi bahwa agen AI akan terhubung ke basis data yang tidak memiliki label kepatuhan yang diwajibkan, lalu menghentikan build. Kompiler mengevaluasi label selector yang ditulis arsitek terhadap label target, sebagai string; kompiler tidak menafsirkan makna sebuah label, dan tidak ada plugin kebijakan yang terlibat.

1. Pustaka standar (schema: terpadu di katalog) Platform Architect mendefinisikan struktur skema, dengan memisahkan logika kognitif dari target topologis secara native.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/enterprise-agent
version: 1.0.0
labels:
component.aggrega.ai/type: "worker"
spec:
usesSchema:
datastores:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema:
# 1. The Cognitive Intent
values:
system_prompt: { type: string, required: true }

2. Niat pengembang (Aggregate) Pengembang dengan rapi memisahkan apa yang dilakukan agen (values) dari apa yang dihubungkan oleh agen (uses).

components:
my_secure_vector_db:
type: core/qdrant-secure:1.0.0
values:
collection_name: finance_data
auditing_agent:
type: core/enterprise-agent:1.0.0
values:
system_prompt: "You are a financial auditing AI..."
uses:
datastores:
finance_memory: { target: "my_secure_vector_db" }

3. Eksekusi kompiler dan validasi topologis

  1. Validasi lokal: Kompiler Go mengevaluasi seluruh objek terhadap JSON Schema yang telah di-resolve saat resolusi. Kompiler memeriksa label katalog yang mendasari my_secure_vector_db. Jika basis data tidak memiliki label restricted, kompiler akan segera menghentikan build dengan pelanggaran keamanan tipe.
  2. Penggambaran graf: Saat konstruksi topologi, kompiler Go sepenuhnya mengabaikan konten yang divalidasi skema. Kompiler membaca uses.datastores.finance_memory.target secara native dari YAML dan menggambar sisi eksplisit di graf IR.

Contoh B: Polimorfisme dan .context.uses yang dinormalisasi

Skenario ini menunjukkan bagaimana kompiler menangani baik alat AI kotak hitam (diberikan sebagai array) maupun basis data relasional lama (yang memerlukan map dengan kontrak inject).

1. Katalog (domain 2): deklarasi schema: Architect mengizinkan array polimorfik untuk alat, tetapi menuntut objek ketat untuk basis data.

spec:
usesSchema:
# Polymorphic Array Socket (No injection needed)
tools:
selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract)
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file"]
schema:
values:
system_prompt: { type: string, required: true }

2. Niat pengembang (domain 1): Aggregate Pengembang menggunakan array sederhana untuk alat, dan map eksplisit untuk basis data.

components:
my-agent:
type: core/python-worker:1.0.0
values:
system_prompt: "You are an HR bot."
uses:
# 1. Polymorphic Array: Simple logical component reference
tools:
- "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery
databases:
hr_db:
target: corporate-hr-db
inject:
env:
- in: HR_DATABASE_URI # Local env var
from: "host" # Target provides key

3. Realitas Ops (domain 3): Recipe Kompiler Go menormalisasi polimorfisme. Ops menerima kamus .context.uses yang datar dan dapat diprediksi. Cukup lakukan perulangan pada pipa .context.inject di bagian templat yang relevan.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: generic-worker
version: 1.0.0
spec:
capability: helm
implements: core/python-worker:1.0.0
source: "./charts/internal/python-runner"
locals:
primary_compute: worker-container
valuesMapping: |
env:
# Ops uses the pre-resolved inject map, kept apart from values and topology loops
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }}
value: "{{ $value }}"
{{- end }}