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

Features de IA

O conjunto de Feature de IA do Aggrega

Para atender às demandas específicas, à volatilidade e às ameaças de segurança dos sistemas de IA modernos, o Aggrega incorpora inteligência especializada diretamente em sua biblioteca padrão de IA (o Catálogo) de código aberto. Ela garante que tanto a estrutura cloud-native genérica quanto os motores de raciocínio nativos de IA altamente especializados coexistam com segurança.

O compilador Go central é um roteador universal neutro quanto ao conteúdo; toda a inteligência específica de IA fica em políticas WebAssembly (Wasm) plugáveis e nas declarações JSON Schema 2020-12 que os arquitetos de plataforma escrevem nas entidades do Catálogo.

1. A ontologia operacional de nuvem e o duck typing de IA

Para conectar o Open Application Model (OAM) genérico às realidades rígidas da infraestrutura moderna, o label component.aggrega.ai/type é mapeado exclusivamente para um conjunto fechado de primitivas cloud-native universais. Essa identidade semântica é o que um seletor de socket, o appliesTo de uma Feature e uma política de governança leem para saber como um componente trata estado, entrada de rede e ciclos de vida; o compilador a compara como uma string opaca e não se ramifica com base nela, e como um componente é renderizado é decidido pela Recipe que o Manifest mapeia para ele.

Os tipos cloud-native (a base de infraestrutura):

  • server: computação sem estado de longa duração que espera tráfego de aplicação de entrada (por exemplo, um AI Gateway ou uma interface de chat).
  • worker: computação sem estado de longa duração que consome filas ou executa loops em segundo plano sem nenhuma porta de aplicação de entrada (por exemplo, um agente LangGraph ou um worker Celery).
  • task: computação efêmera que é executada até a conclusão e termina (por exemplo, scripts de migração de banco de dados).
  • function: computação orientada a eventos que escala até zero (por exemplo, AWS Lambda).
  • stateful-server: computação dentro do cluster que exige identidades de rede estáveis e discos permanentes (por exemplo, um banco de dados vetorial Qdrant, um broker Kafka).
  • resource: infraestrutura externa, gerenciada pela plataforma (por exemplo, AWS RDS PostgreSQL, buckets S3, um barramento de eventos hospedado).

O conjunto é do próprio Aggrega e é fechado. O schema de Component publicado enumera esses valores, e um documento que carregue qualquer outro é recusado ao ser carregado — E0215 nomeia o label e lista o que ele aceita. É isso que o eixo proporciona: uma Feature ou um seletor de socket escrito contra stateful-server significa a mesma coisa em todo catálogo que encontra.

O que um componente é no seu próprio vocabulário vai em uma chave sua. Um nível, uma zona de dados, uma classe de serviço, uma divisão mais fina das primitivas — cada um é uma chave de label que você escreve ao lado da reservada, já que o schema de Component aceita qualquer chave de label adicional com valor string e toda superfície de seleção a lê de forma idêntica. É o mesmo mecanismo que os labels de duck typing de IA descritos abaixo já usam; a chave reservada é a base comum, e tudo acima dela é seu.

O tipo operacional não é a categoria de navegação, e eles são eixos separados de propósito. Um broker Kafka fica na categoria messaging — onde um usuário o procura — e carrega stateful-server como seu tipo, porque é isso que a infraestrutura precisa fazer por ele. Um seletor escrito contra um eixo nunca corresponde no outro.

Consulte entities/component para ver as tabelas da taxonomia de labels semânticos — os labels Generic Cloud Layer, Specialized AI Layer, Cross-Cutters e Dynamic Business Context que os arquitetos usam para sobrepor uma identidade cognitiva aos tipos base.


1.1 O padrão do catálogo de código aberto: “Base nua, bordas especializadas”

Ao aplicar esses labels, há uma distinção fundamental entre o Catálogo oficial de código aberto do Aggrega (core/*) e um Catálogo corporativo privado (acme/*).

Para que o catálogo oficial de código aberto continue universalmente utilizável, ele precisa distinguir rigorosamente entre física técnica imutável e intenção cognitiva subjetiva. Se o core/datastore/postgres de uso geral tiver engine: relational fixado no código, um plugin de veredito de governança configurado para impor a correspondência de tipo de datastore vai interromper o build quando um desenvolvedor habilitar a extensão pgvector em seus values e tentar conectar um agente de IA que exige um datastore vector.

Para manter um catálogo central sem opiniões próprias, os componentes oficiais seguem este padrão: mantenha a base nua e especialize as bordas.

  1. A base nua: o Component de código aberto de nível raiz fixa no código apenas o que é objetivamente verdadeiro sobre o produto e não pode ser alterado por nada que um autor configure — em primeiro lugar e sempre, a primitiva operacional (component.aggrega.ai/type). Um banco de dados Postgres é objetivamente um stateful-server; esse fato não pode mudar. O mesmo teste admite um label de capacidade quando a identidade do produto é essa capacidade: core/datastore/qdrant e core/datastore/weaviate são motores de busca vetorial e nada que um autor escreva os transforma em outra coisa, então cada um carrega datastore.aggrega.ai/engine: vector na base, exatamente como core/datastore/redis carrega kv. O que a base nua recusa é o caso oposto — uma característica que depende de como um componente é configurado ou usado, para a qual existe o terceiro mecanismo descrito abaixo.
  2. As interfaces especializadas (herança de schema): um Component pode declarar extends, nomeando outro Component como sua base, e o que isso compõe é a estrutura: labels, anotações, slots de anexo, a allowlist de autoinjeção, sockets de topologia e assertions nomeadas. Os três pilares de dados não se compõem — um Component que estende escreve o marcador literal schema: inherited e não escreve nenhum conteúdo próprio de values, infra ou provides, de modo que seu contrato é idêntico ao de sua base. É por isso que o mecanismo restringe em vez de variar: como o contrato não muda, toda Recipe escrita para a base já atende à especialização, e a especialização custa uma entidade de catálogo e uma linha de mapeamento no Manifest. O que uma especialização acrescenta é, portanto, identidade que um seletor ou uma política lê — um nível de auditoria, uma zona de dados, um contato de governança ou um socket cujo seletor admite menos que o da base. Ela não pode acrescentar um contrato diferente, porque não tem nenhuma superfície em que escrever um. Uma consequência é fácil de passar despercebida: a linha de mapeamento continua obrigatória. A seleção de Recipe é feita por chave de mapeamento exata, então uma especialização precisa de sua própria entrada mappings.components.type, mesmo que não precise de uma Recipe própria. Consulte examples/extends-wrapper para ver um wrapper publicado que acrescenta um label de nível revisado e restringe um socket com ele, junto com o build que é interrompido quando uma aresta conectada a esse socket sai do nível. Uma característica que depende de como um componente é configurado não é objeto deste mecanismo: uma especialização fixa o artefato de sua base e herda seu contrato, então uma característica verdadeira da especialização já é verdadeira da base, onde a regra da base nua a coloca. Uma característica assim pertence ao mutador dinâmico descrito abaixo.
  3. O mutador dinâmico (promoção Wasm): se uma característica é ditada pelo payload do desenvolvedor (por exemplo, enable_vector: true), a empresa usa o papel label-transform do socket de governança na construção da topologia para ler dinamicamente os values opacos e injetar automaticamente o label datastore.aggrega.ai/engine: vector no grafo IR antes de as políticas serem executadas. É aqui que uma característica dependente da configuração se torna disponível para uma avaliação rigorosa de políticas — são os values declarados pelo desenvolvedor que a promovem, e a transformação é executada antes que qualquer política leia um label.

A exceção corporativa: como o compilador se mantém sem opiniões próprias, as empresas que escrevem seus próprios catálogos internos são livres para quebrar esta regra. Se uma política de segurança corporativa determina que todos os bancos de dados internos são altamente sensíveis, o arquiteto de plataforma pode e deve fixar compliance.aggrega.ai/data-class: restricted (ou um label semelhante determinado pela empresa) diretamente em seu componente base acme/postgres, de modo que toda instância dele carregue a classe e uma política que a empresa anexa a leia em cada uma. O label em si não impõe nada: o compilador o carrega como string, e é a política anexada que interrompe um build. Quando apenas alguns dos usos de um produto em um parque contêm esses dados, é uma especialização por meio de extends que carrega a classe — consulte examples/policy-data-class-route, cujo assistente de sinistros é o agente LangGraph da biblioteca padrão mais um label de classe, ao lado da política que o lê.

1.2 Como os labels semânticos alimentam o pipeline do compilador

Para manter os labels no domínio do arquiteto de plataforma, os desenvolvedores não podem escrever labels em suas instâncias de Component dentro do Aggregate: o schema do Aggregate não dá a uma instância de componente nenhuma chave labels. Os labels de um nó são os de sua entidade de catálogo, junto com os que um anexo de governança label-transform configurado pelo operador acrescenta durante a construção da topologia. Veja exatamente como esses labels conduzem o pipeline de compilação sem exigir código Go personalizado:

1. component.aggrega.ai/type (a primitiva base)

  • Quem o escreve? O arquiteto de plataforma (domínio 2). Ele é obrigatório para todo componente do catálogo.
  • Quem o consome? O analisador estático e os Plugins de renderização Wasm.
  • Caso de uso no compilador: esta é a ontologia operacional de nuvem central. O analisador estático avalia nativamente em Go as strings de seletor usesSchema para garantir que um desenvolvedor não possa anexar um agente a um banco de dados padrão se o socket exigir uma capacidade de IA específica. Além disso, o DevOps usa este label para rotear explicitamente as primitivas com estado (stateful-server, resource) para fronteiras físicas de cluster que suportam discos persistentes, enquanto um papel de veredito de governança pode impor que componentes com estado nunca sejam colocados em fronteiras apenas efêmeras.

2. model.aggrega.ai/capability

  • Quem o escreve? O arquiteto de plataforma.
  • Quem o consome? O analisador estático (por meio dos seletores de labels no estilo Kubernetes dos sockets usesSchema).
  • Caso de uso no compilador: quando um arquiteto escreve um seletor usesSchema que nomeia o label de capacidade exigido, o mecanismo nativo de correspondência de labels do compilador rejeita o cabeamento que não satisfaz o seletor antes que os artefatos sejam gerados. O compilador trata esses labels como strings opacas; o significado semântico de “text-generation” versus “embedding” está na forma como o arquiteto escreve o seletor.

3. component.aggrega.ai/hosting

  • Quem o escreve? O arquiteto de plataforma.
  • Quem o consome? O mecanismo de políticas (um papel de veredito de governança), os Plugins de renderização Wasm e os próprios chamadores de um modelo ou de um agente na biblioteca padrão: seus agentes, cuja asserção o lê em cada conexão model, core/ai-tool/agent-invocation, cuja asserção o lê em sua conexão target_agent, assim como sua realização Kubernetes, que recusa uma credencial a um agente external alcançado por http, o gateway de IA, cuja asserção o lê em cada conexão aos seus sockets models e cache_store, e core/gateway/kong, core/gateway/kong-enterprise, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/traefik-hub, core/gateway/agentgateway e core/gateway/higress, cujas asserções o leem em cada conexão aos seus sockets models, e ao backend dos dois Kong, aos sockets cache_store do APISIX e do Traefik Hub e aos sockets cache do Envoy Gateway, do Higress e do Traefik Hub — consulte “A chave que um chamador apresenta” abaixo.
  • Caso de uso no compilador: ele registra quem opera o recurso subjacente do componente, permitindo que uma política anexada por um operador avalie o risco de exfiltração de dados; o compilador lê o valor como string e não julga nada. Quando um agente cujo label de classe diz que ele contém dados internal se conecta a um modelo rotulado managed — um serviço operado fora da fronteira da própria Release — uma política assim pode ler que os dados saem dessa fronteira, e interromper o build a menos que a conexão seja roteada por um gateway de IA que carregue core/data-masking, que mascara o texto de chat e de completion que o gateway encaminha. O socket model de um agente aceita um gateway assim no lugar do modelo, de modo que essa rota é uma aresta do grafo que a política lê, e um modelo que o gateway serve a partir de seu socket models é uma aresta própria, do gateway ao componente do modelo, cujos labels a política lê — assim, o caminho de um agente através do gateway até um modelo managed está no grafo de ponta a ponta. Um upstream digitado à mão no mapa de modelos do gateway não está: é uma string que o compilador não resolve, então uma política que lê o grafo vê o gateway e nada por trás dele. examples/policy-data-class-route é uma política assim: suas configurações classificam um modelo managed como public, e ela interrompe um build em que um assistente que contém dados restricted alcança um deles sem gateway de mascaramento na rota. Esta é uma característica transversal: os mesmos valores self-hosted | managed | external descrevem um banco de dados gerenciado ou um servidor de inferência autogerenciado tanto quanto descrevem um modelo, por isso o label fica sob o namespace compartilhado component.aggrega.ai/, e não sob o específico de modelos.

4. agent.aggrega.ai/autonomy

  • Quem o escreve? O arquiteto de plataforma.
  • Quem o consome? O mecanismo de políticas (um papel de veredito de governança).
  • Caso de uso no compilador: ele identifica o risco de execução do loop cognitivo. Se um agente estiver rotulado como autonomous (ou seja, executa loops em segundo plano sem prompts do usuário) e se conectar a um banco de dados altamente sensível, o mecanismo de políticas pode interromper o build a menos que um autor anexe a Feature de aprovação ou de contenção que as próprias regras da empresa exigirem, para que um loop sem supervisão não possa alcançar esses dados sem revisão.
  • O que significa um componente sem label neste eixo, porque a ausência é deliberada. O label descreve o risco de execução de um loop cognitivo, então um componente que não contém um loop próprio não carrega nenhum valor aqui, em vez do mais baixo dos dois. Muitos componentes da categoria de agentes ficam sem label exatamente por esse motivo: as peças de apoio que uma plataforma de agentes distribui ao lado do seu servidor — um console no navegador, uma execução de migração de schema, um task worker, um sandbox de código, um proxy de saída — estão nessa categoria porque é lá que você as procura, enquanto o loop que elas apoiam vive no servidor da plataforma, que é onde o label fica. O caso mais claro é um único produto dividido entre os dois tratamentos: o servidor de uma plataforma carrega copilot, e o sandbox de código distribuído ao lado não carrega nada. O teste é onde o loop vive, e não que forma a peça assume, então um runtime que hospeda código de agente fornecido por você também fica sem label — o loop ali é o que quer que você implante nele, não algo que o produto afirma. Um seletor que nomeia qualquer um dos valores corresponde, portanto, aos componentes que contêm um loop e a nenhum outro, e um seletor escrito para corresponder a qualquer postura de autonomia ignora as peças de apoio em vez de tratá-las como o elemento menos autônomo da implantação.

5. gateway.aggrega.ai/intelligence

  • Quem o escreve? O arquiteto de plataforma.
  • Quem o consome? O analisador estático e os plugins Wasm de linter escritos pela empresa.
  • Caso de uso no compilador: ele determina quais funcionalidades um roteador pode suportar fisicamente. A Feature de IA fallback-chain declara appliesTo: gateway.aggrega.ai/intelligence=semantic, e o analisador estático avalia esse seletor em relação aos labels do componente de destino antes que qualquer artefato seja renderizado. Se um desenvolvedor a anexar a um gateway l4-mesh padrão, o build é interrompido com uma violação de seletor que nomeia a Feature e o seletor em que ela falhou, porque o arquiteto escreveu esse seletor sabendo que uma malha TCP padrão não consegue analisar payloads JSON de LLM para ler o modelo que uma requisição nomeia. A recusa se baseia na ausência de semantic, e não na presença de l4-mesh, então vale igualmente para um roteador que não carrega nenhum label de inteligência. O compilador trata o label como uma string opaca, exatamente como acima: o que semantic significa está na forma como o arquiteto escreve o seletor. Em um roteador que carrega semantic, o anexo passa pelo seletor, e o que acontece em seguida cabe à sua realização: a realização da biblioteca padrão escreve a cadeia na configuração de roteamento do gateway de IA.
  • O que a biblioteca padrão carrega. Estes componentes carregam semantic: core/gateway/litellm, cuja realização renderiza a tabela de roteamento do proxy: um mapa de modelos sobre vários provedores upstream; core/gateway/cloudflare-ai-gateway, o gateway hospedado da Cloudflare, que lê cada requisição de modelo que encaminha — o modelo que ela nomeia, os tokens cobrados por ela e, quando as verificações próprias do gateway estão ativas, seu conteúdo; core/gateway/azure-api-management, o gateway de IA do Azure API Management, um serviço hospedado, que lê cada requisição de modelo em uma API que serve um modelo — o prompt que seu cache semântico compara, os tokens que uma resposta informa e o conteúdo que sua verificação de segurança envia para inspeção; core/gateway/apisix, cujo proxy de IA lê o corpo de cada requisição em uma rota que serve um modelo e os tokens que a resposta do modelo informa; core/gateway/envoy-gateway, cuja extensão Envoy AI Gateway lê o corpo de cada requisição na rota que serve os modelos conectados a ele, para encontrar o modelo que ela nomeia, e os tokens que cada resposta informa; core/gateway/kong-enterprise, Kong Gateway Enterprise, cujo proxy de IA lê o corpo de cada requisição em uma rota que serve um modelo conectado — o modelo que ela nomeia e as mensagens que carrega — e os tokens que cada resposta informa; core/gateway/traefik-hub, Traefik Hub, cujo middleware Chat Completion lê o corpo de cada requisição na rota que serve um modelo conectado, verifica-o em relação ao schema de chat completion e lê os tokens que cada resposta informa; core/gateway/agentgateway, agentgateway, que lê o corpo de cada requisição em seus caminhos de serviço de modelos para encontrar o modelo que ela nomeia, que é a forma como escolhe o modelo conectado para o qual uma requisição é enviada, e os tokens que cada resposta informa; e core/gateway/higress, Higress, cujo proxy de IA lê o corpo de cada requisição em uma rota que serve um modelo conectado — o modelo que ela nomeia e se ela faz streaming — e cujos plugins leem os tokens que cada resposta informa — de modo que as Features de IA que exigem este valor são resolvidas em relação a qualquer um deles, e cada realização diz o que seu gateway respeita, ou interrompe o build onde seu gateway não respeita nada disso; uma Feature sem realização para um gateway interrompe o build ali, nomeando seu tipo. Nenhum componente carrega l4-mesh, e os demais componentes de gateway da biblioteca padrão não carregam nenhum label de inteligência: os que roteiam tráfego terminam HTTP e roteiam na camada 7, e um deles é um plano de controle que não roteia nada, então nenhum dos dois valores o descreve. Uma malha TCP de camada 4 é ainda outra classe de produto. Isso deixa a recusa acima plenamente em vigor, porque ela se baseia na ausência de semantic: um anexo que exige esse valor é interrompido em qualquer um deles. Um arquiteto cujo catálogo de fato executa uma malha de camada 4 coloca l4-mesh nesse componente, o que torna a distinção selecionável nas duas direções.
  • Este eixo nomeia um nível de produto, o que é uma questão diferente do que um componente pode fazer com o tráfego, e lê-lo neste segundo sentido é o erro que ele convida a cometer. semantic diz que o roteador analisa o corpo da requisição, que é o que um controle que age sobre o modelo nomeado por uma requisição precisa — portanto é o eixo certo para isso. Não diz nada sobre se um roteador consegue copiar tráfego, transportar a identidade de um chamador, verificar o certificado de um upstream, recusar um prompt que corresponde a uma lista de padrões ou manter um orçamento ao longo de um período, e uma Feature que precisa de uma dessas não tem por que perguntar pelo nível: a maioria dos componentes que as oferecem são proxies comuns de camada 7 sem nenhum valor de inteligência, e onde um roteador semantic oferece uma delas, oferece por razões que o nível não registra. Assim, o nível alcança o conjunto errado nas duas direções — exclui totalmente os proxies simples e não diz nada sobre quais capacidades o gateway de IA que ele alcança realmente tem. Essa pergunta pertence ao eixo do caminho de dados descrito mais adiante, e os dois se combinam — uma Feature pode exigir um roteador semantic que também espelhe, nomeando ambos.

6. tool.aggrega.ai/impact

  • Quem o escreve? O arquiteto de plataforma.
  • Quem a consome? O mecanismo de políticas e os Plugins Wasm de renderização.
  • Caso de uso do compilador: Ao tirar essa informação do bloco values mutável do desenvolvedor e levá-la para a identidade imutável dos labels, permite que o mecanismo de políticas avalie configurações estritas de privilégio mínimo. Um plugin de renderização pode gerar permissões invoke padrão para uma ferramenta de busca na web read-only, mas exigir configurações estritas de assinatura criptográfica para invocar uma ferramenta mutating de SQL drop.

7. compliance.aggrega.ai/data-class

  • Quem a escreve? O arquiteto de plataforma do catálogo próprio de uma organização (ou injetada dinamicamente por meio do papel de governança label-transform).
  • Quem o consome? O mecanismo de políticas (um papel de veredito de governança).
  • Caso de uso do compilador: Dá aos dados que um componente mantém uma identidade de governança que uma política pode seguir ao longo do grafo. O compilador leva o label ao grafo IR como uma string e não classifica nada: não sabe que restricted é mais sensível que public, nem que qualquer das duas palavras signifique algo. Uma política anexada ao papel ir-verdict fornece esse significado em suas próprias configurações — quais classes existem e como se ordenam — e lê o label nos componentes das rotas que o compilador enumera sobre as arestas uses, de modo que pode interromper um build em que um componente com dados restricted alcança um componente de outra classe por uma rota sem nenhuma Feature anexada que a política considere desclassificadora, como core/data-masking no gateway de IA pelo qual a rota passa. A enumeração é limitada por componente de partida e não lista nada além do limite, de modo que uma rota que a política lê é real, enquanto a ausência de uma não prova que nenhuma exista. examples/policy-data-class-route é essa política, escrita para os mecanismos Rego e CEL compilados na CLI e para o OPA, com os builds interrompidos e o concluído lado a lado.
  • O que a biblioteca padrão traz. Nenhum Component core/ carrega este label. A classe dos dados de um componente é uma afirmação sobre como uma organização usa o componente, não uma propriedade do produto verdadeira em toda Release, então, pela regra Naked Base, ela fica fora da base: uma organização a carrega em seu próprio Component — uma especialização por meio de extends, como é o assistente de sinistros do exemplo completo, ou uma base própria sob a Enterprise Exception descrita acima.

8. hardware.aggrega.ai/accelerator

  • Quem a escreve? O arquiteto de plataforma. Ao empacotar um componente de modelo local, ele sabe que esse componente fundamentalmente requer uma GPU para funcionar.
  • Quem a consome? O DevOps (Domínio 4).
  • Caso de uso do compilador: O DevOps roteia explicitamente os componentes rotulados com GPU para as fronteiras de pools de hardware físico na Release por meio do mapa components: {}. O desenvolvedor simplesmente pede o modelo cognitivo em seu Aggregate, e o DevOps o coloca na fronteira do caro cluster de GPU, preservando inteiramente a separação de responsabilidades. Um papel de veredito de governança pode, além disso, impor que nenhum componente com este label seja jamais colocado em uma fronteira sem infraestrutura de GPU.

9. datastore.aggrega.ai/engine

  • Quem a escreve? O arquiteto de plataforma, em componentes da categoria datastore (estaticamente, em uma especialização flavored, ou injetada pelo papel label-transform quando os values do desenvolvedor promovem o papel). Os valores em uso no catálogo são: relational, document, kv, vector, graph, semantic-memory, search. Cada valor nomeia um mecanismo de armazenamento que um produto é — search nomeia um mecanismo de busca e análise que também indexa vetores — portanto um traço que reside no esquema e no padrão de acesso próprios de uma aplicação, e não em um armazenamento implantável, não é um valor deste eixo.
  • Quem a consome? O analisador estático (por meio de strings de seletor) e o mecanismo de políticas.
  • Caso de uso do compilador: Os seletores visam a semântica de armazenamento em vez de produtos — o socket de base de conhecimento de um agente seleciona datastore.aggrega.ai/engine in (vector, semantic-memory, search), e um mecanismo de políticas pode recusar o roteamento de payloads SQL para um mecanismo vetorial. A relevância para IA em datastores de uso duplo é derivada deste label, nunca armazenada como um booleano separado.
  • O que a biblioteca padrão traz. core/datastore/qdrant, core/datastore/weaviate, core/datastore/chroma, core/datastore/pgvector e core/datastore/milvus carregam vector, core/datastore/cognee carrega semantic-memory, e core/datastore/opensearch e core/datastore/elasticsearch carregam search, de modo que o seletor de base de conhecimento acima é resolvido contra cada um deles. core/datastore/redis, core/datastore/valkey e core/datastore/memcached carregam kv. Cada um desses labels fica na base própria do componente, porque a identidade do produto é esse mecanismo. Para core/datastore/pgvector, essa identidade é o artefato que ele fixa: executa a imagem PostgreSQL do próprio projeto pgvector, que traz a extensão, e toda Recipe habilita a extensão no banco de dados que o componente cria — portanto seu traço vetorial não depende de uma configuração, e é isso que o separa do caso configurado descrito acima em “Naked Base, Flavored Edges”, em que um PostgreSQL de uso geral só ganha o traço quando um desenvolvedor ativa uma extensão. relational, document e graph não têm componente na biblioteca padrão, então um seletor que nomeia apenas valores dentre eles não corresponde a nada aqui e é satisfeito por um catálogo que tenha um.

10. pipeline.aggrega.ai/mode

  • Quem a escreve? O arquiteto de plataforma, em componentes da categoria pipeline. Cada valor nomeia como um produto executa um job de várias etapas, e os valores seguem os componentes que os carregam, e não uma lista definida de antemão. A biblioteca padrão traz dois: durable em core/ai-pipeline/temporal, cujo mecanismo registra o resultado de cada etapa como um histórico de eventos e o reproduz, de modo que um job cujo worker falha retoma de onde parou; e reconciled em core/ai-pipeline/argo-workflows, cujo controlador executa cada etapa como um pod a partir de um recurso de workflow mantido na própria API do cluster.
  • Quem a consome? O mecanismo de políticas e os Plugins Wasm de renderização.
  • Caso de uso do compilador: Permite que políticas e renderizadores distingam mecanismos de pipeline pela forma como uma execução sobrevive a uma falha — um histórico de eventos reproduzido ou um recurso de cluster reconciliado — em vez de pelo nome do produto.

11. dataplane.aggrega.ai/* (As capacidades do caminho de dados)

  • Quem a escreve? O arquiteto de plataforma, em qualquer componente que fique no caminho do tráfego — um proxy reverso, um gateway de entrada, uma service mesh, um gateway de IA.
  • Quem a consome? O analisador estático, por meio do appliesTo de uma Feature e do seletor usesSchema de um socket.
  • Caso de uso do compilador: Responde o que este componente pode fazer com o tráfego, que é o que um controle em tempo de execução realmente precisa saber e o que um label de nível de produto não consegue dizer. core/traffic-shadowing, que copia requisições ao vivo para um segundo serviço para avaliação, declara appliesTo: dataplane.aggrega.ai/request-mirroring — apenas a chave — e o analisador estático avalia isso contra os labels do alvo antes que qualquer coisa seja renderizada, de modo que anexá-la a um componente que não consegue espelhar de forma alguma interrompe o build com uma violação de seletor que nomeia a Feature e o seletor que ela não satisfez. O compilador trata cada uma dessas strings como opaca, exatamente como trata as demais.
  • Por que o prefixo nomeia o caminho do tráfego, e não um tipo de componente. Espelhamento, identidade do chamador e verificação do upstream não são propriedades de gateway — são propriedades de qualquer coisa que esteja no caminho da requisição, e uma service mesh adicionada a um catálogo tem as três. Nomear a família pelo tipo de componente que por acaso as carregou primeiro obrigaria cada tipo posterior a repetir o mesmo vocabulário sob seu próprio prefixo, deixando uma capacidade com vários nomes e nenhum seletor capaz de abrangê-los.
  • Por que a fidelidade vai no valor. Dois componentes podem ambos espelhar requisições e ainda assim diferir da maneira que importa a uma Feature: um copia cada requisição correspondente, o outro copia uma fração configurável delas. Uma chave que dissesse apenas se um componente espelha admitiria ambos e deixaria a diferença para ser descoberta depois da renderização. Colocar a fidelidade no valor permite pedi-la da forma, entre duas, que se ajusta à Feature. Uma Feature que não funciona de forma alguma sem uma determinada fidelidade nomeia esse valor em seu seletor. Uma Feature que ainda funciona com a fidelidade menor seleciona apenas pela chave, e sua realização recusa a configuração que o componente não consegue honrar: copiar o fluxo inteiro funciona em todo componente que espelha, então core/traffic-shadowing se anexa a todos eles, e a realização para um componente que declara full-rate recusa uma fração abaixo de 100 com uma mensagem que nomeia a fração pedida e a fidelidade que o componente declara — duas coisas que a violação de seletor não diz. Os valores são, portanto, derivados do que os produtos disponíveis no mercado implementam, e não compostos como uma taxonomia: request-mirroring carrega full-rate e sampled porque os proxies reais se dividem exatamente assim, um oferecendo uma configuração de taxa de cópia e outro não oferecendo nenhuma.
  • Um valor afirma uma capacidade, nunca um estado configurado. Para um desenvolvedor os dois se leem de forma idêntica, e só um deles é uma propriedade do componente. Um proxy capaz de verificar o certificado de um upstream carrega upstream-tls: trust-anchor quer alguma implantação habilite a verificação, quer não — o label é aquilo pelo qual uma Feature seleciona antes que qualquer coisa seja configurada, então carregá-lo de configuração o tornaria ilegível justamente no momento em que é usado.
  • O que a biblioteca padrão traz. core/gateway/nginx carrega request-mirroring: full-rate, upstream-tls: trust-anchor e concurrency-cap: total, um único limite sobre cada requisição que encaminha. core/gateway/contour carrega request-mirroring: sampled, caller-identity: client-certificate e upstream-tls: trust-anchor. core/gateway/envoy-gateway carrega os mesmos três valores que core/gateway/contour, além de period-budget: tokens, que conta os tokens informados por cada resposta de um modelo que ele serve por meio do Envoy AI Gateway, e concurrency-cap: per-target, um limite sobre as requisições em andamento para cada modelo que ele serve. core/gateway/kong carrega upstream-tls: trust-anchor e prompt-guard: pattern-list, com seu AI Prompt Guard comparando as mensagens de uma requisição de modelo com as listas que suas rotas contêm. core/gateway/tyk carrega upstream-pinning: public-key, que core/upstream-key-pinning seleciona. core/gateway/litellm carrega caller-identity: injected-header, content-masking: entity-recognition, period-budget: cost, prompt-guard: pattern-list, upstream-tls: trust-anchor e concurrency-cap: per-target, um limite sobre as requisições em andamento para cada entrada de seu mapa de modelos. core/gateway/cloudflare-ai-gateway carrega period-budget: cost. core/gateway/apisix carrega period-budget: tokens, que conta os tokens informados pela resposta de cada modelo sem precificar nada, e prompt-guard: pattern-list. core/gateway/kong-enterprise carrega period-budget: tokens, que conta os tokens informados pela resposta de cada modelo, e content-masking: entity-recognition. core/gateway/traefik-hub carrega content-masking: entity-recognition e prompt-guard: pattern-list, com seu middleware Content Guard mascarando as correspondências dos padrões que sua configuração contém ou os tipos de entidade que um analisador Presidio chamado por ele detecta, ou recusando uma requisição que um padrão corresponde, e period-budget: cost, precificado pela lista de preços por modelo que acompanha seu middleware de cota, que pode em vez disso contar os tokens informados por cada resposta. core/gateway/agentgateway carrega content-masking: pattern-list e prompt-guard: pattern-list, com sua proteção baseada em expressões regulares mascarando ou recusando as correspondências dos padrões que sua configuração contém, sem reconhecer tipos de entidade, e period-budget: cost, os orçamentos que ele mantém por chave de API em dólares americanos, precificados por seu catálogo de custos de modelos, ou em tokens. core/gateway/higress carrega content-masking: pattern-list, com seu plugin ai-data-masking mascarando as correspondências dos padrões que sua configuração contém no texto das mensagens de uma requisição de chat, sem reconhecer tipos de entidade, e period-budget: tokens, que conta juntos os tokens de prompt e de completion informados por cada resposta sem precificar nada. core/gateway/azure-api-management carrega period-budget: tokens, que conta juntos os tokens de prompt e de completion informados por cada resposta, com uma contagem separada em cada gateway da instância, sem precificar nada. core/security/nemo-guardrails e core/security/trustyai-guardrails-gateway, duas proteções que ficam no caminho de um modelo e julgam uma requisição com um classificador treinado, carregam prompt-guard: classifier, que os sockets guard do gateway de IA e do gateway NGINX selecionam. Os gateways de IA entre eles — core/gateway/litellm, core/gateway/cloudflare-ai-gateway, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/kong-enterprise, core/gateway/traefik-hub, core/gateway/agentgateway, core/gateway/higress e core/gateway/azure-api-management — carregam semantic e os demais não carregam nenhum valor gateway.aggrega.ai/intelligence, o que é a separação funcionando, e não uma exceção a ela: uma Feature que precisa de espelhamento alcança os três componentes que o têm, ao passo que um seletor de nível de produto alcançaria entre eles apenas o Envoy Gateway, por um motivo que não diz nada sobre espelhamento, e uma Feature que precisa de uma proteção de prompt, mascaramento de conteúdo ou um orçamento por período alcança um gateway de IA pelo que ele pode fazer, e não pelo nível em que está, enquanto uma que limita as requisições em andamento alcança o gateway NGINX, que não carrega valor de nível, assim como alcança o Envoy Gateway e o gateway de IA, e uma que recusa uma requisição com base em uma lista de padrões alcança o Kong de código aberto, que também não carrega nenhum, assim como alcança o APISIX. Um componente sem nada a descrever em um desses eixos não carrega ali nenhum valor, em vez do mais fraco, de modo que um seletor que nomeia qualquer valor nesse eixo corretamente não se anexa a ele.

12. security.aggrega.ai/text-anonymization

  • Quem a escreve? O arquiteto de plataforma, em um serviço que participa do mascaramento de texto sensível. Quando esse trabalho é dividido entre dois serviços, analyzer vai no que encontra os trechos sensíveis de um texto e os informa, e anonymizer no que reescreve os trechos que recebe; sanitizer vai em um serviço que faz as duas coisas em uma só chamada, encontrando os trechos sensíveis no texto que lhe é enviado e reescrevendo-os ele mesmo, respondendo com o texto reescrito.
  • Quem a consome? O analisador estático, por meio do seletor usesSchema de um socket.
  • Caso de uso do compilador: é assim que um consumidor recebe o endereço certo. core/gateway/litellm declara um socket pii_analyzer que seleciona security.aggrega.ai/text-anonymization=analyzer e um socket pii_anonymizer que seleciona o valor anonymizer, de modo que conectar qualquer um dos serviços ao socket do outro interrompe o build com uma violação de seletor que nomeia o socket. core/gateway/kong-enterprise declara um socket, pii_sanitizer, que seleciona o valor sanitizer, e core/gateway/traefik-hub um, pii_analyzer, que seleciona apenas o valor analyzer, porque o Content Guard que sua Recipe de chart escreve para core/data-masking substitui por conta própria o que o analisador encontra. O compilador roteia o endereço que o componente selecionado publica e não verifica nada sobre o que responde ali.
  • O que a biblioteca padrão traz. core/security/presidio-analyzer carrega analyzer e core/security/presidio-anonymizer carrega anonymizer. Ambos falam a API HTTP do Presidio que o gateway de IA chama quando uma vinculação de core/data-masking, ou o próprio values.log_masking do gateway, lista tipos de entidade, e o Content Guard do Traefik Hub chama apenas o analisador quando uma vinculação de core/data-masking nesse gateway os lista. core/security/kong-ai-pii-service carrega sanitizer e fala a API do serviço AI PII da Kong, que o AI PII Sanitizer do Kong Gateway Enterprise chama com cada texto que mascara, incluindo suas expressões regulares, enquanto houver uma vinculação de core/data-masking nesse gateway. O sanitizer não lhe apresenta nenhuma credencial e todo texto chega a ele sem máscara, por isso seu endereço é interno ao cluster e não deve ser exposto fora do cluster.

13. model.aggrega.ai/api

  • Quem escreve? O Platform Architect, em todo componente da categoria model e em um gateway que serve uma API de modelos. O valor indica qual API de modelos responde no endereço que o componente publica: openai quando é a API da OpenAI — a do próprio fornecedor ou a implementação dela por um servidor —, anthropic quando é a Messages API da Anthropic, gemini quando é a Gemini API do Google, e native quando é a API própria do produto e nenhuma dessas, que um consumidor alcança pelo cliente desse produto. Cada valor é extraído da referência do próprio produto, e um componente o carrega independentemente do que uma determinada Release configure.
  • Quem consome? O Static Analyzer, pelo seletor usesSchema de um socket, e as asserções do gateway de IA, de core/gateway/kong, de core/gateway/kong-enterprise, de core/gateway/apisix, de core/gateway/envoy-gateway, de core/gateway/traefik-hub, de core/gateway/agentgateway e de core/gateway/higress, em cada conexão com seus sockets models.
  • Caso de uso do compilador: é o que permite que um único socket aceite tanto um modelo quanto um gateway que serve modelos. O socket model de todo agente, exceto os cinco runtimes citados abaixo, o socket target_model de core/ai-tool/model-invocation e os dois sockets de modelo de core/datastore/cognee selecionam component.aggrega.ai/category in (ai-model, gateway), model.aggrega.ai/api: o requisito de categoria admite as duas categorias, e o requisito de chave admite, dentre os componentes delas, apenas os que carregam o rótulo, de modo que conectar esse socket a um gateway que não serve nenhuma API de modelos interrompe o build com uma violação de seletor que nomeia o socket. Todos os requisitos de um seletor precisam ser atendidos e suas alternativas ficam dentro do conjunto de uma única chave, por isso a única chave a que os dois tipos de componente respondem precisa estar em todo componente de modelo e também no gateway — e é por isso que o rótulo nomeia uma API em vez de marcar apenas gateways. Um gateway que o carrega publica as chaves endpoint e model que um modelo publica, de modo que a Recipe de um consumidor lê qualquer um dos dois da mesma forma. Um agente cujas Recipes entregam as variáveis de uma única API de modelos nomeia, em vez disso, o valor dela: os sockets model de core/ai-agent/openai-agents-sdk, core/ai-agent/agent-framework e core/ai-agent/mastra selecionam model.aggrega.ai/api=openai, o de core/ai-agent/claude-agent-sdk seleciona model.aggrega.ai/api=anthropic e o de core/ai-agent/google-adk seleciona model.aggrega.ai/api=gemini, de modo que conectar um deles a um modelo ou a um gateway que serve outra API interrompe o build com uma violação de seletor que nomeia o socket. O socket de core/ai-agent/google-adk também restringe a categoria a ai-model, recusando todo gateway, porque o cliente do ADK não lê nenhum endereço e enviaria a credencial de um gateway ao próprio endereço do Google. O gateway de IA lê o valor em vez de selecionar por ele: seu socket models seleciona component.aggrega.ai/category=ai-model, admitindo todo modelo, e como o gateway descreve ao seu proxy um modelo conectado ali apenas pela API da OpenAI, a asserção do seu Component interrompe o build em uma conexão cujo destino carrega qualquer valor diferente de openai, nomeando a conexão e orientando a digitar esse upstream no mapa de modelos digitado à mão do gateway. core/gateway/kong, core/gateway/kong-enterprise, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/traefik-hub, core/gateway/agentgateway e core/gateway/higress o leem da mesma forma em seus próprios sockets models, porque cada um escreve a rota de um modelo conectado, ou no agentgateway sua entrada de modelo, apenas para a API da OpenAI. O compilador trata o valor como uma string opaca e não verifica nada sobre o que responde no endereço.
  • O que a biblioteca padrão traz. core/gateway/litellm, core/gateway/kong, core/gateway/kong-enterprise, core/gateway/apisix, core/gateway/envoy-gateway, core/gateway/traefik-hub, core/gateway/agentgateway e core/gateway/higress carregam openai, assim como os servidores auto-hospedados core/ai-model/vllm, ollama, docker-model-runner, tgi, tei, nvidia-nim e litellm, as APIs gerenciadas core/ai-model/openai, openai-embedding e nvidia-api, e o broker core/ai-model/openai-compatible, que é apontado para um serviço que fala essa API. core/ai-model/anthropic carrega anthropic, e core/ai-model/gemini carrega gemini. Todos os outros componentes de modelo carregam native.

14. tool.aggrega.ai/transport

  • Quem escreve? O Platform Architect, em uma ferramenta que um consumidor alcança por um transporte que precisa falar. O valor nomeia esse transporte.
  • Quem consome? O Static Analyzer, pelo socket de ferramentas de um consumidor.
  • Caso de uso do compilador: é assim que um consumidor recebe apenas as ferramentas com que consegue se comunicar. Um socket de ferramentas seleciona component.aggrega.ai/category=ai-tool, tool.aggrega.ai/transport=http: o requisito de categoria admite ferramentas e nada mais, e o requisito de transporte admite apenas as ferramentas alcançadas por HTTP, de modo que conectar esse socket a uma ferramenta que não carrega tal rótulo interrompe o build com uma violação de seletor que nomeia o socket. A forma de alcançar uma ferramenta precisa ser um rótulo e não um valor publicado, porque um seletor lê rótulos e nunca o conteúdo de um valor. O compilador trata o valor como uma string opaca e não verifica nada sobre o que responde no endereço.
  • O que a biblioteca padrão traz. core/ai-tool/mcp carrega http. Ele vincula um servidor Model Context Protocol a um agente, e o Manifest escolhe como esse servidor é realizado: helm/mcp e compose/mcp executam uma imagem que serve o protocolo por HTTP; helm/mcp-stdio-bridge e compose/mcp-stdio-bridge executam um pacote que fala apenas stdio atrás de uma ponte fixada que o serve por HTTP; helm/mcp-remote e compose/mcp-remote alcançam um servidor que outra pessoa opera e não executam nada. Toda realização publica os mesmos host, port, endpoint, protocol e credential_header, de modo que a conexão de um consumidor não muda com a realização. As credenciais próprias de um servidor são variáveis de ambiente, mantidas no slot server_env da ferramenta: entregues à ponte por referência no Kubernetes e, no Docker Compose, escritas no ambiente do serviço tal como entregues, onde uma referência a uma variável do Compose mantém a credencial fora do arquivo; a credencial de um servidor remoto é mantida pelo consumidor em sua própria conexão com a ferramenta e apresentada sob o cabeçalho que credential_header nomeia, Authorization, a menos que a Release nomeie outro. Onde um servidor remoto lê sua chave do próprio endereço, o consumidor também mantém o endereço inteiro nessa conexão, em um slot endpoint preenchido no Kubernetes por uma referência a um Secret e no Docker Compose por uma referência a uma variável do Compose, de modo que a chave não chega a nenhum arquivo renderizado, enquanto o infra.endpoint da ferramenta guarda o endereço sem a parte que carrega a chave; examples/mcp-address-from-secret constrói os dois. core/ai-agent/openai-agents-sdk, core/ai-agent/claude-agent-sdk, core/ai-agent/agent-framework, core/ai-agent/google-adk e core/ai-agent/mastra, e as plataformas de fluxo core/ai-agent/flowise e core/ai-agent/n8n, declaram um socket de ferramentas dessa forma, tools, e entregam o endereço de cada ferramenta conectada, e a credencial da conexão por referência, em variáveis nomeadas de acordo com o alias da conexão, enquanto uma conexão que escreve um bloco inject: recebe o que esse bloco determina no lugar das variáveis derivadas do que a ferramenta publica, e o que seus slots credential e endpoint contêm permanece sob o nome do alias; um consumidor próprio declara um da mesma forma. Cada uma das três plataformas de fluxo leva para a plataforma, no deploy, um fluxo escrito no Aggregate, nos dois destinos: o Langflow carrega a definição transportada do seu diretório de fluxos a cada inicialização, o chatflow do Flowise é semeado por uma etapa única que se autentica como a conta proprietária que a Release nomeia, e o workflow do n8n é importado por uma etapa de init antes de a plataforma iniciar. core/ai-agent/langflow declara um socket tools da mesma forma, que não admite nenhum bloco inject:, e, em vez disso, entrega cada conexão por meio desse fluxo, porque o componente MCP Tools do Langflow aceita o endereço de um servidor apenas das configurações do próprio Langflow ou do fluxo, nunca de uma variável: suas Recipes escrevem o endereço da ferramenta no nó MCP Tools cujo servidor tem o nome do alias da conexão, entregam a credencial da conexão por referência como uma variável que o cabeçalho desse nó nomeia — sob Authorization, uma variável que contém Bearer e a credencial — e deixam os hosts das ferramentas e dos stores conectados passarem pela proteção do Langflow contra endereços privados. As três plataformas também declaram um socket vector_store que seleciona datastore.aggrega.ai/engine in (vector, semantic-memory, search), que entrega da mesma forma o endereço de cada store conectado — o endpoint que ele publica, para core/datastore/pgvector uma URI de conexão sem senha, ou um composto a partir do seu protocolo, host e porta — e a credencial da conexão por referência; um store que também publica seu banco de dados e seu usuário, como faz core/datastore/pgvector, chega ao Flowise e ao n8n também nessas partes, já que o nó vetorial PostgreSQL de nenhuma das duas plataformas aceita uma string de conexão; o Langflow, cujo componente PGVector aceita uma única string, recebe esse store como AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, tendo como senha a credencial da conexão, por referência no Kubernetes e tal como entregue no Docker Compose. Um chatflow do Flowise lê uma variável entregue por meio de uma variável Runtime de mesmo nome criada na página Variables do Flowise, e um workflow do n8n lê uma por meio de $env apenas onde o Aggregate define o valor allow_env_access_in_nodes da plataforma, já que por padrão suas Recipes mantêm o bloqueio do n8n ao acesso ao ambiente nos nós.

2. Abstração de portas (a convenção de zero portas)

O catálogo open source da biblioteca padrão do Aggrega recomenda omitir as declarações de portas físicas da camada cognitiva dos Components, encaminhando a escolha de portas pela Recipe de Ops. Os autores que seguem essa recomendação evitam colisões de portas entre destinos de implantação, impedem APIs de backdoor que contornam o Injection Contract e mantêm a topografia de rede flexível entre provedores. O próprio compilador é agnóstico em relação às portas — ele repassa quaisquer valores que o JSON Schema resolvido permita. A convenção opera com uma via de escape explícita para sistemas legados cujas portas físicas não podem mudar.

  • O padrão cloud-native (injeção dinâmica): para cargas de trabalho modernas, os Components omitem totalmente as portas físicas (sem arrays ports ou expose) da sua declaração schema:. As Recipes de Platform Ops escolhem a porta TCP/UDP interna e a publicam como uma chave provides nomeada, que os consumidores downstream leem pelo Injection Contract .context.uses.
  • A via de escape legada (declaração explícita): quando um componente legado tem uma porta fixa no código e imutável, o Platform Architect expõe explicitamente um campo port na declaração schema: do Component. Isso dá ao Developer uma forma validada de declarar a restrição física. O compilador leva o valor pelo pipeline sem alterá-lo; a Recipe o consome via {{ .values.port }}.
  • Portas operacionais (fora de banda): as portas usadas estritamente pela infraestrutura do cluster (por exemplo, scraping do Prometheus, métricas de sidecar do Envoy) permanecem ocultas da camada cognitiva do Developer. Elas são injetadas fora de banda pelo Platform Ops por meio de Features (por exemplo, vinculando a Feature core/prometheus-exporter, cuja porta de scraping é infra do operador).

3. Schemas específicos de domínio (inteligência de configuração)

Os blocos values do desenvolvedor (opacos para o compilador Go, mas estritamente tipados pela declaração schema: do Component) são validados para dar suporte a fluxos de trabalho de IA explícitos:

  • Links entre agentes (arrays de dependências): o schema compartilhado de parâmetros de agente da biblioteca padrão traz tools_allowed e agents_allowed como arrays de values que nomeiam os Components do catálogo que um agente pode invocar ou para os quais pode delegar — uma convenção documentada que o compilador não avalia. Um link que o compilador conecta como aresta topológica é um socket uses que o Component do agente declara em seu usesSchema, e o seletor desse socket é o que o build verifica.
  • Particionamento profundo da memória cognitiva (CoALA): em vez de um único bucket de memória plano, um arquiteto pode declarar um socket cognitive_memory cujas conexões mapeiam as memórias semântica, episódica e procedural para destinos de infraestrutura distintos como arestas topológicas explícitas, de modo que os motores de políticas possam avaliar e exigir proteções de acesso granulares (por exemplo, garantir que um agente possa ler a memória semântica, mas não sobrescrevê-la se for sequestrado). A biblioteca padrão não declara nenhum socket desse tipo.
  • Pipelines multimodais: o schema: de um Component pode declarar etapas de execução explícitas, como document_chunking, embedding_generation e storage_routing, como values tipados, de modo que um fluxo de dados declarativo seja validado antes que qualquer coisa seja renderizada. A biblioteca padrão não declara nenhuma etapa desse tipo.

4. Inteligência de gateway e roteamento

Os gateways de IA da biblioteca padrão carregam os controles para rotear requisições para APIs de LLM: core/gateway/litellm, que roda no cluster, e dois serviços hospedados — core/gateway/cloudflare-ai-gateway, o gateway hospedado da Cloudflare, que sua Recipe de terraform cria em uma conta da Cloudflare, e core/gateway/azure-api-management, o gateway de IA do Azure API Management, cuja Recipe de terraform adiciona uma API que serve um modelo, com seu backend e sua política, a uma instância do API Management que já existe. As Recipes de helm e compose de cada gateway hospedado o referenciam onde ele já está configurado. Alguns controles são valores no próprio gateway e outros são Features vinculadas a ele, e cada Feature abaixo informa em qual gateway a biblioteca padrão a realiza. Em um gateway hospedado, todo controle é escrito na configuração do próprio gateway — uma configuração do recurso do gateway da Cloudflare, um elemento da política da API no Azure API Management —, por isso apenas sua Recipe de terraform pode carregar um, e suas Recipes de helm e compose interrompem o build em qualquer vinculação. Abaixo, “o gateway de IA” é core/gateway/litellm, “o gateway hospedado” é core/gateway/cloudflare-ai-gateway, e o gateway do Azure API Management é nomeado por extenso.

Fora do Aggrega, em tempo de execução

agente

seu socket model, conectado ao gateway

gateway de IA

com os controles anexados a ele

orçamento de tokens

cache semântico

escudo contra injeção de prompt

modelo

um provedor por trás do gateway

As requisições de um agente passam pelo gateway ao qual seu socket model está conectado, então cada controle anexado ao gateway fica entre o agente e o modelo. Os três desenhados aqui são as Features core/period-budget, core/semantic-caching e core/prompt-injection-shield, mostradas lado a lado pelo lugar que ocupam, e não como a configuração de um único gateway: as entradas abaixo dizem qual gateway realiza cada controle e o que interrompe o build.

  • Os modelos por trás dele: o mapa de modelos do gateway de IA — os aliases que ele serve, cada um com o upstream para o qual uma requisição para ele é enviada — tem duas partes. Um componente de modelo conectado ao socket models do gateway, gerenciado ou auto-hospedado, é servido sob o alias da conexão, com sua entrada escrita a partir do endpoint e do model que o modelo publica, strings que o compilador repassa à configuração do gateway e nunca resolve; o modelo é, portanto, um componente do grafo, alcançado por uma aresta própria. O gateway descreve esse modelo ao seu proxy apenas pela API da OpenAI, de modo que uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai interrompe o build, nomeando a conexão. A outra parte é o values.models do gateway, entradas digitadas à mão na notação provedor/modelo do próprio proxy: para um upstream que o catálogo não modela, para um provedor cuja API própria não é a API da OpenAI, e para várias entradas que compartilham um alias, o que modelos conectados não podem fazer, já que cada um é servido sob o alias da sua própria conexão. Uma entrada conectada apresenta a credencial que sua própria conexão carrega, como descreve “A chave que um chamador apresenta” abaixo, e nunca o provider_key do gateway; toda entrada digitada à mão apresenta a única credencial desse slot. Um alias que as duas partes publicam interrompe o build, nomeando-o, assim como um gateway ao qual nenhuma das partes fornece um modelo.

  • No caminho de um agente: o gateway publica um endpoint e um model, as chaves que um componente de modelo publica, e carrega model.aggrega.ai/api: openai, de modo que o socket model de um agente aceita o gateway diretamente e todo controle vinculado a ele fica entre esse agente e os provedores por trás dele. O model que ele publica é o alias que seu values.model nomeia, no qual o build é interrompido quando nenhuma parte do mapa o publica; ele só pode ser omitido onde o gateway serve um único alias e uma entrada de values.models o publica, que passa a ser o publicado. Um chamador que queira outro alias publicado pelo mapa o pede pelo nome ao mesmo endpoint. core/gateway/cloudflare-ai-gateway publica as mesmas duas chaves — o endereço de um dos endpoints do gateway, composto a partir da conta da Cloudflare e do id do gateway, e o modelo que um chamador pede, que o gateway encaminha sem verificar — mas não carrega nenhum model.aggrega.ai/api, de modo que o socket model de um agente não o aceita. core/gateway/azure-api-management também as publica — o endereço da sua API, composto a partir do host da instância e do caminho da API, e o modelo que um chamador pede, encaminhado sem verificação — e também não carrega nenhum model.aggrega.ai/api: a API responde à requisição chat completions da OpenAI, mas por padrão um chamador apresenta uma chave de assinatura do API Management em um cabeçalho próprio em vez do bearer token da OpenAI, por isso um cliente OpenAI simples não basta para chamá-la.

  • Kong na frente de modelos: core/gateway/kong, o gateway Kong open source, serve os modelos conectados ao seu próprio socket models pelo AI Proxy da Kong e, dos controles abaixo, realiza apenas os padrões de negação de prompts, como o AI Prompt Guard da Kong em cada rota de cada modelo conectado. Cada modelo conectado ganha uma rota de chat e uma rota de completion sob /<alias>/v1, escritas a partir do endpoint e do model que o modelo publica, e suas Recipes importam essas rotas para o backend PostgreSQL do gateway antes que ele inicie. A rota escolhe o modelo, de modo que uma requisição é enviada ao modelo que seu caminho nomeia, qualquer que seja o nome de modelo que ela carregue. O gateway apresenta a credencial própria de cada conexão como um bearer token que sua configuração lê pelo nome do ambiente do gateway, e uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai interrompe o build. Ele publica a rota do alias que seu values.model nomeia como seu endpoint e esse alias como seu model, e carrega model.aggrega.ai/api: openai, de modo que o socket model de um agente o aceita como aceita o gateway de IA. Sem nada conectado a esse socket, o gateway não serve nenhum modelo e publica as duas chaves vazias, e um agente conectado a ele então não lê nenhum endereço nem nome de modelo. A importação adiciona e atualiza rotas e não remove nenhuma, de modo que uma rota cuja conexão é removida continua respondendo, e o prompt guard que uma vinculação de core/prompt-deny-patterns escreveu continua recusando depois que a vinculação é removida, até que cada um seja excluído pela Admin API da Kong. Pelo mesmo motivo, o gateway não declara chamadores, e suas rotas de modelo não verificam a chave de nenhum chamador: a Kong distingue chamadores apenas como os consumers que um plugin de autenticação nomeia, e um consumer e sua chave, uma vez importados, continuariam capazes de se autenticar depois que o chamador fosse removido da Release, e uma chave rotacionada deixaria a antiga funcionando; nem pode uma chave key-auth ser mantida por referência, de modo que a chave de um chamador só poderia chegar à Kong como um literal em um arquivo renderizado.

  • Kong Gateway Enterprise na frente dos modelos: core/gateway/kong-enterprise, a edição paga da Kong do mesmo gateway baseado em banco de dados, serve os modelos conectados ao seu próprio socket models nas rotas que core/gateway/kong serve, escritas a partir da mesma configuração e importadas no seu backend PostgreSQL por uma etapa no próprio pod do gateway antes que o gateway inicie, e publica seu endpoint e seu model como o Kong faz. Sua única realização é uma Recipe de chart sobre o chart Helm oficial da Kong; não há realização compose. Ele executa a imagem que a Release nomeia em infra.image, tag de versão incluída, porque a Kong distribui a imagem enterprise sob seus próprios termos e, por isso, o catálogo não nomeia nenhuma; o build é interrompido enquanto essa chave não estiver definida ou sua tag não trouxer nenhuma versão. A licença chega ao gateway por referência ao Secret vinculado ao seu slot obrigatório license, nunca como valor, e o build é interrompido enquanto nada vincular esse slot. O compilador não valida nenhuma licença e não contata nenhum fornecedor, então uma Release que compila sem erros não diz nada sobre uma licença: o Kong lê a licença quando um nó inicia, e um nó sem licença válida se comporta como com uma expirada, com sua configuração de entidades somente leitura e seu tráfego de proxy servido com a configuração já existente. A Kong vende seus plugins de IA como sua oferta AI Gateway Enterprise, um direito de uso dentro da licença que nenhum build consegue ver, e ignora tal plugin em vez de recusá-lo onde a licença não tem esse direito, então vincular core/semantic-caching, core/period-budget, core/data-masking, core/fallback-chain, core/retry-policy ou core/target-selection interrompe o build até que a Release defina infra.ai_gateway_entitled como true, afirmando que a licença o inclui. Dos controles abaixo, ele realiza o orçamento por período e a cadeia de fallback, cada um escrito nas rotas que o gateway importa, e realiza core/data-masking como “Exfiltração de dados e interceptação de payloads” descreve abaixo; suas realizações do cache semântico, da política de retry e da seleção de destino interrompem toda vinculação, cada uma informando o motivo, e o limite de concorrência, o registro de auditoria, a triagem de injeção de prompt, a validação de respostas e os padrões de negação de prompts não têm realização ali, então a vinculação de qualquer um deles interrompe o build. Um conjunto de rotas alterado faz o rollout do gateway, e a importação adiciona e atualiza rotas sem remover nenhuma, então uma rota cuja conexão é removida, e um plugin que uma Feature de IA escreveu, depois que a Feature é removida, permanecem no banco de dados até serem excluídos pela Admin API do Kong; pelos motivos que o item acima apresenta, ele também não declara chamadores, e suas rotas de modelos não verificam a chave de nenhum chamador. Que um gateway em execução aplique qualquer um desses controles não é observado por nenhum build.

  • APISIX na frente dos modelos: core/gateway/apisix, o gateway de código aberto Apache APISIX, serve os modelos conectados ao seu próprio socket models por meio do proxy de IA do APISIX onde o Manifest vincula sua Recipe de chart, que executa o APISIX 3.18.0. Cada modelo conectado recebe uma rota de chat e uma rota de completion sob /<alias>/v1 — apenas a rota de chat enquanto um orçamento por período ou padrões de negação de prompts estiverem vinculados, já que o APISIX não conta tokens em uma requisição de completion e seu prompt guard não lê nenhuma —, escritas a partir do endpoint e do model que o modelo publica em um arquivo de rotas renderizado com o gateway, que ele lê na inicialização e novamente sempre que o arquivo muda. Um gateway que lê suas rotas desse arquivo não lê nenhum etcd e não executa nenhuma Admin API, então, com um modelo conectado, uma conexão etcd ou uma vinculação admin_key interrompe o build, e sem nada conectado ambas são obrigatórias. A rota escolhe o modelo. O gateway apresenta a credencial própria de cada conexão como um bearer token que suas rotas leem pelo nome do ambiente do gateway, e uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai interrompe o build. Ele publica a rota do alias que seu values.model nomeia como seu endpoint e esse alias como seu model, e traz model.aggrega.ai/api: openai, então o socket model de um agente o aceita como aceita o gateway de IA; sem nada conectado, publica ambas as chaves vazias. Uma rota cuja conexão é removida desaparece da próxima renderização. Uma Release pode nomear os chamadores do gateway em infra.callers e suas chaves pelo slot caller_keys, um Secret que contém uma chave de dados por nome de chamador: cada chamador é então um consumer no arquivo de rotas cuja chave é lida pelo nome desse Secret, e toda rota recusa com HTTP 401 uma requisição que não apresenta nenhuma chave declarada como Authorization: Bearer <key> — como um cliente OpenAI apresenta uma — e remove a chave da requisição que encaminha. Sem chamadores, as rotas ficam abertas. Sua Recipe de workload, com o APISIX 3.17.0, mantém suas rotas no etcd, não renderiza nenhuma e interrompe o build diante de uma conexão a esse socket e de infra.callers. Dos controles abaixo, ele realiza o orçamento por período, um cache semântico para os chamadores que declara e os padrões de negação de prompts.

  • Envoy Gateway na frente dos modelos: core/gateway/envoy-gateway, o Envoy Gateway de código aberto, serve os modelos conectados ao seu próprio socket models por meio do Envoy AI Gateway, cujo controlador, core/gateway/envoy-ai-gateway-operator, o gateway chama como seu servidor de extensão pelo seu socket extension. Um modelo conectado sem nada nesse socket interrompe o build, e, com o controlador conectado, a Release coloca o gateway em envoy-gateway-system ou o build é interrompido. Cada modelo conectado se torna uma regra de uma única rota de IA vinculada ao gateway, escolhida pelo nome de modelo que uma requisição traz, com um backend escrito a partir do endpoint e do model que o modelo publica, então todo modelo conectado é servido sob /v1 no próprio endereço do gateway. O gateway apresenta a credencial própria de cada conexão como um bearer token, que o controlador do Envoy AI Gateway lê do Secret que a credencial nomeia, e uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai interrompe o build. Enquanto um modelo estiver conectado, toda rota no gateway adota o buffer de requisição de 50Mi por conexão que o Envoy AI Gateway configura. Ele publica seu endereço, qualificado com envoy-gateway-system para que seja resolvido a partir de qualquer namespace, como seu endpoint e o alias que seu values.model nomeia como seu model, e traz model.aggrega.ai/api: openai, então o socket model de um agente o aceita como aceita o gateway de IA; sem nada conectado, publica ambas as chaves vazias. O webhook do controlador serve um certificado que o cert-manager emite, então o cert-manager já precisa estar em execução no cluster, a menos que a Release nomeie, no infra.webhook_tls_secret do controlador, um Secret com um certificado fornecido pelo operador, que o webhook então serve. Dos controles abaixo, ele realiza o orçamento por período, a política de retry e o limite de concorrência, cada um escrito na única política de tráfego da rota que serve seus modelos. Ele não realiza o cache semântico nem a validação de respostas, já que o Envoy AI Gateway não guarda nenhuma resposta com a qual responder a uma requisição posterior e não verifica nenhuma resposta em relação a um schema, nem a cadeia de fallback: o Envoy AI Gateway faz fallback tentando novamente em outros backends da regra de um modelo, e o gateway escreve a contagem de retries da sua única política de tráfego em cada regra da rota que serve seus modelos, então uma lista de fallback obteria exatamente seus envios apenas onde a lista de todo modelo conectado tivesse o mesmo comprimento. Ele realiza core/audit-logging como seu log de acesso, como “Registro de auditoria” descreve abaixo, e recusa pelo nome o que esse log não consegue guardar: quanto uma requisição custou, já que o custo por requisição que o Envoy AI Gateway consegue calcular não tem unidade e o gateway não guarda preços; um chamador que o gateway verificou, já que nada nesse caminho verifica o chamador; e uma retenção, já que esse log não tem armazenamento nem configuração de retenção. examples/envoy-ai-gateway-token-budget constrói o caminho inteiro, com um agente que alcança o modelo gerenciado da OpenAI pelo gateway.

  • agentgateway na frente dos modelos: core/gateway/agentgateway, o agentgateway de código aberto, serve os modelos conectados ao seu próprio socket models a partir de um único arquivo de configuração que suas Recipes renderizam. Cada modelo conectado é uma entrada desse arquivo, nomeada pelo alias da conexão e escrita a partir do endpoint e do model que o modelo publica como um provedor de chat completions compatível com OpenAI, então todo modelo conectado é servido sob /v1 no próprio endereço do gateway e é o nome de modelo que uma requisição traz que o escolhe: a requisição alcança o modelo pedindo o nome de modelo que o modelo publica, e um nome que nenhuma conexão traz é respondido com HTTP 404. O gateway apresenta a credencial própria de cada conexão como um bearer token, que o arquivo nomeia como uma variável que o gateway lê do seu ambiente quando lê o arquivo, sendo que uma variável ausente ali o impede de iniciar, e uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai interrompe o build. Ele publica essa URL base /v1 como seu endpoint e o alias que seu values.model nomeia como seu model, e traz model.aggrega.ai/api: openai, então o socket model de um agente o aceita como aceita o gateway de IA; sem nada conectado, publica ambas as chaves vazias. Duas Recipes executam a mesma imagem, fixada por digest: agentgateway-chart renderiza o chart Helm standalone do projeto, obtido do registry do projeto, e realiza os controles abaixo, e agentgateway executa a imagem como um único serviço Docker Compose e não realiza nenhum deles, nem chamadores, então uma vinculação ali interrompe o build informando seu tipo; use o chart no Kubernetes, onde o build consegue alcançar esse registry. No chart, uma Release pode nomear os chamadores do gateway em infra.callers e suas chaves pelo slot caller_keys, como no APISIX: cada chamador é uma chave de API do arquivo, verificada em modo estrito e lida pelo nome desse Secret, então uma requisição de modelo que não apresenta nenhuma chave declarada como Authorization: Bearer <key> é recusada com HTTP 401, e a chave é removida da requisição encaminhada; sem chamadores, as rotas de modelos ficam abertas. O agentgateway insere cada chave que o arquivo nomeia dessa forma, a de um modelo conectado em qualquer uma das Recipes e a de um chamador no chart, no texto do arquivo antes de ler o arquivo como YAML, então uma chave precisa ser um token simples — letras, dígitos e -, ., _, ~, +, / e = — e outros caracteres podem ser carregados como uma chave diferente ou parar o gateway. O gateway lê seu arquivo novamente quando ele muda, então um chamador removido da Release é recusado assim que o arquivo montado é atualizado. Enquanto core/audit-logging, ou core/period-budget com escopo caller, estiver vinculado, a Recipe de chart dá ao gateway um armazenamento, um arquivo SQLite em um volume próprio, e executa uma única réplica. Dos controles abaixo, ele realiza o mascaramento de dados, os padrões de negação de prompts, o orçamento por período, o registro de auditoria e a política de retry, cada um escrito no arquivo, e recusa pelo nome cada valor que não consegue manter. O mascaramento de dados substitui cada correspondência dos padrões que a vinculação lista por <masked>, ou, sob refuse, responde à requisição ou à resposta com HTTP 403, nos prompts de sistema e de desenvolvedor de uma requisição, em suas outras mensagens e nos argumentos e resultados de suas chamadas de ferramentas, e no texto da mensagem de uma resposta que chega inteira; ele não reconhece tipos de entidade e não restaura nada. O agentgateway não mascara uma resposta em streaming, então, enquanto as respostas são mascaradas, uma requisição de modelo que pede uma resposta em streaming é recusada com HTTP 403 antes de ser encaminhada, assim como qualquer requisição de modelo cujo corpo seja maior que os 2 MiB que o gateway lê para essa verificação, em streaming ou não. Uma recusa por um guard, incluída a de um padrão de negação, é HTTP 403 com o corpo “The request was rejected due to inappropriate content” (A requisição foi rejeitada devido a conteúdo inadequado). O orçamento, os registros e o retry são descritos em “Orçamento por período”, “Registro de auditoria” e “Resiliência” abaixo. Suas realizações da cadeia de fallback, da seleção de destino, do cache semântico, da validação de respostas e da triagem de injeção de prompt interrompem toda vinculação, cada uma informando o motivo, e o limite de concorrência não se vincula a ele, já que ele não traz nenhum valor dataplane.aggrega.ai/concurrency-cap.

  • Traefik Hub na frente dos modelos: core/gateway/traefik-hub, o gateway pago da Traefik, serve os modelos conectados ao seu próprio socket models por meio do middleware Chat Completion do Traefik Hub. Sua única realização é uma Recipe de chart sobre o próprio chart Helm da Traefik; não há realização compose. Ele executa a imagem que a Release nomeia em infra.image, tag incluída, porque a Traefik distribui o Traefik Hub sob seus próprios termos e, por isso, o catálogo não nomeia nenhuma; o build é interrompido enquanto essa chave não estiver definida ou não nomear nenhuma tag. O token de licença chega ao gateway por referência ao Secret vinculado ao seu slot obrigatório license, sob a chave de dados token, nunca como valor, e o build é interrompido enquanto nada vincular esse slot ou ele publicar outra chave de dados. A Traefik exige HTTPS de saída para api.traefik.io, onde o gateway valida seu token; a partir do Traefik Hub v3.21, o gateway continua servindo enquanto esse host não pode ser alcançado, tentando novamente em segundo plano, e um token dura um ano por padrão, e o gateway para quando ele expira. A Recipe de chart desativa a exportação, feita pelo chart, dos logs de erro do gateway para a plataforma da Traefik e sua verificação de uma versão mais recente. O compilador não valida nenhum token e não contata nenhum fornecedor, então uma Release que compila sem erros não diz nada sobre se o gateway inicia. Cada modelo conectado recebe uma rota em /<alias>/v1/chat/completions, enviada ao endpoint que o modelo publica por meio de um Service do tipo ExternalName e pedindo o model que ele publica, qualquer que seja o nome de modelo que uma requisição traga, então é o caminho que escolhe o modelo; ele serve apenas chat completions. O gateway apresenta a credencial própria de cada conexão como um bearer token, que o Traefik Hub lê do Secret que o middleware Chat Completion da conexão nomeia, e uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai, ou cujo endpoint nomeia um endereço em vez de um host, interrompe o build. Ele publica a rota do alias que seu values.model nomeia como seu endpoint e esse alias como seu model, e traz model.aggrega.ai/api: openai, então o socket model de um agente o aceita como aceita o gateway de IA; sem nada conectado, publica ambas as chaves vazias. Uma Release pode nomear os chamadores do gateway em infra.callers e os hashes htpasswd de suas chaves pelo slot caller_keys: o middleware API Key do Traefik Hub então encabeça toda rota de modelo e recusa uma requisição que não apresenta nenhuma chave declarada como Authorization: Bearer <key>, e a chave é removida da requisição encaminhada; sem chamadores, as rotas ficam abertas. O que o Traefik Hub faz com a entrada de um chamador que nomeia um Secret ou uma chave de dados inexistente não é informado em sua referência, então, no pior caso, as rotas ficam tão abertas quanto sem chamadores. Dos controles abaixo, ele realiza o orçamento por período, o cache semântico para os chamadores que declara, os padrões de negação de prompts e o mascaramento de dados, por meio de middlewares do gateway de IA do Traefik Hub, e a cadeia de fallback e a política de retry, por meio do failover e do retry próprios da Traefik, cada um escrito nas rotas que sua Recipe de chart renderiza. O gateway de IA é um direito de uso incluído na licença, que nenhum build consegue ver, e o que o Traefik Hub faz com um token válido cuja licença não o inclui não está documentado, então vincular qualquer um dos quatro primeiros interrompe o build até que a Release defina infra.ai_gateway_entitled como true. Suas realizações da triagem de injeção de prompt, do registro de auditoria, da seleção de destino e da validação de respostas interrompem toda vinculação, cada uma informando o motivo, e o limite de concorrência não se vincula a ele, já que ele não traz nenhum valor dataplane.aggrega.ai/concurrency-cap. Que um gateway em execução aplique qualquer um desses controles não é observado por nenhum build.

  • Higress na frente dos modelos: core/gateway/higress, o gateway de código aberto Higress, construído sobre o Envoy e configurado por meio de recursos do Kubernetes, serve os modelos conectados ao seu próprio socket models por meio do AI proxy do Higress. Sua única realização é uma Recipe chart sobre o chart Helm higress-core do próprio projeto, que executa o controlador do Higress, com seu serviço de descoberta, e o gateway; não há realização compose, pois o projeto destina sua distribuição compose principalmente a testes locais e essa distribuição executa vários serviços cooperantes configurados por meio de um armazenamento próprio. A Recipe fixa o chart, as imagens e cada módulo de plugin que escreve, e aceita em infra.source_version apenas as versões do chart nas quais sua configuração foi comprovada; o gateway busca esses módulos no registro de plugins do Higress em tempo de execução, que o cluster precisa alcançar e que o build não pode verificar. O controlador observa apenas o namespace da Release, sob uma IngressClass nomeada a partir do gateway e desse namespace, de modo que dois gateways Higress em um mesmo namespace colidem. Cada alias recebe uma rota em /<alias>/v1, enviada ao endpoint que o modelo do alias publica por meio de uma entrada do registro próprio do gateway e solicitando o model que ele publica, qualquer que seja o nome de modelo que uma requisição traga, de modo que é o caminho que escolhe o modelo; as conexões que nomeiam um mesmo alias em seu valor serves dividem suas requisições em partes iguais. O gateway apresenta a credencial própria de cada conexão como bearer token, que o controlador do Higress lê do Secret que a configuração do AI proxy nomeia, no namespace do gateway, e entrega ao gateway, de modo que a chave não aparece em nenhum arquivo renderizado; um nome de Secret que contém um ponto interrompe o build, pois o Higress lê o nome até o primeiro ponto, e uma conexão que não traz credencial repassa a chave que a requisição apresenta. O AI proxy do Higress também copia o cabeçalho Authorization que um cliente envia para um cabeçalho X-HI-ORIGINAL-AUTH, e cada rota de modelo remove essa cópia antes que a requisição chegue ao modelo, de modo que uma chave apresentada por um cliente nunca trafega ao lado da credencial própria de uma conexão. Sobre https, o gateway verifica se o certificado de um modelo se encadeia às âncoras de confiança do sistema e nomeia o host do modelo, qualquer que seja o host que o cliente enviou, e caso contrário não envia nada ao modelo: a Recipe marca a rota de cada alias cujas conexões são todas https com a anotação higress.io/backend-protocol: HTTPS do Higress, de modo que o gateway obtém o nome do servidor a partir do host que o AI proxy escreve em cada requisição — o do modelo, qualificado com o namespace do modelo quando não contém ponto — e verifica o certificado em relação a ele. Essa anotação se aplica a cada conexão de um alias, de modo que um alias que mistura conexões http e https interrompe o build, nomeando ambas; servi-las sob dois aliases resolve isso. Uma conexão que alcança um modelo cujo model.aggrega.ai/api não é openai, ou cujo endpoint indica um endereço em vez de um host, interrompe o build. Ele publica a rota do alias que seu values.model nomeia como seu endpoint e esse alias como seu model, e traz model.aggrega.ai/api: openai, de modo que o socket model de um agente o aceita como aceita o AI gateway; sem nada conectado, publica ambas as chaves vazias. Ele não declara chamadores, de modo que suas rotas de modelo não verificam a chave de nenhum chamador, e um valor que exige um chamador verificado pelo gateway é recusado nominalmente. Dos controles descritos abaixo, ele realiza o orçamento por período, o registro de auditoria e a política de retentativa, cada um escrito nas rotas de modelo, e realiza core/data-masking como descreve “Exfiltração de dados e interceptação de payloads” abaixo. Suas realizações da validação de respostas, da cadeia de fallback, do cache semântico, da triagem de injeção de prompt e da seleção de destino interrompem cada vinculação, cada uma indicando o motivo, e nem os padrões de bloqueio de prompts nem o limite de concorrência se vinculam a ele, pois ele não traz nenhum valor dataplane.aggrega.ai/prompt-guard ou dataplane.aggrega.ai/concurrency-cap. Que um gateway em execução aplique qualquer um desses controles não é observado por nenhum build.

  • Azure API Management na frente de um modelo: core/gateway/azure-api-management, o AI gateway do Azure API Management, um serviço hospedado, serve uma API de modelo por meio de uma API em uma instância do API Management que já existe. Sua Recipe terraform lê a instância e adiciona a API, sua operação de chat completions, o backend para o qual encaminha e a política da API, que remove a chave de assinatura do chamador do que encaminha e se autentica na API do modelo conforme infra.backend_authentication indica: com a identidade gerenciada da instância, com uma chave de provedor mantida no Key Vault ou sem nada. Suas Recipes helm e compose fazem referência a uma API configurada fora da Release e interrompem o build em qualquer vinculação. Dos controles descritos abaixo, sua Recipe terraform realiza o cache semântico, o orçamento por período, a triagem de injeção de prompt e a política de retentativa, cada um escrito na política da API. Ela não realiza o limite de concorrência, já que a Microsoft considera o teto que sua política de concorrência aplica nunca totalmente preciso, e mais baixo quando várias unidades de capacidade são executadas em uma região, nem a cadeia de fallback, já que a API encaminha para um único backend e o fallback próprio do Azure, os grupos de prioridade de um pool de backends, desvia as requisições posteriores de um backend cujo circuit breaker disparou, em vez de enviar uma requisição que falhou a outro modelo. Sua realização de core/audit-logging interrompe cada vinculação, nomeando o que está fora de seu alcance: o próprio log, que uma configuração de diagnóstico na instância ativa; quanto uma requisição custou, enquanto require_cost estiver ativado, já que o log de requisições de modelo do Azure registra contagens de tokens e o modelo, e nenhum preço; e uma retenção, quando retention_days é informado, já que uma linha dura enquanto o workspace do Log Analytics em que ela cai a mantiver. Que as políticas se apliquem e sejam aplicadas como a Microsoft documenta não é observado por nenhum build.

  • A chave que um chamador apresenta: Um servidor que verifica a chave que seus chamadores apresentam mantém essa chave em um slot próprio, chamado api_key em cada destino que serve modelos e verifica uma — core/ai-model/vllm, tei e tgi, o modelo LiteLLM e o AI gateway, onde ela é a chave que o LiteLLM chama de master key — e cada uma de suas Recipes entrega a chave como a variável que o servidor lê. core/gateway/apisix e core/gateway/agentgateway mantêm, cada um, uma chave para cada chamador que sua Release nomeia em infra.callers, em seu slot caller_keys: um único Secret, que contém a chave de cada chamador sob o nome desse chamador. core/gateway/traefik-hub mantém seus chamadores da mesma forma, exceto que seu Secret contém o hash htpasswd da chave de cada chamador, com o qual sua verificação de chaves compara uma chave apresentada, de modo que não é o Secret a partir do qual o chamador apresenta sua chave. Um chamador mantém a chave que apresenta do seu próprio lado, na conexão em que a apresenta, em um slot que seu socket declara: os agentes da biblioteca padrão declaram um em seu socket model, credential; o AI gateway, em seu socket models e em seu socket cache_store, onde é a senha que o cache semântico do gateway apresenta ao seu armazenamento; core/gateway/kong e core/gateway/kong-enterprise, em seus sockets models; core/gateway/apisix, em seu socket models e em seu socket cache_store, onde é igualmente a senha que seu cache semântico apresenta ao seu armazenamento; core/gateway/agentgateway, em seu socket models; core/gateway/envoy-gateway, em seu socket models e em seu socket cache, onde é a senha que o serviço de limitação de taxa do gateway apresenta ao armazenamento que mantém a contagem de um orçamento por período; core/gateway/higress, em seu socket models e em seu socket cache, onde é a senha que seu limite de tokens apresenta ao armazenamento que mantém a contagem de um orçamento por período; e core/gateway/traefik-hub, em seu socket models, em seu socket cache, onde é a senha que sua cota apresenta ao armazenamento que mantém a contagem de um orçamento por período, e em seu socket cache_store, onde é a senha que seu cache semântico apresenta ao seu armazenamento — de modo que um agente que alcança um modelo, ou um gateway que alcança um modelo que serve, mantém ali a chave dessa conexão. O AI gateway, os dois Kongs, o APISIX e o agentgateway entregam a chave de cada modelo conectado sob uma variável própria, que a entrada ou a rota desse modelo em sua configuração nomeia; o Envoy Gateway nomeia o Secret na política de segurança do backend do modelo, e o controlador do Envoy AI Gateway lê a chave dele; o Traefik Hub nomeia o Secret e a chave de dados no middleware Chat Completion da rota do modelo, e lê a chave dele. Uma conexão que alcança um modelo rotulado component.aggrega.ai/hosting: managed traz uma, ou informa em seus próprios values que o modelo não aceita nenhuma, unauthenticated: true; sem nenhuma das duas, a asserção do chamador interrompe o build nomeando a conexão e seu destino, e um modelo rotulado de outra forma não provoca essa interrupção. Uma chave que o Component de um chamador declara, em vez disso, em um slot próprio é uma única chave para todas as conexões que ele estabelece. Nenhuma das duas pontas vê as vinculações da outra, de modo que o servidor não sabe nada da chave de um chamador, e as duas coincidem porque o Aggregate alimenta ambas a partir de um único parâmetro: onde as duas pontas resolvem segredos em um mesmo escopo — um mesmo namespace do Kubernetes, um mesmo projeto do Compose —, elas referenciam um único segredo, e caso contrário cada uma mantém o seu, realizado a partir da mesma entrada do armazenamento. vLLM, TEI e TGI verificam, cada um, uma única chave, de modo que todo chamador apresenta a mesma chave e o servidor não consegue distinguir seus chamadores, e o TGI compara sua chave sem diferenciar maiúsculas de minúsculas; APISIX, agentgateway e Traefik Hub verificam, cada um, a chave de cada chamador declarado e distinguem seus chamadores por ela; os dois Kongs não declaram chamadores e não verificam a chave de nenhum chamador, pelos motivos que “Kong na frente dos modelos” acima apresenta; o modelo LiteLLM e o AI gateway também aceitam as chaves que emitem, enquanto seu banco de dados de contabilização estiver vinculado. Modelo de credenciais desenvolve esse formato em um Aggregate.

  • Escolhendo entre destinos: core/target-selection declara como um gateway escolhe entre vários destinos capazes de atender à mesma requisição, com uma strategy de latency (o destino observado como o que responde mais rápido) ou cost (o destino mais barato de chamar). A estratégia faz parte do que a aplicação pede ao seu gateway, então o desenvolvedor a vincula no Aggregate. No AI gateway, os destinos são as entradas de seu values.models que publicam o mesmo alias — um modelo conectado é servido sob o alias de sua conexão, que nenhuma outra entrada pode publicar — e a biblioteca padrão realiza latency escrevendo o latency-based-routing do proxy na configuração de roteamento que a Recipe do gateway renderiza: o proxy envia cada requisição à entrada cujas dez últimas respostas levaram, em média, o menor tempo, por token de saída quando uma resposta informa seus tokens, ou até o primeiro token para uma requisição em streaming, e uma entrada ainda não testada conta como a mais rápida. Sem a vinculação, a configuração não nomeia nenhuma estratégia, e o proxy escolhe aleatoriamente entre essas entradas. cost é recusado ali nominalmente: o proxy precifica uma entrada procurando seu destino, exatamente como escrito, em uma tabela de preços que nomeia os modelos da OpenAI e da Anthropic sem o prefixo de provedor que os destinos do gateway trazem, e atribui a uma entrada que não encontra um preço de fallback fixo, de modo que as entradas que compartilham um alias teriam o mesmo preço e seriam escolhidas pela ordem. Em core/gateway/kong-enterprise, toda vinculação é interrompida, porque cada modelo conectado a ele é servido em rotas próprias que trazem apenas esse modelo, o que não deixa nada entre o que escolher. Em core/gateway/agentgateway, toda vinculação também é interrompida, indicando o motivo: o agentgateway sorteia dois dos destinos de um nome de modelo e escolhe aquele cuja saúde, dividida pelo tempo que levou para responder, tem a pontuação mais alta, de modo que o destino mais rápido só é escolhido quando é sorteado, e ele não escolhe nenhum destino por custo. Em core/gateway/higress, toda vinculação também é interrompida, indicando o motivo: o Higress pode medir a latência de um serviço, mas seu plugin de balanceamento de carga é executado depois do AI proxy — que já definiu o modelo, o endereço e a credencial da requisição para o candidato que a rota resolveu — e escreve sua escolha em um cabeçalho da requisição pelo qual nada roteia sem um filtro do Envoy que este catálogo não renderiza, de modo que a escolha não tem efeito, e ele não escolhe nenhum destino por custo. Em core/gateway/traefik-hub, toda vinculação também é interrompida, indicando o motivo: o Traefik escolhe pelo menor tempo de resposta apenas entre os servidores de um Service, que um único nome de modelo e uma única credencial cobrem, e entre Services balanceia por peso ou por um hash do endereço do cliente, nunca por latência, e nenhuma de suas estratégias escolhe um destino por custo; além disso, cada modelo conectado ao gateway é servido em uma rota própria que traz apenas esse modelo, o que não deixa nada entre o que escolher. Em qualquer outro gateway, uma vinculação interrompe o build.

  • Resiliência: core/fallback-chain encaminha para outros modelos uma solicitação cujo modelo falha: chains indica, para cada alias de modelo que recorre a fallback, os aliases a tentar em ordem até que um responda, com um fallback que falha seguindo, por sua vez, sua própria entrada, e max_hops limita até onde, ao longo dessa cadeia, uma solicitação é repassada. A biblioteca padrão o realiza no gateway de IA escrevendo ambos na configuração de roteamento que a Recipe do gateway gera, e interrompe o build diante de um nome que o mapa de modelos do gateway não publica. Uma solicitação recorre ao fallback somente depois que o gateway desistiu do alias solicitado: onde um alias é publicado mais de uma vez, uma chamada com falha passa primeiro para outra de suas entradas como nova tentativa, limitada pela contagem de tentativas do gateway. core/retry-policy define essa contagem — quantas vezes o gateway pode enviar uma solicitação, incluindo o primeiro envio (max_attempts), para uma falha que se resolve com um novo envio, como uma conexão recusada, um limite de taxa ou um timeout — e a biblioteca padrão o realiza no gateway de IA escrevendo-a na configuração de roteamento que a Recipe do gateway gera. Em core/gateway/envoy-gateway, ele é realizado como o retry da traffic policy na rota que atende os modelos conectados, a mesma policy que carrega o limite de taxa de um orçamento por período, porque o Envoy Gateway associa uma única traffic policy a uma rota: uma solicitação é reenviada após uma conexão ou um stream recusado, um reset ou uma resposta 429, 503 ou 504, até max_attempts envios, e um modelo que não responde nada dentro do timeout de solicitação da rota não recebe novo envio, porque esse timeout abrange todos os envios. Em core/gateway/azure-api-management, ele é realizado como o retry do Azure em torno do encaminhamento, na seção backend da policy da API: uma solicitação respondida com HTTP 429 ou um status 5xx é reenviada, com seu corpo retido para poder ser reenviado, um segundo após o envio anterior, até max_attempts envios. Uma conexão recusada ou interrompida, e um modelo que não responde nada dentro do timeout do encaminhamento, não geram novo envio, porque o Azure encerra o retry diante de um erro desse tipo e o repassa à seção on-error da policy. O Azure repete de 1 a 50 vezes após o primeiro envio, então um max_attempts de 1 não escreve nenhum retry e um acima de 51 é recusado explicitamente. O retry substitui o encaminhamento que a API herdaria, então, enquanto ele está associado, uma configuração de encaminhamento feita em um escopo mais amplo da instância, como um timeout, não se aplica à API, que encaminha com os padrões do Azure. No gateway hospedado, core/retry-policy é realizado escrevendo no recurso do gateway sua contagem de tentativas, que indica os envios após o primeiro, de 1 a 5, então max_attempts de 2 a 6 é respeitado e qualquer outro valor é recusado; core/fallback-chain não é realizado ali, porque esse gateway recorre a outros modelos somente dentro de uma rota que uma solicitação nomeia no lugar de um modelo, então uma solicitação para um modelo nunca recorre a fallback. Em core/gateway/kong-enterprise, core/fallback-chain é realizado em sua Recipe de chart: as rotas de chat e de completion de cada alias ao qual chains dá uma entrada usam o AI Proxy Advanced do Kong no lugar de seu AI proxy, com o modelo do alias e os modelos aos quais seu percurso recorre como destinos em ordem de prioridade — o alias, depois os fallbacks de sua entrada em ordem, com a própria entrada de um fallback seguida, por sua vez, somente enquanto menos de max_hops tiverem sido contados. O balanceador envia uma solicitação uma vez a cada destino do percurso, em ordem, até que um responda, passando adiante após um erro ou timeout de conexão, um cabeçalho de resposta inválido ou uma resposta 429, 500, 502, 503 ou 504, e devolve qualquer outra resposta como chegou. O build é interrompido diante de um nome que o socket models não carrega, de um percurso que alcança um alias duas vezes, junto com core/retry-policy, já que o Kong mantém uma única contagem de tentativas para todo o percurso e não pode reenviar a um modelo antes de recorrer ao fallback, e de uma imagem do gateway anterior à 3.12. core/retry-policy não é realizado ali, e sua realização interrompe cada associação informando o motivo: cada modelo conectado é atendido em rotas próprias que carregam apenas esse modelo, então um retry precisa reenviar a solicitação a esse mesmo destino, e a referência do Kong admite as duas leituras sobre se seu balanceador faz isso. Em core/gateway/agentgateway, core/retry-policy é realizado na Recipe de chart como uma policy de retry da própria configuração do gateway, associada ao listener em que chegam suas solicitações de modelo: uma solicitação é reenviada, imediatamente e ao mesmo modelo, após uma resposta 429, 500, 502, 503 ou 504, uma conexão recusada ou redefinida, uma conexão que leva mais de 11 segundos para abrir ou uma resolução de nome com falha, até max_attempts envios. O agentgateway envia uma solicitação uma vez a mais do que as tentativas de sua policy, então a policy é escrita como max_attempts menos um, max_attempts 1 não escreve nenhuma, e um acima de 256 é recusado explicitamente. Uma solicitação cujo corpo é maior que 64 KiB é enviada uma única vez, e a configuração não define nenhum timeout, então um modelo que aceita a conexão e não responde nada é aguardado em vez de receber novo envio. core/fallback-chain não é realizado ali, e sua realização interrompe cada associação informando o motivo: o agentgateway alterna entre modelos excluindo um que falhou para as solicitações seguintes, enquanto a solicitação que falhou é respondida com sua falha, então nenhuma solicitação percorre uma cadeia. Em core/gateway/higress, core/retry-policy é realizado como o retry próprio da rota, escrito como anotações de Ingress em cada rota de modelo: uma solicitação é reenviada após uma conexão recusada ou redefinida, uma resposta 5xx ou um 429, inclusive um POST, até max_attempts envios; max_attempts 1 desativa o retry, substituindo o retry que o plano de controle do Higress dá a uma rota sem anotação, e um acima de 2147483648 é recusado explicitamente. Um modelo que aceita a conexão e depois não responde nada, ou responde lentamente, não recebe novo envio, já que a rota não define prazo por tentativa, e uma solicitação em streaming só é reenviada antes de sua resposta ter começado. core/fallback-chain também não é realizado ali, e sua realização interrompe cada associação informando o motivo: o Higress encaminha uma solicitação com falha no máximo uma vez, a um único outro destino — o backend padrão de uma rota, ou a única rota de fallback que seu console escreve para uma rota de IA — então nenhuma solicitação percorre uma cadeia. Em core/gateway/traefik-hub, ambos são realizados na Recipe de chart, e cada um interrompe o build diante de uma imagem do Traefik Hub anterior à v3.20, cujo failover não aceita middlewares nos serviços que tenta e cujo retry não pode reenviar um POST com base no status de uma resposta — exceto uma policy de retry de um único envio. core/fallback-chain faz a rota de cada alias ao qual chains dá uma entrada passar por failovers aninhados do próprio Traefik, tentando em ordem os modelos do percurso do alias — o alias, depois os fallbacks de sua entrada em ordem, com a própria entrada de um fallback seguida, por sua vez, somente enquanto menos de max_hops tiverem sido contados — cada um com seu próprio nome de modelo, credencial, cotas e retry. Uma resposta 429 ou de 500 a 504 de um modelo, após qualquer retry desse modelo, passa a solicitação ao próximo; qualquer outra resposta é devolvida como chegou, a do último modelo seja qual for, e um corpo de solicitação acima de 1 MiB é recusado com HTTP 413 em vez de enviado. O build é interrompido diante de um nome que o socket models não carrega e de um percurso que alcança um alias duas vezes. core/retry-policy é o middleware de retry do Traefik, o último em cada rota de modelo, ou em cada modelo que um percurso tenta: uma solicitação é reenviada imediatamente após uma conexão que não levou nada ao modelo e após uma resposta 429 ou de 500 a 504, inclusive um POST, até max_attempts envios, incluindo o primeiro, e max_attempts 1 não escreve nada. Após uma resposta que o próprio gateway forma — uma recusa de sua verificação de chave, uma proteção, o mascaramento ou uma cota — nunca há novo envio, nem após uma resposta em streaming depois de ela ter começado.

  • Orçamento por período: core/period-budget limita o que o tráfego que passa por um gateway pode consumir em um período: um limit, o period que ele cobre, um scope — tudo o que o gateway atende, cada chamador ou cada modelo — e uma unit — um custo em dólares americanos ou em tokens —, e assim que o que o gateway contou no período excede o limite, as solicitações seguintes a modelos são recusadas. Ele é vinculado a qualquer componente que declare dataplane.aggrega.ai/period-budget. A biblioteca padrão o realiza no gateway de IA, cujo orçamento cobre tudo o que o gateway atende, é contado em dólares americanos e recomeça no início de cada período — um número de dias a partir da meia-noite UTC, ou um mês de calendário a partir de seu primeiro dia: a realização escreve o limite e o período na configuração que a Recipe do gateway renderiza, recusa pelo nome qualquer outra unidade, escopo ou período — entre eles 30d, que o gateway conta como um mês de calendário — e é interrompida a menos que os slots de credenciais database_url e api_key do gateway estejam ambos vinculados, porque sem seu banco de dados contábil o gateway não mantém nenhuma contagem e sem uma chave administrativa não verifica nenhum chamador em relação ao orçamento. Assim que a contagem excede o limite, o gateway recusa as solicitações a modelos da chave administrativa, assim como as de todo chamador; sua listagem de modelos e seu gerenciamento de chaves continuam respondendo a essa chave. No gateway hospedado, ele é realizado como uma regra de limite de gastos no recurso do gateway, contada em dólares americanos sobre uma janela que avança com o tempo — o último period, para modelos cujos preços o gateway conhece — para tudo o que o gateway atende: um orçamento por chamador ou por modelo, tokens e um mês de calendário são recusados pelo nome. Em core/gateway/apisix, ele é realizado na Recipe chart, escrito nas rotas dos modelos conectados como a limitação de taxa por tokens do APISIX: contado nos tokens que a resposta de cada modelo informa — total_tokens, prompt_tokens ou completion_tokens — sobre uma janela fixa de period que se abre com a primeira solicitação a um modelo depois que a janela anterior se fechou, e não pelo relógio, para tudo o que o gateway atende, para cada modelo conectado separadamente ou para cada chamador que sua Release declara em infra.callers separadamente, com o gateway os distinguindo pela chave que cada um apresenta. Assim que a contagem atinge o limite, o gateway responde às solicitações a modelos com HTTP 503 até a janela se fechar; os tokens de uma solicitação são somados assim que sua resposta é concluída, de modo que a solicitação que atinge o limite é atendida, e uma resposta que seu cache semântico serve não conta nada e é servida além do limite. O APISIX não conta tokens em uma solicitação de completion, então, enquanto o orçamento estiver vinculado, cada modelo conectado recebe apenas sua rota de chat, e ele mantém a contagem na memória do processo do gateway, então o chart executa uma réplica e uma reinicialização abre uma nova janela. Um orçamento em dólares americanos, um por chamador enquanto infra.callers não declara nenhum, um mês de calendário e um segundo orçamento em um mesmo gateway são recusados pelo nome, assim como uma vinculação em sua Recipe workload, que não renderiza nenhuma rota. Em core/gateway/envoy-gateway, ele é realizado como o rate limit baseado em uso do Envoy Gateway, na rota de IA que atende os modelos conectados ao gateway: a rota declara a contagem de tokens que unit nomeia — total_tokens, prompt_tokens ou completion_tokens — como um custo que o Envoy AI Gateway lê de cada resposta, e uma traffic policy nessa rota o debita quando a resposta é concluída, contra limit tokens por unidade do rate limit do Envoy Gateway, para tudo o que o gateway atende ou para cada modelo conectado separadamente. Cada janela é fixada no relógio UTC — um segundo, um minuto, uma hora, um dia a partir da meia-noite, uma semana a partir de uma quinta-feira, ou 30 ou 365 dias contados a partir de 1º de janeiro de 1970 — e 1mo é um mês de calendário, sob uma configuração do serviço de rate limit do Envoy Gateway que passa então a valer para todo rate limit mensal que essa instalação mantém. A contagem é mantida pelo serviço de rate limit que o control plane do Envoy Gateway cria e ativa para cada gateway que atende, no armazenamento de protocolo Redis conectado ao socket cache do gateway. Assim que a contagem excede o limite, o gateway responde às solicitações a modelos com HTTP 429 até a janela terminar; os tokens de uma solicitação são somados assim que sua resposta é concluída, de modo que a solicitação que ultrapassa o limite é atendida. Enquanto o armazenamento ou o serviço de rate limit não puder ser alcançado, ou uma verificação demorar mais que o timeout de rate limit do Envoy, as solicitações a modelos são recusadas com HTTP 500, sob uma configuração do control plane do Envoy Gateway que passa então a valer para todo rate limit que essa instalação mantém, de modo que um rate limit aplicado a ele manualmente também falha fechado; uma solicitação admitida pouco antes de uma interrupção ainda é atendida e não é contada, porque seus tokens são debitados após a resposta, e um armazenamento que mantém a contagem em memória recomeça toda janela ao reiniciar. Um orçamento em dólares americanos, um por chamador — o gateway distingue chamadores apenas por um header que o próprio chamador escreve, e nada nesse caminho o verifica —, qualquer outro período e um segundo orçamento em um mesmo gateway são recusados pelo nome, assim como uma vinculação sem nada conectado ao socket models ou ao socket cache. Em core/gateway/azure-api-management, ele é realizado como o limite de tokens do Azure, escrito na política da API: contado nos tokens de prompt e de completion que cada resposta informa, juntos, para tudo o que a API atende ou para cada assinatura do API Management, cuja chave o gateway verifica — seja uma cota sobre uma janela fixa no relógio UTC, uma hora, um dia, uma semana, um mês de calendário ou um ano de calendário (1h, 1d, 7d, 1mo ou 12mo; a Microsoft não diz em que dia começa uma semana), respondida com HTTP 403 quando excedida, seja uma taxa sobre um minuto (1m), respondida com HTTP 429 e contada sobre uma janela deslizante nas camadas clássicas e como um token bucket nas camadas v2. A contagem é o uso que cada resposta informa, de modo que solicitações simultâneas podem ultrapassar o limite, e cada gateway da instância mantém sua própria contagem. Um orçamento em dólares americanos ou apenas em tokens de prompt ou de completion, um por modelo — o modelo que uma solicitação nomeia é escrito pelo chamador, e vários nomes podem chegar a um mesmo modelo —, um por assinatura em uma API que não exige chave de assinatura, qualquer outro período e um limite que não seja um número inteiro são recusados pelo nome. A camada Consumption não executa nenhum limite de tokens. Em core/gateway/kong-enterprise, ele é realizado na Recipe chart, escrito nas rotas que o gateway importa como o AI Rate Limiting Advanced do Kong: contado nos tokens que a resposta de cada modelo informa — total_tokens, prompt_tokens ou completion_tokens — em janelas fixas de period, um número de segundos, minutos, horas ou dias, com cada solicitação contada na única janela em que cai seu instante, para tudo o que o gateway atende ou para cada modelo conectado separadamente, e com uma solicitação sob o escopo model contada contra o alias que nomeou, qualquer que seja o modelo que a respondeu. Assim que a contagem atinge o limite, a próxima solicitação a um modelo é respondida com HTTP 429 até a janela terminar, de modo que a solicitação que ultrapassa o limite é atendida; o Kong também pode recusar uma solicitação antecipadamente, com base em sua própria estimativa dos tokens de prompt que ela carrega. A contagem é mantida no backend PostgreSQL do gateway, compartilhada por todas as réplicas e preservada após uma reinicialização. Um orçamento em dólares americanos — o Kong conta custo apenas a partir de um preço que sua configuração atribui a cada modelo, e o catálogo não fornece nenhum —, um por chamador — o Kong distingue chamadores apenas como os consumers que um plugin de autenticação nomeia, e o gateway não declara chamadores, pelas razões que “Kong na frente dos modelos” acima apresenta —, um mês de calendário, um segundo orçamento em um mesmo gateway e uma imagem do gateway anterior à 3.15 são recusados pelo nome, assim como uma vinculação sem nada conectado ao socket models. Em core/gateway/agentgateway, ele é realizado na Recipe chart, escrito na configuração do gateway e contado nos tokens totais que cada resposta informa: sob o escopo caller como um orçamento sobre a chave de API de cada chamador que sua Release declara em infra.callers, sobre janelas fixas de period alinhadas à época Unix, com um dia começando à meia-noite UTC, mantido em um armazenamento SQLite em um volume que a Recipe renderiza, com uma réplica; sob o escopo gateway ou model como um token bucket para tudo o que o gateway atende ou para cada nome de modelo que uma solicitação pede, preenchido até o limite a cada period a partir do momento em que o gateway leu sua configuração e mantido em sua memória, de modo que uma reinicialização ou uma configuração alterada o preenche novamente. Assim que o que foi contado atinge o limite, as solicitações a modelos são respondidas com HTTP 429 até a janela terminar ou o bucket ser preenchido; a solicitação que o atinge é atendida. Um orçamento em dólares americanos — o catálogo de custos de modelos do gateway não precifica nenhum dos modelos conectados a ele, então o orçamento não contaria nada —, apenas em tokens de prompt ou de completion, um por chamador enquanto infra.callers não declara nenhum, um mês de calendário, um limite que não seja um número inteiro e um segundo orçamento em um mesmo gateway são recusados pelo nome, assim como uma vinculação sem nada conectado ao socket models; sua Recipe compose não tem nenhuma realização dele. Em core/gateway/traefik-hub, ele é realizado na Recipe chart como o middleware de cota do Traefik Hub na rota de cada modelo conectado, que mantém sua contagem no armazenamento de protocolo Redis conectado ao socket cache do gateway: ele conta os tokens que cada resposta informa — total_tokens, prompt_tokens ou completion_tokens — ou, sob usd, seu custo em dólares americanos, precificado a partir de uma lista de modelos que acompanha o middleware, sendo recusado com HTTP 422 um modelo para o qual ele não tem preço, sobre uma janela que desliza com o tempo, em que o que foi contado em um momento é liberado novamente um período depois, para cada modelo conectado separadamente, ou para tudo o que o gateway atende enquanto um único modelo estiver conectado. Assim que a contagem atinge o limite, as solicitações a modelos são recusadas com HTTP 429; a contagem de uma solicitação é somada assim que sua resposta é concluída, de modo que a solicitação que ultrapassa o limite, e qualquer outra atendida ao lado dela, é atendida, e uma resposta que o cache semântico serve não conta nada. A referência do Traefik diz que a cota atende solicitações sem contá-las enquanto o armazenamento não puder ser alcançado. Um orçamento por chamador — a cota distingue solicitações pelo endereço do cliente, por um header da solicitação ou pelo host da solicitação, e nenhum deles é o chamador que a verificação de chaves do gateway verificou —, um para o gateway inteiro enquanto vários modelos estiverem conectados, já que a referência do Traefik não diz se rotas que nomeiam uma mesma cota compartilham sua contagem, um mês de calendário e qualquer período que não seja em horas ou dias, ou em minutos ou segundos que formem horas inteiras, são recusados pelo nome, assim como um limite que não seja um número inteiro de tokens e uma vinculação sem nada conectado ao socket models ou ao socket cache. Em core/gateway/higress, ele é realizado na Recipe chart como o plugin de limite de tokens do Higress na rota de cada modelo conectado, que mantém sua contagem no armazenamento de protocolo Redis conectado ao socket cache do gateway: ele soma os tokens de prompt e de completion que cada resposta informa, juntos, assim que a resposta é concluída, sobre uma janela fixa de period — um segundo, um minuto, uma hora ou um dia — que se abre quando a primeira resposta nela é contada, para tudo o que o gateway atende ou para cada alias separadamente. Enquanto a contagem excede o limite, as solicitações a modelos são respondidas com HTTP 429 até a janela terminar, de modo que a solicitação que ultrapassa o limite é atendida. Uma resposta que não informa uso não conta nada, então a Recipe pede ao modelo de uma solicitação em streaming que informe seu uso e recusa com HTTP 403 uma solicitação em streaming que desativa esse relatório, uma solicitação cujo content type nem contém application/json nem começa com multipart/form-data, que o proxy de IA encaminha sem pedir o relatório, e uma cujo body os plugins do gateway não leem — um body comprimido, um content type contendo octet-stream ou grpc, um upgrade; um cliente que envia deliberadamente um body que a validação do gateway não consegue decodificar passa por essas recusas, e essa solicitação em streaming fica sem ser contada. Sem nenhum mascaramento vinculado, uma solicitação cujo body excede o buffer de 32 KiB do gateway pode ser recusada com HTTP 413, dependendo de quando o armazenamento responde. Enquanto o armazenamento não puder ser alcançado, as solicitações a modelos são atendidas e não contadas: o plugin não tem nenhuma configuração que as recuse nesse caso. Um orçamento em dólares americanos ou apenas em tokens de prompt ou de completion, um por chamador — o gateway não declara chamadores, então não verifica nenhum —, qualquer outro período, um limite que não seja um número inteiro e um segundo orçamento em um mesmo gateway são recusados pelo nome, assim como uma vinculação sem nada conectado ao socket models ou ao socket cache.

  • Concorrência: core/concurrency-limit limita quantas solicitações um gateway transporta ao mesmo tempo (max_in_flight), o que impede que uma rajada de chamadores se torne uma fila no modelo por trás dele. scope diz o que um limite conta: gateway, o padrão, conta juntas todas as solicitações que o gateway encaminha; model dá a cada destino ao qual o gateway envia solicitações uma contagem própria, sendo um destino cada entrada upstream para a qual o gateway roteia, de modo que, onde um nome de modelo tem várias entradas, cada uma é contada separadamente. O limite e seu escopo são um dimensionamento de capacidade que o operador decide, definido no infra da vinculação, então o operador o vincula na Release. O limite é contado por proxy em execução, de modo que, onde várias réplicas são executadas, cada uma delas admite essa quantidade. Ele é vinculado a qualquer componente que declare dataplane.aggrega.ai/concurrency-cap, e uma realização recusa pelo nome o escopo que seu gateway não conta. Em core/gateway/nginx, o escopo gateway é realizado como o limit_conn do NGINX, com uma chave de uma palavra igual para toda solicitação, de modo que o NGINX conta toda solicitação que está processando como um único total, mantido em memória compartilhada por seus processos worker, e responde a uma solicitação além do limite com HTTP 503; o escopo model é recusado, já que o NGINX não mantém contagem por destino upstream, assim como um max_in_flight acima de 65535, o máximo que limit_conn aceita. Em core/gateway/envoy-gateway, o escopo model é realizado como o circuit breaker da traffic policy na rota que atende os modelos conectados, a policy que também carrega o rate limit de um orçamento por período e a nova tentativa da política de novas tentativas: o Envoy Gateway o aplica ao backend de cada regra dessa rota, e cada modelo conectado tem uma regra própria, de modo que no máximo max_in_flight solicitações são enviadas ao mesmo tempo a cada modelo conectado, e uma solicitação além do limite é respondida com HTTP 503 e não é enviada novamente; um envio que a política de novas tentativas repete conta contra o limite como o primeiro. As threads worker do Envoy verificam a contagem e depois a incrementam, de modo que solicitações que chegam juntas podem levá-la brevemente acima do limite. O escopo gateway é recusado, já que o Envoy Gateway mantém um limite para cada backend e nenhum sobre o total deles, assim como uma vinculação sem nada conectado ao socket models. No gateway de IA, o escopo model é realizado como o max_parallel_requests de toda entrada de seu mapa de modelos, digitada à mão ou conectada: no máximo max_in_flight solicitações estão em andamento para cada entrada ao mesmo tempo, e uma solicitação que encontra sua entrada cheia é respondida com HTTP 429 — após as novas tentativas do gateway, onde seu alias tem uma entrada, e imediatamente, onde tem várias, mesmo enquanto outra delas tem espaço, já que o proxy escolhe a entrada antes de contar — a menos que core/fallback-chain liste fallbacks para seu alias, para os quais ela é então enviada. O proxy mantém cada contagem em memória, onde por padrão um registro expira dez minutos depois de criado e uma nova contagem então começa do zero, então a vinculação também define esse tempo de vida como um século, mantendo toda contagem enquanto o proxy estiver em execução. Por causa desse tempo de vida, o gateway recusa uma solicitação que carrega priority enquanto o limite estiver vinculado, mesmo onde a Release admite o campo, já que o proxy mantém uma entrada de fila para cada solicitação desse tipo até seu registro expirar; e o build é interrompido diante de um mapa de modelos com mais de 100 entradas, além das quais o armazenamento em que as contagens são mantidas, que comporta 200 registros e descarta um sempre que está cheio, poderia descartar uma contagem. O escopo gateway é recusado ali, já que o único total do proxy é lido apenas por um limitador de solicitações que uma variável de ambiente ativa, o qual conta uma solicitação durante seu primeiro segundo. Nem o gateway hospedado o realiza: o limite de solicitações que sua Recipe terraform escreve no recurso do gateway é uma taxa, um número de solicitações em um intervalo, e não um limite sobre as solicitações em andamento.

  • Registro de auditoria: core/audit-logging faz um gateway manter um registro de cada solicitação ao modelo que ele atende, indicando o modelo que respondeu e os tokens que a resposta informa, e cada realização diz onde o registro vai parar. Ele se anexa a qualquer componente que tenha gateway.aggrega.ai/intelligence: semantic, e seus três valores são do operador, definidos no seu infra, então é o operador quem o anexa na Release. require_cost, ativado por padrão, faz o registro dizer também quanto cada solicitação custou, em uma moeda que a realização especifica. require_verified_caller, ativado por padrão, faz o registro indicar o chamador que o gateway verificou, por meio de uma chave que o gateway emitiu ou conferiu. retention_days, não definido por padrão, faz o gateway excluir um registro quando ele atinge essa quantidade de dias; sem ele, o próprio gateway não exclui nenhum registro, e um registro dura enquanto o lugar onde ele vai parar o mantiver. Um gateway que não consegue respeitar um valor recusa o anexo no build, indicando o valor, de modo que um anexo que deixa require_cost e require_verified_caller nos valores padrão obtém o custo e o chamador verificado, ou uma interrupção. Desativar require_verified_caller significa aceitar um registro cujo chamador é o que a própria solicitação alega, ou nenhum chamador: qualquer pessoa que envie uma solicitação pode então fazer com que ela seja registrada em nome de outro chamador, de modo que tal registro não mostra quem enviou uma solicitação. No gateway de IA, o registro é uma linha no banco de dados contábil do gateway, e todo valor é respeitado: a linha diz quanto a solicitação custou em dólares americanos, com o preço tirado da tabela que o gateway mantém por modelo — um modelo que a tabela não precifica é registrado como sem custo — e indica a chave que o gateway verificou, com o usuário e a equipe a que a chave pertence, enquanto o usuário final indicado em uma linha é o que a solicitação escreve, sem verificação. Sem seu banco de dados contábil, o gateway não grava nenhuma linha, e sem uma chave administrativa ele não confere nenhum chamador e não grava nenhuma linha para uma solicitação que não apresenta chave e não indica usuário final, então o build é interrompido a menos que os slots de credencial database_url e api_key do gateway estejam ambos anexados; enquanto values.log_masking do gateway listar o que mascarar, ele registra apenas as solicitações respondidas. Em core/gateway/envoy-gateway, o registro é uma linha do log de acesso do gateway, que sua Recipe grava enquanto o anexo estiver presente: uma linha JSON por solicitação na saída padrão do data plane, com os campos que o Envoy Gateway grava por padrão, o modelo que a solicitação nomeou, o modelo que respondeu e os tokens de prompt, de completion e totais que a resposta informa, com a rota que atende os modelos declarando essas contagens para que o Envoy AI Gateway as registre. Uma solicitação que o modelo não respondeu não traz nenhum modelo que respondeu nem tokens, e o log de acesso não guarda nada por si só, então quanto tempo uma linha dura depende do que coleta essa saída. Nenhum campo indica um chamador que o gateway verificou: o endereço do cliente e os cabeçalhos que ele envia são gravados como chegam. O gateway não mantém preços, nada na rota que sua Recipe gera verifica o chamador, e o log de acesso não guarda nenhum registro que possa excluir, então sua realização gera um anexo que desativa require_cost e require_verified_caller e não informa retention_days, e caso contrário é interrompida indicando cada valor que não consegue respeitar, todos em uma única falha; ela também é interrompida quando nada está conectado ao socket models. Em core/gateway/agentgateway, o registro é uma linha que o gateway grava em um armazenamento SQLite em um volume que sua Recipe chart gera enquanto o anexo estiver presente, com uma réplica, para cada solicitação ao modelo que passa pelas verificações de chave, orçamento e autorização, incluindo a recusa de um guard: o modelo que o gateway pediu ao servidor de modelos — o nome que o modelo conectado publica, não o alias que o chamador enviou — e o modelo que respondeu, os tokens de entrada, de saída e totais que a resposta informa, seu status e seus tempos e, para cada chamador que sua Release declara em infra.callers, o nome desse chamador, a partir da chave de API que o gateway verificou. Uma solicitação recusada por sua chave, por uma regra de autorização ou pelo orçamento de um chamador não deixa nenhuma linha. Nenhum texto de prompt ou de resposta é mantido, e as linhas são lidas pela interface de administração do gateway, que escuta dentro do seu pod. require_verified_caller é respeitado enquanto houver chamadores declarados; require_cost é recusado pelo nome, já que o catálogo de custos de modelos do gateway não precifica nenhum dos modelos conectados a ele, assim como são recusados require_verified_caller sem nenhum chamador declarado e retention_days, já que o gateway não exclui nenhum registro; sua Recipe compose não tem nenhuma realização dele. Em core/gateway/higress, o registro é o campo ai_log da linha do log de acesso do gateway, que o plugin de estatísticas do Higress preenche enquanto o anexo estiver presente: o modelo que respondeu e os tokens de entrada, de saída e totais que a resposta informa, na saída padrão do gateway, sem texto de prompt ou de resposta. O gateway não declara chamadores, não precifica nada e não guarda nenhum registro que pudesse excluir, então sua realização gera um anexo que desativa require_cost e require_verified_caller e não informa retention_days, e caso contrário é interrompida indicando cada valor que não consegue respeitar, todos em uma única falha; ela também é interrompida quando nada está conectado ao socket models. Em core/gateway/traefik-hub, todo anexo é interrompido, indicando o motivo: o Traefik Hub mantém um registro de uma solicitação ao modelo apenas como um span do OpenTelemetry que seus middlewares de IA exportam para um backend de tracing — indicando o modelo e, no nível detalhado, os tokens e seu custo em dólares americanos — e sua realização não conecta nenhum backend de tracing, então o registro não iria parar em lugar nenhum; o span também não indica um chamador, então não pode indicar aquele que a verificação de chave do gateway verificou. Em core/gateway/azure-api-management, todo anexo é interrompido, como diz o item do gateway mais acima, e nenhum outro gateway da biblioteca padrão o realiza, então um anexo em qualquer outro gateway é interrompido indicando o tipo.

  • Cache semântico: core/semantic-caching declara um cache que responde a um prompt com a resposta armazenada para um prompt anterior suficientemente próximo em significado, em vez de chamar o modelo novamente. embedding_model nomeia o modelo que transforma cada prompt em um vetor, como o gateway o publica; uma resposta armazenada é servida quando os dois prompts são pelo menos tão parecidos quanto indica similarity_threshold, e permanece utilizável por ttl_seconds. scope decide quem compartilha um cache: end_user, o padrão, mantém separado cada usuário final que o gateway identifica, enquanto key atende a partir de um único cache todo chamador que apresenta a mesma chave, de modo que um usuário final por trás dessa chave pode receber uma resposta gerada para outro. core/data-masking declara um conflito com ele, então o build é interrompido em um componente que traga ambos. A biblioteca padrão o realiza no gateway de IA, que mantém as respostas em um core/datastore/redis conectado ao seu socket cache_store, apresentando ao armazenamento a senha contida na credencial dessa conexão quando o armazenamento exige uma, com o armazenamento removendo cada resposta depois de decorridos ttl_seconds, e coloca em cache solicitações chat, responses e messages, não completions nem embeddings. A realização interrompe o build a menos que o slot api_key do gateway esteja anexado, porque sem uma chave administrativa o gateway não confere nenhum chamador, diante de um embedding_model que o mapa de modelos do gateway não publica, e quando nada está conectado a cache_store. Uma resposta armazenada só é servida a uma solicitação que corresponda àquilo sob o qual ela foi armazenada: a chave que a solicitação apresenta, que o gateway verifica, com a equipe e a organização dessa chave; com end_user, o usuário final que a solicitação nomeia; e o modelo que a solicitação pede com seus demais parâmetros. O gateway grava a chave, a equipe, a organização e o usuário final na própria solicitação, por cima de qualquer valor que um chamador tenha enviado para eles em uma solicitação chat; em uma solicitação responses ou messages, ele remove um campo de equipe, organização ou usuário final dos metadados próprios da solicitação e recusa um que nomeie a chave ali, de modo que nenhuma solicitação consegue chegar às respostas de outra chave apenas nomeando-a. Os metadados próprios de uma solicitação ainda podem movê-la entre as respostas da chave que ela apresenta: em uma solicitação responses, model_group substitui o modelo que ela pede naquilo sob o qual sua resposta é armazenada; em uma solicitação responses ou messages, caching_groups permite que solicitações que nomeiam o mesmo grupo de aliases de modelo compartilhem respostas entre eles; e em uma solicitação responses ou chat, redis_namespace mantém as solicitações que nomeiam um namespace separadas das que não nomeiam nenhum. O gateway lê um usuário final de um cabeçalho ou de um campo do corpo que a própria solicitação nomeia, e não verifica nenhum deles: com end_user, um chamador que nomeia outro usuário final recebe as respostas desse usuário final, e solicitações que não nomeiam nenhum usuário final compartilham um único cache com todas as outras solicitações desse tipo sob a chave que apresentam. O gateway hospedado não o realiza: seu cache só responde a uma solicitação idêntica a uma anterior. Em core/gateway/azure-api-management, ele é realizado como a consulta e o armazenamento do cache semântico do Azure, gravados na política da API: embedding_model nomeia um backend que a instância do API Management já tem para um modelo de embeddings, que a instância alcança com sua identidade gerenciada, e a instância precisa de um cache Redis com RediSearch configurado como seu cache externo, nada disso visível ao build, então o build é interrompido até que o operador afirme que o cache oferece RediSearch definindo infra.cache_serves_vector_search do gateway; o armazenamento mantém uma resposta por ttl_seconds; e similarity_threshold é gravado como o limiar de pontuação do Azure, um menos o limiar, lendo essa pontuação como uma distância de cosseno, já que a Microsoft informa seu intervalo e sua direção — mais baixo exige prompts mais próximos — mas não sua medida. Uma resposta é armazenada e servida separadamente por API e por assinatura do API Management, cuja chave o gateway verifica, então a realização mantém key, recusa-o em uma API que não exige chave de assinatura, e recusa end_user: a API que sua Recipe gera não valida o token de nenhum usuário final, então o gateway não tem nenhum usuário final verificado para manter separado. core/gateway/contour e core/gateway/nginx também não o realizam, já que não oferecem nenhum cache semântico. Em core/gateway/agentgateway, sua realização interrompe todo anexo, indicando o motivo: o agentgateway não mantém nenhum cache de respostas, e seu cache de prompts apenas marca onde um provedor que coloca os prompts em cache por conta própria pode fazê-lo. Em core/gateway/kong-enterprise, sua realização interrompe todo anexo, indicando o escopo pedido: o AI Semantic Cache do Kong não tem nenhuma configuração que mantenha as respostas armazenadas de um chamador separadas das de outro, e o gateway distingue os chamadores apenas como os consumers que um plugin de autenticação nomeia e não declara nenhum chamador, pelos motivos que “Kong na frente dos modelos” dá mais acima, então com end_user e com key igualmente todas as solicitações compartilhariam um único cache. Em core/gateway/higress, sua realização interrompe todo anexo, indicando o escopo pedido: o cache semântico do Higress armazena cada resposta sob um único prefixo de chave seguido do texto do prompt, e nada nessa chave nomeia um chamador ou um usuário final, enquanto o gateway não declara nenhum chamador, então todas as solicitações compartilhariam um único cache. Em core/gateway/apisix, ele é realizado na Recipe chart, gravado na rota de chat de cada modelo conectado como o cache semântico do APISIX 3.18.0, para os chamadores que sua Release declara em infra.callers: uma resposta é armazenada por rota e por chamador, sob a chave que o chamador apresentou, que o gateway verifica, de modo que nenhum chamador recebe uma resposta armazenada para outro; a realização mantém key e recusa end_user pelo nome, porque o gateway não consegue distinguir os usuários finais por trás de uma mesma chave. embedding_model nomeia uma conexão no socket models do gateway, com cujo endpoint, modelo e credencial o cache calcula os embeddings. O cache calcula o embedding da última mensagem de usuário de uma solicitação e serve uma resposta armazenada cuja mensagem é pelo menos tão parecida quanto indica similarity_threshold e cujas mensagens anteriores — um prompt de sistema, turnos anteriores — são as mesmas. As respostas ficam por ttl_seconds em um core/datastore/redis conectado ao socket cache_store do gateway, ao qual o cache apresenta a senha contida na credencial dessa conexão, e uma resposta servida por significado é armazenada novamente sob essa solicitação por mais ttl_seconds. Solicitações de completion não são colocadas em cache, e uma falha do armazenamento ou do embedding é um miss: a solicitação é respondida mesmo assim. A realização é interrompida quando nenhum chamador está declarado, quando nada está conectado a cache_store ou ao socket models, e diante de um embedding_model que nenhuma conexão ali carrega. O APISIX indexa uma resposta armazenada por rota e chamador em vez de por gateway, então dois gateways APISIX conectados a um mesmo armazenamento, ou duas Releases de um mesmo Aggregate apontando seu gateway para um mesmo armazenamento externo, podem servir uma resposta em cache a um chamador de mesmo nome no mesmo alias e modelo. Sua Recipe workload, no APISIX 3.17.0, não traz nenhum cache semântico. Em core/gateway/traefik-hub, ele é realizado na Recipe chart como o cache semântico do Traefik Hub na rota de cada modelo conectado, para os chamadores que sua Release declara em infra.callers: uma resposta é armazenada por modelo conectado e por chamador, sob o chamador que a verificação de chave do gateway verificou, cada um por sua própria chave, de modo que nenhum chamador recebe uma resposta armazenada para outro; a realização mantém key e recusa end_user pelo nome, porque o gateway não consegue distinguir os usuários finais por trás de uma mesma chave. embedding_model nomeia uma conexão no socket models do gateway, com cujo endpoint, modelo e credencial o cache calcula o embedding do texto de uma solicitação. similarity_threshold é gravado como o limite de distância do cache, um menos o limiar, lido como uma distância de cosseno, já que a referência do Traefik informa a direção do limite, mas não sua medida. Uma resposta é mantida por ttl_seconds em um core/datastore/redis conectado ao socket cache_store do gateway, e uma solicitação grande demais para calcular o embedding é respondida sem cache. A realização é interrompida quando nenhum chamador está declarado, quando nada está conectado a cache_store ou ao socket models, diante de um embedding_model que nenhuma conexão ali carrega, e diante de uma imagem do Traefik Hub cuja tag não nomeia nenhuma versão a partir da v3.19.11 dentro da 3.19 ou a partir da v3.20.6, já que uma versão anterior compartilha um único cache entre todos os chamadores de uma rota.

  • Triagem de injeção de prompt: core/prompt-injection-shield declara que as requisições a modelos que um gateway encaminha são verificadas, antes de o modelo ser chamado, em busca de uma tentativa de sobrepor as instruções dadas ao modelo, com uma sensitivity de standard ou strict — strict recusando mais tentativas desse tipo, e mais requisições legítimas junto com elas. A verificação é o veredito de um classificador probabilístico: ela deixa passar alguns ataques — entre eles os reformulados, codificados ou escritos de outra forma —, recusa algumas requisições legítimas e é sabidamente contornável, portanto é um controle ao lado de outros, e não julga a resposta do modelo, os argumentos de chamadas de ferramentas nem imagens. Ela se anexa a qualquer gateway, e uma realização ou envia as requisições do gateway por uma guarda conectada ao seu socket guard, o que não exige do gateway nada além de encaminhar para um endereço com o qual está configurado, ou ativa uma verificação que o próprio gateway executa. Com uma guarda, a guarda verifica cada requisição e encaminha ao modelo o que admite, e anexar a Feature sem nada nesse socket interrompe o build, indicando isso. A biblioteca padrão a realiza no gateway de IA e no gateway NGINX, cada um com core/security/nemo-guardrails como guarda: um serviço que fala a API chat-completions da OpenAI, cujo rail envia a última mensagem de usuário de uma requisição ao classificador do core/security/trustyai-huggingface-detector conectado a ele e recusa a requisição quando a pontuação desse classificador atinge o limiar da guarda. Uma requisição recusada é respondida pela própria guarda, com uma completion comum, e nada dela chega ao modelo; quando a guarda ou seu detector não pode ser alcançado, a requisição também é recusada. Cada um dos dois interrompe o build, a menos que a guarda seja essa, executando o limiar que a sensibilidade indica — 0.5 para standard e 0.001 para strict, os dois valores medidos para o classificador padrão do detector, cujo modelo o gateway, que vê a guarda e não o detector por trás dela, não consegue verificar. No gateway de IA, cada alias do mapa de modelos é enviado à guarda, com cada destino escrito como openai/<model>, de modo que o mapa é o digitado à mão: um modelo conectado ao socket models do gateway seria enviado ao seu próprio endpoint com a credencial da sua própria conexão, passando ao largo da guarda, e a realização interrompe o build enquanto esse socket contiver uma conexão, indicando-a. O gateway de IA recusa toda requisição que não seja uma chat completion, o único tipo que a guarda verifica; no gateway NGINX, sua única location encaminha para a guarda no lugar do upstream, e a guarda não responde a nenhuma outra rota de modelo. Em core/gateway/azure-api-management, ela é realizada como o prompt shield do próprio Azure, ativado na policy da API por meio do backend Azure AI Content Safety da instância indicado por infra.content_safety_backend_id, e o build é interrompido enquanto essa chave não estiver definida: o Azure AI Content Safety verifica cada requisição em busca de um ataque de usuário antes de o modelo ser chamado, antes da consulta a um cache semântico, e o gateway responde com HTTP 403 a uma requisição em que detecta um, assim como responde a uma requisição mais longa do que o serviço aceita. O shield está ligado ou desligado, então standard é mantido e strict é recusado pelo nome, e ele opera na sensibilidade própria da Microsoft, não medida em relação ao limiar que standard indica nas guardas. A instância alcança esse backend com sua identidade gerenciada, que precisa da função Cognitive Services User no serviço; o build não vê nenhum dos dois. Nenhum gateway da biblioteca padrão além desses três a realiza, e anexá-la a outro interrompe o build indicando o tipo: a maioria não gera nenhuma rota que uma realização possa enviar por uma guarda — eles mantêm suas rotas em um armazenamento próprio, as obtêm dos serviços por trás deles ou são um serviço hospedado no qual a biblioteca padrão não ativa nenhuma verificação desse tipo —, e core/gateway/apisix, cuja Recipe de chart gera as rotas dos modelos conectados a ele, e core/gateway/envoy-gateway, cuja Recipe gera a rota de IA dos modelos conectados a ele, não têm realização dela. Em core/gateway/agentgateway, cujas Recipes geram uma entrada para cada modelo conectado a ele, a realização interrompe todo anexo, indicando o motivo: o agentgateway julga uma requisição em busca de tal tentativa somente por meio de um serviço que ele chama — um webhook que o operador executa, ou Azure AI Content Safety, Google Model Armor ou AWS Bedrock Guardrails —, e a realização não conecta nenhum deles. Em core/gateway/higress, a realização também interrompe todo anexo, indicando o motivo: o Higress julga tal tentativa somente por meio de um serviço que ele chama — o serviço de segurança de conteúdo da Alibaba Cloud ou, por meio de um plugin que seu código-fonte contém, mas que sua versão de plugins 2.2.5 não publica, um serviço de modelo Qwen3Guard que o operador executa —, cada um deixando a requisição passar quando essa chamada falha, e a realização não conecta nenhum dos dois. Em core/gateway/traefik-hub, a realização também interrompe todo anexo, indicando o motivo: o Traefik Hub julga tal tentativa somente por meio de um serviço que ele chama — seus middlewares LLM Guard e Parallel LLM Guard, que chamam um serviço de guarda ou um modelo com uma requisição e com condições que a realização teria de escrever, e cujo funcionamento com um detector de ataques de prompt não é medido, de modo que nenhuma sensibilidade corresponde a uma verificação ali; ou seus middlewares Azure Prompt Shield, Amazon Bedrock Guardrails e GCP Model Armor, que chamam serviços hospedados que a realização não conecta. A guarda lê somente a última mensagem de usuário, então uma mensagem de sistema, um turno anterior ou o resultado de uma ferramenta chega ao modelo sem ser lido, e somente o tráfego que atravessa o gateway é triado: uma carga de trabalho que chama diretamente o endereço do modelo o contorna.

  • Validação de respostas e avaliações: core/response-validation declara uma verificação da resposta de um modelo em relação a um JSON Schema antes que ela chegue ao chamador: schema contém o próprio schema, e uma resposta que não corresponde a ele é recusada em vez de repassada — ou, com invert ativado, uma resposta que corresponde. O schema pertence ao anexo e é o mesmo para toda requisição, não um que o chamador envia com sua própria requisição; por isso o desenvolvedor o anexa no Aggregate, escrevendo o schema em seus values. Nenhuma realização da biblioteca padrão o aplica: em core/gateway/agentgateway, sua realização interrompe todo anexo, indicando o motivo — as guardas de resposta do agentgateway comparam padrões ou chamam um serviço de content safety ou um webhook, e nenhuma delas aceita um schema —, e o mesmo faz sua realização em core/gateway/higress, cuja verificação de respostas responde a uma resposta aprovada com o JSON puro que encontra na mensagem da resposta em vez da chat completion que sua rota OpenAI retorna, é ignorada por qualquer cliente que envie o cabeçalho de requisição X-HIGRESS-AI-JSON-RESP: true e deixa sem verificação um schema aninhado a mais de seis níveis de profundidade; e o mesmo faz sua realização em core/gateway/traefik-hub, já que nenhum middleware na referência do Traefik Hub verifica uma resposta em relação a um schema — seu middleware Chat Completion verifica as requisições em relação ao schema de chat completion, seu gerenciamento de APIs verifica os corpos das requisições em relação a um documento OpenAPI, e seu LLM Guard envia uma resposta a um serviço externo, que a realização não conecta; em qualquer outro gateway, um anexo interrompe o build indicando o tipo. core/traffic-shadowing copia requisições reais para um segundo serviço e descarta as respostas desse serviço, para que um modelo ou serviço candidato possa ser avaliado sob tráfego real sem que nenhum chamador veja sua saída. Ela se anexa a qualquer componente que declare dataplane.aggrega.ai/request-mirroring, o que o gateway de IA não faz; a biblioteca padrão a realiza no gateway NGINX, que copia o fluxo inteiro em vez de uma parcela dele, e é interrompida, indicando-a pelo nome, diante de uma parcela menor.

5. Execução assíncrona e infraestrutura HITL

O Aggrega trata frameworks de interação humana (como AutoGen e LangGraph) como nós worker. Para dar suporte a agentes “adormecidos” que aguardam entrada humana sem perder o estado, arquitetos de plataforma podem declarar sockets usesSchema nos Components desses agentes que impõem estritamente o vínculo explícito de componentes da categoria datastore a eles, selecionados pelo rótulo de engine do datastore — datastore.aggrega.ai/engine in (vector, semantic-memory, search) para um armazenamento do qual o agente recupera por similaridade, ou datastore.aggrega.ai/engine=kv para um no qual ele grava checkpoints do seu estado de execução. O socket se vincula ao rótulo de engine em vez de a um nome de produto, de modo que um autor escolhe qual armazenamento chega e a declaração continua válida. Além disso, para ciclos de feedback de humano para agente (por exemplo, integrações com o Slack), é possível configurar uma função de veredito de governança para rejeitar a arquitetura, a menos que um componente gateway declarado explicitamente esteja anexado, de modo que os webhooks de callback entrem por um limite de entrada declarado.

Agentes construídos sobre um framework ou SDK em torno do qual uma aplicação é escrita, em vez de distribuídos como um produto próprio, assumem uma única forma na biblioteca padrão. A Release indica a imagem da aplicação, que o catálogo não fixa. Um socket model leva o que o framework lê do modelo conectado — seu endereço e o nome do modelo, onde o framework os lê, e a credencial da conexão, por referência — às variáveis que esse framework lê. Onde o framework não define um servidor próprio, o componente é um worker e não abre nenhuma porta: core/ai-agent/crewai e core/ai-agent/langgraph assumem essa forma, assim como core/ai-agent/openai-agents-sdk, cujo socket model aceita apenas um modelo ou gateway que tenha model.aggrega.ai/api: openai, core/ai-agent/claude-agent-sdk, cujo socket aceita apenas um que tenha model.aggrega.ai/api: anthropic, e core/ai-agent/agent-framework, para uma aplicação construída sobre o Microsoft Agent Framework, que não serve nada por si só, cujo socket aceita apenas um que tenha model.aggrega.ai/api: openai e entrega as variáveis que os clientes OpenAI em Python do Agent Framework leem; esses três interrompem o build, indicando infra.image, até que a Release o defina. O OpenAI Agents SDK envia por padrão um trace de cada execução para a OpenAI, então core/ai-agent/openai-agents-sdk desativa esse envio, a menos que o Aggregate defina seu valor upload_traces_to_openai como true. Onde o framework serve HTTP por conta própria, o componente é um server na porta própria do framework e publica o endereço que um chamador alcança como host, port, endpoint e protocol, e ele também interrompe o build, indicando infra.image, até que a Release o defina: core/ai-agent/google-adk serve a API REST do ADK na porta 8000 e entrega a chave que o cliente Gemini do ADK envia à API Gemini, com seu socket model aceitando apenas um modelo que tenha model.aggrega.ai/api: gemini, como core/ai-model/gemini, e nunca um gateway, cujo endereço o cliente do ADK não leria; core/ai-agent/mastra serve o servidor que o Mastra constrói na porta 4111, pronto no Kubernetes assim que sua rota /health responde, aceita um modelo ou gateway que tenha model.aggrega.ai/api: openai e, onde o Aggregate indica um dos agentes da aplicação em seu valor agent_id, publica o endereço do cartão Agent2Agent desse agente, para que core/ai-tool/agent-invocation possa delegar a ele. As rotas de ambos os servidores respondem a qualquer chamador, a menos que a aplicação as autentique, então um anexo core/public-ingress ou core/http-route em qualquer um deles interrompe o build até que a Release defina seu infra.routes_authenticated como true, afirmando que a aplicação autentica toda requisição que suas rotas recebem. Os runtimes de SDK e de servidor e core/ai-agent/agent-framework também declaram um socket tools opcional, que entrega o endereço de cada ferramenta conectada, e a credencial da conexão por referência, em variáveis nomeadas conforme o alias da conexão. Como a aplicação é o código próprio da Release, as variáveis que esses agentes entregam para esse código ler são padrões: cada socket deles admite um bloco inject:, por meio do qual o Aggregate indica as variáveis, ou os arquivos, que a aplicação lê em vez delas, enquanto uma variável que o framework lê por conta própria e o que um anexo na conexão entrega permanecem. O mesmo vale para os valores próprios do agente: cada componente admite em si mesmo um bloco inject: de entradas env e file, e uma entrada cujo template lê um de seus valores próprios e nada mais do componente — nenhum outro valor, nem seu infra, seus metadados ou sua identidade — substitui o nome padrão sob o qual uma Recipe entrega esse valor, como CREWAI_ROLE para o role de um agente CrewAI. Uma importação das declarações de agentes de um projeto CrewAI, do langgraph.json de uma aplicação LangGraph, das configurações de agentes de uma aplicação Google ADK ou de um agente declarativo do Agent Framework gera rascunhos desses agentes — core/ai-agent/crewai, core/ai-agent/langgraph, core/ai-agent/google-adk e core/ai-agent/agent-framework — conectados ao datastore que a configuração indica, e ao modelo que ela indica onde o socket model do agente o aceita, ao lado de um rascunho de Release que deixa para o operador indicar a imagem em que o programa é executado, e lê apenas a configuração, nunca o programa, como descreve Plugins de importação.

6. Validação topológica de segurança e aplicação em tempo de execução

Como as cargas de trabalho de IA introduzem novos vetores de ataque (como injeção de prompt e exfiltração autônoma de dados), protegê-las exige unir a governança arquitetural estática à aplicação ativa em tempo de execução. Como compilador antecipado (Ahead-of-Time, AOT), o Aggrega não intercepta tráfego de rede ao vivo nem avalia prompts de IA. Em vez disso, ele resolve requisitos de segurança complexos por meio de um handshake arquitetural em duas partes: compilação estática da arquitetura (em tempo de compilação) e passagem para a execução (em tempo de implantação).

A. Tempo de compilação: validação de policies e geração de artefatos

O compilador constrói um grafo plano de representação intermediária (IR) contendo todos os nós, arestas e Features anexadas. Antes que qualquer infraestrutura física seja gerada, a postura de segurança da empresa é aplicada avaliando esse grafo JSON estático com engines de policy padrão do setor em uma função de veredito de governança.

Como o socket avalia dados JSON genéricos, ele não fica preso a uma única linguagem de policy. As empresas podem compilar e aplicar suas regras arquiteturais usando o padrão que melhor se adapta ao seu ecossistema:

  • Open Policy Agent (OPA/Rego): uma linguagem amplamente usada para avaliar relações de grafo complexas e de múltiplos saltos e calcular o acesso de privilégio mínimo em topologias distribuídas. O engine Rego compilado na CLI executa arquivos .rego como estão; uma policy que precisa de toda a superfície de builtins do OPA é compilada com a toolchain do próprio OPA e é executada atrás de um guest adaptador.
  • Common Expression Language (CEL): o engine CEL compilado na CLI executa regras escritas como expressões únicas sobre um documento, do modo como se escreve uma validating admission policy do Kubernetes.
  • Kyverno: avalia manifestos JSON/YAML estáticos, permitindo que as equipes escrevam policies em YAML nativo em vez de aprender Rego. Nenhum guest Kyverno é distribuído com o compilador, que executa policies apenas como guests WebAssembly e nunca invoca a CLI do Kyverno, então as regras do Kyverno são executadas atrás de um guest que encapsula o engine.
  • Validação personalizada em Rust/TypeScript: as equipes de segurança podem escrever policies organizacionais sob medida em linguagens padrão e compilá-las para Wasm para que atuem como portão de validação.

Depois que a engine de policy valida o grafo, o compilador traduz esses requisitos de segurança abstratos em configuração física. Quando um desenvolvedor anexa uma Feature de segurança — core/data-masking no gateway de IA, por exemplo —, o compilador executa a etapa de pipeline que sua realização indica, um plugin WebAssembly (Wasm) isolado, e essa etapa grava a configuração de que o controle precisa na configuração que a própria Recipe do gateway já gera. Uma realização pode, em vez disso, deixar a gravação para a própria Recipe do gateway, que lê o anexo e grava a configuração por conta própria, como faz core/data-masking em core/gateway/kong-enterprise, e uma realização para outro tipo de controle pode emitir um recurso próprio; em qualquer caso, a saída é um artefato estático escrito a partir do que o desenvolvedor anexou.

B. Tempo de implantação e de execução: passagem para a execução e aplicação

A responsabilidade do Aggrega termina no exato momento em que ele conclui o processamento da entrada e grava os artefatos estáticos configurados no diretório de saída. Ele é um compilador puro: grava a configuração, e então o controle retorna inteiramente ao sistema que o invocou.

Como essas configurações são executadas é altamente flexível e fica inteiramente a critério da empresa:

  • A passagem dos artefatos (tempo de implantação): controladores de implantação externos assumem para tornar os artefatos realidade. Isso poderia ser um controlador GitOps rigoroso (como ArgoCD ou Flux) sincronizando arquivos em um cluster Kubernetes, mas poderia igualmente ser um pipeline de CI/CD padrão executando terraform apply, ou um desenvolvedor executando um script de shell local com Docker Compose.
  • Aplicação em tempo de execução: depois que as configurações são aplicadas ao ambiente de destino, a infraestrutura física assume. As ferramentas especializadas configuradas pelo Aggrega (como um sidecar de guardrails, uma service mesh ativa ou firewalls nativos de nuvem) são inicializadas e começam seu trabalho ativo: interceptar fisicamente payloads, verificar JWTs ou descartar injeções de prompt maliciosas.

7. Como o Aggrega aborda os desafios de segurança da IA

Ao desacoplar a validação arquitetural da execução, as equipes de plataforma podem usar o Aggrega para modelar, validar e gerar explicitamente soluções de configuração para as vulnerabilidades de IA descritas abaixo.

A. Exfiltração de dados e interceptação de payloads

  • O problema: um agente autônomo pode tentar vazar dados corporativos restritos para uma API externa não autorizada.
  • A solução do Aggrega:
    1. Tempo de compilação (validação e geração): a equipe de plataforma escreve uma policy (por exemplo, Rego) avaliada em uma função de veredito de governança que declara: “Todo caminho que passa por um gateway de IA deve ter core/data-masking.” Se estiver ausente, o compilador é interrompido. Se estiver presente, a realização que o Manifest vincula grava o mascaramento na configuração que o gateway já gera: em core/gateway/litellm, entradas de guardrail que correspondem às expressões regulares que o anexo lista e que enviam o texto a um analyzer e a um anonymizer do Presidio conectados aos sockets pii_analyzer e pii_anonymizer do gateway para os tipos de entidade que ele lista; em core/gateway/kong-enterprise, o AI PII Sanitizer do Kong nas rotas de chat e de completion de cada modelo conectado, gravado pela Recipe de chart do gateway, que envia o texto que mascara, com as expressões regulares e os tipos de entidade que o anexo lista, ao serviço Kong AI PII conectado ao socket pii_sanitizer do gateway; em core/gateway/agentgateway, as guardas de expressão regular do próprio gateway, gravadas em sua configuração pela sua Recipe de chart, que substituem cada correspondência dos padrões que o anexo lista por <masked>, ou, sob refuse, respondem à requisição ou à resposta com HTTP 403, e não reconhecem tipos de entidade; essas guardas não mascaram uma resposta em streaming, então, enquanto as respostas são mascaradas, a mesma Recipe grava uma regra que recusa com HTTP 403, antes de ser encaminhada, uma requisição que peça uma, e qualquer requisição cujo corpo seja maior que os 2 MiB que o gateway lê para essa regra, em streaming ou não; em core/gateway/traefik-hub, um Content Guard do gateway de IA do Traefik Hub na rota de cada modelo conectado, gravado pela sua Recipe de chart, que mascara as correspondências dos padrões que o anexo lista por meio do seu mecanismo de expressões regulares, ou dos tipos de entidade que ele lista por meio do analyzer do Presidio conectado ao socket pii_analyzer do gateway, um mecanismo por anexo; em core/gateway/higress, o plugin ai-data-masking do Higress na rota de cada modelo conectado, gravado pela sua Recipe de chart, que substitui cada correspondência dos padrões que o anexo lista nas mensagens de uma requisição de chat pelo nome do padrão entre colchetes, e não reconhece tipos de entidade. Uma policy também pode fazer a pergunta mais restrita — se o mascaramento fica entre os dados restritos e o provedor — lendo os anexos de cada componente ao longo da rota em vez dos anexos da rota como um todo, como faz examples/policy-data-class-route.
    2. Tempo de execução (aplicação física): Depois que o orquestrador implanta os artefatos gerados, o gateway substitui cada correspondência no texto da requisição que ele mascara por um placeholder antes de encaminhá-la, de modo que o provedor do modelo recebe o placeholder; com action: refuse, a vinculação não encaminha nada de uma requisição que contenha uma correspondência e, em vez disso, responde a ela com um erro. Um reconhecedor que não pode ser alcançado ou que falha faz a requisição falhar, de modo que seu texto não é repassado. O que o mascaramento não alcança é decidido por dois valores cujos valores padrão são a proteção. No AI gateway, enquanto a vinculação também mascara as respostas, o gateway mascara o texto da resposta e as partes que um modelo ou seu provedor adiciona ao lado dele — uma recusa, citações e anotações, a consulta e os resultados de uma pesquisa na web, campos com nomes próprios do provedor — ou, com refuse, não envia nada de uma resposta que contenha uma correspondência; uma resposta em streaming que ele mascara por correspondência de padrões chega ao chamador inteira, no final. Por padrão, o que o mascaramento não alcança em uma requisição — uma rota como a geração de imagens, um campo como safety_identifier, uma imagem ou um arquivo na conversa, uma ferramenta que o próprio provedor executa — o AI gateway recusa com HTTP 400 antes de encaminhar qualquer parte dela; um operador que aceita que esse texto chegue ao provedor sem máscara define allow_unmasked_text na vinculação na Release, com a realização listando exatamente o que passa então, e o conteúdo que não é texto continua regido por allow_non_text_content. Por padrão, o que uma resposta mascarada traz e que o mascaramento não consegue ler — áudio falado e sua transcrição, uma imagem, as probabilidades dos tokens que o modelo escolheu — é retido, e uma chamada que falhou chega ao chamador com uma mensagem fixa no lugar da que o provedor retornou; allow_unmasked_reply_parts permite que essas partes cheguem ao chamador sem máscara. O texto da própria resposta nunca é liberado por esse valor, mas as partes que ele libera podem conter as palavras da resposta: a transcrição de uma resposta falada, os tokens por trás das probabilidades de tokens, a mensagem de erro de um provedor que cita a resposta. Em core/gateway/kong-enterprise, cada correspondência é substituída por um placeholder numerado, de modo que uma vinculação que lista padrões em redact define placeholder_shows_name: false; refuse alcança apenas requisições, a partir do Kong 3.12, que responde a uma requisição com correspondência com HTTP 400; e as respostas são mascaradas a partir da 3.12, quando uma requisição que pede uma resposta em streaming passa a ser recusada antes de ser encaminhada, e allow_streamed_replies é recusado. O sanitizer do Kong lê o texto dos turnos do usuário, o prompt de uma completion e o texto da mensagem de uma resposta, e a referência do Kong não cita nenhuma configuração que recuse uma requisição pelo que o sanitizer não lê ou que retenha o restante de uma resposta, de modo que nesse gateway cada proteção é recusada pelo nome em tempo de build enquanto mantém seu valor padrão, e uma vinculação é compilada assim que a Release as flexibiliza — allow_unmasked_text e allow_non_text_content onde as requisições são mascaradas, allow_unmasked_reply_parts e mask_reasoning: false onde as respostas são —, com data-masking-kong-enterprise listando o que cada uma libera então. Ali, uma resposta cujo texto não chega como a string única que a API da OpenAI retorna passa sem ser lida, e seu próprio texto chega ao chamador sem máscara; a salvaguarda é a verificação que o build faz em cada modelo conectado a esse gateway, que é interrompida diante de um modelo cujo model.aggrega.ai/api não seja openai. Em core/gateway/traefik-hub, cada correspondência é substituída por uma sequência de * tão longa quanto a correspondência, de modo que uma vinculação que lista padrões em redact define placeholder_shows_name: false; refuse responde HTTP 403 no lugar da requisição ou da resposta; e uma resposta mascarada é retida inteira e enviada no final, inclusive uma em streaming, de modo que uma vinculação que mascara tipos de entidade nas respostas define allow_streamed_replies. A referência do Traefik não diz quais campos de uma requisição ou resposta de chat o Content Guard lê, e não cita nenhuma configuração que recuse uma requisição, ou retenha parte de uma resposta, pelo que ele não lê, de modo que nesse gateway cada proteção é recusada pelo nome em tempo de build enquanto mantém seu valor padrão, e uma vinculação é compilada assim que a Release as flexibiliza — allow_unmasked_text e allow_non_text_content onde as requisições são mascaradas, allow_unmasked_reply_parts e mask_reasoning: false onde as respostas são —, com data-masking-traefik-hub listando o que cada uma libera então. Uma vinculação que lista tanto padrões quanto tipos de entidade, e uma segunda vinculação de mascaramento em um mesmo gateway, são recusadas, já que a referência do Traefik não diz se um segundo Content Guard em uma rota lê o texto que o primeiro mascarou ou a requisição tal como o chamador a enviou. Em core/gateway/higress, o plugin ai-data-masking do Higress substitui cada correspondência dos padrões que a vinculação lista, no conteúdo e no raciocínio de cada mensagem de uma requisição de chat, pelo nome do padrão entre colchetes; ele mascara apenas requisições, então scope response e both são recusados, e não reconhece nenhum tipo de entidade. O plugin não lê mais nada de uma requisição, então, enquanto as proteções mantêm seus valores padrão, a Recipe de chart do gateway também escreve o plugin de validação de requisições do Higress para recusar com HTTP 403, antes que qualquer coisa seja encaminhada, uma requisição que traga o que o mascaramento não lê — um corpo não enviado como JSON ou que não seja uma chat completion, uma mensagem cujo conteúdo seja uma lista ou null, uma chamada de ferramenta ou um turno de ferramenta, o nome de uma mensagem, qualquer parâmetro exceto os não textuais de uma chat completion e as ferramentas, o formato de resposta e as sequências de parada do próprio desenvolvedor — e, seja o que for que a vinculação flexibilize, uma requisição cujo corpo os plugins do Higress ignoram — um corpo comprimido, um content type contendo octet-stream ou grpc, um upgrade — e um corpo que contenha o caractere de substituição Unicode U+FFFD, que é como essa validação lê um byte que não é UTF-8 válido, já que o plugin de mascaramento encaminha sem máscara um corpo que não é UTF-8 válido. Uma requisição cujo corpo excede o buffer de 32 KiB do gateway é recusada com HTTP 413. A validação lê apenas um corpo que seu decodificador JSON aceita, de modo que um cliente que envia deliberadamente JSON válido que o decodificador recusa — um número além do que um double comporta, por exemplo — passa por todas as recusas do seu corpo: o plugin de mascaramento então mascara apenas o conteúdo simples e o raciocínio de cada mensagem, de modo que um valor listado em qualquer outro lugar do corpo — os argumentos de uma chamada de ferramenta, um nome, qualquer outro campo — é encaminhado sem máscara, assim como o conteúdo escrito com sequências de escape JSON, e, se esse corpo também não for UTF-8 válido, tudo é encaminhado sem máscara. Um cliente que aninha deliberadamente um corpo a mais de 127 níveis de profundidade, dentro de um campo que a validação admite, como tools, envia JSON válido que a validação decodifica e admite, mas o leitor JSON do plugin de mascaramento para nessa profundidade, de modo que o conteúdo escrito com sequências de escape JSON nesse corpo também é encaminhado sem máscara. O mascaramento não basta por si só: o texto que nenhum padrão encontra e nenhum reconhecedor detecta passa inalterado; no AI gateway, os argumentos de chamadas de ferramenta e os resultados de ferramentas são mascarados valor por valor, mas os nomes de suas chaves não; as definições de ferramentas, os formatos de resposta e as sequências de parada do próprio desenvolvedor passam como enviados; o gateway e os serviços de reconhecimento veem o texto original; o que o gateway registra sobre uma chamada — em seu próprio log ou no que entrega a uma integração de logging — ainda pode conter esse texto; e o tráfego que não atravessa o gateway não é tocado.

B. Defesa contra envenenamento de MCP (confiança e isolamento)

  • O problema: Se um agente for comprometido por meio de uma ferramenta do Model Context Protocol (MCP) envenenada, ele poderá executar de forma autônoma ações destrutivas (como excluir um banco de dados ou autorizar uma transferência).
  • A solução do Aggrega:
    1. Tempo de compilação (validação e geração): O desenvolvedor vincula uma Feature de aprovação à ferramenta sensível em seu Aggregate.yaml. A biblioteca padrão não traz nenhuma Feature desse tipo, então esta é escrita no catálogo da própria empresa, junto com a FeatureRecipe que a renderiza. O compilador valida o grafo e traduz a vinculação na configuração para um proxy L7 ou um gateway de webhook.
    2. Tempo de execução (aplicação física): Quando o agente sequestrado tenta invocar a ferramenta, o proxy implantado pausa a requisição e bloqueia fisicamente a execução até receber de um operador humano uma aprovação assinada criptograficamente.

C. Resolvendo o “Confused Deputy” (propagação de contexto)

  • O problema: Em cadeias multiagente, um agente exposto ao público pode ser sequestrado e comandar um agente interno, altamente privilegiado, a buscar dados sensíveis. Firewalls comuns veem apenas que “o agente A está falando com o agente B” e permitem o tráfego, perdendo completamente o contexto do usuário mal-intencionado original.
  • A solução do Aggrega: As empresas podem combinar dois padrões específicos:
    1. Propagação da identidade do chamador, em dois saltos: A identidade do chamador original precisa sobreviver a dois saltos diferentes, e cada um é protegido em um lugar diferente. No salto do gateway, o desenvolvedor vincula core/context-propagation, que seleciona por dataplane.aggrega.ai/caller-identity, ao gateway pelo qual uma requisição entra. Em tempo de compilação, a vinculação é realizada na configuração do próprio gateway — no Envoy Gateway, uma client traffic policy que verifica o certificado de cada cliente em relação a uma autoridade que a Release nomeia e encaminha os detalhes do certificado; no AI gateway LiteLLM, um hook de requisição que remove qualquer cabeçalho de identidade fornecido por um chamador e adiciona o usuário e a equipe da chave virtual que o gateway verificou, e sua organização quando a chave nomeia uma, nas requisições aos aliases de modelo que a vinculação lista em destinations. Em tempo de execução, o serviço por trás do gateway recebe quem chamou, e não apenas que o gateway chamou. No salto entre cargas de trabalho, uma requisição que um agente faz diretamente a outro nunca atravessa esse gateway, então ela é verificada no próprio ingress do agente receptor, onde uma service mesh rejeita qualquer requisição sem um token assinado que comprove a intenção do usuário original (por exemplo, uma AuthorizationPolicy JWT do Istio). A biblioteca padrão traz a Feature do salto do gateway e nenhuma Feature do salto entre cargas de trabalho, então vincular core/context-propagation protege o tráfego que passa por um gateway e deixa as chamadas de agente para agente a cargo da configuração da mesh que a própria empresa fornece. Um agente que outra parte executa, que core/ai-tool/agent-invocation alcança via A2A como core/ai-agent/a2a-remote, fica totalmente fora da Release: essa parte verifica cada chamada segundo o esquema de segurança que o Agent Card do agente declara, e a ferramenta apresenta a credencial mantida em sua conexão, lida por referência de um Secret, no cabeçalho de requisição que o agente publica. Quando o card exige client credentials do OAuth 2.0 ou OpenID Connect, a conexão mantém um client secret em vez disso, ou também, com o client id que o operador escreve nela, e o agente publica o endereço do token ou de discovery e os scopes que seu card declara; o próprio contêiner da ferramenta obtém o token com eles, renova-o e o apresenta em cada chamada; o catálogo entrega apenas essas entradas, e nenhum build pode verificar o que o contêiner faz com elas. Quando o card exige TLS mútuo, a conexão mantém um certificado de cliente e, quando uma autoridade em que a imagem ainda não confia assina o certificado de servidor do agente, também essa autoridade; cada um é montado no contêiner da ferramenta como arquivos de um Secret que a conexão nomeia, e o próprio contêiner apresenta o certificado no handshake TLS. Assim, a ferramenta alcança um agente cujo card declara uma chave de API em um cabeçalho ou cookie, um esquema de autenticação HTTP de valor fixo, como Bearer ou Basic, com o Secret contendo o valor inteiro do cabeçalho, OAuth 2.0 ou OpenID Connect com o grant client-credentials, ou TLS mútuo. Ela não alcança um cujo card exige uma chave na query string, um esquema HTTP que responde a um desafio do agente, como Digest, ou um fluxo OAuth 2.0 diferente de client credentials. Tampouco apresenta uma credencial a um agente que outra parte executa sobre HTTP simples: quando o endereço desse agente é http, uma credencial ou um client secret na conexão interrompe o build, nomeando a conexão, porque a credencial, ou o token obtido com o secret, chegaria a ele sem criptografia. Um agente executado dentro da Release continua acessível por http com qualquer um deles, e a credencial então atravessa a rede do cluster sem criptografia.
    2. Inspeção de payload entre agentes: Uma requisição que um agente envia diretamente a outro nunca atravessa o AI gateway, então ela é inspecionada no próprio ingress do agente receptor, por um mecanismo de guardrails executado ao lado desse agente (por exemplo, NeMo Guardrails). Em tempo de compilação, a FeatureRecipe que realiza uma Feature vinculada ao agente receptor renderiza a configuração do mecanismo. Em tempo de execução, o mecanismo avalia cada requisição segundo regras que a empresa escreve e recusa aquela que essas regras rejeitam; o quão bem ele distingue uma requisição sequestrada de uma legítima depende do mecanismo e das regras, porque o Aggrega compila configuração e nunca avalia um prompt. A biblioteca padrão não traz nenhuma Feature que posicione tal mecanismo, então esse padrão é escrito no catálogo da própria empresa. A proteção por padrões do próprio gateway, dataplane.aggrega.ai/prompt-guard: pattern-list, é mais restrita, e core/prompt-deny-patterns a ativa — no AI gateway, lendo cada mensagem de uma requisição e ignorando maiúsculas e minúsculas, em core/gateway/apisix e core/gateway/kong, lendo cada mensagem de cada papel como um único texto, diferenciando maiúsculas e minúsculas e respeitando também uma lista de padrões aos quais uma requisição deve corresponder, em core/gateway/agentgateway, lendo separadamente cada mensagem, argumento de chamada de ferramenta e resultado de ferramenta, diferenciando maiúsculas e minúsculas, e em core/gateway/traefik-hub, lendo a requisição como uma chat completion, da qual a referência do Traefik não lista os campos lidos, diferenciando maiúsculas e minúsculas: ela recusa uma requisição ao modelo cujo texto corresponde literalmente a uma das expressões que a vinculação lista — uma paráfrase, outro idioma ou uma codificação passam por ela — e apenas no tráfego que passa pelo gateway, de modo que uma requisição enviada diretamente entre agentes nunca a encontra. core/prompt-injection-shield é sua contraparte baseada em classificador no mesmo salto, enviando cada requisição ao modelo que um gateway encaminha por um guard do NeMo Guardrails conectado ao socket guard desse gateway, ou pelo prompt shield do Azure AI Content Safety no Azure API Management, e também cobre apenas o tráfego que atravessa o gateway.

D. Análise topológica de riscos

  • O problema: Arquiteturas de IA complexas com dezenas de modelos, vetores e ferramentas interconectados são grandes demais para que uma pessoa as audite manualmente em busca de vulnerabilidades transitivas (por exemplo, “O agente A pode falar com a ferramenta B, que fala com o agente C, que tem acesso ao banco de dados D?”).
  • A solução do Aggrega: Essa verificação é executada antecipadamente. Como o Aggrega constrói em memória um grafo IR completo da topologia pretendida, um papel de veredito de governança pode executar regras avançadas de busca de caminhos em toda a arquitetura. Se a política detectar uma cadeia contínua e transitiva de arestas que se origina em um nó público e termina em um banco de dados altamente sensível sem nenhum dos controles que a empresa exige vinculado em qualquer ponto ao longo dela, ela interrompe imediatamente o build. A arquitetura insegura é bloqueada antes que uma única linha de código de infraestrutura seja gerada.

8. Observabilidade e conformidade

Para atender a requisitos regulatórios rigorosos (por exemplo, o EU AI Act), os arquitetos de plataforma podem utilizar o sistema de funcionalidades do Aggrega para impor a observabilidade de IA como um requisito estrutural da infraestrutura, em vez de depender do código da aplicação:

  • Registro de auditoria: plugins Wasm criados pela empresa podem configurar sidecars do gateway para transmitir de forma assíncrona prompts e respostas brutos, sem redação, para um bucket de armazenamento WORM (Write Once, Read Many) seguro, contornando os logs padrão da aplicação.
  • Rastreamento de LLM: funcionalidades de proxy podem configurar o data plane para extrair e encaminhar cabeçalhos de span OpenTelemetry específicos de IA, garantindo que loops complexos de raciocínio de agentes possam ser visualizados em ferramentas externas.

9. Compatibilidade de Feature e segurança topológica

Como o compilador central é agnóstico em relação à mecânica da infraestrutura física, ele depende inteiramente de declarações explícitas no catálogo para impedir a geração de configurações incompatíveis.

  • conflictsWith: uma lista, declarada na entidade de catálogo de uma Feature sob interoperability, das Features ao lado das quais ela não pode ser anexada. O compilador a compara com as Features que cada componente acaba carregando depois que todos os escopos contribuíram — os anexos do próprio componente, os escritos em um subsistema ou fronteira que o contém, os de sua entrada de componente na Release e os produzidos pela expansão orientada por anotações — e para antes de renderizar quaisquer artefatos físicos quando um componente carrega ambas (ou seja, quando um autor anexa, diretamente ou por meio de um escopo, duas Features que o autor de uma delas declarou explicitamente incompatíveis). Uma declaração basta, e as Features são correspondidas pelo nome, quaisquer que sejam suas versões. O compilador não interpreta nada nos nomes: a incompatibilidade é a declaração do autor, e a verificação é uma comparação de nomes. A atomicidade e a pureza das Features continuam sendo um contrato social — nada verifica se uma Feature faz uma única coisa.

10. Mapeamento dinâmico de topologia (resolução de dependências)

Para construir o grafo IR sem regras codificadas, o compilador o lê a partir de três declarações explícitas:

  • Arestas uses: os desenvolvedores vinculam componentes no bloco uses de cada instância, indicando o componente de destino em um socket, e toda aresta do grafo vem de um deles. Uma entrada de values que por acaso nomeie outro componente não traça nenhuma aresta: o compilador não atribui nenhum significado a um valor.
  • Destinos das arestas: todo destino de uses deve indicar um componente que o build contém; um destino que não existe interrompe o build, indicando o socket ao qual estava conectado.
  • Segurança de tipos entre nós: as strings de seletor de usesSchema atuam como instruções explícitas fora de banda, avaliadas nativamente pelo mecanismo de correspondência de labels do compilador Go durante a análise estática. Elas garantem que os desenvolvedores não possam conectar acidentalmente componentes padrão a um socket declarado que exige uma capacidade nativa de IA ou um label de conformidade específico. A garantia é limitada aos sockets declarados por construção: um seletor vive em uma entrada usesSchema, então um socket ad hoc não tem nenhum a avaliar. Cada aresta registra se seu socket foi declarado no catálogo, de modo que um operador que precise que a garantia seja total pode exigi-la como veredito de governança.

11. Design automatizado de sistemas agênticos (ADAS)

Sistemas de IA avançados contam com metaagentes que escrevem código para inventar e implantar novos agentes em tempo real. Como o Aggrega exige uma arquitetura estática ahead-of-time (AOT), ele resolve a evolução da infraestrutura em tempo de execução por meio de duas fronteiras explícitas:

  • A fronteira de sandbox pré-provisionada: para ferramentas efêmeras inventadas em tempo de execução, o arquiteto define uma funcionalidade (por exemplo, dynamic-execution-environment). Quando ela é anexada, o plugin de renderização Wasm gera a configuração para provisionar um pool de computação restrito (como um runtime WebAssembly). O metaagente injeta código novo nessa sandbox, mas seu raio de impacto fica limitado pelas políticas de rede estáticas geradas.
  • O metaagente no papel de “desenvolvedor” (o loop GitOps): se o metaagente precisar de uma infraestrutura física genuinamente nova, ele atua como desenvolvedor. Ele escreve um novo Aggregate.yaml e faz commit dele no Git. Isso aciona o pipeline de CI/CD padrão. Um papel de veredito de governança analisa estaticamente a topologia solicitada pela IA, interrompendo o build com segurança se a IA tiver alucinado uma vulnerabilidade.

12. Serialização de modelos e segurança da cadeia de suprimentos

Implantar um modelo de código aberto muitas vezes significa baixar arquivos .pkl ou .gguf opacos que podem conter payloads de código malicioso. As empresas podem tratar a segurança da cadeia de suprimentos de modelos como um problema de configuração da plataforma de destino. Ao definir uma funcionalidade model_provenance no catálogo, o plugin de renderização Wasm de uma empresa pode avaliar a configuração e traduzi-la em artefatos de runtime (como políticas Kyverno do Kubernetes), de modo que o cluster de destino fique configurado para impedir que o orquestrador baixe pesos de modelo não assinados ou não verificados.