Un agente, un router y dos modelos upstream
Una aplicación de agente que llega a dos modelos de proveedores upstream a través de un único router dentro del clúster, compilada a manifiestos de Kubernetes.
El agente pide un modelo por un solo nombre. Detrás de ese nombre hay un router que contiene un mapa de alias, y detrás del mapa hay dos proveedores. El agente nunca sabe qué proveedor respondió, nunca guarda una credencial de un proveedor y no cambia cuando el mapa se redirige — que es precisamente la razón de poner ahí un router.
Este workspace no crea ninguna entidad de catálogo propia. Cada Component, Feature y Recipe que nombra se distribuye en el catálogo de la biblioteca estándar; los tres archivos de entidad de aquí — un Aggregate, un Manifest y una Release — son todo lo que se escribe.
Lo que construye
agent ───────────────────┐ ┌────► openai/gpt-4o │ │ │ ▼ ├────► router ──────┤ checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4 (run state) │ │ an Ingress at ───────────┘ assistant.example.internalEl router tiene dos entradas para las solicitudes — el agente llega a él por su arista model, y cualquier cosa de fuera llega a él a través del Ingress — y una salida por cada entrada del mapa. Un tercer puerto sirve sus métricas a un scraper dentro del clúster.
Tres componentes, y cada uno hace un trabajo distinto:
| instancia | Component del catálogo | qué es aquí |
|---|---|---|
router | core/gateway/litellm | el componente de enrutamiento: un endpoint, un mapa de alias, dos proveedores upstream. Publica su dirección y el alias que pide el agente |
agent | core/ai-agent/langgraph | la aplicación, que ejecuta su propia imagen de grafo |
checkpointer | core/datastore/valkey | donde el agente guarda el estado de las ejecuciones, seleccionado por la categoría datastore |
Dos aristas uses, ambas hacia sockets que declara el Component del agente: model (obligatorio, que admite un componente de modelo o un gateway que sirve una API de modelo — el router es lo segundo) y checkpointer_db (obligatorio, que selecciona por la categoría datastore). Seis vinculaciones de Feature sobre cuatro tipos de Feature — cinco en el router, una en la conexión model del agente — cada una de las cuales pone algo en la salida renderizada; la sección de abajo muestra lo que produce cada una.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example ai-agent-and-model-routerDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd ai-agent-and-model-routerCompilación
aggrega build --release release.yaml --auto-pullUna release necesita un lockfile antes de compilarse, y los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno. aggrega build es de solo lectura por defecto: sin lockfile se detiene y nombra las dos formas de continuar. Resuelve uno primero, o deja que la compilación lo rellene:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resuelve sus entidades desde el registro predeterminado que nombra .aggrega-config.yaml, así que no hace falta ningún flag --catalog.
La realización de la vinculación selection del router ejecuta un plugin que no se distribuye ni en el compilador ni en el catálogo, el paso de configuración del gateway pipeline-step/litellm-gateway-config, que la resolución obtiene del registro que nombra default_registry, hub.aggrega.ai.
Varias secciones de abajo te piden cambiar una línea y volver a compilar. El lockfile fija un digest para cada entidad que resolvió la release, incluidos el Aggregate y el Manifest de este directorio, y registra la propia Release por el digest de su contenido — así que editar cualquiera de estos tres archivos deja el lockfile desactualizado, y la siguiente compilación se detiene en lugar de renderizar contra un pin obsoleto. El mensaje nombra lo que cambió — la Release por su archivo, el Aggregate o el Manifest por su nombre — e imprime el digest que registró junto al que encontró. Un pull registra el cambio respetando todos los demás pines:
aggrega pull --release release.yamlEjecútalo y vuelve a compilar, o compila con --auto-pull, que ejecuta antes el mismo pull. En cualquier caso, la detención es el objetivo y no un obstáculo: una compilación no renderiza contra un pin que puede ver que está obsoleto.
La compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:
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>/distLas entidades se comprueban contra las convenciones del catálogo una vez mientras se resuelve el lockfile y otra mientras se compila la release, y cada aviso que generan esas comprobaciones se imprime como una línea lint:; esta release no genera ninguno. Para ejecutar las mismas comprobaciones por separado, y leer cada aviso completo con el archivo de entidad del que procede y lo que haría que cumpliera:
aggrega lint --release release.yamlque aquí informa de conventions checked: 19 entities, 0 advisory finding(s).
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta tú mismo. Si la carpeta del espacio de trabajo aún no contiene una carpeta `ai-agent-and-model-router`, llama una sola vez a la herramienta `scaffold` con `example` establecido en `ai-agent-and-model-router` y sin `dir`: escribe el ejemplo en una nueva carpeta `ai-agent-and-model-router`. Después llama a la herramienta `build` con `workspace_root` establecido en `ai-agent-and-model-router`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `ai-agent-and-model-router/dist/`.El árbol renderizado
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.yamlBajo router/ están los archivos que emite la propia Recipe del router. Ambos proceden de bundles que la Recipe importa en lugar de escribir, así que cada uno está bajo la clave con la que se importó, litellm-gateway-config y request-guard.
Todo lo que aportó una vinculación está en el mismo directorio que los manifiestos propios del componente, con dos coordenadas en su nombre de archivo: el componente al que se vinculó y el nombre que recibió la vinculación. router--metrics-- es la vinculación metrics en router. Qué vino de dónde sigue pudiéndose leer en el árbol, y cada archivo está donde lo encontrará una herramienta que lee un solo directorio — que es lo que hacen los consumidores de este destino salvo que les indiques otra cosa.
Las dos coordenadas se codifican en lugar de escribirse tal como las tecleaste, porque comparten una cadena con el nombre propio del archivo. Un carácter que un nombre de archivo no puede llevar con seguridad se convierte en -z y una letra: api_key es api-zukey; router_model.credential — el nombre que toma la vinculación en la conexión router_model del agente, es decir, el alias de la conexión, un punto y el slot — es router-zumodel-zdcredential; y feature.aggrega.ai/monitoring — un nombre de vinculación que acuña la propia anotación de una Feature — sería feature-zdaggrega-zdai-zsmonitoring. El nombre propio del archivo conserva los puntos que tenga, así que el sufijo .yaml se sigue leyendo como un sufijo.
Donde una página de aquí muestra lo que produjo una compilación, el bloque está copiado de una ejecución real — consulta Leer la salida en estas páginas para la convención y la marca que usa para las líneas omitidas.
La tabla de enrutamiento
La razón de ser del router es su mapa, y el mapa llega a la salida renderizada en lugar de quedarse en el archivo escrito por el autor. Este es el bloque data completo de 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-routingy el bloque data del segundo ConfigMap, dist/helm/router/request-guard/request-guard.yaml, sin el texto de los archivos que contiene:
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]Hay cinco cosas que vale la pena leer en ellos.
Ambas entradas publican el mismo alias. Eso es lo que da al router una elección que hacer en cada solicitud, y los router_settings al final del cuerpo dicen cómo la hace: latency-based-routing, escrito ahí por la vinculación selection del router y no por su propia Recipe, como muestra más abajo la sección sobre esa vinculación. Un mapa cuyos alias son todos distintos enruta solo por nombre, y la estrategia no cambia nada en él. Compartir un alias es también la razón por la que ambas entradas se escriben a mano en values.models en lugar de servirse desde componentes de modelo conectados al socket models del router: un modelo conectado se sirve bajo el alias de su propia conexión, que ninguna otra entrada puede publicar, así que dos modelos conectados nunca comparten uno. La segunda razón es de Anthropic: el router escribe la entrada de un modelo conectado solo a través de la API de OpenAI, mientras que el modelo de Anthropic responde a su propia API, así que conectar core/ai-model/anthropic detiene la compilación, indicando que se escriba en su lugar ese modelo upstream en el mapa.
Los destinos son cadenas que el compilador no interpreta. openai/gpt-4o es un puntero determinista: el proxy en ejecución lo resuelve cuando atiende una solicitud. El compilador nunca contacta con un proveedor en tiempo de compilación, así que no puede decirte que un destino existe, que está bien escrito o que tu cuenta puede alcanzarlo. Cambia openai/gpt-4o por openai/not-a-real-model y la compilación sigue teniendo éxito — el fallo llega en el momento de la solicitud, desde el proveedor.
En este archivo no hay ningún valor de credencial. Cada entrada nombra en su lugar una variable de entorno, mediante la indirección propia del proxy. El valor llega al contenedor por una vía completamente distinta, que se muestra más abajo.
Toda solicitud se encuentra primero con una guarda. La primera entrada de callbacks registra el módulo request_field_filter por la ruta completa de su archivo: el segundo ConfigMap está montado en el contenedor del router en /etc/litellm-request-guard, un directorio propio junto a /etc/litellm, donde está montado el primero y donde el proxy lee su configuración. Ese segundo ConfigMap procede de LiteLLMGuard#/artifacts/RequestGuard, un bundle que importa toda Recipe que ejecute este proxy, de modo que la guarda y la lista de permitidos de abajo tienen un único texto dondequiera que se ejecute el proxy. La Recipe del router entrega esta guarda en cada Release, porque el router guarda la credencial del proveedor. Reenvía de un llamador solo los campos de solicitud que el proxy declara para la ruta que tomó la solicitud, más los que la Release nombre en infra.admitted_request_fields del router, y responde a cualquier otro campo con un error que lo nombra, sin reenviar nada — así un llamador no puede apuntar el router a una dirección propia mediante una lista de modelos en el cuerpo de la solicitud, ni enviar una clave de proveedor propia en lugar de la del router. Tampoco puede un llamador establecer la identidad que el propio router escribe en cada solicitud — el hash de la clave que verificó, el equipo y la organización de esa clave y el usuario final: en una solicitud responses o messages, donde el router mantiene los metadata del llamador separados de los suyos, elimina cualquier campo de equipo, organización o usuario final que el llamador haya escrito ahí y la guarda rechaza una solicitud que nombre ahí la clave, metadata.user_api_key, y en cualquier otra ruta el valor del router sustituye cualquiera que haya enviado el llamador. Esta Release no admite nada más. La segunda entrada, prometheus, es el callback de métricas propio del proxy, que activa el valor metrics_enabled del router; la vinculación metrics de abajo recoge lo que registra.
Solo las rutas propias del router son alcanzables. La guarda ve solo las rutas que le entregan la solicitud, así que el otro archivo del segundo ConfigMap configura el segundo contenedor del pod, que monta solo ese ConfigMap y ejecuta la imagen oficial de nginx como lista de permitidos de paths. El propio router escucha en la dirección de loopback del pod, donde nada de fuera del pod lo alcanza, y la lista de permitidos escucha en el puerto 4000, el puerto al que apunta el Service de abajo. Reenvía una solicitud solo cuando su método y su path corresponden a una de las rutas que sirve el router — las rutas de solicitud de modelo que comprueba la guarda, en las grafías que sirve el router sea cual sea el alias, entre ellas /v1/chat/completions y /v1/messages; el listado de modelos; las comprobaciones de estado; y, de sus rutas administrativas, la gestión de claves — y responde 403 a cualquier otro path, sin reenviar nada. Así, las rutas de recuento de tokens del proxy, sus rutas de paso directo a las API propias de los proveedores, sus otras rutas administrativas y su consola administrativa no se pueden alcanzar a través del router, ni tampoco una ruta de modelo cuyo path lleva el nombre del modelo, como hacen los paths que envía el cliente de Azure: ahí el proxy lee palabras del path, alias incluido, para decidir cómo registra una solicitud, y el router rechazaría en ella una solicitud para el assistant propio de este mapa. Las métricas del proxy tampoco están entre esas rutas: el puerto 4000 responde 403 a /metrics. Con metrics_enabled del router a true, como lo establece el Aggregate, la lista de permitidos escucha también en el puerto 9090 y ahí reenvía únicamente un GET de /metrics, al listener que el proxy mantiene para sus métricas en la dirección de loopback, y responde 403 a cualquier otra solicitud. Ese puerto no comprueba ningún llamador, y las métricas nombran las claves con hash, los alias de claves y los correos de los usuarios a los que el router atribuye el gasto.
Qué publica el router
La Recipe del router publica las dos claves que publica todo componente de modelo: un endpoint, la URL base que se entrega a una biblioteca cliente, y un model, el nombre que pide una solicitud. Eso es lo que permite al socket model del agente aceptar el router en lugar de un modelo. El selector del socket es component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: admite un componente de la categoría de modelo o de gateway que lleve model.aggrega.ai/api, la etiqueta que nombra qué API de modelo responde en la dirección que publica el componente. El router lleva model.aggrega.ai/api: openai. Un gateway que no sirve ninguna API de modelo no lleva esa etiqueta, y una arista del agente hacia uno detiene la compilación, nombrando el socket y el selector que el destino no cumple.
La dirección es el Service que emite la propia Recipe del router — el spec completo de 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 el endpoint que publica, http://router-default:4000/v1, a partir de los mismos dos datos de los que salen el nombre y el puerto del Service: el nombre propio del componente y su infra.port. El puerto al que apunta el Service, http, es aquel en el que escucha la lista de permitidos de paths del router; metrics, el segundo, está ahí porque las métricas del router están activadas, y solo lleva esas. Nada en los tres archivos escribe router-default explícitamente. Renombra el componente router — su clave en el Aggregate y en la Release, y la arista del agente que lo nombra — y la dirección que recibe el agente lo sigue: renombrado gateway, el OPENAI_BASE_URL del agente es http://gateway-default:4000/v1.
El nombre es el alias que el router publica como su modelo. Este mapa publica un solo alias, assistant, desde sus dos entradas, así que el router publica ese y su values.model se omite. Da a la segunda entrada un alias propio — summarizer, por ejemplo — y la compilación se detiene antes de que se renderice nada, porque el router solo puede publicar uno. La detención es E0033, una aserción fallida del Component del router, y su mensaje termina con la frase propia de la regla: 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 no está establecido, pero values.models publica 2 alias (assistant, summarizer), así que el gateway no puede saber cuál pide un componente conectado a él; establece values.model en uno de ellos). Establecer model: assistant junto a models lo resuelve, y al agente se le entrega de nuevo assistant. Un llamador que quiera summarizer lo pide por su nombre al mismo endpoint.
Qué recibe el agente
La Recipe del agente lee sus dos aristas y los valores propios del agente, y los convierte en el entorno del contenedor. Este es el bloque env completo de 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 primera procede de la vinculación que lleva la arista model, y el proveedor helm escribe una entrada así, leída de un Secret, antes que las simples. El límite de recursión es el propio recursion_limit del agente, bajo la variable que LangGraph lee por sí mismo; las dos siguientes proceden de la arista model, las dos posteriores de la arista checkpointer_db, y la última es el propio graph_entrypoint del agente, bajo un nombre predeterminado que lee el código de la aplicación y que un bloque inject en el propio componente sustituiría. Observa lo que el Aggregate no tuvo que decir: ninguna de las dos aristas lleva un bloque inject, porque la Recipe consumidora entrega cada conexión bajo nombres predeterminados, que un bloque inject en la arista sustituiría. El desarrollador declara que el agente usa un modelo; la variable bajo la que llega su endpoint es la que lee la biblioteca cliente, y sigue siendo la que dicte la arista.
Observa también LANGGRAPH_CHECKPOINTER_PORT: "6379". La Release declara checkpointer: {} y no configura nada, así que ese puerto es el valor predeterminado del esquema propio del Component de caché, materializado y canalizado a través de la arista.
El agente habla con el router exactamente en el dialecto que usaría para hablar directamente con un proveedor — una URL base, un nombre de modelo y una clave. Eso es lo que permite insertar, mover o redirigir el router sin que la aplicación cambie.
Las seis vinculaciones, y lo que renderiza cada una
Una vinculación que no cambia nada en la salida no enseña nada. Cada una de estas seis pone algo ahí.
api_key en el router — la clave que exige a los llamadores
core/referenced-secret, que llena un slot que declara el Component del router; la clave que contiene es la que LiteLLM llama su clave maestra. Renderiza su propio Secret, y el contenedor del router hace referencia a él. De dist/helm/router--api-zukey--router-secret-router-api-key.yaml:
stringData: master-key: "dev-router-admin-key-change-me"y en el env del contenedor del router, de dist/helm/router-deployment.yaml:
- name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-keyEl contenedor lleva una referencia, no el valor. El nombre del Secret lo publica la vinculación y lo lee el consumidor, así que ninguna de las dos partes lo vuelve a derivar.
provider_key en el router — la clave que presenta upstream
La misma Feature en otro slot, y la diferencia entre los dos slots es la razón de ser del router. Es la única credencial de las entradas escritas en values.models, aquí ambas; un modelo conectado al socket models del router presenta en cambio la clave que lleva su propia conexión, nunca esta. De dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:
stringData: provider-key: "upstream-provider-key-change-me"y en el mismo env del contenedor:
- name: LITELLM_PROVIDER_API_KEY valueFrom: secretKeyRef: name: router-provider-key key: provider-keyEsta vinculación también cambia la tabla de enrutamiento. Vuelve al bloque data de la tabla de enrutamiento de arriba: cada entrada del mapa lleva api_key: os.environ/LITELLM_PROVIDER_API_KEY, que nombra esta misma variable. Quita la vinculación provider_key del Aggregate y vuelve a compilar. La compilación informa de once archivos en lugar de doce — el Secret ya no está — y el ConfigMap de la tabla de enrutamiento difiere exactamente en esas dos líneas api_key y en nada más; el ConfigMap de la guarda no cambia. El resto del mapa conserva su orden y su formato escritos, el router sigue sirviendo y enrutando, y una solicitud enrutada ahora falla en el proveedor porque no hay ninguna credencial que presentar.
El nombre de la variable se escribe una vez en la Recipe del router y desde ahí lo leen tanto la tabla de enrutamiento como el entorno del contenedor, así que una tabla no puede llegar a nombrar una variable que nada establece.
Las dos credenciales se mantienen separadas, y esa separación es lo que aporta el router: la clave upstream se queda dentro del router, y la aplicación que llama no guarda nada más que la clave del router.
credential en la conexión model del agente — la clave que presenta al router
core/referenced-secret de nuevo, al otro lado de la misma conversación. El socket model del agente declara un slot credential, así que la clave se vincula en la conexión en la que se presenta, bajo la arista en el Aggregate:
uses: model: router_model: target: router features: credential: type: core/referenced-secret values: key: api-key origin: "{{ .parameters.router_admin_key }}"De dist/helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml:
stringData: api-key: "dev-router-admin-key-change-me"Es el mismo valor que la master-key del router de arriba, y no se escribe dos veces. Ambas vinculaciones leen un único parámetro elevado:
origin: "{{ .parameters.router_admin_key }}"El Aggregate declara el parámetro y la Release lo cumple, así que la clave tiene un único lugar donde se escribe y los dos Secrets no pueden editarse por separado. Cámbiala una vez en la Release y ambos Secrets renderizados cambian juntos.
Cada vinculación sigue renderizando su propio Secret, nombrado a partir del componente que lo consume — y, en el caso del agente, de la conexión en la que está vinculado: agent-router-model.credential. Lo que comparte el parámetro compartido es el valor, no el recurso.
published en el router — una dirección fuera del clúster
core/public-ingress, que no llena ningún slot: la admite su propio selector, component.aggrega.ai/type=server, que lleva el router. Aporta un recurso del que la Recipe del router no sabe nada. El spec completo de 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: httpEl desarrollador la vincula en el Aggregate con el path, porque qué solicitudes sirve una aplicación es parte de lo que la aplicación es. El operador escribe el host y el nombre del puerto en la entrada de la Release para la misma vinculación: el host es el nombre que el entorno da al router, así que el operador lo nombra por entorno, en la Release de cada entorno. El Service de backend no lo proporcionó ninguno de los dos: service_name se deja sin establecer, y la realización de la vinculación recurre al Service que emite la propia Recipe del router. No hay ningún campo ingressClassName en la salida, porque nada estableció uno y la realización omite lo que no se le dio, dejando que la clase predeterminada del clúster reclame el recurso.
metrics en el router — un destino de scraping
core/prometheus-exporter, admitida por el mismo selector, que aporta otro recurso propio. Cada parámetro que acepta es dimensionamiento del operador y no intención de la aplicación — con qué frecuencia hace scraping una plataforma, y qué puerto y qué path lee, son propiedades de la plataforma — así que es el operador quien la vincula, en la Release, en la entrada del router, con su tipo junto a su infra. El Aggregate no la menciona:
components: router: features: metrics: type: core/prometheus-exporter infra: interval: 30s port: metrics path: /metricsEl spec completo de dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:
spec: selector: matchLabels: app.kubernetes.io/name: router endpoints: - port: metrics interval: 30s path: /metricsEl port nombra un puerto del Service en lugar de un número: metrics, que la Recipe del router emite porque el Aggregate establece el valor metrics_enabled del router, y que sirve sus métricas. Es también el nombre de puerto predeterminado de la Feature, escrito aquí explícitamente con los otros dos ajustes. El puerto http al que enruta el Ingress de arriba responde 403 a /metrics, así que un scraping dirigido ahí no recogería nada. Si las métricas se sirven o no es elección del desarrollador, hecha en el Aggregate; con qué frecuencia y en qué puerto y path las recoge una plataforma es elección del operador, hecha aquí.
selection en el router — cómo elige entre sus destinos
core/target-selection, que se vincula a un gateway que lleve gateway.aggrega.ai/intelligence: semantic, como hace el router. La manera en que el router elige forma parte de lo que la aplicación le pide, así que el desarrollador la vincula en el Aggregate, con su strategy como valor:
components: router: features: selection: type: core/target-selection values: strategy: latencyy el Manifest la enlaza a la realización para este router:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0No renderiza ningún archivo propio. Su realización escribe un ajuste en la tabla de enrutamiento que renderiza la Recipe del router — las dos últimas líneas del bloque data de arriba:
router_settings: routing_strategy: latency-based-routingCon ella, el proxy envía cada solicitud de assistant a la entrada cuyas diez últimas respuestas tardaron menos de media, por token de salida cuando una respuesta informa de sus tokens, y una entrada aún no probada cuenta como la más rápida, así que cada una se prueba antes de que decidan las medias. Quita la vinculación del Aggregate y vuelve a compilar: la compilación sigue informando de doce archivos, y el ConfigMap de la tabla de enrutamiento difiere exactamente en esas dos líneas. La Recipe del router no escribe ninguna estrategia propia, y sin una el proxy elige al azar entre las dos entradas.
Pide en su lugar strategy: cost y la compilación se detiene, sin escribir nada. La detención es E0033, una aserción fallida de la realización, y su mensaje termina con la frase propia de la regla: 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 (la vinculación core/target-selection “selection” en “router” pide la estrategia cost, pero core/gateway/litellm no puede elegir entre las entradas de su mapa de modelos por coste: el proxy busca el destino de cada entrada, exactamente como está escrito, en su propia tabla de precios, que nombra los modelos de OpenAI y de Anthropic sin el prefijo de proveedor que lleva un destino (gpt-4o, no openai/gpt-4o) y que el proxy puede volver a descargar al arrancar, y asigna a una entrada que no encuentra, y que no lleva precio propio, un precio de reserva fijo, así que las entradas que comparten un alias reciben el mismo precio y la elección recae en su orden. Pide la estrategia latency, o quita la vinculación). Ambos destinos aquí están escritos así, de modo que el proxy enviaría todas las solicitudes al primero de ellos mientras el Aggregate pedía el coste.
Dónde el compilador no interpreta
La dirección y el nombre de modelo del agente se leen de lo que publica el router, así que ningún par de nombres en los tres archivos tiene que mantenerse sincronizado a mano. Lo que la compilación sí comprueba es la regla propia del router de que el alias que publica es uno de los que publica su mapa — una regla que declara su Component y que evalúa la compilación, como cualquier otra aserción que lleve una entidad.
El resto son cadenas canalizadas de un lugar a otro. El compilador enruta la dirección y el alias sin leerlos: no sabe que uno es un nombre de host y el otro un nombre de modelo, y no tiene acceso a un clúster en ejecución para comprobar que algo responde en router-default:4000. La etiqueta model.aggrega.ai/api que admitió el router es el mismo tipo de cadena — el selector del socket la compara, y nada comprueba qué API responde realmente ahí. Y cada target del mapa es un puntero que resuelve el proxy en ejecución: cambia openai/gpt-4o por openai/not-a-real-model y la compilación sigue teniendo éxito, con el fallo llegando en el momento de la solicitud.
Es la misma propiedad que hace funcionar el resto del ejemplo. Como el compilador no interpreta lo que canaliza, el router puede redirigirse a otro proveedor, el agente puede conectarse a otro router y la realización de la credencial puede sustituirse por una respaldada por un almacén — todo ello sin que el compilador necesite entender nada de eso, y sin que el agente cambie.
Adaptarlo
-
Redirigir un proveedor. Edita un
targeten el mapa del router. Nada más cambia: ni el modelo, ni el agente, ni un Secret renderizado. -
Añadir un tercer proveedor. Añade una entrada al mapa. Si publica el alias existente, la estrategia empieza a elegir entre tres. Si publica uno nuevo, el mapa publica dos alias, y el
values.modeldel router nombra el que se entrega al agente; un llamador que quiera el otro lo pide por su nombre. Un modelo que el catálogo modela y cuya API es la API de OpenAI puede en cambio conectarse al socketmodelsdel router, bajo un alias propio y presentando la clave que lleva su conexión;values.modelnombra entonces el alias que se entrega al agente. -
Obtener en cambio las credenciales de un almacén. Cambia a
helm/k8s-external-secretla única línea del Manifest que vinculacore/referenced-secrety vuelve a compilar. CadaSecretrenderizado se convierte en unExternalSecretque nombra una entrada de un almacén de secretos del clúster, para que un operador del almacén lo reconcilie — y la referencia renderizada de cada consumidor sigue siendo idéntica byte a byte, porque el localizador lo publica el lado productor en lugar de acordarse entre ambos. Nada más en los tres archivos tiene que cambiar para que la compilación tenga éxito.Sin embargo, hay algo que sí hay que reescribir antes de que el cambio signifique algo:
origincambia de significado entre las dos realizaciones. La realización de este workspace lo lee como el valor que almacenar; la otra lo lee como la clave que obtener. Cambia la línea sin revisar los valores deoriginy elremoteRef.keyrenderizado es el marcador de posición que hubiera en lugar del valor — aquídev-router-admin-key-change-me. Entonces nada en el árbol de salida guarda esa cadena como material secreto, pero sigue ahí como clave del almacén que nombra una entrada que no existe. -
Prescindir del router. Apunta en cambio la arista
modeldel agente a un componente de modelo propio de un proveedor. El agente guarda entonces él mismo una credencial de proveedor, que es justo la contrapartida que el router existe para eliminar. -
Llegar a un router que el catálogo no modela. Apunta la arista
modeldel agente a un componentecore/ai-model/openai-compatibley escribe la dirección de ese router en suinfra.endpointen la Release. Nada se ejecuta detrás de ese componente dentro del clúster, así que escribir la dirección y mantenerla sincronizada con el servicio que nombra corresponde al operador.
Para compartir una credencial entre las conexiones de varios consumidores, consulta model-api-key-sharing. Para un socket que ninguna entidad del catálogo declara, consulta adhoc-uses-socket.