Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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

O 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ânciaComponent do catálogoo que é aqui
routercore/gateway/litellmo 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
agentcore/ai-agent/langgrapha aplicação, executando a sua própria imagem de grafo
checkpointercore/datastore/valkeyonde 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:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

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

Build

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

Uma 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:

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

Este 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:

Terminal window
aggrega pull --release release.yaml

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

As 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:

Terminal window
aggrega lint --release release.yaml

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

Em 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-routing

e 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: metrics

A 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:graph

A 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-key

O 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-key

Esta 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: http

O 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: /metrics

O 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: /metrics

O 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: latency

e o Manifest a associa à realização para este roteador:

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

Ela 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-routing

Com 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 target no 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.model do 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 socket models do roteador, sob um alias próprio e apresentando a chave que a sua conexão carrega; values.model então nomeia o alias entregue ao agente.

  • Buscar as credenciais em um repositório. Mude para helm/k8s-external-secret a única linha do Manifest que vincula core/referenced-secret e refaça o build. Cada Secret renderizado se torna um ExternalSecret que 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: origin muda 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 de origin e o remoteRef.key renderizado é 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 model do 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 model do agente para um componente core/ai-model/openai-compatible e escreva o endereço desse roteador no seu infra.endpoint na 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.