Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Ein Agent, ein Router und zwei Upstream-Modelle

Eine Agentenanwendung, die über einen einzigen Router im Cluster zwei Modelle von Upstream-Providern erreicht, kompiliert zu Kubernetes-Manifesten.

Der Agent fragt ein Modell unter einem einzigen Namen an. Hinter diesem Namen sitzt ein Router mit einer Map von Aliasen, und hinter der Map sitzen zwei Provider. Der Agent erfährt nie, welcher Provider geantwortet hat, hält nie Zugangsdaten eines Providers und ändert sich nicht, wenn die Map neu ausgerichtet wird — und genau das ist der Grund, dort überhaupt einen Router einzusetzen.

Dieser Workspace schreibt keine eigene Katalogentität. Jede Component, jedes Feature und jedes Recipe, das er nennt, wird im Katalog der Standardbibliothek ausgeliefert; die drei Entitätsdateien hier — ein Aggregate, ein Manifest und ein Release — sind alles, was irgendjemand schreibt.

Was es baut

agent ───────────────────┐ ┌────► openai/gpt-4o
│ │ │
▼ ├────► router ──────┤
checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4
(run state) │
│
an Ingress at ───────────┘
assistant.example.internal

Der Router hat zwei Wege hinein für Anfragen — der Agent erreicht ihn über seine Kante model, und alles außerhalb erreicht ihn über den Ingress — und einen Weg hinaus pro Map-Eintrag. Ein dritter Port liefert seine Metriken an einen Scraper innerhalb des Clusters.

Drei Komponenten, und jede erledigt eine andere Aufgabe:

InstanzKatalog-Componentwas es hier ist
routercore/gateway/litellmdie Routing-Komponente: ein Endpunkt, eine Map von Aliasen, zwei Upstream-Provider. Sie veröffentlicht ihre Adresse und den Alias, nach dem der Agent fragt
agentcore/ai-agent/langgraphdie Anwendung, die ihr eigenes Graph-Image ausführt
checkpointercore/datastore/valkeywo der Agent den Laufzustand hält, ausgewählt über die Datastore-Kategorie

Zwei Kanten uses, beide in Sockets, die die Component des Agenten deklariert: model (erforderlich, lässt eine Modellkomponente oder ein Gateway zu, das eine Modell-API bedient — der Router ist das Zweite) und checkpointer_db (erforderlich, wählt über die Datastore-Kategorie aus). Sechs Feature-Anbindungen über vier Feature-Arten — fünf am Router, eine an der Verbindung model des Agenten —, von denen jede etwas in die gerenderte Ausgabe bringt; der Abschnitt unten zeigt, was jede erzeugt.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

Terminal window
aggrega scaffold --example ai-agent-and-model-router

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd ai-agent-and-model-router

Build

Terminal window
aggrega build --release release.yaml --auto-pull

Ein Release braucht ein Lockfile, bevor es baut, und Lockfiles werden erzeugt statt mitgeliefert, daher hat ein frischer Klon keines. aggrega build arbeitet standardmäßig nur lesend: Ohne Lockfile bricht es ab und nennt die beiden möglichen Wege. Lösen Sie zuerst eines auf, oder lassen Sie den Build es füllen:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega build --release release.yaml --auto-pull # or resolve during the build

Dieser Workspace löst seine Entitäten aus der Standard-Registry auf, die .aggrega-config.yaml nennt, daher wird kein Flag --catalog benötigt.

Die Realisierung der Anbindung selection des Routers führt ein Plugin aus, das weder im Compiler noch im Katalog ausgeliefert wird, den Gateway-Konfigurationsschritt pipeline-step/litellm-gateway-config, den die Auflösung aus der Registry holt, die default_registry nennt, hub.aggrega.ai.

Mehrere Abschnitte unten fordern Sie auf, eine Zeile zu ändern und neu zu bauen. Das Lockfile pinnt einen Digest für jede Entität, die das Release aufgelöst hat, einschließlich des Aggregate und des Manifest in diesem Verzeichnis, und hält das Release selbst über den Digest seines Inhalts fest — wer also eine dieser drei Dateien bearbeitet, macht das Lockfile veraltet, und der nächste Build bricht ab, statt gegen einen veralteten Pin zu rendern. Die Meldung nennt, was sich geändert hat — das Release über seine Datei, das Aggregate oder das Manifest über seinen Namen — und gibt den festgehaltenen Digest neben dem gefundenen aus. Ein Pull hält die Änderung fest und berücksichtigt dabei jeden anderen Pin:

Terminal window
aggrega pull --release release.yaml

Führen Sie das aus und bauen Sie erneut, oder bauen Sie mit --auto-pull, das zuerst denselben Pull ausführt. So oder so ist der Abbruch der Zweck und kein Hindernis: Ein Build rendert nicht gegen einen Pin, von dem er sehen kann, dass er veraltet ist.

Der Build gibt aus, wobei <workspace> für den Ordner dieses Beispiels steht:

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>/dist

Die Entitäten werden einmal beim Auflösen des Lockfile und einmal beim Bauen des Release gegen die Konventionen des Katalogs geprüft, und jeder Hinweis, den diese Prüfungen erzeugen, wird als Zeile lint: ausgegeben; dieses Release erzeugt keinen. Um dieselben Prüfungen eigenständig auszuführen und jeden Hinweis vollständig zu lesen, mit der Entitätsdatei, aus der er stammt, und dem, was ihn zur Übereinstimmung bringen würde:

Terminal window
aggrega lint --release release.yaml

was hier conventions checked: 19 entities, 0 advisory finding(s) meldet.

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `ai-agent-and-model-router` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `ai-agent-and-model-router` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `ai-agent-and-model-router`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `ai-agent-and-model-router`, `release` auf `release.yaml`, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die der Build geschrieben hat; sie liegen unter `ai-agent-and-model-router/dist/`.

Der gerenderte Baum

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.yaml

Unter router/ liegen die Dateien, die das Recipe des Routers selbst ausgibt. Beide stammen aus Bundles, die das Recipe importiert, statt sie zu schreiben, sodass jede unter dem Schlüssel liegt, unter dem sie importiert wurde, litellm-gateway-config und request-guard.

Alles, was eine Anbindung mitgebracht hat, liegt im selben Verzeichnis wie die eigenen Manifeste der Komponente und trägt zwei Koordinaten im Dateinamen: die Komponente, an die sie angebunden wurde, und den Namen, den die Anbindung erhalten hat. router--metrics-- ist die Anbindung metrics an router. Was woher kam, lässt sich weiterhin am Baum ablesen, und jede Datei liegt dort, wo ein Werkzeug, das ein einziges Verzeichnis liest, sie findet — und genau das tun die Konsumenten dieses Ziels, sofern Sie ihnen nichts anderes sagen.

Die beiden Koordinaten werden kodiert, statt so geschrieben, wie Sie sie eingegeben haben, weil sie sich eine Zeichenkette mit dem eigenen Namen der Datei teilen. Ein Zeichen, das ein Dateiname nicht sicher tragen kann, wird zu -z und einem Buchstaben: api_key wird zu api-zukey; router_model.credential — der Name, den die Anbindung an der Verbindung router_model des Agenten trägt, also der Alias der Verbindung, ein Punkt und der Slot — wird zu router-zumodel-zdcredential; und feature.aggrega.ai/monitoring — ein Anbindungsname, den die eigene Annotation eines Feature prägt — wäre feature-zdaggrega-zdai-zsmonitoring. Der eigene Name der Datei behält alle Punkte, die er enthält, sodass das Suffix .yaml weiterhin als Suffix lesbar ist.

Wo eine Seite hier ausgibt, was ein Build erzeugt hat, ist der Block aus einem echten Lauf kopiert — siehe Die Ausgabe auf diesen Seiten lesen für die Konvention und die Markierung, die sie für ausgelassene Zeilen verwendet.

Die Routing-Tabelle

Der Daseinszweck des Routers ist seine Map, und die Map gelangt in die gerenderte Ausgabe, statt in der verfassten Datei zu bleiben. Hier ist der gesamte Block data von 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-routing

und der Block data der zweiten ConfigMap, dist/helm/router/request-guard/request-guard.yaml, ohne den Text der Dateien, die sie enthält:

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]

Fünf Dinge lohnt es sich daraus abzulesen.

Beide Einträge veröffentlichen denselben Alias. Das gibt dem Router bei jeder Anfrage eine Wahl, und die router_settings am Ende des Inhalts sagen, wie er sie trifft: latency-based-routing, dort von der Anbindung selection des Routers geschrieben und nicht von seinem eigenen Recipe, wie der Abschnitt zu dieser Anbindung weiter unten zeigt. Eine Map, deren Aliase alle verschieden sind, routet allein nach Namen, und die Strategie ändert daran nichts. Das Teilen eines Alias ist auch der Grund, weshalb beide von Hand in values.models eingetragen sind, statt von Modellkomponenten bereitgestellt zu werden, die mit dem Socket models des Routers verdrahtet sind: Ein verdrahtetes Modell wird unter dem Alias seiner eigenen Verbindung bereitgestellt, den kein anderer Eintrag veröffentlichen darf, sodass zwei verdrahtete Modelle nie einen teilen. Der zweite Grund liegt bei Anthropic: Der Router schreibt den Eintrag eines verdrahteten Modells ausschließlich über die OpenAI-API, während das Modell von Anthropic seine eigene API beantwortet; daher bricht das Verdrahten von core/ai-model/anthropic den Build ab, mit dem Hinweis, dieses Upstream-Modell stattdessen in die Map einzutragen.

Die Ziele sind Strings, die der Compiler nicht interpretiert. openai/gpt-4o ist ein deterministischer Zeiger: Der laufende Proxy löst ihn auf, wenn er eine Anfrage bedient. Der Compiler kontaktiert zur Build-Zeit nie einen Provider, daher kann er Ihnen nicht sagen, dass ein Ziel existiert, dass es richtig geschrieben ist oder dass Ihr Konto es erreichen kann. Ändern Sie openai/gpt-4o in openai/not-a-real-model, und der Build gelingt trotzdem — der Fehler tritt zur Anfragezeit auf, beim Provider.

In dieser Datei steht kein Wert von Zugangsdaten. Jeder Eintrag nennt stattdessen eine Umgebungsvariable, über die eigene Indirektion des Proxys. Der Wert gelangt auf einem ganz anderen Weg in den Container, der weiter unten gezeigt wird.

Jede Anfrage trifft zuerst auf einen Wächter. Der erste Eintrag von callbacks registriert das Modul request_field_filter über den vollständigen Pfad seiner Datei: Die zweite ConfigMap ist im Container des Routers unter /etc/litellm-request-guard eingehängt, einem eigenen Verzeichnis neben /etc/litellm, wo die erste eingehängt ist und der Proxy seine Konfiguration liest. Diese zweite ConfigMap stammt aus LiteLLMGuard#/artifacts/RequestGuard, einem Bundle, das jedes Recipe importiert, das diesen Proxy ausführt, sodass der Wächter und die Allowlist weiter unten überall, wo der Proxy läuft, denselben Text haben. Das Recipe des Routers liefert diesen Wächter in jedem Release aus, weil der Router die Zugangsdaten des Providers hält. Er leitet von einem Aufrufer nur die Anfragefelder weiter, die der Proxy für die Route deklariert, die die Anfrage genommen hat, zuzüglich derjenigen, die das Release in infra.admitted_request_fields des Routers nennt, und beantwortet jedes andere Feld mit einem Fehler, der es nennt, ohne etwas weiterzuleiten — so kann ein Aufrufer den Router weder über eine Modellliste im Anfragekörper auf eine eigene Adresse richten noch einen eigenen Provider-Schlüssel anstelle des Schlüssels des Routers senden. Ebenso wenig kann ein Aufrufer die Identität festlegen, die der Router selbst in jede Anfrage schreibt — den Hash des Schlüssels, den er geprüft hat, Team und Organisation dieses Schlüssels sowie den Endbenutzer: Bei einer responses- oder messages-Anfrage, bei der der Router die metadata des Aufrufers von seinen eigenen getrennt hält, entfernt er jedes Team-, Organisations- oder Endbenutzerfeld, das der Aufrufer dort geschrieben hat, und der Wächter weist eine Anfrage zurück, die dort den Schlüssel nennt, metadata.user_api_key, und auf jeder anderen Route ersetzt der Wert des Routers jeden, den der Aufrufer gesendet hat. Dieses Release lässt nichts weiter zu. Der zweite Eintrag, prometheus, ist der eigene Metrik-Callback des Proxys, den der Wert metrics_enabled des Routers einschaltet; die Anbindung metrics weiter unten scrapt, was er aufzeichnet.

Erreichbar sind nur die eigenen Routen des Routers. Der Wächter sieht nur die Routen, die ihm die Anfrage übergeben, daher konfiguriert die andere Datei der zweiten ConfigMap den zweiten Container des Pods, der nur diese ConfigMap einhängt und das offizielle nginx-Image als Pfad-Allowlist ausführt. Der Router selbst lauscht auf der Loopback-Adresse des Pods, wo ihn nichts außerhalb des Pods erreicht, und die Allowlist lauscht auf Port 4000, dem Port, auf den der Service weiter unten zielt. Sie leitet eine Anfrage nur weiter, wenn ihre Methode und ihr Pfad einer der Routen entsprechen, die der Router bedient — den Modellanfrage-Routen, die der Wächter prüft, in den Schreibweisen, die der Router unabhängig vom Alias bedient, darunter /v1/chat/completions und /v1/messages; der Modellauflistung; den Health-Checks; und, von seinen Verwaltungsrouten, der Schlüsselverwaltung —, und beantwortet jeden anderen Pfad mit 403, ohne etwas weiterzuleiten. Daher sind die Token-Zähl-Routen des Proxys, seine Pass-through-Routen zu den eigenen APIs der Provider, seine übrigen Verwaltungsrouten und seine Verwaltungskonsole über den Router nicht erreichbar, und ebenso wenig eine Modellroute, deren Pfad den Modellnamen enthält, wie es die Pfade tun, die der Client von Azure sendet: Dort liest der Proxy Wörter im Pfad, einschließlich des Alias, um zu entscheiden, wie er eine Anfrage aufzeichnet, und der Router würde darauf eine Anfrage für das eigene assistant dieser Map zurückweisen. Auch die Metriken des Proxys gehören nicht zu diesen Routen: Port 4000 beantwortet /metrics mit 403. Ist metrics_enabled des Routers true, wie das Aggregate es setzt, lauscht die Allowlist zusätzlich auf Port 9090 und leitet dort allein ein GET von /metrics weiter, an den Listener, den der Proxy für seine Metriken auf der Loopback-Adresse vorhält, und beantwortet jede andere Anfrage mit 403. Dieser Port prüft keinen Aufrufer, und die Metriken nennen die gehashten Schlüssel, Schlüssel-Aliase und Benutzer-E-Mails, denen der Router Ausgaben zuordnet.

Was der Router veröffentlicht

Das Recipe des Routers veröffentlicht die beiden Schlüssel, die jede Modellkomponente veröffentlicht: einen endpoint, die Basis-URL, die einer Client-Bibliothek übergeben wird, und ein model, den Namen, den eine Anfrage anfordert. Dadurch kann der Socket model des Agenten den Router anstelle eines Modells aufnehmen. Der Selektor des Sockets ist component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: Er lässt eine Komponente der Kategorie Modell oder Gateway zu, die model.aggrega.ai/api trägt, das Label, das nennt, welche Modell-API an der Adresse antwortet, die die Komponente veröffentlicht. Der Router trägt model.aggrega.ai/api: openai. Ein Gateway, das keine Modell-API bedient, trägt kein solches Label, und eine Kante vom Agenten zu einem solchen Gateway bricht den Build ab und nennt dabei den Socket und den Selektor, den das Ziel nicht erfüllt.

Die Adresse ist der Service, den das eigene Recipe des Routers ausgibt — die gesamte spec von dist/helm/router-default-service.yaml:

spec:
type: ClusterIP
selector:
app: router
ports:
- name: http
port: 4000
targetPort: http
- name: metrics
port: 9090
targetPort: metrics

Das Recipe setzt den Endpunkt, den es veröffentlicht, http://router-default:4000/v1, aus denselben zwei Fakten zusammen, aus denen Name und Port des Service gebildet werden: dem eigenen Namen der Komponente und ihrem infra.port. Der Port, auf den der Service zielt, http, ist derjenige, auf dem die Pfad-Allowlist des Routers lauscht; metrics, der zweite, ist vorhanden, weil die Metriken des Routers eingeschaltet sind, und überträgt nur diese. Nichts in den drei Dateien schreibt router-default aus. Benennen Sie die Komponente router um — ihren Schlüssel im Aggregate und im Release sowie die Kante des Agenten, die sie nennt —, und die Adresse, die der Agent erhält, folgt: In gateway umbenannt, ist die OPENAI_BASE_URL des Agenten http://gateway-default:4000/v1.

Der Name ist der Alias, den der Router als sein Modell veröffentlicht. Diese Map veröffentlicht einen Alias, assistant, aus beiden ihren Einträgen, daher veröffentlicht der Router diesen, und sein values.model bleibt weg. Geben Sie dem zweiten Eintrag einen eigenen Alias — etwa summarizer —, und der Build bricht ab, bevor irgendetwas gerendert wird, weil der Router nur einen veröffentlichen kann. Der Abbruch ist E0033, eine fehlgeschlagene Assertion der Component des Routers, und seine Meldung endet mit dem eigenen Satz der Regel: 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 ist nicht gesetzt, aber values.models veröffentlicht 2 Aliase (assistant, summarizer), daher kann das Gateway nicht erkennen, welchen eine mit ihm verdrahtete Komponente anfordert; setzen Sie values.model auf einen davon). model: assistant neben models zu setzen, behebt das, und dem Agenten wird wieder assistant übergeben. Ein Aufrufer, der summarizer möchte, fordert es beim selben Endpunkt über den Namen an.

Was der Agent erhält

Das Recipe des Agenten liest beide seiner Kanten und die eigenen Werte des Agenten und macht daraus Umgebungsvariablen des Containers. Hier ist der gesamte Block env von 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:graph

Der erste stammt aus der Anbindung, die die Kante model trägt, und der helm-Provider schreibt einen solchen Eintrag, aus einem Secret gelesen, vor die einfachen. Das Rekursionslimit ist das eigene recursion_limit des Agenten, unter der Variable, die LangGraph von sich aus liest; die nächsten beiden stammen von der Kante model, die zwei danach von der Kante checkpointer_db, und der letzte ist der eigene graph_entrypoint des Agenten, unter einem Standardnamen, den der Code der Anwendung liest und den ein Block inject an der Komponente selbst ersetzen würde. Beachten Sie, was das Aggregate nicht sagen musste: Keine der beiden Kanten trägt einen Block inject, weil das konsumierende Recipe jede Verbindung unter Standardnamen zustellt, die ein Block inject an der Kante ersetzen würde. Der Entwickler deklariert, dass der Agent ein Modell verwendet; die Variable, unter der sein Endpunkt ankommt, ist diejenige, die die Client-Bibliothek liest, und sie bleibt, was auch immer die Kante vorgibt.

Beachten Sie auch LANGGRAPH_CHECKPOINTER_PORT: "6379". Das Release deklariert checkpointer: {} und konfiguriert nichts, daher ist dieser Port der eigene Schema-Standardwert der Cache-Component, materialisiert und über die Kante geleitet.

Der Agent spricht mit dem Router genau in dem Dialekt, den er verwenden würde, um direkt mit einem Provider zu sprechen — eine Basis-URL, ein Modellname und ein Schlüssel. Dadurch kann der Router eingefügt, verschoben oder neu ausgerichtet werden, ohne dass sich die Anwendung ändert.

Die sechs Anbindungen und was jede davon rendert

Eine Anbindung, die nichts an der Ausgabe ändert, lehrt nichts. Jede dieser sechs legt dort etwas ab.

api_key am Router — der Schlüssel, den er von Aufrufern verlangt

core/referenced-secret, das einen Slot füllt, den die Component des Routers deklariert; der Schlüssel, den es hält, ist derjenige, den LiteLLM seinen Master-Key nennt. Es rendert sein eigenes Secret, und der Container des Routers verweist darauf. Aus dist/helm/router--api-zukey--router-secret-router-api-key.yaml:

stringData:
master-key: "dev-router-admin-key-change-me"

und in der env des Containers des Routers, aus dist/helm/router-deployment.yaml:

- name: LITELLM_MASTER_KEY
valueFrom:
secretKeyRef:
name: router-api-key
key: master-key

Der Container trägt eine Referenz, nicht den Wert. Der Name des Secret wird von der Anbindung veröffentlicht und vom Konsumenten gelesen, sodass keine der beiden Seiten ihn neu ableitet.

provider_key am Router — der Schlüssel, den er upstream vorlegt

Dasselbe Feature in einem anderen Slot, und der Unterschied zwischen den beiden Slots ist der Sinn des Routers. Es sind die einzigen Zugangsdaten der in values.models eingetragenen Einträge, hier beider; ein mit dem Socket models des Routers verdrahtetes Modell legt stattdessen den Schlüssel vor, den seine eigene Verbindung trägt, nie diesen. Aus dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:

stringData:
provider-key: "upstream-provider-key-change-me"

und in derselben env des Containers:

- name: LITELLM_PROVIDER_API_KEY
valueFrom:
secretKeyRef:
name: router-provider-key
key: provider-key

Diese Anbindung ändert auch die Routing-Tabelle. Sehen Sie sich noch einmal den Block data der Routing-Tabelle oben an: Jeder Map-Eintrag trägt api_key: os.environ/LITELLM_PROVIDER_API_KEY und nennt damit genau diese Variable. Entfernen Sie die Anbindung provider_key aus dem Aggregate und bauen Sie neu. Der Build meldet elf Dateien statt zwölf — das Secret ist weg —, und die ConfigMap der Routing-Tabelle unterscheidet sich um genau diese beiden Zeilen api_key und um nichts sonst; die ConfigMap des Wächters ist unverändert. Der Rest der Map behält seine verfasste Reihenfolge und Formatierung, der Router bedient und routet weiterhin, und eine geroutete Anfrage scheitert nun beim Provider, weil keine Zugangsdaten vorzulegen sind.

Der Variablenname ist einmal im Recipe des Routers verfasst und wird von dort sowohl von der Routing-Tabelle als auch von der Umgebung des Containers gelesen, sodass eine Tabelle nicht dazu kommen kann, eine Variable zu nennen, die nichts setzt.

Die beiden Zugangsdaten bleiben getrennt, und diese Trennung ist es, was der Router einbringt: Der Upstream-Schlüssel bleibt im Router, und die aufrufende Anwendung hält nichts außer dem Schlüssel zum Router.

credential an der Verbindung model des Agenten — der Schlüssel, den er dem Router vorlegt

Wieder core/referenced-secret, auf der anderen Seite desselben Gesprächs. Der Socket model des Agenten deklariert einen Slot credential, daher wird der Schlüssel an der Verbindung angebunden, an der er vorgelegt wird, unter der Kante im Aggregate:

uses:
model:
router_model:
target: router
features:
credential:
type: core/referenced-secret
values:
key: api-key
origin: "{{ .parameters.router_admin_key }}"

Aus dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml:

stringData:
api-key: "dev-router-admin-key-change-me"

Das ist derselbe Wert wie der master-key des Routers oben, und er wird nicht zweimal geschrieben. Beide Anbindungen lesen einen hochgezogenen Parameter:

origin: "{{ .parameters.router_admin_key }}"

Das Aggregate deklariert den Parameter und das Release erfüllt ihn, sodass der Schlüssel einen einzigen verfassten Ort hat und die beiden Secrets nicht getrennt bearbeitet werden können. Ändern Sie ihn einmal im Release, und beide gerenderten Secrets ändern sich gemeinsam.

Jede Anbindung rendert trotzdem ihr eigenes Secret, benannt nach der Komponente, die es konsumiert — und, beim Secret des Agenten, nach der Verbindung, an der es angebunden ist: agent-router-model.credential. Was der gemeinsame Parameter teilt, ist der Wert, nicht die Ressource.

published am Router — eine Adresse außerhalb des Clusters

core/public-ingress, das keinen Slot füllt: Es wird durch seinen eigenen Selektor zugelassen, component.aggrega.ai/type=server, den der Router trägt. Es bringt eine Ressource mit, von der das Recipe des Routers nichts weiß. Die gesamte spec von 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: http

Der Entwickler bindet es im Aggregate mit dem path an, weil die Frage, welche Anfragen eine Anwendung bedient, Teil dessen ist, was die Anwendung ist. Der Operator schreibt den host und den Portnamen in den Eintrag des Release für dieselbe Anbindung: Der Host ist der Name der Umgebung für den Router, daher benennt der Operator ihn pro Umgebung, im Release jeder Umgebung. Der Backend-Service wurde von keinem der beiden geliefert: service_name bleibt ungesetzt, und die Realisierung der Anbindung greift auf den Service zurück, den das eigene Recipe des Routers ausgibt. In der Ausgabe gibt es kein Feld ingressClassName, weil nichts eines gesetzt hat und die Realisierung weglässt, was ihr nicht übergeben wurde, sodass die Standardklasse des Clusters die Ressource übernimmt.

metrics am Router — ein Scrape-Ziel

core/prometheus-exporter, durch denselben Selektor zugelassen, bringt eine weitere eigene Ressource mit. Jede Eingabe, die es entgegennimmt, ist Dimensionierung durch den Operator statt Anwendungsabsicht — wie oft eine Plattform scrapt und welchen Port und Pfad sie liest, sind Eigenschaften der Plattform —, daher bindet der Operator es an, im Release, am Eintrag des Routers, mit seinem Typ neben seiner infra. Das Aggregate erwähnt es nicht:

components:
router:
features:
metrics:
type: core/prometheus-exporter
infra:
interval: 30s
port: metrics
path: /metrics

Die gesamte spec von dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:

spec:
selector:
matchLabels:
app.kubernetes.io/name: router
endpoints:
- port: metrics
interval: 30s
path: /metrics

Der port nennt einen Service-Port statt einer Nummer: metrics, den das Recipe des Routers ausgibt, weil das Aggregate den Wert metrics_enabled des Routers setzt, und der seine Metriken bereitstellt. Das ist auch der Standard-Portname des Feature, hier zusammen mit den beiden anderen Stellschrauben ausgeschrieben. Der Port http, zu dem das Ingress oben routet, beantwortet /metrics mit 403, daher würde ein dorthin gerichteter Scrape nichts einsammeln. Ob Metriken überhaupt bereitgestellt werden, entscheidet der Entwickler, im Aggregate; wie oft und an welchem Port und Pfad eine Plattform sie scrapt, entscheidet der Operator, hier.

selection am Router — wie er zwischen seinen Zielen wählt

core/target-selection, das an ein Gateway angebunden wird, das gateway.aggrega.ai/intelligence: semantic trägt, wie es der Router tut. Auf welche Weise der Router wählt, ist Teil dessen, was die Anwendung von ihm verlangt, daher bindet der Entwickler es im Aggregate an, mit seiner strategy als Wert:

components:
router:
features:
selection:
type: core/target-selection
values:
strategy: latency

und das Manifest bindet es an die Realisierung für diesen Router:

core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0

Es rendert keine eigene Datei. Seine Realisierung schreibt eine Einstellung in die Routing-Tabelle, die das Recipe des Routers rendert — die letzten beiden Zeilen des Blocks data oben:

router_settings:
routing_strategy: latency-based-routing

Damit sendet der Proxy jede Anfrage für assistant an den Eintrag, dessen letzte zehn Antworten im Durchschnitt am wenigsten Zeit brauchten, pro Ausgabe-Token, wo eine Antwort ihre Token meldet, und ein noch nicht ausprobierter Eintrag gilt als der schnellste, sodass jeder ausprobiert wird, bevor die Durchschnitte entscheiden. Entfernen Sie die Anbindung aus dem Aggregate und bauen Sie neu: Der Build meldet weiterhin zwölf Dateien, und die ConfigMap der Routing-Tabelle unterscheidet sich um genau diese beiden Zeilen. Das Recipe des Routers schreibt keine eigene Strategie, und ohne eine wählt der Proxy zufällig zwischen den beiden Einträgen.

Fordern Sie stattdessen strategy: cost an, und der Build bricht ab, ohne etwas zu schreiben. Der Abbruch ist E0033, eine fehlgeschlagene Assertion der Realisierung, und seine Meldung endet mit dem eigenen Satz der Regel: 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 (Die core/target-selection-Anbindung “selection” an “router” fordert die Strategie cost an, aber core/gateway/litellm kann zwischen den Einträgen seiner Modell-Map nicht nach Kosten wählen: Der Proxy schlägt das Ziel jedes Eintrags, genau wie geschrieben, in seiner eigenen Preistabelle nach, die die Modelle von OpenAI und Anthropic ohne das Provider-Präfix nennt, das ein Ziel trägt (gpt-4o, nicht openai/gpt-4o), und die der Proxy beim Start neu abrufen kann, und er bepreist einen Eintrag, den er nicht findet und der keinen eigenen Preis trägt, mit einem festen Ersatzpreis, sodass die Einträge, die sich einen Alias teilen, gleich bepreist werden und die Wahl auf ihre Reihenfolge fällt. Fordern Sie die Strategie latency an, oder entfernen Sie die Anbindung). Beide Ziele hier sind so geschrieben, daher würde der Proxy jede Anfrage an das erste von ihnen senden, während das Aggregate Kosten verlangte.

Wo der Compiler nicht interpretiert

Die Adresse und der Modellname des Agenten werden aus dem abgelesen, was der Router veröffentlicht, sodass kein Namenspaar in den drei Dateien von Hand synchron gehalten werden muss. Was der Build tatsächlich prüft, ist die eigene Regel des Routers, dass der Alias, den er veröffentlicht, einer ist, den seine Map veröffentlicht — eine Regel, die seine Component deklariert und der Build auswertet, wie jede andere Assertion, die eine Entität trägt.

Der Rest sind Strings, die von einer Stelle zur anderen geleitet werden. Der Compiler routet die Adresse und den Alias, ohne sie zu lesen: Er weiß nicht, dass das eine ein Hostname und das andere ein Modellname ist, und er hat keinen Zugriff auf einen laufenden Cluster, um zu prüfen, ob unter router-default:4000 etwas antwortet. Das Label model.aggrega.ai/api, das den Router zugelassen hat, ist dieselbe Art von String — der Selektor des Sockets gleicht es ab, und nichts prüft, welche API dort tatsächlich antwortet. Und jedes target in der Map ist ein Zeiger, den der laufende Proxy auflöst: Ändern Sie openai/gpt-4o in openai/not-a-real-model, und der Build gelingt trotzdem, wobei der Fehler erst zur Anfragezeit auftritt.

Das ist dieselbe Eigenschaft, die den Rest des Beispiels funktionieren lässt. Weil der Compiler nicht interpretiert, was er weiterleitet, kann der Router auf einen anderen Provider umgerichtet, der Agent mit einem anderen Router verdrahtet und die Realisierung der Zugangsdaten gegen eine Store-gestützte ausgetauscht werden — alles, ohne dass der Compiler irgendetwas davon verstehen muss, und ohne dass sich der Agent ändert.

Anpassen

  • Einen Provider neu ausrichten. Bearbeiten Sie ein target in der Map des Routers. Sonst ändert sich nichts: nicht das Modell, nicht der Agent, kein gerendertes Secret.

  • Einen dritten Provider hinzufügen. Fügen Sie einen Map-Eintrag hinzu. Veröffentlicht er den bestehenden Alias, wählt die Strategie fortan zwischen dreien. Veröffentlicht er einen neuen, veröffentlicht die Map zwei Aliase, und values.model des Routers nennt den, der dem Agenten übergeben wird; ein Aufrufer, der den anderen möchte, fordert ihn über den Namen an. Ein Modell, das der Katalog modelliert und dessen API die OpenAI-API ist, kann stattdessen mit dem Socket models des Routers verdrahtet werden, unter einem eigenen Alias und mit dem Schlüssel, den seine Verbindung trägt; values.model nennt dann den Alias, der dem Agenten übergeben wird.

  • Die Zugangsdaten stattdessen aus einem Store abrufen. Ändern Sie die eine Manifest-Zeile, die core/referenced-secret bindet, auf helm/k8s-external-secret, und bauen Sie neu. Jedes gerenderte Secret wird zu einem ExternalSecret, das einen Eintrag in einem Secret-Store des Clusters nennt, den ein Store-Operator abgleicht — und die gerenderte Referenz jedes Konsumenten bleibt Byte für Byte identisch, weil der Lokator von der produzierenden Seite veröffentlicht und nicht zwischen beiden vereinbart wird. Sonst muss sich in den drei Dateien nichts ändern, damit der Build gelingt.

    Eines muss allerdings neu verfasst werden, bevor der Austausch etwas bedeutet: origin ändert seine Bedeutung zwischen den beiden Realisierungen. Die Realisierung dieses Workspace liest es als den zu speichernden Wert; die andere liest es als den abzurufenden Schlüssel. Tauschen Sie die Zeile aus, ohne die Werte von origin zu überarbeiten, und der gerenderte remoteRef.key ist der Platzhalter, der an der Stelle des Werts stand — hier dev-router-admin-key-change-me. Nichts im Ausgabebaum hält diesen String dann als geheimes Material, aber er steht weiterhin dort als Store-Schlüssel, der einen nicht existierenden Eintrag nennt.

  • Den Router weglassen. Richten Sie die Kante model des Agenten stattdessen auf eine Modellkomponente pro Provider. Der Agent hält dann selbst Zugangsdaten eines Providers, und genau diesen Kompromiss soll der Router beseitigen.

  • Einen Router erreichen, den der Katalog nicht modelliert. Richten Sie die Kante model des Agenten auf eine Komponente core/ai-model/openai-compatible und schreiben Sie die Adresse dieses Routers in ihren infra.endpoint im Release. Hinter dieser Komponente läuft nichts im Cluster, daher ist es Sache des Operators, die Adresse zu schreiben und mit dem Dienst, den sie nennt, synchron zu halten.

Um dieselben Zugangsdaten über die Verbindungen mehrerer Konsumenten hinweg zu teilen, siehe model-api-key-sharing. Für einen Socket, den keine Katalogentität deklariert, siehe adhoc-uses-socket.