Un agente, un router e due modelli a monte
Un’applicazione agente che raggiunge due modelli di provider a monte attraverso un unico router interno al cluster, compilata in manifest Kubernetes.
L’agente chiede un modello con un unico nome. Dietro quel nome c’è un router che contiene una mappa di alias, e dietro la mappa ci sono due provider. L’agente non sa mai quale provider abbia risposto, non detiene mai una credenziale di un provider e non cambia quando la mappa viene ripuntata — ed è proprio questa la ragione per mettere lì un router.
Questo workspace non scrive alcuna entità di catalogo propria. Ogni Component, Feature e Recipe che nomina è distribuito nel catalogo della libreria standard; i tre file di entità qui presenti — un Aggregate, un Manifest e una Release — sono tutto ciò che chiunque scrive.
Che cosa costruisce
agent ───────────────────┐ ┌────► openai/gpt-4o │ │ │ ▼ ├────► router ──────┤ checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4 (run state) │ │ an Ingress at ───────────┘ assistant.example.internalIl router ha due vie d’ingresso per le richieste — l’agente lo raggiunge tramite il suo arco model, e qualunque cosa all’esterno lo raggiunge attraverso l’Ingress — e una via d’uscita per ogni voce della mappa. Una terza porta serve le sue metriche a uno scraper all’interno del cluster.
Tre componenti, e ciascuno svolge un compito diverso:
| istanza | Component del catalogo | che cosa è qui |
|---|---|---|
router | core/gateway/litellm | il componente di instradamento: un endpoint, una mappa di alias, due provider a monte. Pubblica il proprio indirizzo e l’alias che l’agente richiede |
agent | core/ai-agent/langgraph | l’applicazione, che esegue la propria immagine del grafo |
checkpointer | core/datastore/valkey | dove l’agente conserva lo stato delle esecuzioni, selezionato in base alla categoria datastore |
Due archi uses, entrambi verso socket che il Component dell’agente dichiara: model (obbligatorio, che ammette un componente modello o un gateway che serve un’API di modello — il router è il secondo caso) e checkpointer_db (obbligatorio, che seleziona in base alla categoria datastore). Sei associazioni di Feature su quattro tipi di Feature — cinque sul router, una sulla connessione model dell’agente — ciascuna delle quali mette qualcosa nell’output renderizzato; la sezione più sotto mostra ciò che ciascuna produce.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example ai-agent-and-model-routerPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd ai-agent-and-model-routerBuild
aggrega build --release release.yaml --auto-pullUna release ha bisogno di un lockfile prima di eseguire il build, e i lockfile sono generati anziché distribuiti, quindi un clone appena creato non ne ha nessuno. aggrega build è di sola lettura per impostazione predefinita: senza lockfile si arresta e nomina le due strade possibili. Risolvine prima uno, oppure lascia che sia il build a crearlo:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildQuesto workspace risolve le sue entità dal registry predefinito che .aggrega-config.yaml indica, quindi non serve alcun flag --catalog.
La realizzazione dell’associazione selection del router esegue un plugin che non è distribuito né nel compilatore né nel catalogo, il passo di configurazione del gateway pipeline-step/litellm-gateway-config, che la risoluzione recupera dal registry indicato da default_registry, hub.aggrega.ai.
Diverse sezioni più sotto ti chiedono di modificare una riga e rieseguire il build. Il lockfile fissa un digest per ogni entità risolta dalla release, inclusi l’Aggregate e il Manifest in questa directory, e registra la Release stessa tramite il digest del suo contenuto — quindi modificare uno qualsiasi di questi tre file rende il lockfile non aggiornato, e il build successivo si arresta anziché eseguire il rendering con un pin obsoleto. Il messaggio nomina ciò che è cambiato — la Release tramite il suo file, l’Aggregate o il Manifest tramite il suo nome — e stampa il digest registrato accanto a quello trovato. Un pull registra la modifica rispettando ogni altro pin:
aggrega pull --release release.yamlEseguilo e riesegui il build, oppure esegui il build con --auto-pull, che esegue prima lo stesso pull. In entrambi i casi l’arresto è lo scopo anziché un ostacolo: un build non esegue il rendering con un pin che può vedere come obsoleto.
Il build stampa, con <workspace> al posto della cartella di questo esempio:
verify: plugin pipeline-step/litellm-gateway-config:1.0.0 host functions match the published .wasm[… omitted: three warnings, one per credential attachment, that the declared-sensitive origin reaches the target with no per-key sensitivity marking, because the realization maps it through a valuesMapping]Pull complete: release.lock (entities=24, source_artifacts=0, external_inputs=0)[… omitted: a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 12 files written to <workspace>/distLe entità vengono verificate rispetto alle convenzioni del catalogo una volta durante la risoluzione del lockfile e una volta durante il build della release, e ogni avviso sollevato da questi controlli viene stampato come riga lint:; questa release non ne solleva alcuno. Per eseguire gli stessi controlli da soli, e leggere ogni avviso per intero con il file di entità da cui proviene e ciò che lo renderebbe conforme:
aggrega lint --release release.yamlche qui riporta conventions checked: 19 entities, 0 advisory finding(s).
Con un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu stesso alcuna cartella. Se la cartella del workspace non contiene ancora una cartella `ai-agent-and-model-router`, chiama una sola volta lo strumento `scaffold` con `example` impostato su `ai-agent-and-model-router` e senza `dir`: scrive l’esempio in una nuova cartella `ai-agent-and-model-router`. Poi chiama lo strumento `build` con `workspace_root` impostato su `ai-agent-and-model-router`, `release` impostato su `release.yaml`, `auto_pull` impostato su true e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `ai-agent-and-model-router/dist/`.L’albero renderizzato
dist/helm/├── agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml├── agent-deployment.yaml├── checkpointer-default-service.yaml├── checkpointer-deployment.yaml├── router--api-zukey--router-secret-router-api-key.yaml├── router--metrics--router-servicemonitor-router-scrape.yaml├── router--provider-zukey--router-secret-router-provider-key.yaml├── router--published--router-ingress-router-ingress.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlSotto router/ si trovano i file che la Recipe del router emette da sé. Entrambi provengono da bundle che la Recipe importa anziché scrivere, quindi ciascuno si trova sotto la chiave con cui è stato importato, litellm-gateway-config e request-guard.
Tutto ciò che un’associazione ha portato si trova nella stessa directory dei manifest propri del componente, con due coordinate nel nome del file: il componente a cui è stata associata e il nome dato all’associazione. router--metrics-- è l’associazione metrics su router. Che cosa provenga da dove resta leggibile dall’albero, e ogni file si trova dove lo troverà uno strumento che legge una sola directory — ed è ciò che fanno i consumatori di questa destinazione, a meno che tu non indichi loro altrimenti.
Le due coordinate sono codificate anziché scritte come le hai digitate, perché condividono una stringa con il nome proprio del file. Un carattere che un nome di file non può contenere in modo sicuro diventa -z seguito da una lettera: api_key diventa api-zukey; router_model.credential — il nome che assume l’associazione sulla connessione router_model dell’agente, cioè l’alias della connessione, un punto e lo slot — diventa router-zumodel-zdcredential; e feature.aggrega.ai/monitoring — un nome di associazione coniato dall’annotazione propria di una Feature — sarebbe feature-zdaggrega-zdai-zsmonitoring. Il nome proprio del file mantiene tutti i punti che contiene, quindi il suffisso .yaml si legge ancora come un suffisso.
Dove una pagina qui riporta ciò che un build ha prodotto, il blocco è copiato da un’esecuzione reale — vedi Leggere l’output in queste pagine per la convenzione e il contrassegno che usa per le righe omesse.
La tabella di instradamento
La ragion d’essere del router è la sua mappa, e la mappa arriva nell’output renderizzato anziché restare nel file scritto dall’autore. Ecco l’intero blocco data di dist/helm/router/litellm-gateway-config/configmap.yaml:
data: config.yaml: | model_list: - model_name: assistant litellm_params: model: openai/gpt-4o api_key: os.environ/LITELLM_PROVIDER_API_KEY - model_name: assistant litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/LITELLM_PROVIDER_API_KEY litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - prometheus router_settings: routing_strategy: latency-based-routinge il blocco data della seconda ConfigMap, dist/helm/router/request-guard/request-guard.yaml, con il testo dei file che contiene omesso:
data: request_field_filter.py: | [… omitted: the text of the router's request guard, a Python module described below] path-allowlist.conf: | [… omitted: the configuration of the router's path allowlist, described below]Cinque cose meritano di essere lette da questi blocchi.
Entrambe le voci pubblicano lo stesso alias. È questo che dà al router una scelta da fare a ogni richiesta, e i router_settings alla fine del corpo dicono come la fa: latency-based-routing, scritto lì dall’associazione selection del router anziché dalla sua Recipe, come mostra più sotto la sezione su quell’associazione. Una mappa i cui alias sono tutti distinti instrada solo per nome, e la strategia non cambia nulla al riguardo. Condividere un alias è anche il motivo per cui entrambe le voci sono scritte a mano in values.models anziché servite da componenti di modello cablati al socket models del router: un modello cablato viene servito sotto l’alias della propria connessione, che nessun’altra voce può pubblicare, quindi due modelli cablati non ne condividono mai uno. Il secondo motivo riguarda Anthropic: il router scrive la voce di un modello cablato solo tramite l’API di OpenAI, mentre il modello di Anthropic risponde alla propria API, quindi cablare core/ai-model/anthropic arresta il build, con un messaggio che dice di scrivere invece quel modello a monte nella mappa.
Le destinazioni sono stringhe che il compilatore non interpreta. openai/gpt-4o è un puntatore deterministico: il proxy in esecuzione lo risolve quando serve una richiesta. Il compilatore non contatta mai un provider in fase di build, quindi non può dirti che una destinazione esiste, che è scritta correttamente o che il tuo account può raggiungerla. Cambia openai/gpt-4o in openai/not-a-real-model e il build riesce comunque — l’errore arriva al momento della richiesta, dal provider.
In questo file non c’è alcun valore di credenziale. Ogni voce nomina invece una variabile d’ambiente, tramite l’indirezione propria del proxy. Il valore arriva nel container per tutt’altra via, mostrata più sotto.
Ogni richiesta incontra prima una guardia. La prima voce di callbacks registra il modulo request_field_filter tramite il percorso completo del suo file: la seconda ConfigMap è montata nel container del router in /etc/litellm-request-guard, una directory propria accanto a /etc/litellm, dove è montata la prima e dove il proxy legge la sua configurazione. Quella seconda ConfigMap proviene da LiteLLMGuard#/artifacts/RequestGuard, un bundle che ogni Recipe che esegue questo proxy importa, così la guardia e l’allowlist più sotto hanno un unico testo ovunque il proxy sia in esecuzione. La Recipe del router consegna questa guardia in ogni Release, perché il router detiene la credenziale del provider. Da un chiamante inoltra solo i campi della richiesta che il proxy dichiara per la route presa dalla richiesta, più quelli che la Release nomina nell’infra.admitted_request_fields del router, e risponde a qualsiasi altro campo con un errore che lo nomina, senza inoltrare nulla — così un chiamante non può puntare il router verso un indirizzo proprio tramite un elenco di modelli nel corpo della richiesta, né inviare una propria chiave del provider al posto di quella del router. Né un chiamante può impostare l’identità che il router scrive esso stesso in ogni richiesta — l’hash della chiave che ha verificato, il team e l’organizzazione di quella chiave e l’utente finale: in una richiesta responses o messages, dove il router tiene i metadata del chiamante separati dai propri, rimuove qualsiasi campo di team, organizzazione o utente finale che il chiamante vi abbia scritto e la guardia rifiuta una richiesta che vi nomina la chiave, metadata.user_api_key, e su ogni altra route il valore del router sostituisce qualsiasi valore inviato dal chiamante. Questa Release non ammette nient’altro. La seconda voce, prometheus, è la callback di metriche propria del proxy, che il valore metrics_enabled del router attiva; l’associazione metrics più sotto raccoglie ciò che essa registra.
Sono raggiungibili solo le route proprie del router. La guardia vede solo le route che le passano la richiesta, quindi l’altro file della seconda ConfigMap configura il secondo container del pod, che monta solo quella ConfigMap ed esegue l’immagine ufficiale di nginx come allowlist dei percorsi. Il router stesso è in ascolto sull’indirizzo di loopback del pod, dove nulla al di fuori del pod lo raggiunge, e l’allowlist è in ascolto sulla porta 4000, la porta a cui punta il Service più sotto. Inoltra una richiesta solo quando il suo metodo e il suo percorso corrispondono a una delle route che il router serve — le route di richiesta ai modelli che la guardia controlla, nelle grafie che il router serve qualunque sia l’alias, tra cui /v1/chat/completions e /v1/messages; l’elenco dei modelli; i controlli di salute; e, tra le sue route amministrative, la gestione delle chiavi — e risponde 403 a ogni altro percorso, senza inoltrare nulla. Così le route di conteggio dei token del proxy, le sue route pass-through verso le API proprie dei provider, le sue altre route amministrative e la sua console amministrativa non sono raggiungibili attraverso il router, e nemmeno una route di modello il cui percorso contiene il nome del modello, come i percorsi che invia il client di Azure: lì il proxy legge parole nel percorso, alias compreso, per decidere come registrare una richiesta, e il router rifiuterebbe su di essa una richiesta per l’assistant proprio di questa mappa. Nemmeno le metriche del proxy sono tra quelle route: la porta 4000 risponde 403 a /metrics. Con metrics_enabled del router a true, come lo imposta l’Aggregate, l’allowlist è in ascolto anche sulla porta 9090 e lì inoltra soltanto una GET di /metrics, al listener che il proxy mantiene per le sue metriche sull’indirizzo di loopback, rispondendo 403 a ogni altra richiesta. Quella porta non controlla alcun chiamante, e le metriche nominano le chiavi hashate, gli alias delle chiavi e le email degli utenti a cui il router attribuisce la spesa.
Che cosa pubblica il router
La Recipe del router pubblica le due chiavi che ogni componente di modello pubblica: un endpoint, l’URL di base che viene passato a una libreria client, e un model, il nome che una richiesta chiede. È questo che permette al socket model dell’agente di accettare il router al posto di un modello. Il selettore del socket è component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: ammette un componente della categoria dei modelli o di quella dei gateway che porta model.aggrega.ai/api, l’etichetta che nomina quale API di modelli risponde all’indirizzo pubblicato dal componente. Il router porta model.aggrega.ai/api: openai. Un gateway che non serve alcuna API di modelli non porta tale etichetta, e un arco dall’agente verso di esso arresta il build, nominando il socket e il selettore che la destinazione non soddisfa.
L’indirizzo è il Service che la Recipe del router stesso emette — l’intero spec di dist/helm/router-default-service.yaml:
spec: type: ClusterIP selector: app: router ports: - name: http port: 4000 targetPort: http - name: metrics port: 9090 targetPort: metricsLa Recipe compone l’endpoint che pubblica, http://router-default:4000/v1, a partire dagli stessi due dati da cui derivano il nome e la porta del Service: il nome proprio del componente e il suo infra.port. La porta a cui punta il Service, http, è quella su cui è in ascolto l’allowlist dei percorsi del router; metrics, la seconda, è presente perché le metriche del router sono attive, e trasporta solo quelle. Nulla nei tre file scrive per esteso router-default. Rinomina il componente router — la sua chiave nell’Aggregate e nella Release, e l’arco dell’agente che lo nomina — e l’indirizzo che l’agente riceve segue: rinominato gateway, l’OPENAI_BASE_URL dell’agente è http://gateway-default:4000/v1.
Il nome è l’alias che il router pubblica come proprio modello. Questa mappa pubblica un solo alias, assistant, da entrambe le sue voci, quindi il router pubblica quello e il suo values.model è omesso. Dai alla seconda voce un alias proprio — summarizer, per esempio — e il build si arresta prima che venga renderizzato qualsiasi cosa, perché il router può pubblicarne solo uno. L’arresto è E0033, un’asserzione fallita del Component del router, e il suo messaggio termina con la frase propria della regola: values.model is not set, but values.models publishes 2 aliases (assistant, summarizer), so the gateway cannot tell which one a component wired to it asks for; set values.model to one of them (values.model non è impostato, ma values.models pubblica 2 alias (assistant, summarizer), quindi il gateway non può sapere quale chieda un componente cablato a esso; imposta values.model su uno di essi). Impostare model: assistant accanto a models lo risolve, e all’agente viene di nuovo passato assistant. Un chiamante che vuole summarizer lo chiede per nome allo stesso endpoint.
Che cosa riceve l’agente
La Recipe dell’agente legge entrambi i suoi archi e i valori propri dell’agente, e li trasforma in ambiente del container. Ecco l’intero blocco env di dist/helm/agent-deployment.yaml:
env: - name: OPENAI_API_KEY valueFrom: secretKeyRef: name: agent-router-model.credential key: api-key - name: LANGGRAPH_DEFAULT_RECURSION_LIMIT value: "25" - name: OPENAI_BASE_URL value: http://router-default:4000/v1 - name: OPENAI_MODEL value: assistant - name: LANGGRAPH_CHECKPOINTER_HOST value: checkpointer-default - name: LANGGRAPH_CHECKPOINTER_PORT value: "6379" - name: LANGGRAPH_GRAPH_ENTRYPOINT value: app.graph:graphLa prima proviene dall’associazione che porta l’arco model, e il provider helm scrive una voce del genere, letta da un Secret, prima di quelle semplici. Il limite di ricorsione è il recursion_limit proprio dell’agente, sotto la variabile che LangGraph legge da sé; le due successive provengono dall’arco model, le due dopo di esse dall’arco checkpointer_db, e l’ultima è il graph_entrypoint proprio dell’agente, sotto un nome predefinito che legge il codice dell’applicazione, e che un blocco inject sul componente stesso sostituirebbe. Nota che cosa l’Aggregate non ha dovuto dire: nessuno dei due archi porta un blocco inject, perché la Recipe consumatrice consegna ogni connessione sotto nomi predefiniti, che un blocco inject sull’arco sostituirebbe. Lo sviluppatore dichiara che l’agente usa un modello; la variabile con cui arriva il suo endpoint è quella che legge la libreria client, e resta qualunque cosa detti l’arco.
Nota anche LANGGRAPH_CHECKPOINTER_PORT: "6379". La Release dichiara checkpointer: {} e non configura nulla, quindi quella porta è il valore predefinito dello schema proprio del Component della cache, materializzato e convogliato attraverso l’arco.
L’agente parla al router esattamente nel dialetto che userebbe per parlare direttamente a un provider — un URL di base, un nome di modello e una chiave. È questo che permette di inserire, spostare o ripuntare il router senza che l’applicazione cambi.
Le sei associazioni, e che cosa renderizza ciascuna
Un’associazione che non cambia nulla nell’output non insegna nulla. Ognuna di queste sei vi mette qualcosa.
api_key sul router — la chiave che richiede ai chiamanti
core/referenced-secret, che riempie uno slot dichiarato dal Component del router; la chiave che contiene è quella che LiteLLM chiama la sua master key. Renderizza un proprio Secret, e il container del router vi fa riferimento. Da dist/helm/router--api-zukey--router-secret-router-api-key.yaml:
stringData: master-key: "dev-router-admin-key-change-me"e nell’env del container del router, da dist/helm/router-deployment.yaml:
- name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-keyIl container porta un riferimento, non il valore. Il nome del Secret è pubblicato dall’associazione e letto dal consumatore, quindi nessuna delle due parti lo ricava di nuovo.
provider_key sul router — la chiave che presenta a monte
La stessa Feature in uno slot diverso, e la differenza tra i due slot è il senso stesso del router. È l’unica credenziale delle voci scritte in values.models, qui entrambe; un modello cablato al socket models del router presenta invece la chiave che porta la propria connessione, mai questa. Da dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:
stringData: provider-key: "upstream-provider-key-change-me"e nello stesso env del container:
- name: LITELLM_PROVIDER_API_KEY valueFrom: secretKeyRef: name: router-provider-key key: provider-keyQuesta associazione cambia anche la tabella di instradamento. Torna al blocco data della tabella di instradamento più sopra: ogni voce della mappa porta api_key: os.environ/LITELLM_PROVIDER_API_KEY, che nomina questa stessa variabile. Rimuovi l’associazione provider_key dall’Aggregate e rifai il build. Il build riporta undici file anziché dodici — il Secret non c’è più — e la ConfigMap della tabella di instradamento differisce esattamente per quelle due righe api_key e nient’altro; la ConfigMap della guardia è invariata. Il resto della mappa mantiene l’ordine e la formattazione dell’autore, il router continua a servire e instradare, e una richiesta instradata ora fallisce presso il provider perché non c’è alcuna credenziale da presentare.
Il nome della variabile è scritto una sola volta nella Recipe del router e letto da lì sia dalla tabella di instradamento sia dall’ambiente del container, così una tabella non può arrivare a nominare una variabile che nulla imposta.
Le due credenziali restano separate, ed è questa separazione ciò che il router offre: la chiave a monte resta dentro il router, e l’applicazione chiamante non detiene altro che la chiave del router.
credential sulla connessione model dell’agente — la chiave che presenta al router
Di nuovo core/referenced-secret, dall’altro lato della stessa conversazione. Il socket model dell’agente dichiara uno slot credential, quindi la chiave viene associata sulla connessione su cui viene presentata, sotto l’arco nell’Aggregate:
uses: model: router_model: target: router features: credential: type: core/referenced-secret values: key: api-key origin: "{{ .parameters.router_admin_key }}"Da dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml:
stringData: api-key: "dev-router-admin-key-change-me"È lo stesso valore della master-key del router più sopra, e non è scritto due volte. Entrambe le associazioni leggono un unico parametro sollevato:
origin: "{{ .parameters.router_admin_key }}"L’Aggregate dichiara il parametro e la Release lo soddisfa, così la chiave ha un’unica sede in cui è scritta e i due Secret non possono essere modificati separatamente. Cambiala una volta nella Release ed entrambi i Secret renderizzati cambiano insieme.
Ogni associazione renderizza comunque il proprio Secret, il cui nome deriva dal componente che lo consuma — e, per quello dell’agente, dalla connessione su cui è associato: agent-router-model.credential. Ciò che il parametro condiviso condivide è il valore, non la risorsa.
published sul router — un indirizzo al di fuori del cluster
core/public-ingress, che non riempie alcuno slot: è ammessa dal proprio selettore, component.aggrega.ai/type=server, che il router porta. Porta una risorsa di cui la Recipe del router non sa nulla. L’intero spec di dist/helm/router--published--router-ingress-router-ingress.yaml:
spec: rules: - host: assistant.example.internal http: paths: - path: / pathType: Prefix backend: service: name: router-default port: name: httpLo sviluppatore la associa nell’Aggregate con il path, perché quali richieste un’applicazione serve fa parte di ciò che l’applicazione è. L’operatore scrive l’host e il nome della porta sulla voce della Release per la stessa associazione: l’host è il nome che l’ambiente dà al router, quindi l’operatore lo nomina per ambiente, nella Release di ciascun ambiente. Il Service di backend non è stato fornito da nessuno dei due: service_name è lasciato non impostato, e la realizzazione dell’associazione ripiega sul Service che la Recipe del router stesso emette. Nell’output non c’è alcun campo ingressClassName, perché nulla ne ha impostato uno e la realizzazione omette ciò che non le è stato dato, lasciando che sia la classe predefinita del cluster a prendere in carico la risorsa.
metrics sul router — un target di scraping
core/prometheus-exporter, ammessa dallo stesso selettore, che porta un’altra risorsa propria. Ogni input che accetta è dimensionamento dell’operatore anziché intento dell’applicazione — quanto spesso una piattaforma esegue lo scraping, e quale porta e quale percorso legge, sono proprietà della piattaforma — quindi è l’operatore ad associarla, nella Release, sulla voce del router, con il suo tipo accanto al suo infra. L’Aggregate non la menziona:
components: router: features: metrics: type: core/prometheus-exporter infra: interval: 30s port: metrics path: /metricsL’intero spec di dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:
spec: selector: matchLabels: app.kubernetes.io/name: router endpoints: - port: metrics interval: 30s path: /metricsIl port nomina una porta del Service anziché un numero: metrics, che la Recipe del router emette perché l’Aggregate imposta il valore metrics_enabled del router, e che serve le sue metriche. È anche il nome di porta predefinito della Feature, scritto qui per esteso con le altre due manopole. La porta http verso cui instrada l’Ingress più sopra risponde 403 a /metrics, quindi uno scraping puntato lì non raccoglierebbe nulla. Se le metriche vengano servite o no è una scelta dello sviluppatore, fatta nell’Aggregate; quanto spesso e su quale porta e percorso una piattaforma ne esegue lo scraping è una scelta dell’operatore, fatta qui.
selection sul router — come sceglie tra le sue destinazioni
core/target-selection, che si associa a un gateway che porta gateway.aggrega.ai/intelligence: semantic, come fa il router. Il modo in cui il router sceglie fa parte di ciò che l’applicazione gli chiede, quindi è lo sviluppatore ad associarla nell’Aggregate, con la sua strategy come valore:
components: router: features: selection: type: core/target-selection values: strategy: latencye il Manifest la vincola alla realizzazione per questo router:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Non renderizza alcun file proprio. La sua realizzazione scrive un’impostazione nella tabella di instradamento che la Recipe del router renderizza — le ultime due righe del blocco data più sopra:
router_settings: routing_strategy: latency-based-routingCon essa, il proxy invia ogni richiesta per assistant alla voce le cui ultime dieci risposte hanno impiegato in media il minor tempo, per token di output dove una risposta riporta i propri token, e una voce non ancora provata conta come la più rapida, così ognuna viene provata prima che decidano le medie. Rimuovi l’associazione dall’Aggregate e rifai il build: il build riporta ancora dodici file, e la ConfigMap della tabella di instradamento differisce esattamente per quelle due righe. La Recipe del router non scrive alcuna strategia propria, e senza una strategia il proxy sceglie a caso tra le due voci.
Chiedi invece strategy: cost e il build si arresta, senza scrivere nulla. L’arresto è E0033, un’asserzione fallita della realizzazione, e il suo messaggio termina con la frase propria della regola: core/target-selection attachment “selection” on “router” asks for strategy cost, but core/gateway/litellm cannot choose between the entries of its model map by cost: the proxy looks each entry’s target up, exactly as written, in its own price table, which names OpenAI’s and Anthropic’s models without the provider prefix a target carries (gpt-4o, not openai/gpt-4o) and which the proxy may fetch afresh when it starts, and it prices an entry it does not find, and that carries no price of its own, at a fixed fallback, so the entries sharing an alias are priced alike and the choice falls to their order. Ask for strategy latency, or remove the attachment (l’associazione core/target-selection “selection” su “router” chiede la strategia cost, ma core/gateway/litellm non può scegliere tra le voci della sua mappa di modelli in base al costo: il proxy cerca la destinazione di ogni voce, esattamente come è scritta, nella propria tabella dei prezzi, che nomina i modelli di OpenAI e di Anthropic senza il prefisso del provider che una destinazione porta (gpt-4o, non openai/gpt-4o) e che il proxy può scaricare di nuovo all’avvio, e assegna a una voce che non trova, e che non porta alcun prezzo proprio, un prezzo di ripiego fisso, quindi le voci che condividono un alias hanno lo stesso prezzo e la scelta ricade sul loro ordine. Chiedi la strategia latency, o rimuovi l’associazione). Entrambe le destinazioni qui sono scritte in quel modo, quindi il proxy invierebbe ogni richiesta alla prima delle due mentre l’Aggregate chiedeva il costo.
Dove il compilatore non interpreta
L’indirizzo e il nome del modello dell’agente vengono letti da ciò che il router pubblica, quindi nessuna coppia di nomi nei tre file deve essere tenuta allineata a mano. Ciò che il build controlla davvero è la regola propria del router secondo cui l’alias che pubblica è uno di quelli che la sua mappa pubblica — una regola che il suo Component dichiara e che il build valuta, come qualsiasi altra asserzione portata da un’entità.
Il resto sono stringhe convogliate da un punto all’altro. Il compilatore instrada l’indirizzo e l’alias senza leggerli: non sa che uno è un hostname e l’altro un nome di modello, e non ha accesso a un cluster in esecuzione per verificare che qualcosa risponda a router-default:4000. L’etichetta model.aggrega.ai/api che ha ammesso il router è lo stesso tipo di stringa — il selettore del socket la confronta, e nulla verifica quale API risponda effettivamente lì. E ogni target nella mappa è un puntatore che il proxy in esecuzione risolve: cambia openai/gpt-4o in openai/not-a-real-model e il build riesce comunque, con l’errore che arriva al momento della richiesta.
È la stessa proprietà che fa funzionare il resto dell’esempio. Poiché il compilatore non interpreta ciò che convoglia, il router può essere ripuntato verso un provider diverso, l’agente può essere cablato a un router diverso e la realizzazione della credenziale può essere sostituita con una basata su uno store — il tutto senza che il compilatore debba capire nulla di tutto ciò, e senza che l’agente cambi.
Adattarlo
-
Ripunta un provider. Modifica un
targetnella mappa del router. Nient’altro cambia: né il modello, né l’agente, né un Secret renderizzato. -
Aggiungi un terzo provider. Aggiungi una voce alla mappa. Se pubblica l’alias esistente, la strategia inizia a scegliere tra tre. Se ne pubblica uno nuovo, la mappa pubblica due alias, e il
values.modeldel router nomina quello che viene passato all’agente; un chiamante che vuole l’altro lo chiede per nome. Un modello che il catalogo modella e la cui API è l’API di OpenAI può invece essere cablato al socketmodelsdel router, sotto un alias proprio e presentando la chiave che porta la sua connessione;values.modelnomina allora l’alias che viene passato all’agente. -
Recupera invece le credenziali da uno store. Cambia in
helm/k8s-external-secretl’unica riga del Manifest che vincolacore/referenced-secrete rifai il build. OgniSecretrenderizzato diventa unExternalSecretche nomina una voce in un secret store del cluster, che un operatore dello store riconcilia — e il riferimento renderizzato di ogni consumatore resta identico byte per byte, perché il localizzatore è pubblicato dal lato produttore anziché concordato tra i due. Nient’altro nei tre file deve cambiare perché il build riesca.Una cosa va però riscritta prima che la sostituzione abbia senso:
origincambia significato tra le due realizzazioni. La realizzazione di questo workspace lo legge come il valore da memorizzare; l’altra lo legge come la chiave da recuperare. Sostituisci la riga senza rivedere i valori diorigine ilremoteRef.keyrenderizzato è il segnaposto che stava al posto del valore, qualunque fosse — quidev-router-admin-key-change-me. A quel punto nulla nell’albero di output contiene quella stringa come materiale segreto, ma essa è ancora lì come chiave dello store che nomina una voce inesistente. -
Elimina il router. Punta invece l’arco
modeldell’agente verso un componente di modello specifico di un provider. L’agente detiene allora esso stesso una credenziale del provider, che è proprio il compromesso che il router esiste per eliminare. -
Raggiungi un router che il catalogo non modella. Punta l’arco
modeldell’agente verso un componentecore/ai-model/openai-compatiblee scrivi l’indirizzo di quel router nel suoinfra.endpointnella Release. Dietro quel componente non viene eseguito nulla all’interno del cluster, quindi spetta all’operatore scrivere l’indirizzo e tenerlo allineato con il servizio che nomina.
Per condividere una credenziale tra le connessioni di più consumatori, vedi model-api-key-sharing. Per un socket che nessuna entità del catalogo dichiara, vedi adhoc-uses-socket.