Um agente, um roteador e dois modelos upstream
Uma aplicação de agente que alcança dois modelos de provedores upstream por meio de um único roteador dentro do cluster, compilada para manifestos Kubernetes.
O agente pede um modelo por um único nome. Por trás desse nome há um roteador que mantém um mapa de aliases, e por trás do mapa há dois provedores. O agente nunca sabe qual provedor respondeu, nunca detém uma credencial de provedor e não muda quando o mapa é reapontado — que é justamente o motivo de colocar um roteador ali.
Este workspace não cria nenhuma entidade de catálogo própria. Cada Component, Feature e Recipe que ele nomeia é distribuído no catálogo da biblioteca padrão; os três arquivos de entidade daqui — um Aggregate, um Manifest e uma Release — são tudo o que alguém escreve.
O que ele constrói
agent ───────────────────┐ ┌────► openai/gpt-4o │ │ │ ▼ ├────► router ──────┤ checkpointer │ (the alias map) └────► anthropic/claude-sonnet-4 (run state) │ │ an Ingress at ───────────┘ assistant.example.internalO roteador tem duas entradas para requisições — o agente o alcança pela sua aresta model, e qualquer coisa de fora o alcança pelo Ingress — e uma saída por entrada do mapa. Uma terceira porta serve as suas métricas a um scraper dentro do cluster.
Três componentes, e cada um faz um trabalho diferente:
| instância | Component do catálogo | o que é aqui |
|---|---|---|
router | core/gateway/litellm | o componente de roteamento: um endpoint, um mapa de aliases, dois provedores upstream. Ele publica o seu endereço e o alias que o agente pede |
agent | core/ai-agent/langgraph | a aplicação, executando a sua própria imagem de grafo |
checkpointer | core/datastore/valkey | onde o agente mantém o estado das execuções, selecionado pela categoria datastore |
Duas arestas uses, ambas para sockets que o Component do agente declara: model (obrigatório, admitindo um componente de modelo ou um gateway que serve uma API de modelo — o roteador é o segundo caso) e checkpointer_db (obrigatório, selecionando pela categoria datastore). Seis vinculações de Feature sobre quatro tipos de Feature — cinco no roteador, uma na conexão model do agente — cada uma das quais coloca algo na saída renderizada; a seção abaixo mostra o que cada uma produz.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example ai-agent-and-model-routerEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd ai-agent-and-model-routerBuild
aggrega build --release release.yaml --auto-pullUma release precisa de um lockfile antes de fazer o build, e os lockfiles são gerados em vez de distribuídos, então um clone recém-feito não tem nenhum. aggrega build é somente leitura por padrão: sem lockfile, ele é interrompido e nomeia os dois caminhos possíveis. Resolva um primeiro, ou deixe o build preenchê-lo:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste workspace resolve as suas entidades a partir do registro padrão que .aggrega-config.yaml nomeia, então nenhuma flag --catalog é necessária.
A realização da vinculação selection do roteador executa um plugin que não é distribuído nem no compilador nem no catálogo, a etapa de configuração do gateway pipeline-step/litellm-gateway-config, que a resolução busca no registro que default_registry nomeia, hub.aggrega.ai.
Várias seções abaixo pedem que você altere uma linha e refaça o build. O lockfile fixa um digest para cada entidade que a release resolveu, incluindo o Aggregate e o Manifest deste diretório, e registra a própria Release pelo digest do seu conteúdo — então editar qualquer um desses três arquivos deixa o lockfile desatualizado, e o build seguinte é interrompido em vez de renderizar contra um pin obsoleto. A mensagem nomeia o que mudou — a Release pelo seu arquivo, o Aggregate ou o Manifest pelo seu nome — e imprime o digest que registrou ao lado do que encontrou. Um pull registra a mudança respeitando todos os outros pins:
aggrega pull --release release.yamlExecute isso e faça o build de novo, ou faça o build com --auto-pull, que executa o mesmo pull antes. De qualquer forma, a interrupção é o objetivo e não um obstáculo: um build não renderiza contra um pin que ele consegue ver que está obsoleto.
O build imprime, com <workspace> representando a pasta deste exemplo:
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>/distAs entidades são verificadas em relação às convenções do catálogo uma vez enquanto o lockfile é resolvido e uma vez enquanto a release passa pelo build, e cada aviso que essas verificações geram é impresso como uma linha lint:; esta release não gera nenhum. Para executar as mesmas verificações isoladamente, e ler qualquer aviso por completo com o arquivo de entidade de onde veio e o que o faria concordar:
aggrega lint --release release.yamlque aqui reporta conventions checked: 19 entities, 0 advisory finding(s).
Com um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta você mesmo. Se a pasta do workspace ainda não contiver uma pasta `ai-agent-and-model-router`, chame a ferramenta `scaffold` uma única vez com `example` definido como `ai-agent-and-model-router` e sem `dir`: ela escreve o exemplo em uma nova pasta `ai-agent-and-model-router`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `ai-agent-and-model-router`, `release` definido como `release.yaml`, `auto_pull` definido como true e `write` definido como true. Diga-me quais arquivos o build escreveu; eles ficam em `ai-agent-and-model-router/dist/`.A árvore renderizada
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.yamlEm router/ ficam os arquivos que a própria Recipe do roteador emite. Ambos vêm de bundles que a Recipe importa em vez de escrever, então cada um fica sob a chave com que foi importado, litellm-gateway-config e request-guard.
Tudo o que uma vinculação trouxe fica no mesmo diretório que os manifestos próprios do componente, com duas coordenadas no nome do arquivo: o componente ao qual foi vinculada e o nome que a vinculação recebeu. router--metrics-- é a vinculação metrics em router. O que veio de onde continua legível na árvore, e cada arquivo está onde uma ferramenta que lê um único diretório o encontrará — que é o que os consumidores deste destino fazem, a menos que você lhes diga o contrário.
As duas coordenadas são codificadas em vez de escritas como você as digitou, porque compartilham uma string com o nome próprio do arquivo. Um caractere que um nome de arquivo não pode carregar com segurança se torna -z e uma letra: api_key é api-zukey; router_model.credential — o nome que a vinculação na conexão router_model do agente recebe, ou seja, o alias da conexão, um ponto e o slot — é router-zumodel-zdcredential; e feature.aggrega.ai/monitoring — um nome de vinculação que a própria anotação de uma Feature cunha — seria feature-zdaggrega-zdai-zsmonitoring. O nome próprio do arquivo mantém todos os pontos que tiver, então o sufixo .yaml ainda é lido como um sufixo.
Onde uma página daqui mostra o que um build produziu, o bloco é copiado de uma execução real — veja Lendo a saída nestas páginas para a convenção e a marca que ela usa para linhas omitidas.
A tabela de roteamento
A razão de ser do roteador é o seu mapa, e o mapa chega à saída renderizada em vez de ficar no arquivo escrito pelo autor. Aqui está o bloco data inteiro 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-routinge o bloco data do segundo ConfigMap, dist/helm/router/request-guard/request-guard.yaml, sem o texto dos arquivos que ele contém:
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]Cinco coisas valem a pena ser lidas nesses blocos.
As duas entradas publicam o mesmo alias. É isso que dá ao roteador uma escolha a fazer a cada requisição, e os router_settings no fim do corpo dizem como ele a faz: latency-based-routing, escrito ali pela vinculação selection do roteador e não pela sua própria Recipe, como mostra mais abaixo a seção sobre essa vinculação. Um mapa cujos aliases são todos distintos roteia apenas por nome, e a estratégia não muda nada nisso. Compartilhar um alias é também o motivo pelo qual as duas entradas são digitadas à mão em values.models em vez de servidas por componentes de modelo ligados ao socket models do roteador: um modelo ligado é servido sob o alias da sua própria conexão, que nenhuma outra entrada pode publicar, então dois modelos ligados nunca compartilham um. O segundo motivo é da Anthropic: o roteador escreve a entrada de um modelo ligado apenas pela API da OpenAI, enquanto o modelo da Anthropic responde à sua própria API, então ligar core/ai-model/anthropic interrompe o build, dizendo para digitar esse modelo upstream no mapa em vez disso.
Os destinos são strings que o compilador não interpreta. openai/gpt-4o é um ponteiro determinístico: o proxy em execução o resolve quando atende uma requisição. O compilador nunca contata um provedor em tempo de build, então não pode dizer a você que um destino existe, que está escrito corretamente ou que a sua conta consegue alcançá-lo. Mude openai/gpt-4o para openai/not-a-real-model e o build ainda tem sucesso — a falha chega no momento da requisição, vinda do provedor.
Nenhum valor de credencial está neste arquivo. Cada entrada nomeia, em vez disso, uma variável de ambiente, por meio da indireção própria do proxy. O valor chega ao contêiner por um caminho totalmente diferente, mostrado abaixo.
Toda requisição encontra primeiro uma guarda. A primeira entrada de callbacks registra o módulo request_field_filter pelo caminho completo do seu arquivo: o segundo ConfigMap é montado no contêiner do roteador em /etc/litellm-request-guard, um diretório próprio ao lado de /etc/litellm, onde o primeiro é montado e onde o proxy lê a sua configuração. Esse segundo ConfigMap vem de LiteLLMGuard#/artifacts/RequestGuard, um bundle que toda Recipe que executa este proxy importa, de modo que a guarda e a lista de permissões abaixo têm um único texto onde quer que o proxy execute. A Recipe do roteador entrega essa guarda em toda Release, porque o roteador detém a credencial do provedor. Ela encaminha de um chamador apenas os campos de requisição que o proxy declara para a rota que a requisição tomou, mais os que a Release nomeia em infra.admitted_request_fields do roteador, e responde a qualquer outro campo com um erro que o nomeia, sem encaminhar nada — assim um chamador não pode apontar o roteador para um endereço próprio por meio de uma lista de modelos no corpo da requisição, nem enviar uma chave de provedor própria no lugar da do roteador. Um chamador também não pode definir a identidade que o próprio roteador escreve em toda requisição — o hash da chave que ele verificou, a equipe e a organização dessa chave e o usuário final: em uma requisição responses ou messages, em que o roteador mantém os metadata do chamador separados dos seus, ele remove qualquer campo de equipe, organização ou usuário final que o chamador tenha escrito ali e a guarda recusa uma requisição que nomeie ali a chave, metadata.user_api_key, e em qualquer outra rota o valor do roteador substitui qualquer um que o chamador tenha enviado. Esta Release não admite nada além disso. A segunda entrada, prometheus, é o callback de métricas próprio do proxy, que o valor metrics_enabled do roteador ativa; a vinculação metrics abaixo coleta o que ele registra.
Somente as rotas próprias do roteador são alcançáveis. A guarda vê apenas as rotas que lhe entregam a requisição, então o outro arquivo do segundo ConfigMap configura o segundo contêiner do pod, que monta apenas esse ConfigMap e executa a imagem oficial do nginx como lista de permissões de caminhos. O próprio roteador escuta no endereço de loopback do pod, onde nada fora do pod o alcança, e a lista de permissões escuta na porta 4000, a porta que o Service abaixo tem como alvo. Ela encaminha uma requisição apenas quando o seu método e o seu caminho correspondem a uma das rotas que o roteador serve — as rotas de requisição de modelo que a guarda verifica, nas grafias que o roteador serve qualquer que seja o alias, entre elas /v1/chat/completions e /v1/messages; a listagem de modelos; as verificações de integridade; e, das suas rotas administrativas, o gerenciamento de chaves — e responde 403 a qualquer outro caminho, sem encaminhar nada. Assim, as rotas de contagem de tokens do proxy, as suas rotas de passagem direta para as APIs próprias dos provedores, as suas outras rotas administrativas e o seu console administrativo não podem ser alcançados pelo roteador, nem uma rota de modelo cujo caminho contém o nome do modelo, como fazem os caminhos que o cliente do Azure envia: ali o proxy lê palavras no caminho, incluindo o alias, para decidir como registra uma requisição, e o roteador recusaria nela uma requisição para o assistant próprio deste mapa. As métricas do proxy também não estão entre essas rotas: a porta 4000 responde 403 a /metrics. Com metrics_enabled do roteador como true, como o Aggregate o define, a lista de permissões também escuta na porta 9090 e ali encaminha apenas um GET de /metrics, para o listener que o proxy mantém para as suas métricas no endereço de loopback, respondendo 403 a qualquer outra requisição. Essa porta não verifica nenhum chamador, e as métricas nomeiam as chaves com hash, os aliases de chaves e os e-mails de usuários aos quais o roteador atribui o gasto.
O que o roteador publica
A Recipe do roteador publica as duas chaves que todo componente de modelo publica: um endpoint, a URL base entregue a uma biblioteca cliente, e um model, o nome que uma requisição pede. É isso que permite ao socket model do agente aceitar o roteador no lugar de um modelo. O seletor do socket é component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: ele admite um componente da categoria de modelo ou de gateway que carregue model.aggrega.ai/api, o rótulo que nomeia qual API de modelo responde no endereço que o componente publica. O roteador carrega model.aggrega.ai/api: openai. Um gateway que não serve nenhuma API de modelo não carrega esse rótulo, e uma aresta do agente para um deles interrompe o build, nomeando o socket e o seletor que o destino não satisfaz.
O endereço é o Service que a própria Recipe do roteador emite — o spec inteiro 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: metricsA Recipe compõe o endpoint que publica, http://router-default:4000/v1, a partir dos mesmos dois fatos dos quais o Service tira o nome e a porta: o nome próprio do componente e o seu infra.port. A porta que o Service tem como alvo, http, é aquela em que a lista de permissões de caminhos do roteador escuta; metrics, a segunda, existe porque as métricas do roteador estão ativadas, e transporta apenas elas. Nada nos três arquivos escreve router-default por extenso. Renomeie o componente router — a sua chave no Aggregate e na Release, e a aresta do agente que o nomeia — e o endereço que o agente recebe acompanha: renomeado para gateway, o OPENAI_BASE_URL do agente é http://gateway-default:4000/v1.
O nome é o alias que o roteador publica como o seu modelo. Este mapa publica um único alias, assistant, a partir das suas duas entradas, então o roteador publica esse e o seu values.model fica de fora. Dê à segunda entrada um alias próprio — summarizer, por exemplo — e o build é interrompido antes que qualquer coisa seja renderizada, porque o roteador só pode publicar um. A interrupção é E0033, uma asserção falha do Component do roteador, e a sua mensagem termina com a frase própria da regra: 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 não está definido, mas values.models publica 2 aliases (assistant, summarizer), então o gateway não consegue saber qual deles um componente ligado a ele pede; defina values.model como um deles). Definir model: assistant ao lado de models resolve isso, e o agente recebe assistant novamente. Um chamador que queira summarizer o pede pelo nome ao mesmo endpoint.
O que o agente recebe
A Recipe do agente lê as suas duas arestas e os valores próprios do agente, e os transforma no ambiente do contêiner. Aqui está o bloco env inteiro 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:graphA primeira veio da vinculação que a aresta model carrega, e o provedor helm escreve uma entrada assim, lida de um Secret, antes das simples. O limite de recursão é o próprio recursion_limit do agente, sob a variável que o LangGraph lê por conta própria; as duas seguintes vieram da aresta model, as duas depois delas da aresta checkpointer_db, e a última é o próprio graph_entrypoint do agente, sob um nome padrão que o código da aplicação lê, que um bloco inject no próprio componente substituiria. Observe o que o Aggregate não precisou dizer: nenhuma das arestas carrega um bloco inject, porque a Recipe consumidora entrega cada conexão sob nomes padrão, que um bloco inject na aresta substituiria. O desenvolvedor declara que o agente usa um modelo; a variável sob a qual chega o seu endpoint é a que a biblioteca cliente lê, e continua sendo a que a aresta determinar.
Observe também LANGGRAPH_CHECKPOINTER_PORT: "6379". A Release declara checkpointer: {} e não configura nada, então essa porta é o valor padrão do esquema próprio do Component de cache, materializado e canalizado pela aresta.
O agente fala com o roteador exatamente no dialeto que usaria para falar diretamente com um provedor — uma URL base, um nome de modelo e uma chave. É isso que permite inserir, mover ou reapontar o roteador sem que a aplicação mude.
As seis vinculações, e o que cada uma renderiza
Uma vinculação que não muda nada na saída não ensina nada. Cada uma destas seis coloca algo ali.
api_key no roteador — a chave que ele exige dos chamadores
core/referenced-secret, preenchendo um slot que o Component do roteador declara; a chave que ela contém é a que o LiteLLM chama de sua master key. Ela renderiza o seu próprio Secret, e o contêiner do roteador faz referência a ele. De dist/helm/router--api-zukey--router-secret-router-api-key.yaml:
stringData: master-key: "dev-router-admin-key-change-me"e no env do contêiner do roteador, de dist/helm/router-deployment.yaml:
- name: LITELLM_MASTER_KEY valueFrom: secretKeyRef: name: router-api-key key: master-keyO contêiner carrega uma referência, não o valor. O nome do Secret é publicado pela vinculação e lido pelo consumidor, então nenhum dos lados o deriva novamente.
provider_key no roteador — a chave que ele apresenta upstream
A mesma Feature em um slot diferente, e a diferença entre os dois slots é a razão de ser do roteador. Ela é a única credencial das entradas digitadas em values.models, aqui as duas; um modelo ligado ao socket models do roteador apresenta, em vez disso, a chave que a sua própria conexão carrega, nunca esta. De dist/helm/router--provider-zukey--router-secret-router-provider-key.yaml:
stringData: provider-key: "upstream-provider-key-change-me"e no mesmo env do contêiner:
- name: LITELLM_PROVIDER_API_KEY valueFrom: secretKeyRef: name: router-provider-key key: provider-keyEsta vinculação também muda a tabela de roteamento. Volte ao bloco data da tabela de roteamento acima: toda entrada do mapa carrega api_key: os.environ/LITELLM_PROVIDER_API_KEY, nomeando esta mesma variável. Remova a vinculação provider_key do Aggregate e refaça o build. O build relata onze arquivos em vez de doze — o Secret sumiu — e o ConfigMap da tabela de roteamento difere exatamente por essas duas linhas api_key e nada mais; o ConfigMap da guarda não muda. O resto do mapa mantém a ordem e a formatação escritas pelo autor, o roteador ainda serve e roteia, e uma requisição roteada agora falha no provedor porque não há credencial a apresentar.
O nome da variável é escrito uma única vez na Recipe do roteador e lido a partir dali tanto pela tabela de roteamento quanto pelo ambiente do contêiner, de modo que uma tabela não pode chegar a nomear uma variável que nada define.
As duas credenciais ficam separadas, e essa separação é o que o roteador oferece: a chave upstream fica dentro do roteador, e a aplicação chamadora não detém nada além da chave do roteador.
credential na conexão model do agente — a chave que ele apresenta ao roteador
core/referenced-secret novamente, do outro lado da mesma conversa. O socket model do agente declara um slot credential, então a chave é vinculada na conexão em que é apresentada, sob a aresta no 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"É o mesmo valor da master-key do roteador acima, e não é escrito duas vezes. As duas vinculações leem um único parâmetro elevado:
origin: "{{ .parameters.router_admin_key }}"O Aggregate declara o parâmetro e a Release o cumpre, então a chave tem um único lugar onde é escrita e os dois Secrets não podem ser editados separadamente. Altere-a uma vez na Release e os dois Secrets renderizados mudam juntos.
Cada vinculação ainda renderiza o seu próprio Secret, nomeado a partir do componente que o consome — e, no caso do agente, da conexão em que está vinculado: agent-router-model.credential. O que o parâmetro compartilhado compartilha é o valor, não o recurso.
published no roteador — um endereço fora do cluster
core/public-ingress, que não preenche nenhum slot: ela é admitida pelo seu próprio seletor, component.aggrega.ai/type=server, que o roteador carrega. Ela traz um recurso do qual a Recipe do roteador não sabe nada. O spec inteiro 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: httpO desenvolvedor a vincula no Aggregate com o path, porque quais requisições uma aplicação serve faz parte do que a aplicação é. O operador escreve o host e o nome da porta na entrada da Release para a mesma vinculação: o host é o nome do ambiente para o roteador, então o operador o nomeia por ambiente, na Release de cada ambiente. O Service de backend não foi fornecido por nenhum dos dois: service_name fica sem definir, e a realização da vinculação recorre ao Service que a própria Recipe do roteador emite. Não há campo ingressClassName na saída, porque nada definiu um e a realização omite o que não recebeu, deixando que a classe padrão do cluster reivindique o recurso.
metrics no roteador — um alvo de scraping
core/prometheus-exporter, admitida pelo mesmo seletor, trazendo outro recurso próprio. Cada parâmetro que ela recebe é dimensionamento do operador e não intenção da aplicação — com que frequência uma plataforma faz scraping, e qual porta e qual caminho ela lê, são propriedades da plataforma — então é o operador quem a vincula, na Release, na entrada do roteador, com o seu tipo ao lado da sua infra. O Aggregate não a menciona:
components: router: features: metrics: type: core/prometheus-exporter infra: interval: 30s port: metrics path: /metricsO spec inteiro de dist/helm/router--metrics--router-servicemonitor-router-scrape.yaml:
spec: selector: matchLabels: app.kubernetes.io/name: router endpoints: - port: metrics interval: 30s path: /metricsO port nomeia uma porta do Service em vez de um número: metrics, que a Recipe do roteador emite porque o Aggregate define o valor metrics_enabled do roteador, e que serve as suas métricas. Esse é também o nome de porta padrão da Feature, escrito aqui por extenso com os outros dois ajustes. A porta http para a qual o Ingress acima roteia responde 403 a /metrics, então um scraping apontado para ali não coletaria nada. Se as métricas são servidas ou não é escolha do desenvolvedor, feita no Aggregate; com que frequência e em qual porta e caminho uma plataforma as coleta é escolha do operador, feita aqui.
selection no roteador — como ele escolhe entre os seus destinos
core/target-selection, que se vincula a um gateway que carregue gateway.aggrega.ai/intelligence: semantic, como o roteador faz. A forma como o roteador escolhe faz parte do que a aplicação pede a ele, então o desenvolvedor a vincula no Aggregate, com a sua strategy como valor:
components: router: features: selection: type: core/target-selection values: strategy: latencye o Manifest a associa à realização para este roteador:
core/target-selection:1.0.0: helm/target-selection-litellm:1.0.0Ela não renderiza nenhum arquivo próprio. A sua realização escreve uma configuração na tabela de roteamento que a Recipe do roteador renderiza — as duas últimas linhas do bloco data acima:
router_settings: routing_strategy: latency-based-routingCom ela, o proxy envia cada requisição para assistant à entrada cujas dez últimas respostas levaram, em média, o menor tempo, por token de saída quando uma resposta informa os seus tokens, e uma entrada ainda não testada conta como a mais rápida, de modo que cada uma é testada antes que as médias decidam. Remova a vinculação do Aggregate e refaça o build: o build ainda relata doze arquivos, e o ConfigMap da tabela de roteamento difere exatamente por essas duas linhas. A Recipe do roteador não escreve nenhuma estratégia própria, e sem uma o proxy escolhe ao acaso entre as duas entradas.
Peça strategy: cost em vez disso e o build é interrompido, sem escrever nada. A interrupção é E0033, uma asserção falha da realização, e a sua mensagem termina com a frase própria da regra: 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 (a vinculação core/target-selection “selection” em “router” pede a estratégia cost, mas core/gateway/litellm não consegue escolher entre as entradas do seu mapa de modelos por custo: o proxy procura o destino de cada entrada, exatamente como está escrito, na sua própria tabela de preços, que nomeia os modelos da OpenAI e da Anthropic sem o prefixo de provedor que um destino carrega (gpt-4o, não openai/gpt-4o) e que o proxy pode baixar novamente ao iniciar, e atribui a uma entrada que não encontra, e que não carrega preço próprio, um preço de fallback fixo, de modo que as entradas que compartilham um alias recebem o mesmo preço e a escolha recai sobre a sua ordem. Peça a estratégia latency, ou remova a vinculação). Os dois destinos aqui estão escritos dessa forma, então o proxy enviaria toda requisição ao primeiro deles enquanto o Aggregate pedia custo.
Onde o compilador não interpreta
O endereço e o nome de modelo do agente são lidos do que o roteador publica, então nenhum par de nomes nos três arquivos precisa ser mantido em sincronia à mão. O que o build de fato verifica é a regra própria do roteador de que o alias que ele publica é um dos que o seu mapa publica — uma regra que o seu Component declara e o build avalia, como qualquer outra asserção que uma entidade carrega.
O resto são strings canalizadas de um lugar para outro. O compilador roteia o endereço e o alias sem lê-los: ele não sabe que um é um hostname e o outro um nome de modelo, e não tem acesso a um cluster em execução para verificar se algo responde em router-default:4000. O rótulo model.aggrega.ai/api que admitiu o roteador é o mesmo tipo de string — o seletor do socket o compara, e nada verifica qual API de fato responde ali. E cada target no mapa é um ponteiro que o proxy em execução resolve: mude openai/gpt-4o para openai/not-a-real-model e o build ainda tem sucesso, com a falha chegando no momento da requisição.
É a mesma propriedade que faz o resto do exemplo funcionar. Como o compilador não interpreta o que canaliza, o roteador pode ser reapontado para um provedor diferente, o agente pode ser ligado a um roteador diferente e a realização da credencial pode ser trocada por uma apoiada em um repositório — tudo sem que o compilador precise entender nada disso, e sem que o agente mude.
Adaptando-o
-
Reapontar um provedor. Edite um
targetno mapa do roteador. Nada mais muda: nem o modelo, nem o agente, nem um Secret renderizado. -
Adicionar um terceiro provedor. Adicione uma entrada ao mapa. Se ela publicar o alias existente, a estratégia passa a escolher entre três. Se publicar um novo, o mapa publica dois aliases, e o
values.modeldo roteador nomeia aquele que é entregue ao agente; um chamador que queira o outro o pede pelo nome. Um modelo que o catálogo modela e cuja API é a API da OpenAI pode, em vez disso, ser ligado ao socketmodelsdo roteador, sob um alias próprio e apresentando a chave que a sua conexão carrega;values.modelentão nomeia o alias entregue ao agente. -
Buscar as credenciais em um repositório. Mude para
helm/k8s-external-secreta única linha do Manifest que vinculacore/referenced-secrete refaça o build. CadaSecretrenderizado se torna umExternalSecretque nomeia uma entrada em um repositório de segredos do cluster, para que um operador do repositório a reconcilie — e a referência renderizada de cada consumidor permanece idêntica byte a byte, porque o localizador é publicado pelo lado produtor em vez de combinado entre os dois. Nada mais nos três arquivos precisa mudar para o build ter sucesso.Uma coisa, porém, precisa ser reescrita antes que a troca signifique algo:
originmuda de significado entre as duas realizações. A realização deste workspace o lê como o valor a armazenar; a outra o lê como a chave a buscar. Troque a linha sem revisitar os valores deorigine oremoteRef.keyrenderizado é qualquer que seja o placeholder que estava no lugar do valor — aqui,dev-router-admin-key-change-me. Nada na árvore de saída guarda então essa string como material secreto, mas ela ainda está ali como uma chave do repositório que nomeia uma entrada que não existe. -
Dispensar o roteador. Aponte, em vez disso, a aresta
modeldo agente para um componente de modelo específico de um provedor. O agente então detém ele mesmo uma credencial de provedor, que é exatamente a concessão que o roteador existe para eliminar. -
Alcançar um roteador que o catálogo não modela. Aponte a aresta
modeldo agente para um componentecore/ai-model/openai-compatiblee escreva o endereço desse roteador no seuinfra.endpointna Release. Nada é executado por trás desse componente dentro do cluster, então cabe ao operador escrever o endereço e mantê-lo em sincronia com o serviço que ele nomeia.
Para compartilhar uma credencial entre as conexões de vários consumidores, veja model-api-key-sharing. Para um socket que nenhuma entidade do catálogo declara, veja adhoc-uses-socket.