Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Features AI

L’insieme di Feature AI di Aggrega

Per supportare le esigenze specifiche, la volatilità e le minacce alla sicurezza dei moderni sistemi di AI, Aggrega incorpora un’intelligenza specializzata direttamente nella sua libreria standard AI (il Catalogo) open source. Fa sì che sia l’impalcatura cloud-native generica sia i motori di ragionamento AI-native altamente specializzati coesistano in modo sicuro.

Il compilatore Go di base è un router universale neutrale rispetto ai contenuti; tutta l’intelligenza specifica dell’AI risiede in policy WebAssembly (Wasm) collegabili e nelle dichiarazioni JSON Schema 2020-12 che gli architetti di piattaforma scrivono sulle entità del Catalogo.

1. L’ontologia cloud operativa e il duck typing dell’AI

Per collegare il generico Open Application Model (OAM) alle rigide realtà dell’infrastruttura moderna, l’etichetta component.aggrega.ai/type mappa esclusivamente su un insieme chiuso di primitive cloud-native universali. Questa identità semantica è ciò che un selettore di socket, l’appliesTo di una Feature e una policy di governance leggono per sapere come un componente tratta lo stato, l’ingresso di rete e i cicli di vita; il compilatore la confronta come stringa opaca e non si dirama in base a essa, e il modo in cui un componente viene renderizzato lo decide la Recipe che il Manifest mappa per esso.

I tipi cloud-native (la base infrastrutturale):

  • server: calcolo stateless di lunga durata che si aspetta traffico applicativo in ingresso (ad es. un AI Gateway o una Chat UI).
  • worker: calcolo stateless di lunga durata che preleva da code o esegue cicli in background senza alcuna porta applicativa in ingresso (ad es. un agente LangGraph o un worker Celery).
  • task: calcolo effimero che viene eseguito fino al completamento e poi termina (ad es. script di migrazione del DB).
  • function: calcolo guidato dagli eventi che scala fino a zero (ad es. AWS Lambda).
  • stateful-server: calcolo nel cluster che richiede identità di rete stabili e dischi permanenti (ad es. un database vettoriale Qdrant, un broker Kafka).
  • resource: infrastruttura esterna, gestita dalla piattaforma (ad es. AWS RDS PostgreSQL, bucket S3, un event bus ospitato).

L’insieme è proprio di Aggrega ed è chiuso. Lo schema del Component pubblicato enumera questi valori, e un documento che riporti qualsiasi altro valore viene rifiutato al caricamento — E0215 nomina l’etichetta ed elenca i valori che accetta. È questo che l’asse offre: una Feature o un selettore di socket scritto rispetto a stateful-server significa la stessa cosa in ogni catalogo che incontra.

Che cosa è un componente nel tuo vocabolario va su una tua chiave. Un livello, una zona dati, una classe di servizio, una suddivisione più fine delle primitive — ciascuno è una chiave di etichetta che scrivi accanto a quella riservata, poiché lo schema del Component accetta qualsiasi ulteriore chiave di etichetta con valore stringa e ogni superficie di selezione la legge in modo identico. È lo stesso meccanismo che usano già le etichette di duck typing per l’AI descritte più avanti; la chiave riservata è la base comune, e tutto ciò che sta sopra è tuo.

Il tipo operativo non è la categoria di consultazione, e sono assi separati di proposito. Un broker Kafka si trova nella categoria messaging — dove un utente lo cerca — e porta stateful-server come tipo, perché è ciò che l’infrastruttura deve fare per lui. Un selettore scritto rispetto a un asse non trova mai corrispondenze sull’altro.

Vedi entities/component per le tabelle della tassonomia delle etichette semantiche — le etichette Generic Cloud Layer, Specialized AI Layer, Cross-Cutters e Dynamic Business Context che gli architetti usano per sovrapporre un’identità cognitiva ai tipi di base.


1.1 Lo standard del catalogo open source: «Base spoglia, bordi caratterizzati»

Nell’applicare queste etichette, c’è una distinzione fondamentale tra il Catalogo open source ufficiale di Aggrega (core/*) e un Catalogo aziendale privato (acme/*).

Perché il catalogo open source ufficiale resti utilizzabile universalmente, deve distinguere rigorosamente tra fisica tecnica immutabile e intento cognitivo soggettivo. Se nel core/datastore/postgres generico è cablato engine: relational, un plugin di verdetto di governance configurato per imporre la corrispondenza del tipo di datastore arresterà la build quando uno sviluppatore abilita l’estensione pgvector nei suoi values e tenta di collegare un agente AI che richiede un datastore vector.

Per mantenere un catalogo di base privo di opinioni, i componenti ufficiali seguono questo standard: mantieni la base spoglia e caratterizza i bordi.

  1. La base spoglia: il Component open source di livello radice cabla soltanto ciò che è oggettivamente vero del prodotto e non può essere cambiato da nulla che un autore configuri — anzitutto e sempre la primitiva operativa (component.aggrega.ai/type). Un database Postgres è oggettivamente uno stateful-server; questo fatto non può cambiare. Lo stesso criterio ammette un’etichetta di capacità quando l’identità del prodotto è quella capacità: core/datastore/qdrant e core/datastore/weaviate sono motori di ricerca vettoriale e nulla di ciò che un autore scrive li rende qualcos’altro, quindi ciascuno porta datastore.aggrega.ai/engine: vector sulla base, esattamente come core/datastore/redis porta kv. Ciò che la base spoglia rifiuta è il caso opposto — un tratto che dipende da come un componente è configurato o usato, per il quale esiste il terzo meccanismo descritto più avanti.
  2. Le interfacce caratterizzate (ereditarietà dello schema): un Component può dichiarare extends, nominando un altro Component come sua base, e ciò che questo compone è la struttura: etichette, annotazioni, slot di allegato, l’allowlist di auto-iniezione, i socket di topologia e le assertions con nome. I tre pilastri dei dati non si compongono — un Component che estende scrive il marcatore letterale schema: inherited e non scrive alcun contenuto values, infra o provides proprio, quindi il suo contratto è identico a quello della sua base. Per questo il meccanismo restringe anziché variare: poiché il contratto non cambia, ogni Recipe scritta per la base serve già la specializzazione, e la specializzazione costa un’entità di catalogo e una riga di mappatura nel Manifest. Ciò che una specializzazione aggiunge è quindi un’identità che un selettore o una policy leggono — un livello di audit, una zona dati, un referente di governance, o un socket il cui selettore ammette meno di quello della base. Non può aggiungere un contratto diverso, perché non ha alcuna superficie su cui scriverne uno. Una conseguenza è facile da trascurare: la riga di mappatura resta necessaria. La selezione della Recipe avviene per chiave di mappatura esatta, quindi una specializzazione ha bisogno di una propria voce mappings.components.type anche se non ha bisogno di una Recipe propria. Vedi examples/extends-wrapper per un wrapper pubblicato che aggiunge un’etichetta di livello revisionato e restringe un socket su di essa, insieme alla build che si arresta quando un arco collegato a quel socket esce dal livello. Un tratto che dipende da come un componente è configurato non è oggetto di questo meccanismo: una specializzazione fissa l’artefatto della sua base ed eredita il suo contratto, quindi un tratto vero della specializzazione è già vero della base, dove lo colloca la regola della base spoglia. Un tale tratto appartiene al mutatore dinamico descritto più avanti.
  3. Il mutatore dinamico (promozione Wasm): se un tratto è dettato dal payload dello sviluppatore (ad es. enable_vector: true), l’azienda usa il ruolo label-transform del socket di governance durante la costruzione della topologia per leggere dinamicamente i values opachi e iniettare automaticamente l’etichetta datastore.aggrega.ai/engine: vector nel grafo IR prima che le policy vengano eseguite. È qui che un tratto dipendente dalla configurazione diventa disponibile per una valutazione rigorosa delle policy — sono i values dichiarati dallo sviluppatore a promuoverlo, e la trasformazione viene eseguita prima che qualsiasi policy legga un’etichetta.

L’eccezione aziendale: poiché il compilatore è privo di opinioni, le aziende che scrivono i propri cataloghi interni sono libere di infrangere questa regola. Se una policy di sicurezza aziendale stabilisce che tutti i database interni sono altamente sensibili, l’architetto di piattaforma può e deve cablare compliance.aggrega.ai/data-class: restricted (o un’etichetta simile stabilita dall’azienda) direttamente sul proprio componente di base acme/postgres, così che ogni sua istanza porti la classe e una policy collegata dall’azienda la legga su ciascuna. L’etichetta di per sé non impone nulla: il compilatore la trasporta come stringa, ed è la policy collegata ad arrestare una build. Dove solo alcuni degli usi di un prodotto all’interno di un parco contengono quei dati, è invece una specializzazione tramite extends a portare la classe — vedi examples/policy-data-class-route, il cui assistente per i sinistri è l’agente LangGraph della libreria standard più un’etichetta di classe, accanto alla policy che la legge.

1.2 Come le etichette semantiche alimentano la pipeline del compilatore

Per mantenere le etichette nel dominio dell’architetto di piattaforma, gli sviluppatori non possono scrivere etichette sulle proprie istanze di Component all’interno dell’Aggregate: lo schema dell’Aggregate non dà a un’istanza di componente alcuna chiave labels. Le etichette di un nodo sono quelle della sua entità di catalogo, insieme a quelle che un allegato di governance label-transform configurato dall’operatore aggiunge durante la costruzione della topologia. Ecco esattamente come queste etichette guidano la pipeline di compilazione senza richiedere codice Go personalizzato:

1. component.aggrega.ai/type (la primitiva di base)

  • Chi la scrive? L’architetto di piattaforma (Dominio 2). È obbligatoria per ogni componente del catalogo.
  • Chi la consuma? L’analizzatore statico e i Plugins di rendering Wasm.
  • Caso d’uso nel compilatore: è l’ontologia cloud operativa di base. L’analizzatore statico valuta in modo nativo in Go le stringhe di selettore usesSchema per garantire che uno sviluppatore non possa collegare un agente a un database standard se il socket richiede una specifica capacità AI. Inoltre, il DevOps usa questa etichetta per instradare esplicitamente le primitive stateful (stateful-server, resource) verso confini fisici del cluster che supportano dischi persistenti, mentre un ruolo di verdetto di governance può imporre che i componenti stateful non siano mai collocati in confini solo effimeri.

2. model.aggrega.ai/capability

  • Chi la scrive? L’architetto di piattaforma.
  • Chi la consuma? L’analizzatore statico (tramite i selettori di etichette in stile Kubernetes dei socket usesSchema).
  • Caso d’uso nel compilatore: quando un architetto scrive un selettore usesSchema che nomina l’etichetta di capacità richiesta, il motore nativo di corrispondenza delle etichette del compilatore rifiuta i collegamenti che non soddisfano il selettore prima che vengano generati gli artefatti. Il compilatore tratta queste etichette come stringhe opache; il significato semantico di «text-generation» rispetto a «embedding» risiede nel modo in cui l’architetto scrive il selettore.

3. component.aggrega.ai/hosting

  • Chi la scrive? L’architetto di piattaforma.
  • Chi la consuma? Il motore di policy (un ruolo di verdetto di governance), i Plugins di rendering Wasm e i chiamanti di un modello o di un agente presenti nella libreria standard stessa: i suoi agenti, la cui asserzione la legge su ogni connessione model, core/ai-tool/agent-invocation, la cui asserzione la legge sulla sua connessione target_agent, come fa la sua realizzazione Kubernetes, che rifiuta una credenziale a un agente external raggiunto via http, l’AI gateway, la cui asserzione la legge su ogni connessione ai suoi socket models e cache_store, e core/gateway/kong, core/gateway/kong-enterprise, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/traefik-hub, core/gateway/agentgateway e core/gateway/higress, le cui asserzioni la leggono su ogni connessione ai loro socket models, nonché al backend dei due Kong, ai socket cache_store di APISIX e Traefik Hub e ai socket cache di Envoy Gateway, Higress e Traefik Hub — vedi «La chiave che un chiamante presenta» più avanti.
  • Caso d’uso nel compilatore: registra chi gestisce la risorsa sottostante del componente, consentendo a una policy collegata da un operatore di valutare il rischio di esfiltrazione dei dati; il compilatore legge il valore come stringa e non giudica nulla. Quando un agente la cui etichetta di classe dice che contiene dati internal si connette a un modello etichettato managed — un servizio gestito al di fuori del confine della Release stessa — una tale policy può leggere che i dati escono da quel confine, e arrestare la build a meno che la connessione non sia instradata attraverso un AI gateway che porta core/data-masking, che maschera il testo di chat e di completamento inoltrato dal gateway. Il socket model di un agente accetta un tale gateway al posto del modello, così quel percorso è un arco del grafo che la policy legge, e un modello che il gateway serve dal suo socket models è un arco a sé, dal gateway al componente del modello, le cui etichette la policy legge — così il percorso da un agente attraverso il gateway fino a un modello managed è nel grafo da un capo all’altro. Un upstream digitato a mano nella mappa dei modelli del gateway non lo è: è una stringa che il compilatore non risolve, quindi una policy che legge il grafo vede il gateway e nulla dietro di esso. examples/policy-data-class-route è una tale policy: le sue impostazioni classificano un modello managed come public, e arresta una build in cui un assistente che contiene dati restricted ne raggiunge uno senza un gateway di mascheramento sul percorso. È un tratto trasversale: gli stessi valori self-hosted | managed | external descrivono un database gestito o un server di inferenza autogestito esattamente come descrivono un modello, quindi l’etichetta vive sotto lo spazio dei nomi condiviso component.aggrega.ai/ anziché in quello specifico dei modelli.

4. agent.aggrega.ai/autonomy

  • Chi la scrive? L’architetto di piattaforma.
  • Chi la consuma? Il motore di policy (un ruolo di verdetto di governance).
  • Caso d’uso nel compilatore: identifica il rischio di esecuzione del ciclo cognitivo. Se un agente è etichettato autonomous (ovvero esegue cicli in background senza prompt dell’utente) e si connette a un database altamente sensibile, il motore di policy può arrestare la build a meno che un autore non colleghi la Feature di approvazione o di contenimento richiesta dalle regole proprie dell’azienda, così che un ciclo non presidiato non possa raggiungere quei dati senza revisione.
  • Che cosa significa un componente senza etichetta su questo asse, perché l’assenza è voluta. L’etichetta descrive il rischio di esecuzione di un ciclo cognitivo, quindi un componente che non contiene un proprio ciclo non porta qui alcun valore anziché il più basso dei due. Parecchi componenti della categoria degli agenti sono privi di etichetta proprio per questo motivo: i pezzi di supporto che una piattaforma di agenti distribuisce accanto al proprio server — una console nel browser, un’esecuzione di migrazione dello schema, un task worker, una sandbox per il codice, un proxy di uscita — stanno in quella categoria perché è lì che li cerchi, mentre il ciclo che supportano vive nel server della piattaforma, che è dove si trova l’etichetta. Il caso più chiaro è un singolo prodotto diviso tra entrambi i trattamenti: il server di una piattaforma porta copilot, e la sandbox per il codice distribuita accanto non porta nulla. Il criterio è dove vive il ciclo e non la forma che assume il pezzo, quindi anche un runtime che ospita codice di agenti fornito da te è privo di etichetta — lì il ciclo è qualunque cosa tu vi distribuisca, non qualcosa che il prodotto afferma. Un selettore che nomina uno dei due valori trova quindi corrispondenza con i componenti che contengono un ciclo e con nessun altro, e uno scritto per corrispondere a qualsiasi postura di autonomia salta i pezzi di supporto anziché trattarli come la cosa meno autonoma del deployment.

5. gateway.aggrega.ai/intelligence

  • Chi la scrive? L’architetto di piattaforma.
  • Chi la consuma? L’analizzatore statico e i plugin Wasm di linting scritti dall’azienda.
  • Caso d’uso nel compilatore: stabilisce quali funzionalità un router può fisicamente supportare. La Feature AI fallback-chain dichiara appliesTo: gateway.aggrega.ai/intelligence=semantic, e l’analizzatore statico valuta quel selettore rispetto alle etichette del componente di destinazione prima che venga renderizzato qualsiasi artefatto. Se uno sviluppatore la collega a un gateway l4-mesh standard, la build si arresta con una violazione del selettore che nomina la Feature e il selettore non soddisfatto, perché l’architetto ha scritto quel selettore sapendo che una mesh TCP standard non può analizzare i payload JSON degli LLM per leggere il modello che una richiesta nomina. Il rifiuto si basa sull’assenza di semantic anziché sulla presenza di l4-mesh, quindi vale ugualmente su un router che non porta alcuna etichetta di intelligenza. Il compilatore tratta l’etichetta come una stringa opaca, esattamente come sopra: ciò che semantic significa risiede nel modo in cui l’architetto scrive il selettore. Su un router che porta semantic il collegamento supera il selettore, e ciò che accade dopo dipende dalla sua realizzazione: la realizzazione della libreria standard scrive la catena nella configurazione di instradamento dell’AI gateway.
  • Che cosa porta la libreria standard. Questi componenti portano semantic: core/gateway/litellm, la cui realizzazione renderizza la tabella di instradamento del proxy: una mappa di modelli su diversi provider upstream; core/gateway/cloudflare-ai-gateway, il gateway ospitato di Cloudflare, che legge ogni richiesta di modello che inoltra — il modello che nomina, i token che gli vengono fatturati e, dove i controlli propri del gateway sono attivi, il suo contenuto; core/gateway/azure-api-management, l’AI gateway di Azure API Management, un servizio ospitato, che legge ogni richiesta di modello su un’API che serve un modello — il prompt confrontato dalla sua cache semantica, i token riportati da una risposta e il contenuto che il suo controllo di sicurezza invia per l’ispezione; core/gateway/apisix, il cui proxy AI legge il corpo di ogni richiesta su una route che serve un modello e i token riportati dalla risposta del modello; core/gateway/envoy-gateway, la cui estensione Envoy AI Gateway legge il corpo di ogni richiesta sulla route che serve i modelli a esso collegati, per trovare il modello che nomina, e i token riportati da ogni risposta; core/gateway/kong-enterprise, Kong Gateway Enterprise, il cui proxy AI legge il corpo di ogni richiesta su una route che serve un modello collegato — il modello che nomina e i messaggi che trasporta — e i token riportati da ogni risposta; core/gateway/traefik-hub, Traefik Hub, il cui middleware Chat Completion legge il corpo di ogni richiesta sulla route che serve un modello collegato, lo verifica rispetto allo schema di chat completion e legge i token riportati da ogni risposta; core/gateway/agentgateway, agentgateway, che legge il corpo di ogni richiesta sui suoi percorsi di servizio dei modelli per trovare il modello che nomina, il che è il modo in cui sceglie il modello collegato a cui inviare una richiesta, e i token riportati da ogni risposta; e core/gateway/higress, Higress, il cui proxy AI legge il corpo di ogni richiesta su una route che serve un modello collegato — il modello che nomina e se è in streaming — e i cui plugin leggono i token riportati da ogni risposta — così le Features AI che richiedono questo valore si risolvono rispetto a ciascuno di essi, e ogni realizzazione dice che cosa il suo gateway rispetta, oppure arresta la build dove il suo gateway non ne rispetta nulla; una Feature senza realizzazione per un gateway arresta lì la build, nominandone il tipo. Nessun componente porta l4-mesh, e gli altri componenti gateway della libreria standard non portano alcuna etichetta di intelligenza: quelli che instradano traffico terminano HTTP e instradano al livello 7, e uno di essi è un control plane che non instrada nulla, quindi nessuno dei due valori lo descrive. Una mesh TCP di livello 4 è ancora un’altra classe di prodotto. Ciò lascia pienamente in vigore il rifiuto descritto sopra, perché si basa sull’assenza di semantic: un collegamento che richiede quel valore si arresta su uno qualsiasi di essi. Un architetto il cui catalogo esegue davvero una mesh di livello 4 applica l4-mesh a quel componente, il che rende la distinzione selezionabile in entrambe le direzioni.
  • Questo asse nomina un livello di prodotto, che è una questione diversa da ciò che un componente può fare al traffico, e leggerlo nel secondo senso è l’errore che induce a commettere. semantic dice che il router analizza il corpo della richiesta, che è ciò di cui ha bisogno un controllo che agisce sul modello nominato da una richiesta — quindi è l’asse giusto per questo. Non dice nulla sulla capacità di un router di copiare il traffico, trasportare l’identità di un chiamante, verificare il certificato di un upstream, rifiutare un prompt che corrisponde a un elenco di pattern o mantenere un budget su un periodo, e una Feature che ha bisogno di una di queste non ha motivo di interrogare il livello: la maggior parte dei componenti che le offrono sono comuni proxy di livello 7 privi di qualsiasi valore di intelligence, e dove un router semantic ne offre una, la offre per ragioni che il livello non registra. Il livello raggiunge quindi l’insieme sbagliato in entrambe le direzioni — esclude del tutto i proxy semplici e non dice nulla su quali capacità abbia effettivamente il gateway AI che raggiunge. Questa domanda spetta all’asse del percorso dei dati descritto più avanti, e i due si compongono — una Feature può richiedere un router semantic che effettua anche il mirroring, nominandoli entrambi.

6. tool.aggrega.ai/impact

  • Chi la scrive? L’architetto di piattaforma.
  • Chi la consuma? Il motore delle policy e i Plugins Wasm di rendering.
  • Caso d’uso del compilatore: Spostando questa informazione dal blocco values mutabile dello sviluppatore all’identità immutabile delle label, consente al motore delle policy di valutare configurazioni rigorose a privilegio minimo. Un plugin di rendering potrebbe generare permessi invoke standard per uno strumento di ricerca web read-only, ma esigere configurazioni rigorose di firma crittografica per invocare uno strumento mutating di SQL drop.

7. compliance.aggrega.ai/data-class

  • Chi la scrive? L’architetto di piattaforma del catalogo proprio di un parco IT (oppure iniettata dinamicamente tramite il ruolo di governance label-transform).
  • Chi la consuma? Il motore di policy (un ruolo di verdetto di governance).
  • Caso d’uso del compilatore: Conferisce ai dati contenuti in un componente un’identità di governance che una policy può seguire lungo il grafo. Il compilatore porta la label nel grafo IR come stringa e non classifica nulla: non sa che restricted è più sensibile di public, né che l’una o l’altra parola significhi qualcosa. Una policy collegata al ruolo ir-verdict fornisce quel significato nelle proprie impostazioni — quali classi esistono e come si ordinano — e legge la label sui componenti dei percorsi che il compilatore enumera lungo gli archi uses, così può arrestare una build in cui un componente che contiene dati restricted raggiunge un componente di un’altra classe lungo un percorso su cui non è collegata alcuna Feature che la policy consideri di declassificazione, come core/data-masking sul gateway AI attraversato dal percorso. L’enumerazione è limitata per ciascun componente di partenza e non elenca nulla oltre il limite, quindi un percorso che la policy legge è reale, mentre l’assenza di un percorso non prova che non ne esista nessuno. examples/policy-data-class-route è quella policy, scritta per i motori Rego e CEL compilati nella CLI e per OPA, con le build che si arrestano e quella che si completa affiancate.
  • Cosa include la libreria standard. Nessun Component core/ porta questa label. La classe dei dati di un componente è un’affermazione su come un parco IT usa il componente, non una proprietà del prodotto vera in ogni Release, quindi per la regola Naked Base resta fuori dalla base: un parco IT la porta sul proprio Component — una specializzazione tramite extends, come l’assistente per i sinistri dell’esempio svolto, oppure una base propria nell’ambito della Enterprise Exception descritta sopra.

8. hardware.aggrega.ai/accelerator

  • Chi la scrive? L’architetto di piattaforma. Quando impacchetta un componente di modello locale, sa che per funzionare richiede fondamentalmente una GPU.
  • Chi la consuma? Il DevOps (Dominio 4).
  • Caso d’uso del compilatore: Il DevOps instrada esplicitamente i componenti etichettati GPU nei confini dei pool di hardware fisico nella Release tramite la mappa components: {}. Lo sviluppatore chiede semplicemente il modello cognitivo nel proprio Aggregate, e il DevOps lo colloca nel confine del costoso cluster GPU, preservando interamente la separazione delle responsabilità. Un ruolo di verdetto di governance può inoltre imporre che qualsiasi componente con questa label non venga mai collocato in un confine privo di infrastruttura GPU.

9. datastore.aggrega.ai/engine

  • Chi la scrive? L’architetto di piattaforma, sui componenti della categoria datastore (staticamente, su una specializzazione flavored, oppure iniettata dal ruolo label-transform quando i values dello sviluppatore promuovono il ruolo). I valori in uso nel catalogo sono: relational, document, kv, vector, graph, semantic-memory, search. Ogni valore nomina un motore di archiviazione che un prodotto è — search nomina un motore di ricerca e analisi che indicizza anche vettori — quindi una caratteristica che risiede nello schema e nel modello di accesso di un’applicazione anziché in un archivio distribuibile non è un valore su questo asse.
  • Chi la consuma? L’analizzatore statico (tramite stringhe di selettore) e il motore delle policy.
  • Caso d’uso del compilatore: I selettori puntano alla semantica di archiviazione anziché ai prodotti — il socket della knowledge base di un agente seleziona datastore.aggrega.ai/engine in (vector, semantic-memory, search), e un motore delle policy può rifiutare l’instradamento di payload SQL verso un motore vettoriale. La rilevanza per l’AI nei datastore a duplice uso è derivata da questa label, mai memorizzata come booleano separato.
  • Cosa include la libreria standard. core/datastore/qdrant, core/datastore/weaviate, core/datastore/chroma, core/datastore/pgvector e core/datastore/milvus portano vector, core/datastore/cognee porta semantic-memory, e core/datastore/opensearch e core/datastore/elasticsearch portano search, quindi il selettore della knowledge base visto sopra si risolve su ciascuno di essi. core/datastore/redis, core/datastore/valkey e core/datastore/memcached portano kv. Ognuna di queste label si trova sulla base del componente stesso, perché l’identità del prodotto è quel motore. Per core/datastore/pgvector quell’identità è l’artefatto che fissa: esegue l’immagine PostgreSQL del progetto pgvector, che include l’estensione, e ogni Recipe abilita l’estensione nel database che il componente crea — quindi la sua caratteristica vettoriale non dipende da un’impostazione, ed è questo che lo distingue dal caso configurato descritto sopra in «Naked Base, Flavored Edges», dove un PostgreSQL generico acquisisce la caratteristica solo quando uno sviluppatore attiva un’estensione. relational, document e graph non hanno alcun componente nella libreria standard, quindi un selettore che nomina solo valori tra questi qui non corrisponde a nulla ed è soddisfatto da un catalogo che ne include uno.

10. pipeline.aggrega.ai/mode

  • Chi la scrive? L’architetto di piattaforma, sui componenti della categoria pipeline. Ogni valore nomina il modo in cui un prodotto esegue un job in più passi, e i valori seguono i componenti che li portano anziché un elenco stabilito in anticipo. La libreria standard ne include due: durable su core/ai-pipeline/temporal, il cui motore registra l’esito di ogni passo come cronologia di eventi e la riproduce, così un job il cui worker si arresta in modo anomalo riprende da dove si era fermato; e reconciled su core/ai-pipeline/argo-workflows, il cui controller esegue ogni passo come pod a partire da una risorsa workflow conservata nell’API del cluster stesso.
  • Chi la consuma? Il motore delle policy e i Plugins Wasm di rendering.
  • Caso d’uso del compilatore: Consente a policy e renderer di distinguere i motori di pipeline in base a come un’esecuzione sopravvive a un guasto — una cronologia di eventi riprodotta o una risorsa di cluster riconciliata — anziché in base al nome del prodotto.

11. dataplane.aggrega.ai/* (Le capacità del percorso dei dati)

  • Chi la scrive? L’architetto di piattaforma, su qualsiasi componente che si trovi nel percorso del traffico — un reverse proxy, un gateway di ingresso, una service mesh, un gateway AI.
  • Chi la consuma? L’analizzatore statico, tramite l’appliesTo di una Feature e il selettore usesSchema di un socket.
  • Caso d’uso del compilatore: Risponde a cosa questo componente può fare al traffico, che è ciò che un controllo di runtime ha effettivamente bisogno di sapere e ciò che una label di livello di prodotto non può dire. core/traffic-shadowing, che copia le richieste live verso un secondo servizio per la valutazione, dichiara appliesTo: dataplane.aggrega.ai/request-mirroring — la sola chiave — e l’analizzatore statico la valuta rispetto alle label del target prima che venga renderizzato qualsiasi cosa, quindi collegarla a un componente che non può fare affatto mirroring arresta la build con una violazione del selettore che nomina la Feature e il selettore non soddisfatto. Il compilatore tratta ciascuna di queste stringhe come opaca, esattamente come tratta le altre.
  • Perché il prefisso nomina il percorso del traffico anziché un tipo di componente. Il mirroring, l’identità del chiamante e la verifica dell’upstream non sono proprietà dei gateway — sono proprietà di qualsiasi cosa si trovi nel percorso della richiesta, e una service mesh aggiunta a un catalogo le ha tutte e tre. Dare alla famiglia il nome del tipo di componente che le ha portate per primo obbligherebbe ogni tipo successivo a ridichiarare lo stesso vocabolario sotto il proprio prefisso, lasciando a una stessa capacità diversi nomi e nessun selettore in grado di coprirli tutti.
  • Perché la fedeltà viaggia nel valore. Due componenti possono entrambi fare il mirroring delle richieste e differire comunque nel modo che interessa a una Feature: uno copia ogni richiesta corrispondente, l’altro ne copia una quota impostabile. Una chiave che dicesse solo se un componente fa mirroring li ammetterebbe entrambi e lascerebbe la differenza da scoprire dopo il rendering. Mettere la fedeltà nel valore permette di richiederla in quello, tra due modi, che si adatta alla Feature. Una Feature che non può funzionare affatto senza una certa fedeltà nomina quel valore nel proprio selettore. Una Feature che funziona anche con la fedeltà inferiore seleziona sulla sola chiave, e la sua realizzazione rifiuta l’impostazione che il componente non può onorare: copiare l’intero flusso funziona su ogni componente che fa mirroring, quindi core/traffic-shadowing si collega a tutti, e la realizzazione per un componente che dichiara full-rate rifiuta una quota inferiore a 100 con un messaggio che nomina la quota richiesta e la fedeltà dichiarata dal componente — due cose che la violazione del selettore non dice. I valori sono quindi derivati da ciò che i prodotti in commercio implementano anziché composti come una tassonomia: request-mirroring porta full-rate e sampled perché i proxy reali si dividono esattamente in questo modo, uno che offre un’impostazione del tasso di copia e un altro che non ne offre nessuna.
  • Un valore afferma una capacità, mai uno stato configurato. Per uno sviluppatore i due si leggono in modo identico, e solo uno è una proprietà del componente. Un proxy in grado di verificare il certificato di un upstream porta upstream-tls: trust-anchor indipendentemente dal fatto che una qualche distribuzione abiliti il controllo — la label è ciò su cui una Feature seleziona prima che qualsiasi cosa sia configurata, quindi caricarla di configurazione la renderebbe illeggibile proprio nel momento in cui viene usata.
  • Cosa include la libreria standard. core/gateway/nginx porta request-mirroring: full-rate, upstream-tls: trust-anchor e concurrency-cap: total, un unico limite su ogni richiesta che inoltra. core/gateway/contour porta request-mirroring: sampled, caller-identity: client-certificate e upstream-tls: trust-anchor. core/gateway/envoy-gateway porta gli stessi tre valori di core/gateway/contour, period-budget: tokens, che conta i token riportati da ogni risposta di un modello che serve tramite Envoy AI Gateway, e concurrency-cap: per-target, un limite sulle richieste in corso verso ciascun modello che serve. core/gateway/kong porta upstream-tls: trust-anchor e prompt-guard: pattern-list, con il suo AI Prompt Guard che confronta i messaggi di una richiesta al modello con gli elenchi contenuti nelle sue route. core/gateway/tyk porta upstream-pinning: public-key, che core/upstream-key-pinning seleziona. core/gateway/litellm porta caller-identity: injected-header, content-masking: entity-recognition, period-budget: cost, prompt-guard: pattern-list, upstream-tls: trust-anchor e concurrency-cap: per-target, un limite sulle richieste in corso verso ciascuna voce della sua mappa dei modelli. core/gateway/cloudflare-ai-gateway porta period-budget: cost. core/gateway/apisix porta period-budget: tokens, che conta i token riportati dalla risposta di ogni modello senza attribuire alcun prezzo, e prompt-guard: pattern-list. core/gateway/kong-enterprise porta period-budget: tokens, che conta i token riportati dalla risposta di ogni modello, e content-masking: entity-recognition. core/gateway/traefik-hub porta content-masking: entity-recognition e prompt-guard: pattern-list, con il suo middleware Content Guard che maschera le corrispondenze dei pattern contenuti nella sua configurazione o i tipi di entità rilevati da un analizzatore Presidio che chiama, oppure rifiuta una richiesta a cui corrisponde un pattern, e period-budget: cost, con prezzi tratti dal listino per modello fornito con il suo middleware di quota, che può invece contare i token riportati da ogni risposta. core/gateway/agentgateway porta content-masking: pattern-list e prompt-guard: pattern-list, con la sua guardia basata su espressioni regolari che maschera o rifiuta le corrispondenze dei pattern contenuti nella sua configurazione senza riconoscere alcun tipo di entità, e period-budget: cost, i budget che mantiene per chiave API in dollari statunitensi, con prezzi tratti dal suo catalogo dei costi dei modelli, oppure in token. core/gateway/higress porta content-masking: pattern-list, con il suo plugin ai-data-masking che maschera le corrispondenze dei pattern contenuti nella sua configurazione nel testo dei messaggi di una richiesta chat senza riconoscere alcun tipo di entità, e period-budget: tokens, che conta insieme i token di prompt e di completamento riportati da ogni risposta senza attribuire alcun prezzo. core/gateway/azure-api-management porta period-budget: tokens, che conta insieme i token di prompt e di completamento riportati da ogni risposta, con un conteggio separato in ciascun gateway dell’istanza, senza attribuire alcun prezzo. core/security/nemo-guardrails e core/security/trustyai-guardrails-gateway, due guardie che si collocano nel percorso di un modello e giudicano una richiesta con un classificatore addestrato, portano prompt-guard: classifier, che i socket guard del gateway AI e del gateway NGINX selezionano. I gateway AI tra questi — core/gateway/litellm, core/gateway/cloudflare-ai-gateway, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/kong-enterprise, core/gateway/traefik-hub, core/gateway/agentgateway, core/gateway/higress e core/gateway/azure-api-management — portano semantic e gli altri non portano alcun valore gateway.aggrega.ai/intelligence, il che è la separazione che funziona e non un’eccezione a essa: una Feature che ha bisogno di un mirror raggiunge i tre componenti che ne hanno uno, mentre un selettore di livello di prodotto raggiungerebbe tra essi solo Envoy Gateway, per una ragione che non dice nulla sul mirroring, e una Feature che ha bisogno di una guardia dei prompt, del mascheramento dei contenuti o di un budget di periodo raggiunge un gateway AI in base a ciò che può fare anziché al livello in cui si colloca, mentre una che limita le richieste in corso raggiunge il gateway NGINX, che non porta alcun valore di livello, così come raggiunge Envoy Gateway e il gateway AI, e una che rifiuta una richiesta in base a un elenco di pattern raggiunge Kong open source, che anch’esso non ne porta alcuno, così come raggiunge APISIX. Un componente che non ha nulla da descrivere su uno di questi assi non porta lì alcun valore anziché il più debole, quindi un selettore che nomina un qualsiasi valore su quell’asse correttamente non si collega a esso.

12. security.aggrega.ai/text-anonymization

  • Chi la scrive? L’architetto di piattaforma, su un servizio che partecipa al mascheramento di testo sensibile. Dove quel lavoro è suddiviso tra due servizi, analyzer va su quello che trova gli intervalli sensibili in un testo e li riporta, e anonymizer su quello che riscrive gli intervalli che gli vengono passati; sanitizer va su un servizio che fa entrambe le cose in un’unica chiamata, trovando gli intervalli sensibili nel testo che riceve e riscrivendoli esso stesso, e rispondendo con il testo riscritto.
  • Chi la consuma? L’analizzatore statico, tramite il selettore usesSchema di un socket.
  • Caso d’uso del compilatore: è il modo in cui a un consumatore viene consegnato l’indirizzo giusto. core/gateway/litellm dichiara un socket pii_analyzer che seleziona security.aggrega.ai/text-anonymization=analyzer e un socket pii_anonymizer che seleziona il valore anonymizer, quindi collegare uno dei due servizi al socket dell’altro arresta la build con una violazione del selettore che nomina il socket. core/gateway/kong-enterprise dichiara un solo socket, pii_sanitizer, che seleziona il valore sanitizer, e core/gateway/traefik-hub uno solo, pii_analyzer, che seleziona soltanto il valore analyzer, perché il Content Guard che la sua Recipe di chart scrive per core/data-masking sostituisce esso stesso ciò che l’analizzatore trova. Il compilatore instrada l’indirizzo che il componente selezionato pubblica e non verifica nulla di ciò che risponde a quell’indirizzo.
  • Cosa contiene la libreria standard. core/security/presidio-analyzer porta analyzer e core/security/presidio-anonymizer porta anonymizer. Entrambi parlano l’API HTTP di Presidio che il gateway AI chiama quando un’associazione di core/data-masking, o il values.log_masking del gateway stesso, elenca tipi di entità, e il Content Guard di Traefik Hub chiama il solo analizzatore quando un’associazione di core/data-masking su quel gateway li elenca. core/security/kong-ai-pii-service porta sanitizer e parla l’API del servizio AI PII di Kong, che l’AI PII Sanitizer di Kong Gateway Enterprise chiama con ogni testo che maschera, comprese le sue espressioni regolari, finché su quel gateway è presente un’associazione di core/data-masking. Il sanitizer non gli presenta alcuna credenziale e ogni testo gli arriva non mascherato, quindi il suo indirizzo è interno al cluster e non è pensato per essere esposto al di fuori del cluster.

13. model.aggrega.ai/api

  • Chi lo scrive? Il Platform Architect, su ogni componente della categoria dei modelli e su un gateway che serve un’API di modelli. Il valore indica quale API di modelli risponde all’indirizzo che il componente pubblica: openai dove è l’API di OpenAI — quella del fornitore stesso o l’implementazione che ne fa un server —, anthropic dove è la Messages API di Anthropic, gemini dove è la Gemini API di Google, e native dove è l’API propria del prodotto e nessuna di quelle, che un consumatore raggiunge tramite il client di quel prodotto. Ogni valore è ricavato dalla documentazione di riferimento del prodotto stesso, e un componente lo porta qualunque cosa configuri una data Release.
  • Chi lo consuma? Lo Static Analyzer, tramite il selettore usesSchema di un socket, e le asserzioni del gateway AI, di core/gateway/kong, di core/gateway/kong-enterprise, di core/gateway/apisix, di core/gateway/envoy-gateway, di core/gateway/traefik-hub, di core/gateway/agentgateway e di core/gateway/higress, su ogni connessione ai loro socket models.
  • Caso d’uso del compilatore: è ciò che permette a un unico socket di accettare sia un modello sia un gateway che serve modelli. Il socket model di ogni agente tranne i cinque runtime nominati più sotto, il socket target_model di core/ai-tool/model-invocation e i due socket di modello di core/datastore/cognee selezionano component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: il requisito di categoria ammette le due categorie, e il requisito di chiave ammette, tra i loro componenti, solo quelli che portano l’etichetta, quindi collegare un tale socket a un gateway che non serve alcuna API di modelli arresta la build con una violazione del selettore che nomina il socket. I requisiti di un selettore devono valere tutti e le sue alternative stanno dentro l’insieme di una sola chiave, quindi l’unica chiave a cui rispondono entrambi i tipi di componente deve trovarsi su ogni componente di modello oltre che sul gateway — ed è per questo che l’etichetta indica un’API anziché contrassegnare soltanto i gateway. Un gateway che la porta pubblica le chiavi endpoint e model che pubblica un modello, così la Recipe di un consumatore legge l’uno o l’altro allo stesso modo. Un agente le cui Recipes forniscono le variabili di una sola API di modelli ne indica invece il valore: i socket model di core/ai-agent/openai-agents-sdk, core/ai-agent/agent-framework e core/ai-agent/mastra selezionano model.aggrega.ai/api=openai, quello di core/ai-agent/claude-agent-sdk seleziona model.aggrega.ai/api=anthropic e quello di core/ai-agent/google-adk seleziona model.aggrega.ai/api=gemini, quindi collegarne uno a un modello o a un gateway che serve un’altra API arresta la build con una violazione del selettore che nomina il socket. Il socket di core/ai-agent/google-adk restringe inoltre la categoria a ai-model, rifiutando ogni gateway, perché il client di ADK non legge alcun indirizzo e invierebbe la credenziale di un gateway all’indirizzo di Google stesso. Il gateway AI legge il valore anziché selezionare su di esso: il suo socket models seleziona component.aggrega.ai/category=ai-model, ammettendo ogni modello, e poiché il gateway descrive al proprio proxy un modello collegato lì soltanto tramite l’API di OpenAI, l’asserzione del suo Component arresta la build su una connessione il cui target porta un valore diverso da openai, nominando la connessione e indicando di digitare invece quell’upstream nella mappa dei modelli scritta a mano del gateway. core/gateway/kong, core/gateway/kong-enterprise, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/traefik-hub, core/gateway/agentgateway e core/gateway/higress lo leggono allo stesso modo sui propri socket models, perché ciascuno scrive la route di un modello collegato, o su agentgateway la sua voce di modello, soltanto per l’API di OpenAI. Il compilatore tratta il valore come una stringa opaca e non verifica nulla di ciò che risponde all’indirizzo.
  • Cosa contiene la libreria standard. core/gateway/litellm, core/gateway/kong, core/gateway/kong-enterprise, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/traefik-hub, core/gateway/agentgateway e core/gateway/higress portano openai, come anche i server self-hosted core/ai-model/vllm, ollama, docker-model-runner, tgi, tei, nvidia-nim e litellm, le API gestite core/ai-model/openai, openai-embedding e nvidia-api, e il broker core/ai-model/openai-compatible, che si punta verso un servizio che parla quell’API. core/ai-model/anthropic porta anthropic e core/ai-model/gemini porta gemini. Ogni altro componente di modello porta native.

14. tool.aggrega.ai/transport

  • Chi lo scrive? Il Platform Architect, su uno strumento che un consumatore raggiunge tramite un trasporto che deve saper parlare. Il valore indica quel trasporto.
  • Chi lo consuma? Lo Static Analyzer, tramite il socket per gli strumenti di un consumatore.
  • Caso d’uso del compilatore: è il modo in cui a un consumatore vengono consegnati soltanto gli strumenti con cui sa comunicare. Un socket per gli strumenti seleziona component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http: il requisito di categoria ammette gli strumenti e nient’altro, e il requisito di trasporto ammette solo gli strumenti raggiunti via HTTP, quindi collegare un tale socket a uno strumento che non porta tale etichetta arresta la build con una violazione del selettore che nomina il socket. Il modo in cui si raggiunge uno strumento deve essere un’etichetta anziché un valore pubblicato, perché un selettore legge le etichette e mai il contenuto di un valore. Il compilatore tratta il valore come una stringa opaca e non verifica nulla di ciò che risponde all’indirizzo.
  • Cosa contiene la libreria standard. core/ai-tool/mcp porta http. Collega un server Model Context Protocol a un agente, e il Manifest sceglie come quel server viene realizzato: helm/mcp e compose/mcp eseguono un’immagine che serve il protocollo via HTTP; helm/mcp-stdio-bridge e compose/mcp-stdio-bridge eseguono un pacchetto che parla solo stdio dietro un bridge fissato a una versione che lo serve via HTTP; helm/mcp-remote e compose/mcp-remote raggiungono un server gestito da qualcun altro e non eseguono nulla. Ogni realizzazione pubblica gli stessi host, port, endpoint, protocol e credential_header, quindi il cablaggio di un consumatore non cambia con la realizzazione. Le credenziali proprie di un server sono variabili d’ambiente, conservate nello slot server_env dello strumento: consegnate al bridge per riferimento su Kubernetes e, su Docker Compose, scritte nell’ambiente del servizio così come vengono consegnate, dove un riferimento a una variabile di Compose tiene la credenziale fuori dal file; la credenziale di un server remoto è conservata dal consumatore sulla propria connessione allo strumento e presentata sotto l’header indicato da credential_header, Authorization a meno che la Release ne indichi un altro. Dove un server remoto legge la propria chiave dal proprio indirizzo, il consumatore conserva anche l’intero indirizzo su quella connessione, in uno slot endpoint riempito su Kubernetes da un riferimento a un Secret e su Docker Compose da un riferimento a una variabile di Compose, così la chiave non raggiunge alcun file renderizzato, mentre l’infra.endpoint dello strumento contiene l’indirizzo senza la parte che porta la chiave; examples/mcp-address-from-secret costruisce entrambi. core/ai-agent/openai-agents-sdk, core/ai-agent/claude-agent-sdk, core/ai-agent/agent-framework, core/ai-agent/google-adk e core/ai-agent/mastra, e le piattaforme di flussi core/ai-agent/flowise e core/ai-agent/n8n, dichiarano un socket per gli strumenti di questa forma, tools, e consegnano l’indirizzo di ogni strumento collegato, e la credenziale della connessione per riferimento, sotto variabili nominate secondo l’alias della connessione, mentre una connessione che scrive un blocco inject: riceve ciò che quel blocco stabilisce al posto delle variabili derivate da ciò che lo strumento pubblica, e ciò che contengono i suoi slot credential e endpoint resta sotto il nome dell’alias; un consumatore proprio ne dichiara uno allo stesso modo. Ciascuna delle tre piattaforme di flussi porta nella piattaforma, al deploy, un flusso scritto nell’Aggregate, su entrambi i target: Langflow carica la definizione trasportata dalla propria directory dei flussi a ogni avvio, il chatflow di Flowise viene inizializzato da un passo una tantum che accede come l’account proprietario indicato dalla Release, e il workflow di n8n viene importato da un passo di init prima dell’avvio della piattaforma. core/ai-agent/langflow dichiara un socket tools della stessa forma, che non ammette alcun blocco inject:, e consegna invece ogni connessione attraverso quel flusso, perché il componente MCP Tools di Langflow accetta l’indirizzo di un server soltanto dalle impostazioni di Langflow stesso o dal flusso, mai da una variabile: le sue Recipes scrivono l’indirizzo dello strumento nel nodo MCP Tools il cui server porta il nome dell’alias della connessione, consegnano la credenziale della connessione per riferimento come una variabile indicata dall’header di quel nodo — sotto Authorization, una variabile che contiene Bearer e la credenziale — e lasciano passare gli host degli strumenti e degli store collegati attraverso la protezione di Langflow contro gli indirizzi privati. Tutte e tre le piattaforme dichiarano inoltre un socket vector_store che seleziona datastore.aggrega.ai/engine in (vector, semantic-memory, search), che consegna allo stesso modo l’indirizzo di ogni store collegato — l’endpoint che pubblica, per core/datastore/pgvector un URI di connessione senza password, oppure uno composto dal suo protocollo, host e porta — e la credenziale della connessione per riferimento; uno store che pubblica anche il proprio database e utente, come fa core/datastore/pgvector, raggiunge Flowise e n8n anche in quelle parti, poiché il nodo vettoriale PostgreSQL di nessuna delle due piattaforme accetta una stringa di connessione; Langflow, il cui componente PGVector accetta un’unica stringa, riceve un tale store come AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, con la credenziale della connessione come password, per riferimento su Kubernetes e così come viene consegnata su Docker Compose. Un chatflow di Flowise legge una variabile consegnata tramite una variabile Runtime con lo stesso nome creata nella pagina Variables di Flowise, e un workflow di n8n ne legge una tramite $env solo dove l’Aggregate imposta il valore allow_env_access_in_nodes della piattaforma, poiché per impostazione predefinita le sue Recipes mantengono il blocco di n8n sull’accesso all’ambiente nei nodi.

2. Astrazione delle porte (la convenzione zero porte)

Il catalogo open source della libreria standard di Aggrega raccomanda di omettere le dichiarazioni di porte fisiche dallo strato cognitivo dei Components, instradando invece la scelta della porta attraverso la Recipe di Ops. Gli autori che seguono questa raccomandazione evitano collisioni di porte tra i target di deployment, prevengono API backdoor che aggirano l’Injection Contract e mantengono flessibile la topografia di rete tra i provider. Il compilatore stesso è agnostico rispetto alle porte — convoglia qualunque valore lo JSON Schema risolto consenta. La convenzione prevede un’esplicita via d’uscita per i sistemi legacy le cui porte fisiche non possono essere spostate.

  • Il default cloud-native (iniezione dinamica): per i carichi di lavoro moderni, i Components omettono del tutto le porte fisiche (nessun array ports o expose) dalla propria dichiarazione schema:. Le Recipes di Platform Ops scelgono la porta TCP/UDP interna e la pubblicano come chiave provides con nome, che i consumatori a valle leggono tramite l’Injection Contract .context.uses.
  • La via d’uscita legacy (dichiarazione esplicita): quando un componente legacy ha una porta fissa nel codice e non modificabile, il Platform Architect espone esplicitamente un campo port nella dichiarazione schema: del Component. Questo dà al Developer un modo validato per dichiarare il vincolo fisico. Il compilatore porta il valore attraverso la pipeline senza modificarlo; la Recipe lo consuma tramite {{ .values.port }}.
  • Porte operative (fuori banda): le porte usate esclusivamente dall’infrastruttura del cluster (ad es. lo scraping di Prometheus, le metriche dei sidecar Envoy) restano nascoste allo strato cognitivo del Developer. Vengono iniettate fuori banda da Platform Ops tramite Features (ad es. associando la Feature core/prometheus-exporter, la cui porta di scraping è infra dell’operatore).

3. Schemi specifici di dominio (intelligenza di configurazione)

I blocchi values dello sviluppatore (opachi per il compilatore Go ma tipizzati rigorosamente dalla dichiarazione schema: del Component) vengono validati per supportare flussi di lavoro AI espliciti:

  • Collegamenti tra agenti (array di dipendenze): lo schema condiviso dei parametri degli agenti della libreria standard porta tools_allowed e agents_allowed come array di values che nominano i Components del catalogo che un agente può invocare o a cui può delegare — una convenzione documentata che il compilatore non valuta. Un collegamento che il compilatore cabla come arco topologico è un socket uses che il Component dell’agente dichiara nel proprio usesSchema, ed è il selettore di quel socket ciò che la build verifica.
  • Partizionamento profondo della memoria cognitiva (CoALA): anziché un unico contenitore di memoria piatto, un architetto può dichiarare un socket cognitive_memory le cui connessioni mappano la memoria semantica, episodica e procedurale su target infrastrutturali distinti come archi topologici espliciti, così i motori di policy possono valutare e imporre protezioni di accesso granulari (ad es. garantendo che un agente possa leggere la memoria semantica, ma non sovrascriverla se compromesso). La libreria standard non dichiara alcun socket di questo tipo.
  • Pipeline multimodali: lo schema: di un Component può dichiarare fasi di esecuzione esplicite come document_chunking, embedding_generation e storage_routing come values tipizzati, così un flusso di dati dichiarativo viene validato prima che qualcosa venga renderizzato. La libreria standard non dichiara alcuna fase di questo tipo.

4. Intelligenza dei gateway e instradamento

I gateway AI della libreria standard portano i controlli per instradare le richieste verso le API degli LLM: core/gateway/litellm, che gira nel cluster, e due servizi ospitati — core/gateway/cloudflare-ai-gateway, il gateway ospitato di Cloudflare, che la sua Recipe terraform crea in un account Cloudflare, e core/gateway/azure-api-management, il gateway AI di Azure API Management, la cui Recipe terraform aggiunge un’API che serve un modello, con il suo backend e la sua policy, a un’istanza di API Management già esistente. Le Recipes helm e compose di ciascun gateway ospitato vi fanno riferimento dove è già configurato. Alcuni controlli sono valori sul gateway stesso e alcuni sono Features associate a esso, e ogni Feature qui sotto indica su quale gateway la libreria standard la realizza. Su un gateway ospitato ogni controllo viene scritto nella configurazione propria del gateway — un’impostazione della risorsa del gateway Cloudflare, un elemento della policy dell’API su Azure API Management — quindi solo la sua Recipe terraform può portarne uno, e le sue Recipes helm e compose arrestano la build su qualsiasi associazione. Più sotto, «il gateway AI» è core/gateway/litellm, «il gateway ospitato» è core/gateway/cloudflare-ai-gateway, e il gateway di Azure API Management è nominato per esteso.

Fuori da Aggrega, in fase di esecuzione

agente

il suo socket model, collegato al gateway

gateway AI

con i controlli collegati

budget di token

cache semantica

scudo contro la prompt injection

modello

un provider dietro il gateway

Le richieste di un agente passano per il gateway a cui è collegato il suo socket model, quindi ogni controllo collegato al gateway si trova tra l’agente e il modello. I tre disegnati qui sono le Features core/period-budget, core/semantic-caching e core/prompt-injection-shield, mostrate affiancate per il punto in cui si collocano e non come la configurazione di un unico gateway: le voci qui sotto dicono quale gateway realizza ciascun controllo e che cosa arresta la build.

  • I modelli dietro di esso: la mappa dei modelli del gateway AI — gli alias che serve, ciascuno con l’upstream a cui viene inviata una richiesta per esso — ha due parti. Un componente di modello collegato al socket models del gateway, gestito o self-hosted, è servito sotto l’alias della connessione, con la sua voce scritta a partire da endpoint e model pubblicati dal modello, stringhe che il compilatore convoglia nella configurazione del gateway e non risolve mai; il modello è quindi un componente del grafo, raggiunto tramite un arco proprio. Il gateway descrive tale modello al proprio proxy soltanto tramite l’API di OpenAI, quindi una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai arresta la build, nominando la connessione. L’altra parte è il values.models del gateway, voci digitate a mano nella notazione provider/modello del proxy stesso: per un upstream che il catalogo non modella, per un provider la cui API non è l’API di OpenAI, e per più voci che condividono un alias, cosa che i modelli collegati non possono fare, poiché ciascuno è servito sotto l’alias della propria connessione. Una voce collegata presenta la credenziale portata dalla propria connessione, come descrive «La chiave che un chiamante presenta» più sotto, e mai il provider_key del gateway; ogni voce digitata a mano presenta l’unica credenziale in quello slot. Un alias pubblicato da entrambe le parti arresta la build, nominandolo, e così fa un gateway a cui nessuna delle due parti fornisce un modello.

  • Nel percorso di un agente: il gateway pubblica un endpoint e un model, le chiavi che pubblica un componente di modello, e porta model.aggrega.ai/api: openai, quindi il socket model di un agente accetta direttamente il gateway e ogni controllo a esso associato si frappone tra quell’agente e i provider dietro di esso. Il model che pubblica è l’alias indicato dal suo values.model, su cui la build si arresta quando nessuna delle due parti della mappa lo pubblica; può essere omesso solo dove il gateway serve un unico alias e una voce di values.models lo pubblica, e quello è allora l’alias pubblicato. Un chiamante che desidera un altro alias pubblicato dalla mappa lo chiede per nome allo stesso endpoint. core/gateway/cloudflare-ai-gateway pubblica le stesse due chiavi — l’indirizzo di uno degli endpoint del gateway, composto dall’account Cloudflare e dall’id del gateway, e il modello che un chiamante chiede, che il gateway inoltra senza verificarlo — ma non porta alcun model.aggrega.ai/api, quindi il socket model di un agente non lo accetta. Anche core/gateway/azure-api-management le pubblica — l’indirizzo della sua API, composto dall’host dell’istanza e dal percorso dell’API, e il modello che un chiamante chiede, inoltrato senza verifica — e nemmeno esso porta alcun model.aggrega.ai/api: l’API risponde alla richiesta chat completions di OpenAI, ma per impostazione predefinita un chiamante presenta una chiave di sottoscrizione di API Management in un proprio header anziché il bearer token di OpenAI, quindi un semplice client OpenAI non basta per chiamarla.

  • Kong davanti ai modelli: core/gateway/kong, il gateway Kong open source, serve i modelli collegati al proprio socket models tramite l’AI Proxy di Kong e, dei controlli descritti più sotto, realizza soltanto i pattern di rifiuto dei prompt, come AI Prompt Guard di Kong su ogni route di ciascun modello collegato. Ogni modello collegato ottiene una route chat e una route completion sotto /<alias>/v1, scritte a partire da endpoint e model pubblicati dal modello, e le sue Recipes importano quelle route nel backend PostgreSQL del gateway prima che questo si avvii. È la route a scegliere il modello, quindi una richiesta viene inviata al modello indicato dal suo percorso, qualunque nome di modello porti. Il gateway presenta la credenziale propria di ciascuna connessione come bearer token che la sua configurazione legge per nome dall’ambiente del gateway, e una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai arresta la build. Pubblica come proprio endpoint la route dell’alias indicato dal suo values.model e come proprio model quell’alias, e porta model.aggrega.ai/api: openai, quindi il socket model di un agente lo accetta come accetta il gateway AI. Senza nulla collegato a quel socket il gateway non serve alcun modello e pubblica entrambe le chiavi vuote, e un agente collegato a esso non legge allora alcun indirizzo né alcun nome di modello. L’importazione aggiunge e aggiorna route e non ne rimuove nessuna, quindi una route la cui connessione viene rimossa continua a rispondere, e la protezione dei prompt scritta da un’associazione di core/prompt-deny-patterns continua a rifiutare dopo la rimozione dell’associazione, finché ciascuna non viene eliminata tramite l’Admin API di Kong. Per lo stesso motivo il gateway non dichiara chiamanti e le sue route di modello non verificano la chiave di alcun chiamante: Kong distingue i chiamanti solo come i consumer indicati da un plugin di autenticazione, e un consumer con la sua chiave, una volta importati, resterebbero in grado di autenticarsi dopo la rimozione del chiamante dalla Release, e una chiave ruotata lascerebbe funzionante quella vecchia; né una chiave key-auth può essere conservata per riferimento, quindi la chiave di un chiamante potrebbe raggiungere Kong solo come letterale in un file renderizzato.

  • Kong Gateway Enterprise davanti ai modelli: core/gateway/kong-enterprise, l’edizione a pagamento di Kong dello stesso gateway basato su database, serve i modelli collegati al proprio socket models sulle rotte che serve core/gateway/kong, scritte dalla stessa configurazione e importate nel suo backend PostgreSQL da un passaggio nel pod del gateway stesso prima che il gateway si avvii, e pubblica il proprio endpoint e il proprio model come fa Kong. La sua unica realizzazione è una Recipe chart sul chart Helm ufficiale di Kong; non esiste una realizzazione compose. Esegue l’immagine che la Release indica in infra.image, tag di versione incluso, perché Kong distribuisce l’immagine enterprise secondo condizioni proprie e il catalogo quindi non ne indica alcuna; la build si interrompe finché quella chiave non è impostata o il suo tag non riporta alcuna versione. La licenza raggiunge il gateway per riferimento al Secret associato al suo slot obbligatorio license, mai come valore, e la build si interrompe finché nulla associa quello slot. Il compilatore non convalida alcuna licenza e non contatta alcun fornitore, quindi una Release che compila senza errori non dice nulla su di essa: Kong legge la licenza all’avvio di un nodo, e un nodo privo di una licenza valida si comporta come con una licenza scaduta, con la configurazione delle entità in sola lettura e il traffico del proxy servito con la configurazione già in essere. Kong vende i suoi plugin AI come offerta AI Gateway Enterprise, un diritto d’uso interno alla licenza che nessuna build può vedere, e dove la licenza non include quel diritto salta un tale plugin anziché rifiutarlo, quindi associare core/semantic-caching, core/period-budget, core/data-masking, core/fallback-chain, core/retry-policy o core/target-selection interrompe la build finché la Release non imposta infra.ai_gateway_entitled a true, affermando che la licenza lo include. Dei controlli seguenti realizza il budget di periodo e la catena di fallback, ciascuno scritto nelle rotte che il gateway importa, e realizza core/data-masking come descrive più avanti «Esfiltrazione dei dati e intercettazione del payload»; le sue realizzazioni della cache semantica, della policy di retry e della selezione del target interrompono ogni associazione, indicando ciascuna il motivo, e il limite di concorrenza, la registrazione di audit, lo screening della prompt injection, la convalida delle risposte e i pattern di negazione dei prompt non vi hanno alcuna realizzazione, quindi l’associazione di uno qualsiasi di essi interrompe la build. Un insieme di rotte modificato riavvia progressivamente il gateway, e l’importazione aggiunge e aggiorna rotte senza rimuoverne alcuna, quindi una rotta la cui connessione viene rimossa e, una volta rimossa la Feature, un plugin scritto da una Feature AI restano nel database finché non vengono eliminati tramite l’Admin API di Kong; per i motivi indicati nel punto precedente, nemmeno questo gateway dichiara chiamanti, e le sue rotte dei modelli non verificano la chiave di alcun chiamante. Che un gateway in esecuzione applichi uno qualsiasi di questi controlli non è osservato da alcuna build.

  • APISIX davanti ai modelli: core/gateway/apisix, il gateway open source Apache APISIX, serve i modelli collegati al proprio socket models tramite l’AI proxy di APISIX dove il Manifest associa la sua Recipe chart, che esegue APISIX 3.18.0. Ogni modello collegato riceve una rotta chat e una rotta completion sotto /<alias>/v1 — solo la rotta chat finché sono associati un budget di periodo o dei pattern di negazione dei prompt, poiché APISIX non conta alcun token su una richiesta di completion e il suo prompt guard non ne legge alcuna — scritte dall’endpoint e dal model che il modello pubblica in un file di rotte renderizzato con il gateway, che questo legge all’avvio e di nuovo ogni volta che il file cambia. Un gateway che legge le proprie rotte da quel file non legge alcun etcd e non esegue alcuna Admin API, quindi con un modello collegato una connessione etcd o un’associazione admin_key interrompe la build, e senza nulla di collegato entrambe sono obbligatorie. La rotta sceglie il modello. Il gateway presenta la credenziale propria di ciascuna connessione come bearer token che le sue rotte leggono per nome dall’ambiente del gateway, e una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai interrompe la build. Pubblica come proprio endpoint la rotta dell’alias indicato dal suo values.model e quell’alias come proprio model, e riporta model.aggrega.ai/api: openai, quindi il socket model di un agente lo accetta come accetta il gateway AI; senza nulla di collegato pubblica entrambe le chiavi vuote. Una rotta la cui connessione viene rimossa scompare dal render successivo. Una Release può indicare i chiamanti del gateway in infra.callers e le loro chiavi tramite lo slot caller_keys, un Secret che contiene una chiave di dati per ogni nome di chiamante: ciascun chiamante è allora un consumer nel file di rotte, la cui chiave viene letta per nome da quel Secret, e ogni rotta rifiuta con HTTP 401 una richiesta che non presenta alcuna chiave dichiarata come Authorization: Bearer <key> — il modo in cui un client OpenAI ne presenta una — e rimuove la chiave dalla richiesta che inoltra. Senza chiamanti le rotte sono aperte. La sua Recipe workload, con APISIX 3.17.0, conserva le proprie rotte in etcd, non ne renderizza alcuna e interrompe la build in presenza di una connessione a quel socket e di infra.callers. Dei controlli seguenti realizza il budget di periodo, una cache semantica per i chiamanti che dichiara e i pattern di negazione dei prompt.

  • Envoy Gateway davanti ai modelli: core/gateway/envoy-gateway, l’Envoy Gateway open source, serve i modelli collegati al proprio socket models tramite Envoy AI Gateway, il cui controller, core/gateway/envoy-ai-gateway-operator, il gateway chiama come proprio extension server attraverso il suo socket extension. Un modello collegato senza nulla su quel socket interrompe la build, e con il controller collegato la Release colloca il gateway in envoy-gateway-system, altrimenti la build si interrompe. Ogni modello collegato diventa una regola di un’unica AI route associata al gateway, scelta in base al nome di modello che una richiesta riporta, con un backend scritto dall’endpoint e dal model che il modello pubblica, quindi ogni modello collegato è servito sotto /v1 all’indirizzo proprio del gateway. Il gateway presenta la credenziale propria di ciascuna connessione come bearer token, che il controller di Envoy AI Gateway legge dal Secret indicato dalla credenziale, e una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai interrompe la build. Finché un modello è collegato, ogni rotta sul gateway adotta il buffer di richiesta di 50Mi per connessione che Envoy AI Gateway configura. Pubblica come proprio endpoint il proprio indirizzo, qualificato con envoy-gateway-system in modo che si risolva da qualsiasi namespace, e come proprio model l’alias indicato dal suo values.model, e riporta model.aggrega.ai/api: openai, quindi il socket model di un agente lo accetta come accetta il gateway AI; senza nulla di collegato pubblica entrambe le chiavi vuote. Il webhook del controller serve un certificato emesso da cert-manager, quindi cert-manager deve essere già in esecuzione nel cluster, a meno che la Release non indichi, nell’infra.webhook_tls_secret del controller, un Secret contenente un certificato fornito dall’operatore, che il webhook serve allora. Dei controlli seguenti realizza il budget di periodo, la policy di retry e il limite di concorrenza, ciascuno scritto sull’unica traffic policy della rotta che serve i suoi modelli. Non realizza la cache semantica né la convalida delle risposte, poiché Envoy AI Gateway non conserva alcuna risposta con cui rispondere a una richiesta successiva e non verifica alcuna risposta rispetto a uno schema, né la catena di fallback: Envoy AI Gateway esegue il fallback ritentando su ulteriori backend della regola di un modello, e il gateway scrive il numero di tentativi della sua unica traffic policy su ogni regola della rotta che serve i suoi modelli, quindi un elenco di fallback otterrebbe esattamente i propri invii solo dove l’elenco di ogni modello collegato ha la stessa lunghezza. Realizza core/audit-logging come proprio access log, come descrive più avanti «Registrazione di audit», e rifiuta per nome ciò che quel log non può conservare: quanto è costata una richiesta, poiché il costo per richiesta che Envoy AI Gateway può calcolare non ha unità e il gateway non conserva prezzi; un chiamante verificato dal gateway, poiché nulla su quel percorso verifica il chiamante; e una conservazione, poiché quel log non ha archivio né impostazione di conservazione. examples/envoy-ai-gateway-token-budget costruisce l’intero percorso, con un agente che raggiunge il modello gestito di OpenAI attraverso il gateway.

  • agentgateway davanti ai modelli: core/gateway/agentgateway, l’agentgateway open source, serve i modelli collegati al proprio socket models da un unico file di configurazione renderizzato dalle sue Recipes. Ogni modello collegato è una voce di quel file, denominata con l’alias della connessione e scritta dall’endpoint e dal model che il modello pubblica come provider di chat completions compatibile con OpenAI, quindi ogni modello collegato è servito sotto /v1 all’indirizzo proprio del gateway ed è il nome di modello che una richiesta riporta a sceglierlo: la richiesta raggiunge il modello chiedendo il nome di modello che il modello pubblica, e a un nome che nessuna connessione riporta si risponde con HTTP 404. Il gateway presenta la credenziale propria di ciascuna connessione come bearer token, che il file indica come una variabile che il gateway legge dal proprio ambiente quando legge il file, e una variabile lì mancante gli impedisce di avviarsi; una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai interrompe la build. Pubblica quell’URL di base /v1 come proprio endpoint e l’alias indicato dal suo values.model come proprio model, e riporta model.aggrega.ai/api: openai, quindi il socket model di un agente lo accetta come accetta il gateway AI; senza nulla di collegato pubblica entrambe le chiavi vuote. Due Recipes eseguono la stessa immagine, fissata per digest: agentgateway-chart renderizza il chart Helm standalone del progetto, scaricato dal registry del progetto, e realizza i controlli seguenti, mentre agentgateway esegue l’immagine come un unico servizio Docker Compose e non ne realizza nessuno, né i chiamanti, quindi lì un’associazione interrompe la build indicandone il tipo; su Kubernetes, dove la build può raggiungere quel registry, si ricorre al chart. Sul chart una Release può indicare i chiamanti del gateway in infra.callers e le loro chiavi tramite lo slot caller_keys, come su APISIX: ciascun chiamante è una chiave API del file, verificata in modalità strict e letta per nome da quel Secret, quindi una richiesta al modello che non presenta alcuna chiave dichiarata come Authorization: Bearer <key> viene rifiutata con HTTP 401, e la chiave viene rimossa dalla richiesta inoltrata; senza chiamanti le rotte dei modelli sono aperte. agentgateway inserisce ogni chiave che il file indica in questo modo, quella di un modello collegato su entrambe le Recipes e quella di un chiamante sul chart, nel testo del file prima di leggere il file come YAML, quindi una chiave deve essere un token semplice — lettere, cifre e -, ., _, ~, +, / e = — e altri caratteri possono essere caricati come una chiave diversa o arrestare il gateway. Il gateway rilegge il proprio file quando cambia, quindi un chiamante rimosso dalla Release viene rifiutato non appena il file montato è aggiornato. Finché è associato core/audit-logging, o core/period-budget con ambito caller, la Recipe chart fornisce al gateway un archivio, un file SQLite su un volume dedicato, ed esegue una sola replica. Dei controlli seguenti realizza il mascheramento dei dati, i pattern di negazione dei prompt, il budget di periodo, la registrazione di audit e la policy di retry, ciascuno scritto nel file, e rifiuta per nome ogni valore che non può rispettare. Il mascheramento dei dati sostituisce ogni corrispondenza dei pattern elencati dall’associazione con <masked>, oppure, con refuse, risponde alla richiesta o alla risposta con HTTP 403, nei prompt di sistema e da sviluppatore di una richiesta, nei suoi altri messaggi e negli argomenti e nei risultati delle sue chiamate a strumenti, e nel testo del messaggio di una risposta che arriva intera; non riconosce alcun tipo di entità e non ripristina nulla. agentgateway non maschera una risposta in streaming, quindi finché le risposte sono mascherate una richiesta al modello che chiede una risposta in streaming viene rifiutata con HTTP 403 prima di essere inoltrata, e così ogni richiesta al modello il cui corpo supera i 2 MiB che il gateway legge per quel controllo, in streaming o meno. Un rifiuto da parte di una guardia, compreso quello di un pattern di negazione, è un HTTP 403 con il corpo «The request was rejected due to inappropriate content» (La richiesta è stata rifiutata a causa di contenuto inappropriato). Il budget, i record e i retry sono descritti più avanti in «Budget di periodo», «Registrazione di audit» e «Resilienza». Le sue realizzazioni della catena di fallback, della selezione del target, della cache semantica, della convalida delle risposte e dello screening della prompt injection interrompono ogni associazione, indicando ciascuna il motivo, e il limite di concorrenza non vi si associa, poiché il gateway non riporta alcun valore dataplane.aggrega.ai/concurrency-cap.

  • Traefik Hub davanti ai modelli: core/gateway/traefik-hub, il gateway a pagamento di Traefik, serve i modelli collegati al proprio socket models tramite il middleware Chat Completion di Traefik Hub. La sua unica realizzazione è una Recipe chart sul chart Helm di Traefik stesso; non esiste una realizzazione compose. Esegue l’immagine che la Release indica in infra.image, tag incluso, perché Traefik distribuisce Traefik Hub secondo condizioni proprie e il catalogo quindi non ne indica alcuna; la build si interrompe finché quella chiave non è impostata o non indica alcun tag. Il token di licenza raggiunge il gateway per riferimento al Secret associato al suo slot obbligatorio license, sotto la chiave di dati token, mai come valore, e la build si interrompe finché nulla associa quello slot o questo pubblica un’altra chiave di dati. Traefik richiede HTTPS in uscita verso api.traefik.io, dove il gateway convalida il proprio token; da Traefik Hub v3.21 il gateway continua a servire mentre quell’host non è raggiungibile, riprovando in background, e un token dura un anno per impostazione predefinita, dopodiché il gateway si arresta una volta scaduto. La Recipe chart disattiva l’esportazione, prevista dal chart, dei log di errore del gateway verso la piattaforma di Traefik e il suo controllo di una versione più recente. Il compilatore non convalida alcun token e non contatta alcun fornitore, quindi una Release che compila senza errori non dice nulla sul fatto che il gateway si avvii. Ogni modello collegato riceve una rotta in /<alias>/v1/chat/completions, inviata all’endpoint che il modello pubblica tramite un Service di tipo ExternalName e che chiede il model che il modello pubblica, qualunque nome di modello riporti una richiesta, quindi è il percorso a scegliere il modello; serve soltanto chat completions. Il gateway presenta la credenziale propria di ciascuna connessione come bearer token, che Traefik Hub legge dal Secret indicato dal middleware Chat Completion della connessione, e una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai, o il cui endpoint indica un indirizzo anziché un host, interrompe la build. Pubblica come proprio endpoint la rotta dell’alias indicato dal suo values.model e quell’alias come proprio model, e riporta model.aggrega.ai/api: openai, quindi il socket model di un agente lo accetta come accetta il gateway AI; senza nulla di collegato pubblica entrambe le chiavi vuote. Una Release può indicare i chiamanti del gateway in infra.callers e gli hash htpasswd delle loro chiavi tramite lo slot caller_keys: il middleware API Key di Traefik Hub precede allora ogni rotta dei modelli e rifiuta una richiesta che non presenta alcuna chiave dichiarata come Authorization: Bearer <key>, e la chiave viene rimossa dalla richiesta inoltrata; senza chiamanti le rotte sono aperte. Che cosa faccia Traefik Hub con la voce di un chiamante che indica un Secret o una chiave di dati inesistente non è indicato nel suo riferimento, quindi nel caso peggiore le rotte sono aperte come senza chiamanti. Dei controlli seguenti realizza il budget di periodo, la cache semantica per i chiamanti che dichiara, i pattern di negazione dei prompt e il mascheramento dei dati, tramite middleware dell’AI gateway di Traefik Hub, e la catena di fallback e la policy di retry, tramite il failover e il retry di Traefik stesso, ciascuno scritto nelle rotte che la sua Recipe chart renderizza. L’AI gateway è un diritto d’uso incluso nella licenza, che nessuna build può vedere, e ciò che Traefik Hub fa con un token valido la cui licenza non lo include non è documentato, quindi associare uno qualsiasi dei primi quattro interrompe la build finché la Release non imposta infra.ai_gateway_entitled a true. Le sue realizzazioni dello screening della prompt injection, della registrazione di audit, della selezione del target e della convalida delle risposte interrompono ogni associazione, indicando ciascuna il motivo, e il limite di concorrenza non vi si associa, poiché il gateway non riporta alcun valore dataplane.aggrega.ai/concurrency-cap. Che un gateway in esecuzione applichi uno qualsiasi di questi controlli non è osservato da alcuna build.

  • Higress davanti ai modelli: core/gateway/higress, il gateway open source Higress, basato su Envoy e configurato tramite risorse Kubernetes, serve i modelli collegati al proprio socket models tramite l’AI proxy di Higress. La sua unica realizzazione è una Recipe chart sul Helm chart higress-core del progetto stesso, che esegue il controller di Higress, con il suo servizio di discovery, e il gateway; non esiste una realizzazione compose, poiché il progetto pensa la sua distribuzione compose principalmente per i test in locale e quella distribuzione esegue diversi servizi cooperanti configurati tramite uno store proprio. La Recipe fissa il chart, le immagini e ogni modulo plugin che scrive, e accetta in infra.source_version solo le versioni del chart su cui la sua configurazione è verificata; il gateway scarica quei moduli dal registro dei plugin di Higress in fase di esecuzione, che il cluster deve poter raggiungere e che la build non può verificare. Il controller osserva solo il namespace della Release, sotto una IngressClass che prende il nome dal gateway e da quel namespace, quindi due gateway Higress in uno stesso namespace entrano in collisione. Ogni alias riceve una route in /<alias>/v1, inviata all’endpoint che il modello dell’alias pubblica tramite una voce del registro proprio del gateway e che chiede il model da esso pubblicato, qualunque sia il nome di modello che una richiesta porta, quindi è il percorso a scegliere il modello; le connessioni che nominano uno stesso alias nel loro valore serves si dividono le sue richieste in parti uguali. Il gateway presenta la credenziale propria di ciascuna connessione come bearer token, che il controller di Higress legge dal Secret indicato dalla configurazione dell’AI proxy, nel namespace del gateway, e consegna al gateway, quindi la chiave non compare in alcun file renderizzato; un nome di Secret che contiene un punto arresta la build, poiché Higress legge il nome fino al primo punto, e una connessione che non porta alcuna credenziale inoltra la chiave presentata dalla richiesta. L’AI proxy di Higress copia inoltre l’header Authorization inviato da un client in un header X-HI-ORIGINAL-AUTH, e ogni route di modello rimuove quella copia prima che la richiesta raggiunga il modello, quindi una chiave presentata da un client non viaggia mai accanto alla credenziale propria di una connessione. Su https il gateway verifica che il certificato di un modello risalga alle trust anchor del sistema e nomini l’host del modello, qualunque host abbia inviato il client, e altrimenti non invia nulla al modello: la Recipe contrassegna la route di ogni alias le cui connessioni sono tutte https con l’annotazione higress.io/backend-protocol: HTTPS di Higress, così il gateway prende il server name dall’host che l’AI proxy scrive in ogni richiesta — quello del modello, qualificato con il namespace del modello dove non contiene alcun punto — e verifica il certificato rispetto a esso. Quell’annotazione si applica a ogni connessione di un alias, quindi un alias che mescola connessioni http e https arresta la build, nominandole entrambe; servirle sotto due alias risolve il problema. Una connessione che raggiunge un modello il cui model.aggrega.ai/api non è openai, o il cui endpoint indica un indirizzo anziché un host, arresta la build. Pubblica come proprio endpoint la route dell’alias indicato dal suo values.model e quell’alias come proprio model, e porta model.aggrega.ai/api: openai, così il socket model di un agente lo accetta come accetta l’AI gateway; senza nulla collegato pubblica entrambe le chiavi vuote. Non dichiara alcun chiamante, quindi le sue route di modello non verificano la chiave di alcun chiamante, e un valore che richiede un chiamante verificato dal gateway viene rifiutato per nome. Tra i controlli descritti di seguito realizza il budget di periodo, l’audit logging e la retry policy, ciascuno scritto sulle route di modello, e realizza core/data-masking come descrive più avanti «Esfiltrazione dei dati e intercettazione del payload». Le sue realizzazioni della validazione delle risposte, della catena di fallback, della cache semantica, dello screening della prompt injection e della selezione del target arrestano ogni associazione, ciascuna indicando il motivo, e né i pattern di blocco dei prompt né il limite di concorrenza vi si associano, poiché non porta alcun valore dataplane.aggrega.ai/prompt-guard o dataplane.aggrega.ai/concurrency-cap. Che un gateway in esecuzione applichi uno qualsiasi di questi controlli non è osservato da alcuna build.

  • Azure API Management davanti a un modello: core/gateway/azure-api-management, l’AI gateway di Azure API Management, un servizio gestito, serve un’API di modello tramite un’API su un’istanza di API Management già esistente. La sua Recipe terraform legge l’istanza e aggiunge l’API, la sua operazione di chat completions, il backend a cui inoltra e la policy dell’API, che rimuove la subscription key del chiamante da ciò che inoltra e si autentica presso l’API del modello come indica infra.backend_authentication: con la managed identity dell’istanza, con una chiave del provider conservata in Key Vault o senza nulla. Le sue Recipes helm e compose fanno riferimento a un’API configurata al di fuori della Release e arrestano la build a qualsiasi associazione. Tra i controlli descritti di seguito la sua Recipe terraform realizza la cache semantica, il budget di periodo, lo screening della prompt injection e la retry policy, ciascuno scritto nella policy dell’API. Non realizza il limite di concorrenza, poiché Microsoft definisce il limite applicato dalla sua policy di concorrenza mai del tutto accurato, e più basso quando in una regione sono in esecuzione diverse unità di capacità, né la catena di fallback, poiché l’API inoltra a un solo backend e il fallback proprio di Azure, i gruppi di priorità di un backend pool, sposta le richieste successive da un backend il cui circuit breaker è scattato anziché inoltrare una richiesta fallita a un altro modello. La sua realizzazione di core/audit-logging arresta ogni associazione, nominando ciò che è fuori dalla sua portata: il log stesso, che si attiva con un’impostazione di diagnostica sull’istanza; il costo di una richiesta, mentre require_cost è attivo, poiché il log delle richieste ai modelli di Azure registra i conteggi dei token e il modello, ma nessun prezzo; e una conservazione, dove è indicato retention_days, poiché una riga dura finché la conserva l’area di lavoro Log Analytics in cui finisce. Che le policy si applichino e vengano fatte rispettare come documenta Microsoft non è osservato da alcuna build.

  • La chiave che un chiamante presenta: Un server che verifica la chiave presentata dai suoi chiamanti conserva quella chiave in uno slot proprio, chiamato api_key su ciascun target che serve modelli e ne verifica una — core/ai-model/vllm, tei e tgi, il modello LiteLLM e l’AI gateway, dove è la chiave che LiteLLM chiama master key — e ciascuna delle sue Recipes consegna la chiave come la variabile che il server legge. core/gateway/apisix e core/gateway/agentgateway conservano ciascuno una chiave per ogni chiamante che la loro Release nomina in infra.callers, nel loro slot caller_keys: un unico Secret, che contiene la chiave di ciascun chiamante sotto il nome di quel chiamante. core/gateway/traefik-hub conserva i suoi chiamanti allo stesso modo, salvo che il suo Secret contiene l’hash htpasswd della chiave di ciascun chiamante, con cui il suo controllo delle chiavi confronta una chiave presentata, quindi non è il Secret da cui il chiamante presenta la sua chiave. Un chiamante conserva la chiave che presenta dal proprio lato, sulla connessione su cui la presenta, in uno slot dichiarato dal suo socket: gli agenti della libreria standard ne dichiarano uno sul loro socket model, credential, l’AI gateway sul suo socket models e sul suo socket cache_store, dove è la password che la cache semantica del gateway presenta al suo store, core/gateway/kong e core/gateway/kong-enterprise sui loro socket models, core/gateway/apisix sul suo socket models e sul suo socket cache_store, dove è analogamente la password che la sua cache semantica presenta al suo store, core/gateway/agentgateway sul suo socket models, core/gateway/envoy-gateway sul suo socket models e sul suo socket cache, dove è la password che il servizio di rate limit del gateway presenta allo store che tiene il conteggio di un budget di periodo, core/gateway/higress sul suo socket models e sul suo socket cache, dove è la password che il suo limite di token presenta allo store che tiene il conteggio di un budget di periodo, e core/gateway/traefik-hub sul suo socket models, sul suo socket cache, dove è la password che la sua quota presenta allo store che tiene il conteggio di un budget di periodo, e sul suo socket cache_store, dove è la password che la sua cache semantica presenta al suo store — quindi un agente che raggiunge un modello, o un gateway che raggiunge un modello che serve, conserva lì la chiave di quella connessione. L’AI gateway, i due Kong, APISIX e agentgateway consegnano la chiave di ciascun modello collegato sotto una variabile propria, che la voce o la route di quel modello nella loro configurazione nomina; Envoy Gateway nomina il Secret nella security policy del backend del modello, e il controller di Envoy AI Gateway legge la chiave da esso; Traefik Hub nomina il Secret e la data key nel middleware Chat Completion della route del modello, e legge la chiave da esso. Una connessione che raggiunge un modello etichettato component.aggrega.ai/hosting: managed ne porta una, oppure dichiara nei propri values che il modello non ne accetta alcuna, unauthenticated: true; senza nessuna delle due, l’asserzione del chiamante arresta la build nominando la connessione e il suo target, e un modello etichettato diversamente non provoca tale arresto. Una chiave che il Component di un chiamante dichiara invece in uno slot proprio è un’unica chiave per ogni connessione che esso stabilisce. Nessuna delle due estremità vede le associazioni dell’altra, quindi il server non sa nulla della chiave di un chiamante, e le due coincidono perché l’Aggregate le alimenta entrambe da un unico parametro: dove entrambe le estremità risolvono i secret in un unico ambito — un unico namespace Kubernetes, un unico progetto Compose — fanno riferimento a un unico secret, e altrimenti ciascuna conserva il proprio, realizzato dalla stessa voce dello store. vLLM, TEI e TGI verificano ciascuno una sola chiave, quindi ogni chiamante presenta la stessa chiave e il server non può distinguere i suoi chiamanti, e TGI confronta la sua chiave senza distinguere tra maiuscole e minuscole; APISIX, agentgateway e Traefik Hub verificano ciascuno la chiave di ogni chiamante dichiarato e distinguono i loro chiamanti in base a essa; i due Kong non dichiarano chiamanti e non verificano la chiave di alcun chiamante, per i motivi indicati sopra in «Kong davanti ai modelli»; il modello LiteLLM e l’AI gateway accettano anche le chiavi che emettono, mentre il loro database di contabilità è associato. Modello delle credenziali sviluppa questa struttura in un Aggregate.

  • Scegliere tra i target: core/target-selection dichiara come un gateway sceglie tra più target in grado di servire la stessa richiesta, con una strategy di latency (il target che si osserva rispondere più rapidamente) o cost (il target meno costoso da chiamare). La strategia fa parte di ciò che l’applicazione chiede al suo gateway, quindi lo sviluppatore la associa nell’Aggregate. Sull’AI gateway i target sono le voci del suo values.models che pubblicano lo stesso alias — un modello collegato è servito sotto l’alias della sua connessione, che nessun’altra voce può pubblicare — e la libreria standard realizza latency scrivendo il latency-based-routing del proxy nella configurazione di routing che la Recipe del gateway renderizza: il proxy invia ogni richiesta alla voce le cui ultime dieci risposte hanno impiegato in media meno tempo, per token di output dove una risposta riporta i propri token, o fino al primo token per una richiesta in streaming, e una voce non ancora provata conta come la più rapida. Senza l’associazione la configurazione non nomina alcuna strategia, e il proxy sceglie a caso tra quelle voci. cost vi è rifiutato per nome: il proxy stabilisce il prezzo di una voce cercandone il target, esattamente come scritto, in una tabella dei prezzi che nomina i modelli di OpenAI e di Anthropic senza il prefisso del provider che i target del gateway portano, e assegna a una voce che non trova un prezzo di fallback fisso, quindi le voci che condividono un alias avrebbero lo stesso prezzo e verrebbero scelte in base al loro ordine. Su core/gateway/kong-enterprise ogni associazione arresta la build, perché ogni modello collegato è servito su route proprie che portano quel solo modello, il che non lascia nulla tra cui scegliere. Anche su core/gateway/agentgateway ogni associazione arresta la build, indicando il motivo: agentgateway estrae a caso due dei target di un nome di modello e prende quello la cui salute, divisa per il tempo impiegato a rispondere, ottiene il punteggio più alto, quindi il target più rapido viene preso solo quando viene estratto, e non sceglie alcun target in base al costo. Anche su core/gateway/higress ogni associazione arresta la build, indicando il motivo: Higress può misurare la latenza di un servizio, ma il suo plugin di load balancing viene eseguito dopo l’AI proxy — che ha già impostato il modello, l’indirizzo e la credenziale della richiesta per il candidato risolto dalla route — e scrive la sua scelta in un header della richiesta in base al quale nulla instrada senza un filtro Envoy che questo catalogo non renderizza, quindi la scelta non ha effetto, e non sceglie alcun target in base al costo. Anche su core/gateway/traefik-hub ogni associazione arresta la build, indicando il motivo: Traefik sceglie in base al tempo di risposta più basso solo tra i server di un Service, che un solo nome di modello e una sola credenziale coprono, e tra i Service bilancia in base al peso o a un hash dell’indirizzo del client, mai in base alla latenza, e nessuna delle sue strategie sceglie un target in base al costo; inoltre ogni modello collegato al gateway è servito su una route propria che porta quel solo modello, il che non lascia nulla tra cui scegliere. Su qualsiasi altro gateway un’associazione arresta la build.

  • Resilienza: core/fallback-chain inoltra ad altri modelli una richiesta il cui modello fallisce: chains indica, per ogni alias di modello che ripiega, gli alias da provare in ordine finché uno risponde, mentre un fallback che fallisce segue a sua volta la propria voce, e max_hops limita fin dove lungo quella catena viene passata una richiesta. La libreria standard lo realizza sull’AI gateway scrivendo entrambi nella configurazione di instradamento che la Recipe del gateway produce, e interrompe la build su un nome che la mappa dei modelli del gateway non pubblica. Una richiesta ripiega solo dopo che il gateway ha rinunciato all’alias richiesto: dove un alias è pubblicato più di una volta, una chiamata fallita passa prima a un’altra delle sue voci come nuovo tentativo, entro il numero di tentativi del gateway. core/retry-policy imposta quel numero — quante volte il gateway può inviare una richiesta, primo invio compreso (max_attempts), per un errore che si risolve con un nuovo invio, come una connessione rifiutata, un limite di frequenza o un timeout — e la libreria standard lo realizza sull’AI gateway scrivendolo nella configurazione di instradamento che la Recipe del gateway produce. Su core/gateway/envoy-gateway è realizzato come il retry della traffic policy sulla route che serve i modelli collegati, la stessa policy che porta il rate limit di un budget di periodo, perché Envoy Gateway collega una sola traffic policy a una route: una richiesta viene reinviata dopo una connessione o uno stream rifiutati, un reset o una risposta 429, 503 o 504, fino a max_attempts invii, e a un modello che non risponde nulla entro il timeout della richiesta della route non si reinvia, perché quel timeout copre tutti gli invii. Su core/gateway/azure-api-management è realizzato come il retry di Azure attorno all’inoltro, nella sezione backend della policy dell’API: una richiesta a cui viene risposto con HTTP 429 o con uno stato 5xx viene reinviata, con il corpo conservato per poterlo reinviare, un secondo dopo l’invio precedente, fino a max_attempts invii. Una connessione rifiutata o interrotta, e un modello che non risponde nulla entro il timeout dell’inoltro, non vengono ritentati, perché Azure termina il retry su un errore del genere e lo passa alla sezione on-error della policy. Azure ritenta da 1 a 50 volte dopo il primo invio, quindi un max_attempts pari a 1 non scrive alcun retry e uno superiore a 51 viene rifiutato esplicitamente. Il retry prende il posto dell’inoltro che l’API erediterebbe, quindi finché è collegato un’impostazione di inoltro definita a un ambito più ampio dell’istanza, come un timeout, non si applica all’API, che inoltra con i valori predefiniti di Azure. Sul gateway ospitato, core/retry-policy è realizzato scrivendo nella risorsa del gateway il suo numero di tentativi, che indica gli invii successivi al primo, da 1 a 5, quindi max_attempts da 2 a 6 viene rispettato e qualsiasi altro valore rifiutato; core/fallback-chain non vi è realizzato, perché quel gateway ripiega tra modelli solo all’interno di una route che una richiesta indica al posto di un modello, quindi una richiesta per un modello non ripiega mai. Su core/gateway/kong-enterprise, core/fallback-chain è realizzato sulla sua Recipe chart: le route di chat e di completion di ogni alias a cui chains dà una voce usano l’AI Proxy Advanced di Kong al posto del suo AI proxy, con il modello dell’alias e i modelli su cui ripiega il suo percorso come target in ordine di priorità — l’alias, poi i fallback della sua voce in ordine, seguendo a sua volta la voce di un fallback solo finché ne sono stati contati meno di max_hops. Il balancer invia una richiesta a ogni target del percorso una volta, in ordine, finché uno risponde, passando oltre dopo un errore o un timeout di connessione, un’intestazione di risposta non valida o una risposta 429, 500, 502, 503 o 504, e restituisce ogni altra risposta così com’è arrivata. La build si interrompe su un nome che il socket models non porta, su un percorso che raggiunge due volte un alias, accanto a core/retry-policy, poiché Kong mantiene un solo numero di tentativi per l’intero percorso e non può reinviare a un modello prima di ripiegare, e su un’immagine del gateway anteriore alla 3.12. core/retry-policy non vi è realizzato, e la sua realizzazione interrompe ogni collegamento indicandone il motivo: ogni modello collegato è servito su route proprie che portano solo quel modello, quindi un retry deve reinviare la richiesta allo stesso target, e la documentazione di riferimento di Kong si presta a entrambe le letture riguardo al fatto che il suo balancer lo faccia. Su core/gateway/agentgateway, core/retry-policy è realizzato sulla Recipe chart come una policy di retry della configurazione propria del gateway, collegata al listener su cui arrivano le sue richieste ai modelli: una richiesta viene reinviata, subito e allo stesso modello, dopo una risposta 429, 500, 502, 503 o 504, una connessione rifiutata o resettata, una connessione che impiega più di 11 secondi ad aprirsi o una risoluzione dei nomi fallita, fino a max_attempts invii. agentgateway invia una richiesta una volta in più rispetto ai tentativi della sua policy, quindi la policy è scritta come max_attempts meno uno, max_attempts pari a 1 non ne scrive alcuna, e uno superiore a 256 viene rifiutato esplicitamente. Una richiesta il cui corpo supera 64 KiB viene inviata una sola volta, e la configurazione non imposta alcun timeout, quindi un modello che accetta la connessione e non risponde nulla viene atteso anziché ritentato. core/fallback-chain non vi è realizzato, e la sua realizzazione interrompe ogni collegamento indicandone il motivo: agentgateway passa da un modello all’altro escludendo quello fallito per le richieste successive, mentre alla richiesta fallita viene risposto con il suo errore, quindi nessuna richiesta viene fatta percorrere una catena. Su core/gateway/higress, core/retry-policy è realizzato come il retry proprio della route, scritto come annotazioni Ingress su ogni route di modello: una richiesta viene reinviata dopo una connessione rifiutata o resettata, una risposta 5xx o un 429, POST compresa, fino a max_attempts invii; max_attempts pari a 1 disattiva il retry, sovrascrivendo il retry che il control plane di Higress dà a una route priva di annotazioni, e uno superiore a 2147483648 viene rifiutato esplicitamente. A un modello che accetta la connessione e poi non risponde nulla o risponde lentamente non si reinvia, poiché la route non imposta alcuna scadenza per tentativo, e una richiesta in streaming viene reinviata solo prima che la sua risposta sia iniziata. Neanche core/fallback-chain vi è realizzato, e la sua realizzazione interrompe ogni collegamento indicandone il motivo: Higress inoltra una richiesta fallita al massimo una volta, a un’unica altra destinazione — il backend predefinito di una route, o l’unica route di fallback che la sua console scrive per una route AI — quindi nessuna richiesta viene fatta percorrere una catena. Su core/gateway/traefik-hub entrambi sono realizzati sulla Recipe chart, e ciascuno interrompe la build su un’immagine Traefik Hub anteriore alla v3.20, il cui failover non accetta middleware sui servizi che prova e il cui retry non può reinviare una POST in base allo stato di una risposta — fatta eccezione per una policy di retry di un solo invio. core/fallback-chain fa passare la route di ogni alias a cui chains dà una voce attraverso failover annidati propri di Traefik, provando in ordine i modelli del percorso dell’alias — l’alias, poi i fallback della sua voce in ordine, seguendo a sua volta la voce di un fallback solo finché ne sono stati contati meno di max_hops — ciascuno con il proprio nome di modello, credenziale, quote e retry. Una risposta 429 o da 500 a 504 di un modello, dopo l’eventuale retry di quel modello, fa passare la richiesta al successivo; ogni altra risposta viene restituita così com’è arrivata, quella dell’ultimo modello qualunque sia, e un corpo di richiesta superiore a 1 MiB viene rifiutato con HTTP 413 anziché inviato. La build si interrompe su un nome che il socket models non porta e su un percorso che raggiunge due volte un alias. core/retry-policy è il middleware di retry di Traefik, ultimo su ogni route di modello, o su ogni modello che un percorso prova: una richiesta viene reinviata subito dopo una connessione che non ha portato nulla al modello e dopo una risposta 429 o da 500 a 504, POST compresa, fino a max_attempts invii, primo compreso, e max_attempts pari a 1 non scrive nulla. Dopo una risposta che il gateway forma da sé — un rifiuto del suo controllo della chiave, una guardia, il mascheramento o una quota — la richiesta non viene mai reinviata, né dopo una risposta in streaming già iniziata.

  • Budget per periodo: core/period-budget limita ciò che il traffico attraverso un gateway può consumare in un periodo: un limit, il period che copre, uno scope — tutto ciò che il gateway serve, ciascun chiamante o ciascun modello — e una unit — un costo in dollari statunitensi o in token — e, una volta che ciò che il gateway ha conteggiato nel periodo supera il limite, le ulteriori richieste ai modelli vengono rifiutate. Si aggancia a qualsiasi componente che dichiari dataplane.aggrega.ai/period-budget. La libreria standard lo realizza sull’AI gateway, il cui budget copre tutto ciò che il gateway serve, è conteggiato in dollari statunitensi e riparte all’inizio di ogni periodo — un numero di giorni dalla mezzanotte UTC, o un mese di calendario dal suo primo giorno: la realizzazione scrive il limite e il periodo nella configurazione che la Recipe del gateway produce, rifiuta per nome qualsiasi altra unità, ambito o periodo — tra cui 30d, che il gateway conteggia come un mese di calendario — e si arresta a meno che gli slot di credenziali database_url e api_key del gateway non siano entrambi agganciati, perché senza il suo database contabile il gateway non tiene alcun conteggio e senza una chiave amministrativa non verifica alcun chiamante rispetto al budget. Una volta che il conteggio supera il limite, il gateway rifiuta le richieste ai modelli della chiave amministrativa oltre a quelle di ogni chiamante; l’elenco dei modelli e la gestione delle chiavi continuano a rispondere a quella chiave. Sul gateway ospitato è realizzato come una regola di limite di spesa sulla risorsa del gateway, conteggiata in dollari statunitensi su una finestra che avanza con il tempo — l’ultimo period, per i modelli di cui il gateway conosce i prezzi — per tutto ciò che il gateway serve: un budget per chiamante o per modello, i token e un mese di calendario vengono rifiutati per nome. Su core/gateway/apisix è realizzato sulla Recipe chart, scritto sulle rotte dei modelli collegati come il rate limiting dei token di APISIX: conteggiato nei token che la risposta di ciascun modello riporta — total_tokens, prompt_tokens o completion_tokens — su una finestra fissa di period che si apre con la prima richiesta a un modello dopo la chiusura della finestra precedente anziché sull’orologio, per tutto ciò che il gateway serve, per ciascun modello collegato separatamente, o per ciascun chiamante che la sua Release dichiara in infra.callers separatamente, distinguendoli il gateway in base alla chiave che ciascuno presenta. Una volta che il conteggio raggiunge il limite, il gateway risponde alle richieste ai modelli con HTTP 503 finché la finestra non si chiude; i token di una richiesta vengono aggiunti una volta completata la sua risposta, per cui la richiesta che raggiunge il limite viene servita, e una risposta servita dalla sua cache semantica non conta nulla e viene servita oltre il limite. APISIX non conta alcun token su una richiesta di completion, per cui, mentre il budget è agganciato, ciascun modello collegato riceve solo la propria rotta chat, e mantiene il conteggio nella memoria del processo del gateway, per cui il chart esegue una sola replica e un riavvio apre una nuova finestra. Un budget in dollari statunitensi, uno per chiamante mentre infra.callers non ne dichiara nessuno, un mese di calendario e un secondo budget su uno stesso gateway vengono rifiutati per nome, come pure un aggancio sulla sua Recipe workload, che non produce alcuna rotta. Su core/gateway/envoy-gateway è realizzato come il rate limit basato sull’utilizzo di Envoy Gateway, sulla rotta AI che serve i modelli collegati al gateway: la rotta dichiara il conteggio di token indicato da unit — total_tokens, prompt_tokens o completion_tokens — come un costo che Envoy AI Gateway legge da ciascuna risposta, e una traffic policy su quella rotta lo addebita al completamento della risposta, a fronte di limit token per un’unità del rate limit di Envoy Gateway, per tutto ciò che il gateway serve o per ciascun modello collegato separatamente. Ogni finestra è fissata sull’orologio UTC — un secondo, un minuto, un’ora, un giorno dalla mezzanotte, una settimana da un giovedì, o 30 o 365 giorni contati dal 1º gennaio 1970 — e 1mo è un mese di calendario, in base a un’impostazione del servizio di rate limit di Envoy Gateway che vale poi per ogni rate limit mensile mantenuto da quell’installazione. Il conteggio è mantenuto dal servizio di rate limit che il control plane di Envoy Gateway crea e attiva per ogni gateway che serve, nello store a protocollo Redis collegato al socket cache del gateway. Una volta che il conteggio supera il limite, il gateway risponde alle richieste ai modelli con HTTP 429 finché la finestra non termina; i token di una richiesta vengono aggiunti una volta completata la sua risposta, per cui la richiesta che supera il limite viene servita. Mentre lo store o il servizio di rate limit non sono raggiungibili, o un controllo richiede più tempo del timeout di rate limit di Envoy, le richieste ai modelli vengono rifiutate con HTTP 500, in base a un’impostazione del control plane di Envoy Gateway che vale poi per ogni rate limit mantenuto da quell’installazione, per cui anche un rate limit applicato a mano fallisce in modo chiuso; una richiesta ammessa poco prima di un’interruzione viene comunque servita e non conteggiata, perché i suoi token vengono addebitati dopo la risposta, e uno store che mantiene il conteggio in memoria fa ripartire ogni finestra quando si riavvia. Un budget in dollari statunitensi, uno per chiamante — il gateway distingue i chiamanti solo tramite un header che il chiamante scrive da sé, e nulla su quel percorso lo verifica — qualsiasi altro periodo e un secondo budget su uno stesso gateway vengono rifiutati per nome, come pure un aggancio senza nulla collegato al socket models o al socket cache. Su core/gateway/azure-api-management è realizzato come il token limit di Azure, scritto nella policy dell’API: conteggiato nei token di prompt e di completion che ciascuna risposta riporta, insieme, per tutto ciò che l’API serve o per ciascuna sottoscrizione di API Management, la cui chiave il gateway verifica — o una quota su una finestra fissa sull’orologio UTC, un’ora, un giorno, una settimana, un mese di calendario o un anno di calendario (1h, 1d, 7d, 1mo o 12mo; Microsoft non dice in quale giorno inizi una settimana), a cui si risponde con HTTP 403 una volta superata, o una frequenza su un minuto (1m), a cui si risponde con HTTP 429 e conteggiata su una finestra scorrevole nei tier classici e come un token bucket nei tier v2. Il conteggio è l’utilizzo che ciascuna risposta riporta, per cui richieste concorrenti possono superare il limite, e ciascun gateway dell’istanza mantiene il proprio conteggio. Un budget in dollari statunitensi o soltanto in token di prompt o di completion, uno per modello — il modello che una richiesta nomina è scritto dal chiamante, e più nomi possono raggiungere uno stesso modello — uno per sottoscrizione su un’API che non richiede alcuna chiave di sottoscrizione, qualsiasi altro periodo e un limite che non sia un numero intero vengono rifiutati per nome. Il tier Consumption non esegue alcun token limit. Su core/gateway/kong-enterprise è realizzato sulla Recipe chart, scritto nelle rotte che il gateway importa come AI Rate Limiting Advanced di Kong: conteggiato nei token che la risposta di ciascun modello riporta — total_tokens, prompt_tokens o completion_tokens — in finestre fisse di period, un numero di secondi, minuti, ore o giorni, ciascuna richiesta conteggiata nell’unica finestra in cui cade il suo istante, per tutto ciò che il gateway serve o per ciascun modello collegato separatamente, una richiesta con scope model conteggiata a carico dell’alias che ha nominato, qualunque modello le abbia risposto. Una volta che il conteggio raggiunge il limite, alla richiesta successiva a un modello si risponde con HTTP 429 finché la finestra non termina, per cui la richiesta che supera il limite viene servita; Kong può anche rifiutare una richiesta in anticipo, in base a una propria stima dei token di prompt che contiene. Il conteggio è mantenuto nel backend PostgreSQL del gateway, condiviso da ogni replica e conservato attraverso un riavvio. Un budget in dollari statunitensi — Kong conteggia il costo solo a partire da un prezzo che la sua configurazione assegna a ciascun modello, e il catalogo non ne fornisce alcuno — uno per chiamante — Kong distingue i chiamanti solo come i consumer che un plugin di autenticazione nomina, e il gateway non dichiara alcun chiamante, per le ragioni che «Kong davanti ai modelli» espone sopra — un mese di calendario, un secondo budget su uno stesso gateway e un’immagine del gateway anteriore alla 3.15 vengono rifiutati per nome, come pure un aggancio senza nulla collegato al socket models. Su core/gateway/agentgateway è realizzato sulla Recipe chart, scritto nella configurazione del gateway e conteggiato nei token totali che ciascuna risposta riporta: con scope caller come un budget sulla chiave API di ciascun chiamante che la sua Release dichiara in infra.callers, su finestre fisse di period allineate all’epoch Unix, con il giorno che inizia alla mezzanotte UTC, mantenuto in uno store SQLite su un volume che la Recipe produce, con una sola replica; con scope gateway o model come un token bucket per tutto ciò che il gateway serve o per ciascun nome di modello che una richiesta chiede, riempito fino al limite ogni period a partire da quando il gateway ha letto la sua configurazione e mantenuto nella sua memoria, per cui un riavvio o una configurazione modificata lo riempie di nuovo. Una volta che ciò che è stato conteggiato raggiunge il limite, alle richieste ai modelli si risponde con HTTP 429 finché la finestra non termina o il bucket non viene riempito; la richiesta che lo raggiunge viene servita. Un budget in dollari statunitensi — il catalogo dei costi dei modelli del gateway non prezza nessuno dei modelli collegati a esso, per cui il budget non conteggerebbe nulla — soltanto in token di prompt o di completion, uno per chiamante mentre infra.callers non ne dichiara nessuno, un mese di calendario, un limite che non sia un numero intero e un secondo budget su uno stesso gateway vengono rifiutati per nome, come pure un aggancio senza nulla collegato al socket models; la sua Recipe compose non ne ha alcuna realizzazione. Su core/gateway/traefik-hub è realizzato sulla Recipe chart come il middleware di quota di Traefik Hub sulla rotta di ciascun modello collegato, che mantiene il suo conteggio nello store a protocollo Redis collegato al socket cache del gateway: conteggia i token che ciascuna risposta riporta — total_tokens, prompt_tokens o completion_tokens — o, con usd, il loro costo in dollari statunitensi, prezzato da un elenco di modelli fornito con il middleware, rifiutando con HTTP 422 un modello di cui non ha il prezzo, su una finestra che scorre con il tempo, in cui ciò che è stato conteggiato in un momento si libera di nuovo un periodo dopo, per ciascun modello collegato separatamente, o per tutto ciò che il gateway serve mentre è collegato un solo modello. Una volta che il conteggio raggiunge il limite, le richieste ai modelli vengono rifiutate con HTTP 429; il conteggio di una richiesta viene aggiunto una volta completata la sua risposta, per cui la richiesta che supera il limite, e qualsiasi altra servita accanto a essa, viene servita, e una risposta servita dalla cache semantica non conta nulla. Il riferimento di Traefik dice che la quota serve le richieste senza conteggiarle mentre lo store non è raggiungibile. Un budget per chiamante — la quota distingue le richieste in base all’indirizzo del client, a un header della richiesta o all’host della richiesta, e nessuno di questi è il chiamante che il controllo delle chiavi del gateway ha verificato — uno per l’intero gateway mentre sono collegati più modelli, poiché il riferimento di Traefik non dice se le rotte che nominano una stessa quota ne condividano il conteggio, un mese di calendario e qualsiasi periodo che non sia in ore o giorni, o in minuti o secondi che formino ore intere, vengono rifiutati per nome, come pure un limite che non sia un numero intero di token e un aggancio senza nulla collegato al socket models o al socket cache. Su core/gateway/higress è realizzato sulla Recipe chart come il plugin di token limit di Higress sulla rotta di ciascun modello collegato, che mantiene il suo conteggio nello store a protocollo Redis collegato al socket cache del gateway: somma i token di prompt e di completion che ciascuna risposta riporta, insieme, una volta completata la risposta, su una finestra fissa di period — un secondo, un minuto, un’ora o un giorno — che si apre quando viene conteggiata la prima risposta al suo interno, per tutto ciò che il gateway serve o per ciascun alias separatamente. Mentre il conteggio supera il limite, alle richieste ai modelli si risponde con HTTP 429 finché la finestra non termina, per cui la richiesta che supera il limite viene servita. Una risposta che non riporta alcun utilizzo non conta nulla, per cui la Recipe chiede al modello di una richiesta in streaming di riportare il proprio utilizzo e rifiuta con HTTP 403 una richiesta in streaming che disattiva quel resoconto, una richiesta il cui content type né contiene application/json né inizia con multipart/form-data, che il proxy AI inoltra senza chiedere il resoconto, e una il cui body i plugin del gateway non leggono — un body compresso, un content type che contiene octet-stream o grpc, un upgrade; un client che invia deliberatamente un body che la validazione del gateway non riesce a decodificare supera quei rifiuti, e una tale richiesta in streaming non viene conteggiata. Senza alcun mascheramento agganciato, una richiesta il cui body supera il buffer di 32 KiB del gateway può essere rifiutata con HTTP 413, a seconda di quando risponde lo store. Mentre lo store non è raggiungibile, le richieste ai modelli vengono servite e non conteggiate: il plugin non ha alcuna impostazione che le rifiuti in quel caso. Un budget in dollari statunitensi o soltanto in token di prompt o di completion, uno per chiamante — il gateway non dichiara alcun chiamante, per cui non ne verifica nessuno — qualsiasi altro periodo, un limite che non sia un numero intero e un secondo budget su uno stesso gateway vengono rifiutati per nome, come pure un aggancio senza nulla collegato al socket models o al socket cache.

  • Concorrenza: core/concurrency-limit limita quante richieste un gateway trasporta contemporaneamente (max_in_flight), il che impedisce che un picco di chiamanti diventi una coda presso il modello alle sue spalle. scope dice che cosa conta un limite: gateway, il valore predefinito, conta insieme ogni richiesta che il gateway inoltra; model dà a ciascuna destinazione a cui il gateway invia richieste un proprio conteggio, essendo una destinazione ciascuna voce upstream verso cui il gateway instrada, per cui dove un nome di modello ha più voci ciascuna viene conteggiata separatamente. Il limite e il suo ambito sono un dimensionamento della capacità che decide l’operatore, impostato nell’infra dell’aggancio, per cui è l’operatore ad agganciarlo nella Release. Il limite è conteggiato per ogni proxy in esecuzione, per cui dove sono in esecuzione più repliche ciascuna di esse ne ammette altrettante. Si aggancia a qualsiasi componente che dichiari dataplane.aggrega.ai/concurrency-cap, e una realizzazione rifiuta per nome l’ambito che il suo gateway non conteggia. Su core/gateway/nginx lo scope gateway è realizzato come limit_conn di NGINX, con chiave su una parola uguale per ogni richiesta, per cui NGINX conta ogni richiesta che sta elaborando come un unico totale, mantenuto in una memoria condivisa dai suoi processi worker, e risponde a una richiesta oltre il limite con HTTP 503; lo scope model viene rifiutato, poiché NGINX non mantiene alcun conteggio per ciascuna destinazione upstream, e così pure un max_in_flight superiore a 65535, il massimo che limit_conn accetta. Su core/gateway/envoy-gateway lo scope model è realizzato come il circuit breaker della traffic policy sulla rotta che serve i modelli collegati, la policy che porta anche il rate limit di un budget per periodo e il retry della retry policy: Envoy Gateway lo applica al backend di ciascuna regola di quella rotta, e ciascun modello collegato ha una propria regola, per cui al massimo max_in_flight richieste vengono inviate contemporaneamente a ciascun modello collegato, e a una richiesta oltre il limite si risponde con HTTP 503 e non viene inviata di nuovo; un invio che la retry policy ripete conta rispetto al limite come il primo. I thread worker di Envoy controllano il conteggio e poi lo incrementano, per cui richieste che arrivano insieme possono portarlo brevemente oltre il limite. Lo scope gateway viene rifiutato, poiché Envoy Gateway mantiene un limite per ciascun backend e nessuno sul loro totale, e così pure un aggancio senza nulla collegato al socket models. Sull’AI gateway lo scope model è realizzato come il max_parallel_requests di ogni voce della sua mappa dei modelli, sia scritta a mano sia collegata: al massimo max_in_flight richieste sono in corso verso ciascuna voce contemporaneamente, e a una richiesta che trova la propria voce piena si risponde con HTTP 429 — dopo i retry del gateway dove il suo alias ha una sola voce, e subito dove ne ha più di una, anche mentre un’altra di esse ha spazio, poiché il proxy sceglie la voce prima di conteggiare — a meno che core/fallback-chain non elenchi dei fallback per il suo alias, verso i quali viene allora inoltrata. Il proxy mantiene ciascun conteggio in memoria, dove per impostazione predefinita un record scade dieci minuti dopo la sua creazione e un nuovo conteggio riparte allora da zero, per cui l’aggancio imposta anche quella durata a un secolo, conservando ogni conteggio finché il proxy è in esecuzione. A causa di quella durata il gateway rifiuta una richiesta che porta priority mentre il limite è agganciato, anche dove la Release ammette il campo, poiché il proxy mantiene una voce di coda per ogni richiesta di questo tipo finché il suo record non scade; e la build si arresta su una mappa dei modelli di più di 100 voci, oltre le quali lo store in cui sono mantenuti i conteggi, che contiene 200 record e ne scarta uno ogni volta che è pieno, potrebbe scartare un conteggio. Lo scope gateway viene rifiutato lì, poiché l’unico totale del proxy è letto solo da un limitatore di richieste che una variabile d’ambiente attiva, il quale conta una richiesta per il suo primo secondo. Né lo realizza il gateway ospitato: il limite di richieste che la sua Recipe terraform scrive nella risorsa del gateway è una frequenza, un numero di richieste in un intervallo, anziché un limite sulle richieste in corso.

  • Registrazione di audit: core/audit-logging fa sì che un gateway conservi un record di ogni richiesta al modello che serve, indicando il modello che ha risposto e i token riportati dalla risposta, e ogni realizzazione dice dove finisce il record. Si associa a qualsiasi componente che porta gateway.aggrega.ai/intelligence: semantic, e i suoi tre valori sono dell’operatore, impostati nel suo infra, quindi è l’operatore ad associarlo nella Release. require_cost, attivo per impostazione predefinita, fa sì che il record indichi anche quanto è costata ogni richiesta, in una valuta che la realizzazione specifica. require_verified_caller, attivo per impostazione predefinita, fa sì che indichi il chiamante verificato dal gateway, tramite una chiave che il gateway ha emesso o controllato. retention_days, non impostato per impostazione predefinita, fa sì che il gateway elimini un record una volta che ha raggiunto quel numero di giorni; senza di esso il gateway stesso non elimina alcun record, e un record dura quanto lo conserva il luogo in cui finisce. Un gateway che non può rispettare un valore rifiuta l’associazione in fase di build, indicando il valore, per cui un’associazione che lascia require_cost e require_verified_caller ai valori predefiniti ottiene il costo e il chiamante verificato, oppure un arresto. Disattivare require_verified_caller significa accettare un record il cui chiamante è quello che la richiesta stessa dichiara, o nessun chiamante: chiunque invii una richiesta può allora farla registrare a nome di un altro chiamante, quindi un tale record non mostra chi ha inviato una richiesta. Sul gateway AI il record è una riga nel database contabile del gateway, e ogni valore è rispettato: la riga indica quanto è costata la richiesta in dollari statunitensi, con il prezzo tratto dalla tabella che il gateway tiene per ogni modello — un modello a cui la tabella non assegna un prezzo viene registrato a costo zero — e indica la chiave verificata dal gateway, con l’utente e il team a cui la chiave appartiene, mentre l’utente finale indicato in una riga è quello che la richiesta scrive, senza alcun controllo. Senza il suo database contabile il gateway non scrive alcuna riga, e senza una chiave amministrativa non controlla alcun chiamante e non scrive alcuna riga per una richiesta che non presenta una chiave e non indica un utente finale, quindi la build si arresta a meno che gli slot di credenziali database_url e api_key del gateway non siano entrambi associati; finché values.log_masking del gateway elenca cosa mascherare, il gateway registra solo le richieste a cui è stata data risposta. Su core/gateway/envoy-gateway il record è una riga del log di accesso del gateway, che la sua Recipe scrive finché l’associazione è presente: una riga JSON per richiesta sullo standard output del data plane, con i campi che Envoy Gateway scrive per impostazione predefinita, il modello indicato dalla richiesta, il modello che ha risposto e i token di prompt, di completamento e totali riportati dalla risposta, e la route che serve i modelli dichiara quei conteggi affinché Envoy AI Gateway li registri. Una richiesta a cui il modello non ha risposto non riporta alcun modello che ha risposto né alcun token, e il log di accesso di per sé non conserva nulla, quindi quanto dura una riga dipende da ciò che raccoglie quell’output. Nessun campo indica un chiamante verificato dal gateway: l’indirizzo del client e le intestazioni che invia vengono scritti così come arrivano. Il gateway non tiene prezzi, nulla sulla route resa dalla sua Recipe verifica il chiamante, e il log di accesso non conserva alcun record che possa eliminare, quindi la sua realizzazione compila un’associazione che disattiva require_cost e require_verified_caller e non indica retention_days, e altrimenti si arresta indicando ogni valore che non può rispettare, tutti in un unico errore; si arresta anche quando nulla è collegato al socket models. Su core/gateway/agentgateway il record è una riga che il gateway scrive in un archivio SQLite su un volume che la sua Recipe chart rende finché l’associazione è presente, con una sola replica, per ogni richiesta al modello che supera i controlli di chiave, budget e autorizzazione, compreso il rifiuto di una guardia: il modello che il gateway ha chiesto al server del modello — il nome che il modello collegato pubblica, non l’alias inviato dal chiamante — e il modello che ha risposto, i token di input, di output e totali riportati dalla risposta, il suo stato e i suoi tempi e, per ogni chiamante che la sua Release dichiara in infra.callers, il nome di quel chiamante, ricavato dalla chiave API verificata dal gateway. Una richiesta rifiutata per la sua chiave, da una regola di autorizzazione o dal budget di un chiamante non lascia alcuna riga. Non viene conservato alcun testo di prompt o di risposta, e le righe si leggono tramite l’interfaccia di amministrazione del gateway, che è in ascolto all’interno del suo pod. require_verified_caller è rispettato finché sono dichiarati dei chiamanti; require_cost è rifiutato per nome, poiché il catalogo dei costi dei modelli del gateway non assegna un prezzo a nessuno dei modelli collegati, e lo sono anche require_verified_caller senza alcun chiamante dichiarato e retention_days, poiché il gateway non elimina alcun record; la sua Recipe compose non ne ha alcuna realizzazione. Su core/gateway/higress il record è il campo ai_log della riga del log di accesso del gateway, che il plugin di statistiche di Higress compila finché l’associazione è presente: il modello che ha risposto e i token di input, di output e totali riportati dalla risposta, sullo standard output del gateway, senza testo di prompt o di risposta. Il gateway non dichiara chiamanti, non assegna prezzi e non conserva alcun record che potrebbe eliminare, quindi la sua realizzazione compila un’associazione che disattiva require_cost e require_verified_caller e non indica retention_days, e altrimenti si arresta indicando ogni valore che non può rispettare, tutti in un unico errore; si arresta anche quando nulla è collegato al socket models. Su core/gateway/traefik-hub ogni associazione si arresta, indicandone il motivo: Traefik Hub conserva un record di una richiesta al modello solo come span OpenTelemetry che i suoi middleware AI esportano verso un backend di tracing — indicando il modello e, al livello dettagliato, i token e il loro costo in dollari statunitensi — e la sua realizzazione non collega alcun backend di tracing, quindi il record non finirebbe da nessuna parte; né lo span indica un chiamante, quindi non può indicare quello verificato dal controllo della chiave del gateway. Su core/gateway/azure-api-management ogni associazione si arresta, come dice la voce del gateway più sopra, e nessun altro gateway della libreria standard lo realizza, quindi un’associazione su qualsiasi altro gateway si arresta indicando il tipo.

  • Caching semantico: core/semantic-caching dichiara una cache che risponde a un prompt con la risposta memorizzata per un prompt precedente abbastanza vicino nel significato, invece di chiamare di nuovo il modello. embedding_model indica il modello che trasforma ogni prompt in un vettore, così come lo pubblica il gateway; una risposta memorizzata viene servita quando i due prompt sono simili almeno quanto indica similarity_threshold, e resta utilizzabile per ttl_seconds. scope decide chi condivide una cache: end_user, il valore predefinito, tiene separato ogni utente finale che il gateway identifica, mentre key serve da un’unica cache ogni chiamante che presenta la stessa chiave, quindi a un utente finale dietro quella chiave può essere servita una risposta generata per un altro. core/data-masking dichiara un conflitto con essa, quindi la build si arresta su un componente che le porta entrambe. La libreria standard la realizza sul gateway AI, che tiene le risposte in un core/datastore/redis collegato al suo socket cache_store, presentando all’archivio la password contenuta nella credenziale su quella connessione quando l’archivio ne richiede una, con l’archivio che rimuove ogni risposta una volta trascorsi ttl_seconds, e mette in cache le richieste chat, responses e messages, non completions né embeddings. La realizzazione arresta la build a meno che lo slot api_key del gateway non sia associato, perché senza una chiave amministrativa il gateway non controlla alcun chiamante, su un embedding_model che la mappa dei modelli del gateway non pubblica, e quando nulla è collegato a cache_store. Una risposta memorizzata viene servita solo a una richiesta che corrisponde a ciò sotto cui è stata memorizzata: la chiave che la richiesta presenta, che il gateway verifica, con il team e l’organizzazione di quella chiave; con end_user, l’utente finale indicato dalla richiesta; e il modello che la richiesta chiede con i suoi altri parametri. Il gateway scrive la chiave, il team, l’organizzazione e l’utente finale nella richiesta stessa, sovrascrivendo qualsiasi valore che un chiamante abbia inviato per essi in una richiesta chat; in una richiesta responses o messages rimuove un campo team, organizzazione o utente finale dai metadati propri della richiesta e rifiuta un campo che lì indichi la chiave, quindi nessuna richiesta può accedere alle risposte di un’altra chiave semplicemente nominandola. I metadati propri di una richiesta possono comunque spostarla tra le risposte della chiave che presenta: in una richiesta responses model_group sostituisce il modello che chiede in ciò sotto cui viene memorizzata la sua risposta; in una richiesta responses o messages caching_groups consente alle richieste che indicano lo stesso gruppo di alias di modello di condividere le risposte tra di essi; e in una richiesta responses o chat redis_namespace tiene separate le richieste che indicano un namespace da quelle che non ne indicano alcuno. Il gateway legge un utente finale da un’intestazione o da un campo del body che la richiesta stessa indica, e non ne verifica nessuno: con end_user a un chiamante che indica un altro utente finale vengono servite le risposte di quell’utente finale, e le richieste che non indicano alcun utente finale condividono un’unica cache con ogni altra richiesta di quel tipo sotto la chiave che presentano. Il gateway ospitato non la realizza: la sua cache risponde solo a una richiesta identica a una precedente. Su core/gateway/azure-api-management è realizzata come lookup e store della cache semantica di Azure, scritti nella policy dell’API: embedding_model indica un backend che l’istanza di API Management ha già per un modello di embeddings, che l’istanza raggiunge con la sua identità gestita, e l’istanza ha bisogno di una cache Redis con RediSearch configurata come sua cache esterna, cose che la build non può vedere, quindi la build si arresta finché l’operatore non afferma che la cache serve RediSearch impostando infra.cache_serves_vector_search del gateway; l’archivio conserva una risposta per ttl_seconds; e similarity_threshold viene scritto come la soglia di punteggio di Azure, uno meno la soglia, leggendo quel punteggio come una distanza coseno, poiché Microsoft ne indica l’intervallo e la direzione — più basso richiede prompt più vicini — ma non la misura. Una risposta viene memorizzata e servita separatamente per API e per sottoscrizione di API Management, la cui chiave il gateway verifica, quindi la realizzazione mantiene key, lo rifiuta su un’API che non richiede alcuna chiave di sottoscrizione, e rifiuta end_user: l’API resa dalla sua Recipe non convalida il token di alcun utente finale, quindi il gateway non ha alcun utente finale verificato da tenere separato. Non la realizzano nemmeno core/gateway/contour e core/gateway/nginx, poiché non offrono alcuna cache semantica. Su core/gateway/agentgateway la sua realizzazione arresta ogni associazione, indicandone il motivo: agentgateway non tiene alcuna cache delle risposte, e il suo prompt caching segnala solo dove un provider che mette in cache i prompt da sé può farlo. Su core/gateway/kong-enterprise la sua realizzazione arresta ogni associazione, indicando lo scope richiesto: l’AI Semantic Cache di Kong non ha alcuna impostazione che tenga le risposte memorizzate di un chiamante separate da quelle di un altro, e il gateway distingue i chiamanti solo come i consumer indicati da un plugin di autenticazione e non dichiara alcun chiamante, per le ragioni che «Kong davanti ai modelli» indica più sopra, quindi con end_user come con key ogni richiesta condividerebbe un’unica cache. Su core/gateway/higress la sua realizzazione arresta ogni associazione, indicando lo scope richiesto: la cache semantica di Higress memorizza ogni risposta sotto un unico prefisso di chiave seguito dal testo del prompt, e nulla in quella chiave indica un chiamante o un utente finale, mentre il gateway non dichiara alcun chiamante, quindi ogni richiesta condividerebbe un’unica cache. Su core/gateway/apisix è realizzata sulla Recipe chart, scritta sulla route chat di ogni modello collegato come cache semantica di APISIX 3.18.0, per i chiamanti che la sua Release dichiara in infra.callers: una risposta viene memorizzata per route e per chiamante, sotto la chiave presentata dal chiamante, che il gateway verifica, quindi a nessun chiamante viene servita una risposta memorizzata per un altro; la realizzazione mantiene key e rifiuta end_user per nome, perché il gateway non può distinguere gli utenti finali dietro una stessa chiave. embedding_model indica una connessione sul socket models del gateway, con il cui endpoint, modello e credenziale la cache calcola gli embedding. La cache calcola l’embedding dell’ultimo messaggio utente di una richiesta e serve una risposta memorizzata il cui messaggio è simile almeno quanto indica similarity_threshold e i cui messaggi precedenti — un prompt di sistema, turni precedenti — sono gli stessi. Le risposte restano per ttl_seconds in un core/datastore/redis collegato al socket cache_store del gateway, al quale la cache presenta la password contenuta nella credenziale su quella connessione, e una risposta servita per significato viene memorizzata di nuovo sotto quella richiesta per altri ttl_seconds. Le richieste di completamento non vengono messe in cache, e un errore dell’archivio o dell’embedding è un miss: alla richiesta viene comunque data risposta. La realizzazione si arresta quando non è dichiarato alcun chiamante, quando nulla è collegato a cache_store o al socket models, e su un embedding_model che nessuna connessione lì trasporta. APISIX identifica una risposta memorizzata per route e chiamante anziché per gateway, quindi due gateway APISIX collegati a uno stesso archivio, o due Releases di uno stesso Aggregate che puntano il loro gateway verso uno stesso archivio esterno, possono servire una risposta in cache a un chiamante con lo stesso nome sullo stesso alias e modello. La sua Recipe workload, con APISIX 3.17.0, non ha alcuna cache semantica. Su core/gateway/traefik-hub è realizzata sulla Recipe chart come cache semantica di Traefik Hub sulla route di ogni modello collegato, per i chiamanti che la sua Release dichiara in infra.callers: una risposta viene memorizzata per modello collegato e per chiamante, sotto il chiamante verificato dal controllo della chiave del gateway, ciascuno con la propria chiave, quindi a nessun chiamante viene servita una risposta memorizzata per un altro; la realizzazione mantiene key e rifiuta end_user per nome, perché il gateway non può distinguere gli utenti finali dietro una stessa chiave. embedding_model indica una connessione sul socket models del gateway, con il cui endpoint, modello e credenziale la cache calcola l’embedding del testo di una richiesta. similarity_threshold viene scritto come il limite di distanza della cache, uno meno la soglia, letto come una distanza coseno, poiché il riferimento di Traefik indica la direzione del limite ma non la sua misura. Una risposta viene conservata per ttl_seconds in un core/datastore/redis collegato al socket cache_store del gateway, e a una richiesta troppo grande per calcolarne l’embedding viene data risposta senza cache. La realizzazione si arresta quando non è dichiarato alcun chiamante, quando nulla è collegato a cache_store o al socket models, su un embedding_model che nessuna connessione lì trasporta, e su un’immagine di Traefik Hub il cui tag non indica una versione dalla v3.19.11 all’interno della 3.19 o dalla v3.20.6 in poi, poiché una versione precedente condivide un’unica cache tra tutti i chiamanti di una route.

  • Controllo della prompt injection: core/prompt-injection-shield dichiara che le richieste ai modelli inoltrate da un gateway vengono controllate, prima che il modello sia chiamato, alla ricerca di un tentativo di scavalcare le istruzioni date al modello, con una sensitivity pari a standard o strict — strict rifiuta più tentativi di questo tipo, e con essi più richieste legittime. Il controllo è il verdetto di un classificatore probabilistico: non rileva alcuni attacchi — tra cui quelli riformulati, codificati o scritti in modo diverso —, rifiuta alcune richieste legittime ed è notoriamente eludibile, quindi è un controllo accanto ad altri, e non giudica la risposta del modello, gli argomenti delle chiamate agli strumenti né le immagini. Si collega a qualsiasi gateway, e una realizzazione o fa passare le richieste del gateway attraverso una guardia collegata al suo socket guard, che non richiede al gateway altro se non di inoltrare a un indirizzo con cui è configurato, oppure attiva un controllo che il gateway esegue da sé. Con una guardia, la guardia controlla ogni richiesta e inoltra al modello ciò che ammette, e collegare la Feature senza nulla su quel socket interrompe la build indicandolo. La libreria standard la realizza sul gateway AI e sul gateway NGINX, ciascuno con core/security/nemo-guardrails come guardia: un servizio che parla l’API chat-completions di OpenAI, la cui rail invia l’ultimo messaggio utente di una richiesta al classificatore del core/security/trustyai-huggingface-detector collegato a esso e rifiuta la richiesta quando il punteggio di quel classificatore raggiunge la soglia della guardia. A una richiesta rifiutata risponde la guardia stessa, con un normale completamento, e nulla di essa raggiunge il modello; quando la guardia o il suo rilevatore non sono raggiungibili, anche la richiesta viene rifiutata. Ciascuno dei due interrompe la build a meno che la guardia non sia quella, con la soglia indicata dalla sensibilità — 0.5 per standard e 0.001 per strict, i due valori misurati per il classificatore predefinito del rilevatore, di cui il gateway, che vede la guardia e non il rilevatore dietro di essa, non può verificare il modello. Sul gateway AI ogni alias della mappa dei modelli viene inviato alla guardia, con ogni destinazione scritta openai/<model>, quindi la mappa è quella scritta a mano: un modello collegato al socket models del gateway verrebbe inviato al proprio endpoint con la credenziale della propria connessione, aggirando la guardia, e la realizzazione interrompe la build finché quel socket contiene una connessione, indicandola. Il gateway AI rifiuta ogni richiesta che non sia una chat completion, l’unico tipo che la guardia controlla; sul gateway NGINX la sua unica location inoltra alla guardia al posto dell’upstream, e la guardia non risponde a nessun’altra route di modello. Su core/gateway/azure-api-management è realizzata come il prompt shield di Azure, attivato nella policy dell’API tramite il backend Azure AI Content Safety dell’istanza indicato da infra.content_safety_backend_id, e la build si interrompe finché quella chiave non è impostata: Azure AI Content Safety controlla ogni richiesta alla ricerca di un attacco dell’utente prima che il modello sia chiamato, prima della ricerca in una cache semantica, e il gateway risponde con HTTP 403 a una richiesta in cui ne rileva uno, come risponde a una richiesta più lunga di quanto il servizio accetti. Lo shield è attivo o disattivo, quindi standard è mantenuto e strict è rifiutato per nome, e opera alla sensibilità propria di Microsoft, non misurata rispetto alla soglia che standard indica sulle guardie. L’istanza raggiunge quel backend con la propria identità gestita, che necessita del ruolo Cognitive Services User sul servizio; la build non vede né l’una né l’altro. Nessun gateway della libreria standard oltre a questi tre la realizza, e collegarla a un altro interrompe la build indicandone il tipo: la maggior parte non genera alcuna route che una realizzazione possa far passare attraverso una guardia — mantengono le route in un proprio archivio, le prendono dai servizi che stanno dietro di loro, oppure sono un servizio ospitato su cui la libreria standard non attiva alcun controllo di questo tipo — e core/gateway/apisix, la cui Recipe del chart genera le route dei modelli collegati a esso, e core/gateway/envoy-gateway, la cui Recipe genera la route AI dei modelli collegati a esso, non ne hanno alcuna realizzazione. Su core/gateway/agentgateway, le cui Recipes generano una voce per ogni modello collegato a esso, la realizzazione interrompe ogni collegamento, indicandone il motivo: agentgateway giudica una richiesta alla ricerca di un tale tentativo solo tramite un servizio che chiama — un webhook gestito dall’operatore, oppure Azure AI Content Safety, Google Model Armor o AWS Bedrock Guardrails — e la realizzazione non ne collega nessuno. Anche su core/gateway/higress la realizzazione interrompe ogni collegamento, indicandone il motivo: Higress giudica un tale tentativo solo tramite un servizio che chiama — il servizio di sicurezza dei contenuti di Alibaba Cloud oppure, tramite un plugin presente nel suo sorgente ma non pubblicato nella sua release dei plugin 2.2.5, un servizio di modello Qwen3Guard gestito dall’operatore — e ciascuno lascia passare la richiesta quando quella chiamata fallisce, e la realizzazione non collega né l’uno né l’altro. Anche su core/gateway/traefik-hub la realizzazione interrompe ogni collegamento, indicandone il motivo: Traefik Hub giudica un tale tentativo solo tramite un servizio che chiama — i suoi middleware LLM Guard e Parallel LLM Guard, che chiamano un servizio di guardia o un modello con una richiesta e con condizioni che la realizzazione dovrebbe scrivere, e il cui funzionamento con un rilevatore di attacchi ai prompt non è misurato, quindi nessuna sensibilità corrisponde a un controllo lì; oppure i suoi middleware Azure Prompt Shield, Amazon Bedrock Guardrails e GCP Model Armor, che chiamano servizi ospitati che la realizzazione non collega. La guardia legge solo l’ultimo messaggio utente, quindi un messaggio di sistema, un turno precedente o il risultato di uno strumento raggiunge il modello senza essere letto, e viene controllato solo il traffico che attraversa il gateway: un workload che chiama direttamente l’indirizzo del modello lo aggira.

  • Validazione delle risposte e valutazioni: core/response-validation dichiara un controllo della risposta di un modello rispetto a uno JSON Schema prima che raggiunga il chiamante: schema contiene lo schema stesso, e una risposta che non vi corrisponde viene rifiutata anziché inoltrata — oppure, con invert attivo, una risposta che vi corrisponde. Lo schema appartiene al collegamento, è lo stesso per ogni richiesta e non è uno che il chiamante invia con la propria richiesta, quindi lo sviluppatore lo collega nell’Aggregate, scrivendo lo schema nei suoi values. Nessuna realizzazione della libreria standard lo applica: su core/gateway/agentgateway la sua realizzazione interrompe ogni collegamento, indicandone il motivo — le guardie sulle risposte di agentgateway confrontano pattern o chiamano un servizio di content safety o un webhook, e nessuna di esse accetta uno schema — e lo stesso fa la sua realizzazione su core/gateway/higress, il cui controllo delle risposte, a una risposta che lo supera, risponde con il JSON nudo che trova nel messaggio della risposta anziché con la chat completion restituita dalla sua route OpenAI, viene saltato da qualsiasi client che invii l’header di richiesta X-HIGRESS-AI-JSON-RESP: true e lascia senza controllo uno schema annidato per più di sei livelli; e lo stesso fa la sua realizzazione su core/gateway/traefik-hub, poiché nessun middleware nel riferimento di Traefik Hub controlla una risposta rispetto a uno schema — il suo middleware Chat Completion controlla le richieste rispetto allo schema delle chat completion, la sua gestione delle API controlla i corpi delle richieste rispetto a un documento OpenAPI, e il suo LLM Guard invia una risposta a un servizio esterno, che la realizzazione non collega; su qualsiasi altro gateway un collegamento interrompe la build indicandone il tipo. core/traffic-shadowing copia le richieste reali verso un secondo servizio e scarta le risposte di quel servizio, così che un modello o un servizio candidato possa essere valutato con traffico reale senza che alcun chiamante ne veda l’output. Si collega a qualsiasi componente che dichiari dataplane.aggrega.ai/request-mirroring, cosa che il gateway AI non fa; la libreria standard la realizza sul gateway NGINX, che copia l’intero flusso anziché una sua quota, e si interrompe, indicandola per nome, su una quota inferiore.

5. Esecuzione asincrona e infrastruttura HITL

Aggrega tratta i framework con interazione umana (come AutoGen e LangGraph) come nodi worker. Per supportare agenti «dormienti» in attesa di input umano senza perdere lo stato, gli architetti di piattaforma possono dichiarare socket usesSchema sui Components di questi agenti che impongono rigorosamente il binding esplicito di componenti di categoria datastore a essi, selezionati tramite l’etichetta del motore del datastore — datastore.aggrega.ai/engine in (vector, semantic-memory, search) per un archivio da cui l’agente recupera per similarità, oppure datastore.aggrega.ai/engine=kv per uno in cui salva i checkpoint del proprio stato di esecuzione. Il socket si lega all’etichetta del motore anziché al nome di un prodotto, quindi un autore sceglie quale archivio arriva e la dichiarazione resta valida. Inoltre, per i cicli di feedback dall’uomo all’agente (ad es. integrazioni con Slack), è possibile configurare un ruolo di verdetto di governance che rifiuti l’architettura a meno che non sia collegato un componente gateway dichiarato esplicitamente, così che i webhook di callback entrino attraverso un confine di ingresso dichiarato.

Gli agenti costruiti su un framework o un SDK attorno a cui è scritta un’applicazione, anziché distribuiti come prodotto a sé stante, assumono un’unica forma nella libreria standard. La Release indica l’immagine dell’applicazione, che il catalogo non fissa. Un socket model porta ciò che il framework legge del modello collegato — il suo indirizzo e il nome del modello, dove il framework li legge, e la credenziale della connessione, per riferimento — nelle variabili che quel framework legge. Dove il framework non definisce un proprio server, il componente è un worker e non apre alcuna porta: core/ai-agent/crewai e core/ai-agent/langgraph hanno questa forma, e così anche core/ai-agent/openai-agents-sdk, il cui socket model accetta solo un modello o un gateway che porti model.aggrega.ai/api: openai, core/ai-agent/claude-agent-sdk, il cui socket accetta solo uno che porti model.aggrega.ai/api: anthropic, e core/ai-agent/agent-framework, per un’applicazione costruita su Microsoft Agent Framework, che di per sé non serve nulla, il cui socket accetta solo uno che porti model.aggrega.ai/api: openai e fornisce le variabili lette dai client OpenAI Python di Agent Framework; questi tre interrompono la build, indicando infra.image, finché la Release non lo imposta. L’OpenAI Agents SDK carica per impostazione predefinita su OpenAI una traccia di ogni esecuzione, quindi core/ai-agent/openai-agents-sdk disattiva quel caricamento a meno che l’Aggregate non imposti il suo valore upload_traces_to_openai a true. Dove il framework serve HTTP da sé, il componente è un server sulla porta propria del framework e pubblica l’indirizzo che un chiamante raggiunge come host, port, endpoint e protocol, e anch’esso interrompe la build, indicando infra.image, finché la Release non lo imposta: core/ai-agent/google-adk serve la REST API di ADK sulla porta 8000 e fornisce la chiave che il client Gemini di ADK invia alla Gemini API, con il suo socket model che accetta solo un modello che porti model.aggrega.ai/api: gemini, come core/ai-model/gemini, e mai un gateway, il cui indirizzo il client di ADK non leggerebbe; core/ai-agent/mastra serve il server che Mastra costruisce sulla porta 4111, pronto su Kubernetes quando la sua route /health risponde, accetta un modello o un gateway che porti model.aggrega.ai/api: openai e, dove l’Aggregate indica uno degli agenti dell’applicazione nel suo valore agent_id, pubblica l’indirizzo della scheda Agent2Agent di quell’agente, così che core/ai-tool/agent-invocation possa delegargli. Le route di entrambi i server rispondono a qualsiasi chiamante a meno che l’applicazione non le autentichi, quindi un collegamento core/public-ingress o core/http-route su uno dei due interrompe la build finché la Release non imposta il suo infra.routes_authenticated a true, affermando che l’applicazione autentica ogni richiesta ricevuta dalle sue route. I runtime SDK e server e core/ai-agent/agent-framework dichiarano anche un socket tools facoltativo, che fornisce l’indirizzo di ogni strumento collegato, e la credenziale della connessione per riferimento, in variabili denominate in base all’alias della connessione. Poiché l’applicazione è il codice proprio della Release, le variabili che questi agenti forniscono perché quel codice le legga sono valori predefiniti: ogni loro socket ammette un blocco inject:, tramite il quale l’Aggregate indica le variabili, o i file, che l’applicazione legge al loro posto, mentre una variabile che il framework legge da sé e ciò che fornisce un collegamento sulla connessione restano. Lo stesso vale per i valori propri dell’agente: ogni componente ammette su sé stesso un blocco inject: di voci env e file, e una voce il cui template legge uno dei suoi valori propri e nient’altro del componente — nessun altro valore, né il suo infra, i suoi metadati o la sua identità — sostituisce il nome predefinito con cui una Recipe fornisce quel valore, come CREWAI_ROLE per il role di un agente CrewAI. L’importazione delle dichiarazioni degli agenti di un progetto CrewAI, del langgraph.json di un’applicazione LangGraph, delle configurazioni degli agenti di un’applicazione Google ADK o di un agente dichiarativo di Agent Framework genera una bozza di questi agenti — core/ai-agent/crewai, core/ai-agent/langgraph, core/ai-agent/google-adk e core/ai-agent/agent-framework — collegati al datastore che la configurazione indica, e al modello che indica dove il socket model dell’agente lo accetta, accanto a una bozza di Release che lascia all’operatore il compito di indicare l’immagine in cui gira il programma, e legge solo la configurazione, mai il programma, come descrive Plugins di importazione.

6. Validazione topologica della sicurezza e applicazione a runtime

Poiché i workload AI introducono nuovi vettori di attacco (come la prompt injection e l’esfiltrazione autonoma di dati), proteggerli richiede di collegare la governance architetturale statica all’applicazione attiva a runtime. In quanto compilatore ahead-of-time (AOT), Aggrega non intercetta il traffico di rete reale né valuta i prompt AI. Risolve invece requisiti di sicurezza complessi tramite un handshake architetturale in due parti: compilazione statica dell’architettura (in fase di compilazione) e passaggio all’esecuzione (in fase di deploy).

A. Fase di compilazione: validazione delle policy e generazione degli artefatti

Il compilatore costruisce un grafo piatto di rappresentazione intermedia (IR) contenente tutti i nodi, gli archi e le Features collegate. Prima che venga generata qualsiasi infrastruttura fisica, la postura di sicurezza dell’azienda viene applicata valutando questo grafo JSON statico rispetto a motori di policy standard del settore in un ruolo di verdetto di governance.

Poiché il socket valuta dati JSON generici, non è vincolato a un unico linguaggio di policy. Le aziende possono compilare e applicare le proprie regole architetturali usando lo standard più adatto al proprio ecosistema:

  • Open Policy Agent (OPA/Rego): un linguaggio ampiamente usato per valutare relazioni complesse e a più salti nel grafo e calcolare l’accesso con privilegi minimi in topologie distribuite. Il motore Rego compilato nella CLI esegue i file .rego così come sono; una policy che richiede l’intera superficie di builtin di OPA viene compilata con la toolchain propria di OPA e gira dietro un guest adattatore.
  • Common Expression Language (CEL): il motore CEL compilato nella CLI esegue regole scritte come singole espressioni su un documento, nel modo in cui si scrive una validating admission policy di Kubernetes.
  • Kyverno: valuta manifest JSON/YAML statici, consentendo ai team di scrivere policy in YAML nativo anziché imparare Rego. Nessun guest Kyverno è distribuito con il compilatore, che esegue le policy solo come guest WebAssembly e non invoca mai la CLI di Kyverno, quindi le regole Kyverno girano dietro un guest che incapsula il motore.
  • Validazione personalizzata in Rust/TypeScript: i team di sicurezza possono scrivere policy organizzative su misura in linguaggi standard e compilarle in Wasm perché fungano da gate di validazione.

Una volta che il motore di policy ha validato il grafo, il compilatore traduce quei requisiti di sicurezza astratti in configurazione fisica. Quando uno sviluppatore collega una Feature di sicurezza — core/data-masking sul gateway AI, per esempio — il compilatore esegue il passo di pipeline indicato dalla sua realizzazione, un plugin WebAssembly (Wasm) isolato, e quel passo scrive l’impostazione di cui il controllo ha bisogno nella configurazione che la Recipe del gateway già genera. Una realizzazione può invece lasciare la scrittura alla Recipe del gateway stesso, che legge il collegamento e scrive l’impostazione da sé, come fa core/data-masking su core/gateway/kong-enterprise, e una realizzazione per un altro tipo di controllo può emettere una propria risorsa; in entrambi i casi l’output è un artefatto statico scritto a partire da ciò che lo sviluppatore ha collegato.

B. Fase di deploy e runtime: passaggio all’esecuzione e applicazione

La responsabilità di Aggrega termina nel momento esatto in cui finisce di elaborare l’input e scrive gli artefatti statici configurati nella directory di output. È un compilatore puro: scrive la configurazione, e poi il controllo torna interamente al sistema che l’ha invocato.

Il modo in cui quelle configurazioni vengono eseguite è molto flessibile e dipende interamente dall’azienda:

  • Il passaggio degli artefatti (fase di deploy): controller di deployment esterni subentrano per rendere effettivi gli artefatti. Questo potrebbe essere un controller GitOps rigoroso (come ArgoCD o Flux) che sincronizza i file in un cluster Kubernetes, ma potrebbe altrettanto facilmente essere una normale pipeline CI/CD che esegue terraform apply, o uno sviluppatore che esegue uno script di shell locale con Docker Compose.
  • Applicazione a runtime: una volta applicate le configurazioni all’ambiente di destinazione, subentra l’infrastruttura fisica. Gli strumenti specializzati configurati da Aggrega (come un sidecar di guardrail, un service mesh attivo o firewall cloud nativi) si avviano e iniziano il loro lavoro attivo: intercettare fisicamente i payload, verificare i JWT o scartare le prompt injection malevole.

7. Come Aggrega affronta le sfide di sicurezza dell’AI

Separando la validazione architetturale dall’esecuzione a runtime, i team di piattaforma possono usare Aggrega per modellare, validare e generare in modo esplicito soluzioni di configurazione per le vulnerabilità AI descritte di seguito.

A. Esfiltrazione dei dati e intercettazione dei payload

  • Il problema: un agente autonomo potrebbe tentare di far trapelare dati aziendali riservati verso un’API esterna non autorizzata.
  • La soluzione di Aggrega:
    1. Fase di compilazione (validazione e generazione): il team di piattaforma scrive una policy (ad es. Rego) valutata in un ruolo di verdetto di governance che stabilisce: «Ogni percorso che passa attraverso un gateway AI deve portare core/data-masking.» Se manca, il compilatore si interrompe. Se è presente, la realizzazione a cui il Manifest si lega scrive il mascheramento nella configurazione che il gateway già genera: su core/gateway/litellm, voci di guardrail che corrispondono alle espressioni regolari elencate dal collegamento e che inviano il testo a un analyzer e a un anonymizer Presidio collegati ai socket pii_analyzer e pii_anonymizer del gateway per i tipi di entità che elenca; su core/gateway/kong-enterprise, l’AI PII Sanitizer di Kong sulle route di chat e di completion di ogni modello collegato, scritto dalla Recipe del chart del gateway, che invia il testo che maschera, con le espressioni regolari e i tipi di entità elencati dal collegamento, al servizio Kong AI PII collegato al socket pii_sanitizer del gateway; su core/gateway/agentgateway, le guardie a espressioni regolari del gateway stesso, scritte nella sua configurazione dalla sua Recipe del chart, che sostituiscono ogni corrispondenza dei pattern elencati dal collegamento con <masked>, oppure con refuse rispondono alla richiesta o alla risposta con HTTP 403, e non riconoscono alcun tipo di entità; quelle guardie non mascherano una risposta in streaming, quindi mentre le risposte vengono mascherate la stessa Recipe scrive una regola che rifiuta con HTTP 403, prima che venga inoltrata, una richiesta che ne chieda una, e qualsiasi richiesta il cui corpo superi i 2 MiB che il gateway legge per quella regola, in streaming o no; su core/gateway/traefik-hub, un Content Guard dell’AI gateway di Traefik Hub sulla route di ogni modello collegato, scritto dalla sua Recipe del chart, che maschera le corrispondenze dei pattern elencati dal collegamento tramite il suo motore di espressioni regolari, oppure dei tipi di entità che elenca tramite l’analyzer Presidio collegato al socket pii_analyzer del gateway, un motore per collegamento; su core/gateway/higress, il plugin ai-data-masking di Higress sulla route di ogni modello collegato, scritto dalla sua Recipe del chart, che sostituisce ogni corrispondenza dei pattern elencati dal collegamento nei messaggi di una richiesta di chat con il nome del pattern tra parentesi, e non riconosce alcun tipo di entità. Una policy può anche porre la domanda più ristretta — se il mascheramento si trovi tra i dati riservati e il provider — leggendo i collegamenti di ciascun componente lungo la route anziché i collegamenti della route nel suo insieme, come fa examples/policy-data-class-route.
    2. Runtime (applicazione fisica): Una volta che l’orchestratore ha distribuito gli artefatti generati, il gateway sostituisce ogni corrispondenza nel testo della richiesta che maschera con un segnaposto prima di inoltrarla, così il provider del modello riceve il segnaposto; con action: refuse il collegamento non inoltra nulla di una richiesta che contiene una corrispondenza e risponde invece con un errore. Un riconoscitore che non è raggiungibile o che va in errore fa fallire la richiesta, così il suo testo non viene inoltrato. Ciò che il mascheramento non raggiunge è deciso da due valori i cui default costituiscono la protezione. Sull’AI gateway, quando il collegamento maschera anche le risposte, il gateway maschera il testo della risposta e le parti che un modello o il suo provider aggiunge accanto a esso — un rifiuto, citazioni e annotazioni, la query e i risultati di una ricerca web, campi con nomi propri del provider — oppure, con refuse, non invia nulla di una risposta che contiene una corrispondenza; una risposta in streaming che maschera per pattern raggiunge il chiamante per intero, alla fine. Per impostazione predefinita, ciò che il suo mascheramento non raggiunge in una richiesta — una route come la generazione di immagini, un campo come safety_identifier, un’immagine o un file nella conversazione, uno strumento che il provider esegue da sé — l’AI gateway lo rifiuta con HTTP 400 prima di inoltrarne qualsiasi parte; un operatore che accetta che tale testo raggiunga il provider non mascherato imposta allow_unmasked_text sul collegamento nella Release, e la realizzazione elenca esattamente ciò che allora passa, mentre il contenuto che non è testo resta governato da allow_non_text_content. Per impostazione predefinita, ciò che una risposta mascherata contiene e che il suo mascheramento non può leggere — audio parlato e la sua trascrizione, un’immagine, le probabilità dei token scelti dal modello — viene trattenuto, e una chiamata fallita raggiunge il chiamante con un messaggio fisso al posto di quello restituito dal provider; allow_unmasked_reply_parts lascia che queste parti raggiungano il chiamante non mascherate. Il testo stesso di una risposta non viene mai lasciato passare da questo valore, ma le parti che lascia passare possono contenere le parole della risposta: la trascrizione di una risposta parlata, i token dietro le probabilità dei token, il messaggio di errore di un provider che cita la risposta. Su core/gateway/kong-enterprise ogni corrispondenza è sostituita da un segnaposto numerato, quindi un collegamento che elenca pattern sotto redact imposta placeholder_shows_name: false; refuse raggiunge solo le richieste, a partire da Kong 3.12, che risponde a una richiesta contenente una corrispondenza con HTTP 400; e le risposte sono mascherate a partire dalla 3.12, nel qual caso una richiesta che chiede una risposta in streaming viene rifiutata prima di essere inoltrata, e allow_streamed_replies viene rifiutato. Il sanitizer di Kong legge il testo dei turni dell’utente, il prompt di una completion e il testo del messaggio di una risposta, e il riferimento di Kong non indica alcuna impostazione che rifiuti una richiesta per ciò che il sanitizer non legge o che trattenga il resto di una risposta, quindi su quel gateway ogni protezione viene rifiutata per nome in fase di build finché mantiene il suo default, e un collegamento compila una volta che la Release le allenta — allow_unmasked_text e allow_non_text_content dove sono mascherate le richieste, allow_unmasked_reply_parts e mask_reasoning: false dove lo sono le risposte — con data-masking-kong-enterprise che elenca ciò che ciascuna lascia allora passare. Lì una risposta il cui testo non arriva come la singola stringa restituita dall’API OpenAI passa senza essere letta, e il suo testo raggiunge il chiamante non mascherato; la salvaguardia è il controllo che la build esegue su ogni modello collegato a quel gateway, che si arresta su un modello il cui model.aggrega.ai/api non è openai. Su core/gateway/traefik-hub ogni corrispondenza è sostituita da una sequenza di * lunga quanto la corrispondenza, quindi un collegamento che elenca pattern sotto redact imposta placeholder_shows_name: false; refuse risponde HTTP 403 al posto della richiesta o della risposta; e una risposta mascherata viene trattenuta per intero e inviata alla fine, comprese quelle in streaming, quindi un collegamento che maschera tipi di entità nelle risposte imposta allow_streamed_replies. Il riferimento di Traefik non dice quali campi di una richiesta o di una risposta chat legga Content Guard, e non indica alcuna impostazione che rifiuti una richiesta, o trattenga parte di una risposta, per ciò che non legge, quindi su quel gateway ogni protezione viene rifiutata per nome in fase di build finché mantiene il suo default, e un collegamento compila una volta che la Release le allenta — allow_unmasked_text e allow_non_text_content dove sono mascherate le richieste, allow_unmasked_reply_parts e mask_reasoning: false dove lo sono le risposte — con data-masking-traefik-hub che elenca ciò che ciascuna lascia allora passare. Un collegamento che elenca sia pattern sia tipi di entità, e un secondo collegamento di mascheramento su uno stesso gateway, vengono rifiutati, poiché il riferimento di Traefik non dice se un secondo Content Guard su una route legga il testo mascherato dal primo o la richiesta così come l’ha inviata il chiamante. Su core/gateway/higress il plugin ai-data-masking di Higress sostituisce ogni corrispondenza dei pattern elencati dal collegamento, nel contenuto e nel ragionamento di ogni messaggio di una richiesta chat, con il nome del pattern tra parentesi quadre; maschera solo le richieste, quindi scope response e both vengono rifiutati, e non riconosce alcun tipo di entità. Il plugin non legge nient’altro di una richiesta, quindi finché le protezioni mantengono i loro default la Recipe del chart del gateway scrive anche il plugin di validazione delle richieste di Higress per rifiutare con HTTP 403, prima che qualcosa venga inoltrato, una richiesta che contiene ciò che il mascheramento non legge — un body non inviato come JSON o che non è una chat completion, un messaggio il cui contenuto è una lista o null, una tool call o un turno di tool, il nome di un messaggio, qualsiasi parametro tranne quelli non testuali di una chat completion e i tool, il formato di risposta e le sequenze di stop propri dello sviluppatore — e, qualunque cosa il collegamento allenti, una richiesta il cui body i plugin di Higress saltano — un body compresso, un content type che contiene octet-stream o grpc, un upgrade — e un body che contiene il carattere di sostituzione Unicode U+FFFD, che è il modo in cui quella validazione legge un byte che non è UTF-8 valido, poiché il plugin di mascheramento inoltra non mascherato un body che non è UTF-8 valido. Una richiesta il cui body supera il buffer di 32 KiB del gateway viene rifiutata con HTTP 413. La validazione legge solo un body che il suo decoder JSON accetta, quindi un client che invia deliberatamente JSON valido che il decoder rifiuta — per esempio un numero oltre ciò che un double può contenere — supera ogni rifiuto del suo body: il plugin di mascheramento maschera allora solo il contenuto semplice e il ragionamento di ogni messaggio, quindi un valore elencato in qualsiasi altro punto del body — gli argomenti di una tool call, un nome, qualsiasi altro campo — viene inoltrato non mascherato, così come il contenuto scritto con sequenze di escape JSON, e se tale body non è nemmeno UTF-8 valido, viene inoltrato tutto non mascherato. Un client che annida deliberatamente un body a più di 127 livelli di profondità, dentro un campo che la validazione ammette come tools, invia JSON valido che la validazione decodifica e ammette, ma il lettore JSON del plugin di mascheramento si ferma a quella profondità, quindi anche il contenuto scritto con sequenze di escape JSON in quel body viene inoltrato non mascherato. Il mascheramento non basta da solo: il testo che nessun pattern individua e nessun riconoscitore rileva passa invariato; sull’AI gateway, gli argomenti delle tool call e i risultati dei tool sono mascherati valore per valore, ma i nomi delle loro chiavi no; le definizioni dei tool, i formati di risposta e le sequenze di stop propri dello sviluppatore passano come inviati; il gateway e i servizi di riconoscimento vedono il testo originale; ciò che il gateway registra su una chiamata — nel proprio log, o in ciò che consegna a un’integrazione di logging — può ancora contenere quel testo; e il traffico che non attraversa il gateway non viene toccato.

B. Difendersi dall’avvelenamento MCP (fiducia e isolamento)

  • Il problema: Se un agente viene compromesso tramite uno strumento Model Context Protocol (MCP) avvelenato, può eseguire autonomamente azioni distruttive (come eliminare un database o autorizzare un trasferimento).
  • La soluzione di Aggrega:
    1. Compile-time (validazione e generazione): Lo sviluppatore collega una Feature di approvazione allo strumento sensibile nel proprio Aggregate.yaml. La libreria standard non fornisce alcuna Feature di questo tipo, quindi questa viene scritta nel catalogo dell’azienda, insieme alla FeatureRecipe che la genera. Il compilatore valida il grafo e traduce il collegamento nella configurazione per un proxy L7 o un gateway webhook.
    2. Runtime (applicazione fisica): Quando l’agente dirottato tenta di invocare lo strumento, il proxy distribuito mette in pausa la richiesta e blocca fisicamente l’esecuzione finché non riceve da un operatore umano un’approvazione firmata crittograficamente.

C. Risolvere il «Confused Deputy» (propagazione del contesto)

  • Il problema: Nelle catene multi-agente, un agente esposto al pubblico potrebbe essere dirottato e ordinare a un agente interno con privilegi elevati di recuperare dati sensibili. I firewall standard vedono solo che «l’agente A sta parlando con l’agente B» e consentono il traffico, perdendo completamente il contesto dell’utente malevolo originale.
  • La soluzione di Aggrega: Le aziende possono combinare due pattern specifici:
    1. Propagazione dell’identità del chiamante, su due hop: L’identità del chiamante originale deve sopravvivere a due hop diversi, e ciascuno è protetto in un punto diverso. Sull’hop del gateway, lo sviluppatore collega core/context-propagation, che seleziona su dataplane.aggrega.ai/caller-identity, al gateway da cui entra una richiesta. In fase di compilazione, il collegamento è realizzato nella configurazione propria di quel gateway — su Envoy Gateway, una client traffic policy che verifica il certificato di ogni client rispetto a un’autorità indicata dalla Release e inoltra i dettagli del certificato; sull’AI gateway LiteLLM, un hook sulle richieste che rimuove qualsiasi header di identità fornito da un chiamante e aggiunge l’utente e il team della chiave virtuale verificata dal gateway, e la sua organizzazione dove la chiave ne indica una, sulle richieste agli alias di modello che il collegamento elenca in destinations. In fase di esecuzione, il servizio dietro il gateway riceve chi ha chiamato anziché solo il fatto che ha chiamato il gateway. Sull’hop del workload, una richiesta che un agente fa direttamente a un altro non attraversa mai quel gateway, quindi viene controllata all’ingresso dell’agente ricevente, dove una service mesh rifiuta qualsiasi richiesta priva di un token firmato che provi l’intento dell’utente originale (ad es. una AuthorizationPolicy JWT di Istio). La libreria standard fornisce la Feature dell’hop del gateway e nessuna Feature dell’hop del workload, quindi collegare core/context-propagation protegge il traffico che passa attraverso un gateway e lascia le chiamate da agente ad agente alla configurazione della mesh che l’azienda fornisce da sé. Un agente gestito da un’altra parte, che core/ai-tool/agent-invocation raggiunge via A2A come core/ai-agent/a2a-remote, sta del tutto fuori dalla Release: quella parte controlla ogni chiamata rispetto allo schema di sicurezza dichiarato dall’Agent Card dell’agente, e lo strumento presenta la credenziale custodita sulla sua connessione, letta per riferimento da un Secret, nell’header di richiesta che l’agente pubblica. Dove la card richiede le client credentials OAuth 2.0 o OpenID Connect, la connessione custodisce invece, o in aggiunta, un client secret, con il client id che l’operatore vi scrive, e l’agente pubblica l’indirizzo del token o di discovery e gli scope che la sua card dichiara; il container dello strumento ottiene il token con essi, lo rinnova e lo presenta a ogni chiamata; il catalogo fornisce solo questi input, e nessuna build può controllare cosa ne faccia il container. Dove la card richiede il TLS reciproco, la connessione custodisce un certificato client e, dove un’autorità di cui l’immagine non si fida già firma il certificato server dell’agente, anche quell’autorità; ciascuno viene montato nel container dello strumento come file da un Secret indicato dalla connessione, e il container presenta il certificato da sé nell’handshake TLS. Così lo strumento raggiunge un agente la cui card dichiara una chiave API in un header o in un cookie, uno schema di autenticazione HTTP con valore fisso, come Bearer o Basic, con il Secret che contiene l’intero valore dell’header, OAuth 2.0 o OpenID Connect con il grant client-credentials, oppure il TLS reciproco. Non raggiunge un agente la cui card richiede una chiave nella query string, uno schema HTTP che risponde a una challenge dell’agente, come Digest, o un flusso OAuth 2.0 diverso dalle client credentials. Né presenta una credenziale a un agente gestito da un’altra parte su HTTP semplice: dove l’indirizzo di quell’agente è http, una credenziale o un client secret sulla connessione arresta la build, indicando la connessione, perché la credenziale, o il token ottenuto con il secret, gli arriverebbe non cifrata. Un agente in esecuzione all’interno della Release resta raggiungibile su http con l’una o l’altro, e la credenziale attraversa allora la rete del cluster non cifrata.
    2. Ispezione del payload tra agenti: Una richiesta che un agente invia direttamente a un altro non attraversa mai l’AI gateway, quindi viene ispezionata all’ingresso dell’agente ricevente, da un motore di guardrail in esecuzione accanto a quell’agente (ad es. NeMo Guardrails). In fase di compilazione, la FeatureRecipe che realizza una Feature collegata all’agente ricevente genera la configurazione del motore. In fase di esecuzione, il motore valuta ogni richiesta rispetto a regole scritte dall’azienda e rifiuta quella che tali regole respingono; quanto bene distingua una richiesta dirottata da una legittima dipende dal motore e dalle regole, perché Aggrega compila configurazione e non valuta mai un prompt. La libreria standard non fornisce alcuna Feature che collochi un motore del genere, quindi questo pattern viene scritto nel catalogo dell’azienda. La guardia a pattern propria di un gateway, dataplane.aggrega.ai/prompt-guard: pattern-list, è più ristretta, e core/prompt-deny-patterns la attiva — sull’AI gateway, leggendo ogni messaggio di una richiesta e ignorando maiuscole e minuscole, su core/gateway/apisix e core/gateway/kong, leggendo ogni messaggio di ogni ruolo come un unico testo, distinguendo maiuscole e minuscole e rispettando anche un elenco di pattern a cui una richiesta deve corrispondere, su core/gateway/agentgateway, leggendo separatamente ogni messaggio, argomento di tool call e risultato di tool, distinguendo maiuscole e minuscole, e su core/gateway/traefik-hub, leggendo la richiesta come una chat completion, di cui il riferimento di Traefik non elenca i campi letti, distinguendo maiuscole e minuscole: rifiuta una richiesta al modello il cui testo corrisponde letteralmente a una delle espressioni elencate dal collegamento — una parafrasi, un’altra lingua o una codifica la superano — e solo sul traffico che passa attraverso il gateway, quindi una richiesta inviata direttamente tra agenti non la incontra mai. core/prompt-injection-shield è la sua controparte basata su classificatore sullo stesso hop, che invia ogni richiesta al modello inoltrata da un gateway attraverso una guardia NeMo Guardrails collegata al socket guard di quel gateway, o attraverso il prompt shield di Azure AI Content Safety su Azure API Management, e anch’essa copre solo il traffico che attraversa il gateway.

D. Analisi topologica del rischio

  • Il problema: Le architetture AI complesse con decine di modelli, vettori e strumenti interconnessi sono troppo vaste perché un essere umano possa verificarle manualmente alla ricerca di vulnerabilità transitive (ad es. «L’agente A può parlare con lo strumento B, che parla con l’agente C, che ha accesso al database D?»).
  • La soluzione di Aggrega: Questo controllo viene eseguito in anticipo. Poiché Aggrega costruisce in memoria un grafo IR completo della topologia prevista, un ruolo di verdetto di governance può eseguire regole avanzate di ricerca dei percorsi sull’intera architettura. Se la policy rileva una catena continua e transitiva di archi che parte da un nodo pubblico e termina in un database altamente sensibile senza che nessuno dei controlli richiesti dall’azienda sia collegato in alcun punto lungo di essa, arresta immediatamente la build. L’architettura insicura viene bloccata prima che venga mai generata una sola riga di codice infrastrutturale.

8. Osservabilità e conformità

Per soddisfare requisiti normativi rigorosi (ad es. l’AI Act dell’UE), gli architetti di piattaforma possono utilizzare il sistema di feature di Aggrega per imporre l’osservabilità dell’IA come requisito strutturale dell’infrastruttura anziché affidarsi al codice applicativo:

  • Registrazione di audit: I plugin Wasm scritti dall’azienda possono configurare i sidecar del gateway per inviare in streaming, in modo asincrono, prompt e risposte grezzi e non oscurati a un bucket di archiviazione WORM (Write Once, Read Many) sicuro, aggirando i log applicativi standard.
  • Tracciamento LLM: Le feature di proxy possono configurare il data plane per estrarre e inoltrare gli header di span OpenTelemetry specifici dell’IA, garantendo che i complessi cicli di ragionamento degli agenti possano essere visualizzati in strumenti esterni.

9. Compatibilità tra Feature e sicurezza topologica

Poiché il compilatore di base è agnostico rispetto ai meccanismi dell’infrastruttura fisica, si affida interamente a dichiarazioni esplicite nel catalogo per impedire la generazione di configurazioni incompatibili.

  • conflictsWith: Un elenco, dichiarato sull’entità di catalogo di una Feature sotto interoperability, delle Features accanto alle quali non può essere associata. Il compilatore lo confronta con le Features che ciascun componente finisce per portare una volta che ogni ambito ha contribuito — le associazioni del componente stesso, quelle scritte su un sottosistema o un boundary che lo contiene, quelle sulla sua voce di componente nella Release e quelle prodotte dall’espansione guidata dalle annotazioni — e si arresta prima di renderizzare qualsiasi artefatto fisico quando un componente le porta entrambe (ossia quando un autore associa, direttamente o tramite un ambito, due Features che l’autore di una Feature ha dichiarato esplicitamente incompatibili). Basta una sola dichiarazione, e le Features sono confrontate per nome qualunque sia la loro versione. Il compilatore non attribuisce alcun significato ai nomi: l’incompatibilità è la dichiarazione dell’autore, e il controllo è un confronto di nomi. L’atomicità e la purezza della Feature restano di per sé un contratto sociale — nulla verifica che una Feature faccia una sola cosa.

10. Mappatura dinamica della topologia (risoluzione delle dipendenze)

Per costruire il grafo IR senza regole codificate rigidamente, il compilatore lo legge da tre dichiarazioni esplicite:

  • Archi uses: gli sviluppatori collegano i componenti nel blocco uses di ciascuna istanza, indicando il componente di destinazione in un socket, e ogni arco del grafo proviene da uno di essi. Una voce di values che si trovi a nominare un altro componente non traccia alcun arco: il compilatore non attribuisce alcun significato a un valore.
  • Destinazioni degli archi: ogni destinazione di uses deve indicare un componente presente nella build; una destinazione inesistente interrompe la build, indicando il socket a cui era collegata.
  • Sicurezza dei tipi tra nodi: Le stringhe di selettore di usesSchema agiscono come istruzioni esplicite fuori banda, valutate nativamente dal motore di corrispondenza delle etichette del compilatore Go durante l’analisi statica. Garantiscono che gli sviluppatori non possano collegare per errore componenti standard a un socket dichiarato che richiede una specifica capacità nativa per l’IA o un’etichetta di conformità. La garanzia è limitata per costruzione ai socket dichiarati: un selettore risiede in una voce di usesSchema, quindi un socket ad hoc non ne ha nessuno da valutare. Ogni arco registra se il suo socket è stato dichiarato nel catalogo, così un operatore che ha bisogno di una garanzia totale può richiederla come verdetto di governance.

11. Progettazione automatizzata di sistemi agentici (ADAS)

I sistemi di IA avanzati prevedono Meta-Agent che scrivono codice per inventare e distribuire nuovi agenti al volo. Poiché Aggrega richiede un’architettura statica ahead-of-time (AOT), risolve l’evoluzione dell’infrastruttura a runtime tramite due confini espliciti:

  • Il confine della sandbox pre-allocata: Per gli strumenti effimeri inventati a runtime, l’architetto definisce una feature (ad es. dynamic-execution-environment). Quando è associata, il plugin di rendering Wasm genera la configurazione per allocare un pool di calcolo isolato (come un runtime WebAssembly). Il Meta-Agent inietta nuovo codice in questa sandbox, ma il suo raggio d’azione resta limitato dalle policy di rete statiche generate.
  • Il Meta-Agent nel ruolo di «sviluppatore» (il ciclo GitOps): Se il Meta-Agent ha bisogno di nuova infrastruttura fisica vera e propria, agisce come uno sviluppatore. Scrive un nuovo Aggregate.yaml e ne esegue il commit su Git. Questo avvia la pipeline CI/CD standard. Un ruolo di verdetto di governance analizza staticamente la topologia richiesta dall’IA, arrestando in modo sicuro la build se l’IA ha allucinato una vulnerabilità.

12. Serializzazione dei modelli e sicurezza della supply chain

Distribuire un modello open source spesso significa scaricare file .pkl o .gguf opachi che possono contenere payload di codice dannoso. Le aziende possono trattare la sicurezza della supply chain dei modelli come un problema di configurazione della piattaforma di destinazione. Definendo una feature model_provenance nel catalogo, il plugin di rendering Wasm di un’azienda può valutare la configurazione e tradurla in artefatti di runtime (come le policy Kyverno di Kubernetes), così che il cluster di destinazione sia configurato per impedire all’orchestratore di scaricare pesi di modello non firmati o non verificati.