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

Features de IA

O conjunto de Feature de IA do Aggrega

Para responder às exigências únicas, à volatilidade e às ameaças de segurança dos sistemas de IA modernos, o Aggrega incorpora inteligência especializada diretamente na sua biblioteca padrão de IA (o Catálogo) open source. Garante que tanto a estrutura genérica cloud-native como os motores de raciocínio altamente especializados e nativos de IA coexistem de forma segura.

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

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

Para ligar o Open Application Model (OAM) genérico às realidades estritas da infraestrutura moderna, a etiqueta component.aggrega.ai/type mapeia exclusivamente para um conjunto fechado de primitivas cloud-native universais. Esta identidade semântica é o que um seletor de socket, o appliesTo de uma Feature e uma política de governação leem para saber como um componente trata o estado, a entrada de rede e os ciclos de vida; o compilador compara-a como uma cadeia opaca e não se ramifica com base nela, e a forma como um componente é renderizado é decidida pela Recipe que o Manifest lhe mapeia.

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

  • server: Computação de longa duração, sem estado, que espera tráfego de aplicação de entrada (por exemplo, um AI Gateway ou uma Chat UI).
  • worker: Computação de longa duração, sem estado, que obtém trabalho de filas ou executa ciclos 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 corre até à conclusão e termina (por exemplo, scripts de migração de bases 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, uma base de dados vetorial Qdrant, um broker Kafka).
  • resource: Infraestrutura externa gerida pela plataforma (por exemplo, AWS RDS PostgreSQL, buckets S3, um barramento de eventos alojado).

O conjunto é do próprio Aggrega e é fechado. O esquema publicado do Component enumera estes valores, e um documento que contenha qualquer outro é recusado quando é carregado — E0215 indica a etiqueta e lista o que aceita. É isso que o eixo compra: uma Feature ou um seletor de socket escrito contra stateful-server significa a mesma coisa em todos os catálogos que encontra.

O que um componente é no vocabulário próprio do utilizador vai numa chave própria. Um nível, uma zona de dados, uma classe de serviço, uma divisão mais fina das primitivas — cada um é uma chave de etiqueta criada ao lado da reservada, já que o esquema do Component aceita qualquer chave de etiqueta adicional com um valor de cadeia e todas as superfícies de seletores a leem de forma idêntica. É o mesmo mecanismo que as etiquetas de duck typing de IA abaixo já usam; a chave reservada é a base partilhada, e tudo o que está acima dela pertence ao utilizador.

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

Ver entities/component para as tabelas da taxonomia de etiquetas semânticas — as etiquetas da camada cloud genérica, da camada de IA especializada, transversais e de contexto de negócio dinâmico que os arquitetos usam para sobrepor a identidade cognitiva aos tipos base.


1.1 O padrão do catálogo open source: «Naked Base, Flavored Edges»

Ao aplicar estas etiquetas, há uma distinção crítica entre o catálogo open source oficial do Aggrega (core/*) e um catálogo empresarial privado (acme/*).

Para que o catálogo open source oficial continue utilizável universalmente, tem de distinguir estritamente entre física técnica imutável e intenção cognitiva subjetiva. Se o core/datastore/postgres de uso geral for codificado com engine: relational, um plugin de veredicto de governação configurado para impor a correspondência de tipos de armazenamento de dados interrompe a compilação quando um programador ativa a extensão pgvector nos seus values e tenta ligar um agente de IA que exige um armazenamento de dados vector.

Para manter um catálogo central sem opiniões próprias, os componentes oficiais seguem este padrão: manter a base nua e dar sabor às extremidades.

  1. A base nua: O Component open source de nível raiz codifica 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). Uma base de dados Postgres é objetivamente um stateful-server; esse facto não pode mudar. O mesmo teste admite uma etiqueta de capacidade quando a identidade do produto é essa capacidade: core/datastore/qdrant e core/datastore/weaviate são motores de pesquisa vetorial e nada do que um autor escreva os torna outra coisa, pelo que cada um tem datastore.aggrega.ai/engine: vector na base, exatamente como core/datastore/redis tem kv. O que a base nua recusa é o caso oposto — um traço que depende de como um componente é configurado ou usado, para o qual existe o terceiro mecanismo abaixo.
  2. As interfaces com sabor (herança de esquemas): Um Component pode declarar extends, nomeando outro Component como a sua base, e o que isso compõe é estrutura: etiquetas, anotações, slots de anexação, 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 cria nenhum conteúdo values, infra ou provides próprio, pelo que o seu contrato é idêntico ao da sua base. É por isso que o mecanismo restringe em vez de variar: como o contrato não muda, cada Recipe escrita para a base já serve a 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 contacto de governação, ou um socket cujo seletor admite menos do que o da base. Não pode acrescentar um contrato diferente, porque não tem nenhuma superfície em que o criar. Há uma consequência que é fácil não ver: a linha de mapeamento continua a ser necessária. A seleção da Recipe faz-se pela chave de mapeamento exata, pelo que uma especialização precisa da sua própria entrada mappings.components.type, mesmo não precisando de uma Recipe própria. Ver examples/extends-wrapper para um wrapper publicado que acrescenta uma etiqueta de nível revisto e restringe um socket com base nela, juntamente com a compilação que se interrompe quando uma aresta ligada a esse socket sai do nível. Um traço que dependa de como um componente é configurado não é objeto deste mecanismo: uma especialização fixa o artefacto da sua base e herda o seu contrato, pelo que um traço verdadeiro para a especialização já é verdadeiro para a base, onde a regra da base nua o coloca. Esse traço pertence ao mutador dinâmico abaixo.
  3. O mutador dinâmico (promoção Wasm): Se um traço for ditado pelo payload do programador (por exemplo, enable_vector: true), a empresa usa o papel label-transform do socket de governação na construção da topologia para ler dinamicamente os values opacos e injetar automaticamente a etiqueta datastore.aggrega.ai/engine: vector no grafo da IR antes de as políticas serem executadas. É aqui que um traço dependente da configuração fica disponível para a avaliação estrita de políticas — são os values declarados do programador que o promovem, e a transformação é executada antes de qualquer política ler uma etiqueta.

A exceção empresarial: Como o compilador se mantém sem opiniões próprias, as empresas que criam os seus próprios catálogos internos são livres de quebrar esta regra. Se uma política de segurança corporativa ditar que todas as bases de dados internas são altamente sensíveis, o arquiteto de plataforma pode e deve codificar compliance.aggrega.ai/data-class: restricted (ou uma etiqueta semelhante ditada pela empresa) diretamente no seu componente base acme/postgres, para que todas as suas instâncias transportem a classe e uma política que a empresa anexe a leia em cada uma delas. A etiqueta em si não impõe nada: o compilador transporta-a como uma cadeia, e é a política anexada que interrompe uma compilação. Quando apenas alguns dos usos que um parque faz de um produto contêm esses dados, é uma especialização através de extends que transporta a classe — ver examples/policy-data-class-route, cujo assistente de sinistros é o agente LangGraph da biblioteca padrão mais uma etiqueta de classe, ao lado da política que a lê.

1.2 Como as etiquetas semânticas alimentam a pipeline do compilador

Para manter as etiquetas no domínio do arquiteto de plataforma, os programadores não podem escrever etiquetas nas suas instâncias de Component dentro do Aggregate: o esquema do Aggregate não dá a uma instância de componente nenhuma chave labels. As etiquetas de um nó são as da sua entidade de catálogo, juntamente com as que um anexo de governação label-transform configurado pelo operador acrescente durante a construção da topologia. Eis exatamente como estas etiquetas conduzem a pipeline de compilação sem exigir código Go personalizado:

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

  • Quem a escreve? O arquiteto de plataforma (Domínio 2). É obrigatória para todos os componentes 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 cloud operacional central. O analisador estático avalia as cadeias de seletor de usesSchema nativamente em Go para garantir que um programador não pode anexar um agente a uma base de dados padrão se o socket exigir uma capacidade de IA específica. Além disso, o DevOps usa esta etiqueta para encaminhar explicitamente as primitivas com estado (stateful-server, resource) para fronteiras físicas de cluster que suportem discos persistentes, enquanto um papel de veredicto de governação pode impor que os componentes com estado nunca sejam colocados em fronteiras apenas efémeras.

2. model.aggrega.ai/capability

  • Quem a escreve? O arquiteto de plataforma.
  • Quem a consome? O analisador estático (através dos seletores de etiquetas ao estilo Kubernetes dos sockets usesSchema).
  • Caso de uso no compilador: Quando um arquiteto cria um seletor usesSchema que nomeia a etiqueta de capacidade exigida, o motor nativo de correspondência de etiquetas do compilador rejeita as ligações que não satisfaçam o seletor antes de os artefactos serem gerados. O compilador trata estas etiquetas como cadeias opacas; o significado semântico de «text-generation» versus «embedding» vive na criação do seletor pelo arquiteto.

3. component.aggrega.ai/hosting

  • Quem a escreve? O arquiteto de plataforma.
  • Quem o consome? O motor de políticas (um papel de veredicto de governação), os Plugins de renderização Wasm e os próprios chamadores de um modelo ou de um agente na biblioteca padrão: os seus agentes, cuja asserção o lê em cada ligação model, core/ai-tool/agent-invocation, cuja asserção o lê na sua ligação target_agent, tal como a sua realização Kubernetes, que recusa uma credencial a um agente external alcançado por http, o AI gateway, cuja asserção o lê em cada ligaçã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 ligaçã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 — ver «A chave que um chamador apresenta» abaixo.
  • Caso de uso no compilador: Regista 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 uma cadeia e não avalia nada. Quando um agente cuja etiqueta de classe diz que contém dados internal se liga a um modelo com a etiqueta managed — um serviço operado fora da fronteira da própria Release —, essa política pode ler que os dados saem dessa fronteira e interromper a compilação, a menos que a ligação seja encaminhada através de um AI gateway com core/data-masking, que mascara o texto de chat e de conclusão que o gateway reencaminha. O socket model de um agente aceita esse gateway no lugar do modelo, pelo que essa rota é uma aresta do grafo que a política lê, e um modelo que o gateway serve a partir do seu socket models é uma aresta própria, do gateway para o componente de modelo, cujas etiquetas a política lê — pelo que o caminho de um agente, através do gateway, até um modelo managed está no grafo de ponta a ponta. Um upstream escrito à mão no mapa de modelos do gateway não está: é uma cadeia que o compilador não resolve, pelo que uma política que leia o grafo vê o gateway e nada por trás dele. examples/policy-data-class-route é uma dessas políticas: as suas definições classificam um modelo managed como public, e interrompe uma compilação em que um assistente que contém dados restricted alcança um sem gateway de mascaramento na rota. Trata-se de um traço transversal: os mesmos valores self-hosted | managed | external descrevem uma base de dados gerida ou um servidor de inferência executado pelo próprio tal como descrevem um modelo, pelo que a etiqueta vive sob o namespace partilhado component.aggrega.ai/ e não sob o específico dos modelos.

4. agent.aggrega.ai/autonomy

  • Quem a escreve? O arquiteto de plataforma.
  • Quem a consome? O motor de políticas (um papel de veredicto de governação).
  • Caso de uso no compilador: Identifica o risco de execução do ciclo cognitivo. Se um agente tiver a etiqueta autonomous (o que significa que executa ciclos em segundo plano sem pedidos do utilizador) e se ligar a uma base de dados altamente sensível, o motor de políticas pode interromper a compilação, a menos que um autor anexe a Feature de aprovação ou de contenção que as regras da própria empresa exijam, para que um ciclo sem supervisão não possa chegar a esses dados sem revisão.
  • O que significa um componente sem etiqueta neste eixo, porque a ausência é deliberada. A etiqueta descreve o risco de execução de um ciclo cognitivo, pelo que um componente que não contém nenhum ciclo próprio não tem aqui nenhum valor, em vez do mais baixo dos dois. Muitos componentes da categoria de agentes não têm etiqueta exatamente por essa razão: as peças de suporte que uma plataforma de agentes fornece ao lado do seu servidor — uma consola de browser, uma execução de migração de esquemas, um worker de tarefas, uma sandbox de código, um proxy de saída — estão nessa categoria porque é aí que se procuram, enquanto o ciclo que suportam vive no servidor da plataforma, que é onde está a etiqueta. O caso mais claro é um único produto dividido entre os dois tratamentos: o servidor de uma plataforma tem copilot, e a sandbox de código fornecida ao lado dele não tem nada. O critério é onde vive o ciclo e não a forma que a peça assume, pelo que um runtime que aloja código de agentes fornecido pelo utilizador também não tem etiqueta — o ciclo aí é o que quer que se implante nele, não algo que o produto afirme. Um seletor que nomeie qualquer dos valores corresponde, portanto, aos componentes que contêm um ciclo e a nenhuns outros, e um escrito para corresponder a qualquer postura de autonomia ignora as peças de suporte, em vez de as tratar como a coisa menos autónoma da implantação.

5. gateway.aggrega.ai/intelligence

  • Quem a escreve? O arquiteto de plataforma.
  • Quem a consome? O analisador estático e os plugins Wasm de linter criados pela empresa.
  • Caso de uso no compilador: Dita que funcionalidades um router consegue suportar fisicamente. A Feature de IA fallback-chain declara appliesTo: gateway.aggrega.ai/intelligence=semantic, e o analisador estático avalia esse seletor contra as etiquetas do componente de destino antes de qualquer artefacto ser renderizado. Se um programador a anexar a um gateway l4-mesh padrão, a compilação interrompe-se com uma violação de seletor que indica a Feature e o seletor em que falhou, porque o arquiteto criou esse seletor sabendo que uma malha TCP padrão não consegue analisar payloads JSON de LLM para ler o modelo que um pedido nomeia. A recusa decorre da ausência de semantic, e não da presença de l4-mesh, pelo que se aplica igualmente a um router que não tenha nenhuma etiqueta de inteligência. O compilador trata a etiqueta como uma cadeia opaca, exatamente como acima: o que semantic significa vive na criação do seletor pelo arquiteto. Num router que tenha semantic, a anexação passa o seletor, e o que acontece a seguir depende da sua concretização: a concretização da biblioteca padrão escreve a cadeia na configuração de encaminhamento do AI gateway.
  • O que a biblioteca padrão transporta. Estes componentes têm semantic: core/gateway/litellm, cuja concretização renderiza a tabela de encaminhamento do proxy: um mapa de modelos sobre vários fornecedores upstream; core/gateway/cloudflare-ai-gateway, o gateway alojado da Cloudflare, que lê cada pedido de modelo que reencaminha — o modelo que nomeia, os tokens que lhe são faturados e, quando as verificações do próprio gateway estão ativas, o seu conteúdo; core/gateway/azure-api-management, o AI gateway do Azure API Management, um serviço alojado, que lê cada pedido de modelo numa API que serve um modelo — o prompt que a sua cache semântica compara, os tokens que uma resposta reporta e o conteúdo que a sua verificação de segurança envia para inspeção; core/gateway/apisix, cujo proxy de IA lê o corpo de cada pedido numa rota que serve um modelo e os tokens que a resposta do modelo reporta; core/gateway/envoy-gateway, cuja extensão Envoy AI Gateway lê o corpo de cada pedido na rota que serve os modelos a ela ligados, para encontrar o modelo que nomeia, e os tokens que cada resposta reporta; core/gateway/kong-enterprise, o Kong Gateway Enterprise, cujo proxy de IA lê o corpo de cada pedido numa rota que serve um modelo ligado — o modelo que nomeia e as mensagens que transporta — e os tokens que cada resposta reporta; core/gateway/traefik-hub, o Traefik Hub, cujo middleware Chat Completion lê o corpo de cada pedido na rota que serve um modelo ligado, verifica-o contra o esquema de chat completion e lê os tokens que cada resposta reporta; core/gateway/agentgateway, o agentgateway, que lê o corpo de cada pedido nos seus caminhos de serviço de modelos para encontrar o modelo que nomeia — é assim que escolhe o modelo ligado para onde um pedido é enviado — e os tokens que cada resposta reporta; e core/gateway/higress, o Higress, cujo proxy de IA lê o corpo de cada pedido numa rota que serve um modelo ligado — o modelo que nomeia e se é feito em streaming — e cujos plugins leem os tokens que cada resposta reporta — pelo que as Features de IA que exigem este valor se resolvem contra qualquer um deles, e cada concretização diz o que o seu gateway respeita, ou interrompe a compilação quando o seu gateway não respeita nada disso; uma Feature sem concretização para um gateway interrompe aí a compilação, indicando o seu tipo. Nenhum componente tem l4-mesh, e os outros componentes de gateway da biblioteca padrão não têm nenhuma etiqueta de inteligência: os que encaminham tráfego terminam HTTP e encaminham na camada 7, e um deles é um plano de controlo que não encaminha nada, pelo que nenhum dos valores o descreve. Uma malha TCP de camada 4 é, por sua vez, outra classe de produto. Isso deixa a recusa acima plenamente em vigor, porque decorre da ausência de semantic: uma anexação que exija esse valor interrompe-se em qualquer um deles. Um arquiteto cujo catálogo execute de facto uma malha de camada 4 coloca l4-mesh nesse componente, o que torna a distinção selecionável nos dois sentidos.
  • Este eixo nomeia um nível de produto, o que é uma questão diferente do que um componente pode fazer ao tráfego, e lê-lo no segundo sentido é o erro que convida a cometer. semantic diz que o router analisa o corpo do pedido, que é aquilo de que precisa um controlo que atue sobre o modelo que um pedido nomeia — pelo que é o eixo certo para isso. Não diz nada sobre se um router consegue copiar tráfego, transportar a identidade de um chamador, verificar o certificado de um upstream, recusar um prompt que corresponda a uma lista de padrões ou manter um orçamento ao longo de um período, e uma Feature que precise de uma dessas coisas 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 quando um router semantic oferece uma delas, oferece-a por razões que o nível não regista. Assim, o nível alcança o conjunto errado nos dois sentidos — exclui por completo os proxies simples e não diz nada sobre que capacidades tem de facto o AI gateway que alcança. Essa questão pertence ao eixo do caminho de dados abaixo, e os dois compõem-se — uma Feature pode exigir um router semantic que também espelhe, nomeando ambos.

6. tool.aggrega.ai/impact

  • Quem a escreve? O arquiteto de plataforma.
  • Quem o consome? O motor de políticas e os Plugins de renderização Wasm.
  • Caso de uso no compilador: Ao passar isto do bloco values mutável do programador para a identidade imutável das etiquetas, permite ao motor de políticas avaliar configurações estritas de privilégio mínimo. Um plugin de renderização pode gerar permissões invoke padrão para uma ferramenta de pesquisa 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 um parque (ou injetada dinamicamente através do papel de governação label-transform).
  • Quem a consome? O motor de políticas (um papel de veredicto de governação).
  • Caso de uso no compilador: Dá aos dados que um componente contém uma identidade de governação que uma política pode seguir ao longo do grafo. O compilador leva a etiqueta até ao grafo da IR como uma cadeia e não classifica nada: não sabe que restricted é mais sensível do que public, nem que qualquer das palavras significa algo. Uma política anexada no papel ir-verdict fornece esse significado nas suas próprias definições — que classes existem e como se ordenam — e lê a etiqueta nos componentes das rotas que o compilador enumera sobre as arestas uses, pelo que pode interromper uma compilação em que um componente que contém dados restricted alcança um componente de outra classe ao longo de uma rota sem nenhuma Feature anexada que a política considere desclassificadora, como core/data-masking no AI gateway por onde a rota passa. A enumeração é limitada por componente de partida e não lista nada para além do limite, pelo que uma rota que a política lê é real, enquanto a ausência de uma não é prova de que nenhuma existe. examples/policy-data-class-route é essa política, escrita para os motores Rego e CEL compilados na CLI e para o OPA, com as compilações que se interrompem e a que conclui lado a lado.
  • O que a biblioteca padrão transporta. Nenhum Component core/ tem esta etiqueta. A classe dos dados de um componente é uma afirmação sobre a forma como um parque usa o componente, não uma propriedade do produto verdadeira em cada Release, pelo que, pela regra da base nua, fica fora da base: um parque coloca-a no seu próprio Component — uma especialização através de extends, como é o assistente de sinistros do exemplo trabalhado, ou uma base própria ao abrigo da exceção empresarial acima.

8. hardware.aggrega.ai/accelerator

  • Quem a escreve? O arquiteto de plataforma. Ao empacotar um componente de modelo local, sabe que este exige fundamentalmente uma GPU para funcionar.
  • Quem a consome? O DevOps (Domínio 4).
  • Caso de uso no compilador: O DevOps encaminha explicitamente os componentes com etiqueta de GPU para fronteiras de pools de hardware físico na Release, através do mapa components: {}. O programador limita-se a pedir o modelo cognitivo no seu Aggregate, e o DevOps coloca-o na dispendiosa fronteira do cluster de GPU, preservando totalmente a separação de responsabilidades. Um papel de veredicto de governação pode, além disso, impor que nenhum componente com esta etiqueta seja colocado numa fronteira sem infraestrutura de GPU.

9. datastore.aggrega.ai/engine

  • Quem a escreve? O arquiteto de plataforma, em componentes da categoria de armazenamento de dados (estaticamente, numa especialização com sabor, ou injetada pelo papel label-transform quando os values do programador promovem o papel). Os valores em uso no catálogo são: relational, document, kv, vector, graph, semantic-memory, search. Cada valor nomeia um motor de armazenamento que um produto é — search nomeia um motor de pesquisa e análise que também indexa vetores —, pelo que um traço que vive no esquema e no padrão de acesso próprios de uma aplicação, e não em nenhum armazenamento implantável, não é um valor neste eixo.
  • Quem a consome? O analisador estático (através de cadeias de seletor) e o motor de políticas.
  • Caso de uso no compilador: Os seletores visam a semântica de armazenamento e não produtos — o socket de base de conhecimento de um agente seleciona datastore.aggrega.ai/engine in (vector, semantic-memory, search), e um motor de políticas pode recusar o encaminhamento de payloads SQL para um motor vetorial. A relevância para IA nos armazenamentos de dados de dupla utilização deriva desta etiqueta e nunca é guardada como um booleano separado.
  • O que a biblioteca padrão transporta. core/datastore/qdrant, core/datastore/weaviate, core/datastore/chroma, core/datastore/pgvector e core/datastore/milvus têm vector, core/datastore/cognee tem semantic-memory, e core/datastore/opensearch e core/datastore/elasticsearch têm search, pelo que o seletor de base de conhecimento acima se resolve contra cada um deles. core/datastore/redis, core/datastore/valkey e core/datastore/memcached têm kv. Cada uma destas etiquetas está na base do próprio componente, porque a identidade do produto é esse motor. Para core/datastore/pgvector, essa identidade é o artefacto que fixa: executa a própria imagem PostgreSQL do projeto pgvector, que inclui a extensão, e todas as Recipes ativam a extensão na base de dados que o componente cria — pelo que o seu traço vetorial não depende de uma definição, o que o distingue do caso configurado em «Naked Base, Flavored Edges» acima, em que um PostgreSQL de uso geral só ganha o traço quando um programador ativa uma extensão. relational, document e graph não têm nenhum componente na biblioteca padrão, pelo que um seletor que nomeie apenas valores entre estes 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 de pipelines. Cada valor nomeia a forma como um produto executa um trabalho com vários passos, e os valores seguem os componentes que os têm, em vez de uma lista definida antecipadamente. A biblioteca padrão tem dois: durable em core/ai-pipeline/temporal, cujo motor regista o resultado de cada passo como um histórico de eventos e o reproduz, pelo que um trabalho cujo worker falhe retoma onde parou; e reconciled em core/ai-pipeline/argo-workflows, cujo controlador executa cada passo como um pod a partir de um recurso de workflow guardado na própria API do cluster.
  • Quem o consome? O motor de políticas e os Plugins de renderização Wasm.
  • Caso de uso no compilador: Permite às políticas e aos renderizadores distinguir os motores de pipelines pela forma como uma execução sobrevive a uma falha — um histórico de eventos reproduzido ou um recurso de cluster reconciliado — e não 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 esteja no caminho do tráfego — um proxy inverso, um gateway de ingress, uma service mesh, um AI gateway.
  • Quem a consome? O analisador estático, através do appliesTo de uma Feature e do seletor usesSchema de um socket.
  • Caso de uso no compilador: Responde a o que este componente consegue fazer ao tráfego, que é o que um controlo em tempo de execução precisa realmente de saber e o que uma etiqueta de nível de produto não consegue dizer. core/traffic-shadowing, que copia pedidos reais para um segundo serviço para avaliação, declara appliesTo: dataplane.aggrega.ai/request-mirroring — só a chave —, e o analisador estático avalia isso contra as etiquetas do destino antes de qualquer renderização, pelo que anexá-la a um componente que não consegue espelhar de todo interrompe a compilação com uma violação de seletor que indica a Feature e o seletor em que falhou. O compilador trata cada uma destas cadeias como opaca, exatamente como trata as restantes.
  • Porque é que o prefixo nomeia o caminho do tráfego e não um tipo de componente. O espelhamento, a identidade do chamador e a verificação do upstream não são propriedades de gateways — são propriedades de qualquer coisa que esteja no caminho do pedido, e uma service mesh acrescentada a um catálogo tem as três. Dar à família o nome do tipo de componente que por acaso as teve primeiro obrigaria cada tipo posterior a repetir o mesmo vocabulário sob o seu próprio prefixo, deixando uma capacidade com vários nomes e nenhum seletor capaz de os abranger.
  • Porque é que a fidelidade vai no valor. Dois componentes podem ambos espelhar pedidos e ainda assim diferir naquilo que importa a uma Feature: um copia todos os pedidos correspondentes, o outro copia uma fração configurável deles. 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, de entre duas, que convenha à Feature. Uma Feature que não funciona de todo sem uma fidelidade nomeia esse valor no seu seletor. Uma Feature que continua a funcionar com a fidelidade mais baixa seleciona só pela chave, e a sua concretização recusa a definição que o componente não consegue respeitar: copiar todo o fluxo funciona em todos os componentes que espelham, pelo que core/traffic-shadowing se anexa a todos eles, e a concretização para um componente que declara full-rate recusa uma fração inferior a 100 com uma mensagem que indica a fração pedida e a fidelidade que o componente declara — duas coisas que a violação de seletor não diz. Os valores derivam, portanto, do que os produtos fornecidos implementam e não são compostos como uma taxonomia: request-mirroring tem full-rate e sampled porque os proxies reais se dividem exatamente assim, um a oferecer uma definição de taxa de cópia e outro a não oferecer nenhuma.
  • Um valor afirma uma capacidade, nunca um estado configurado. Os dois leem-se de forma idêntica para um programador e só um deles é uma propriedade do componente. Um proxy capaz de verificar o certificado de um upstream tem upstream-tls: trust-anchor, quer alguma implantação ative a verificação quer não — a etiqueta é aquilo com base em que uma Feature seleciona antes de qualquer configuração, pelo que carregá-la com configuração a tornaria ilegível no momento em que é usada.
  • O que a biblioteca padrão transporta. core/gateway/nginx tem request-mirroring: full-rate, upstream-tls: trust-anchor e concurrency-cap: total, um limite único sobre todos os pedidos que reencaminha. core/gateway/contour tem request-mirroring: sampled, caller-identity: client-certificate e upstream-tls: trust-anchor. core/gateway/envoy-gateway tem os mesmos três valores que core/gateway/contour, period-budget: tokens, que conta os tokens que cada resposta de um modelo que serve através do Envoy AI Gateway reporta, e concurrency-cap: per-target, um limite aos pedidos em curso para cada modelo que serve. core/gateway/kong tem upstream-tls: trust-anchor e prompt-guard: pattern-list, com o seu AI Prompt Guard a comparar as mensagens de um pedido de modelo com as listas que as suas rotas contêm. core/gateway/tyk tem upstream-pinning: public-key, que core/upstream-key-pinning seleciona. core/gateway/litellm tem 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 aos pedidos em curso para cada entrada do seu mapa de modelos. core/gateway/cloudflare-ai-gateway tem period-budget: cost. core/gateway/apisix tem period-budget: tokens, que conta os tokens que a resposta de cada modelo reporta sem atribuir preço a nada, e prompt-guard: pattern-list. core/gateway/kong-enterprise tem period-budget: tokens, que conta os tokens que a resposta de cada modelo reporta, e content-masking: entity-recognition. core/gateway/traefik-hub tem content-masking: entity-recognition e prompt-guard: pattern-list, com o seu middleware Content Guard a mascarar as correspondências dos padrões que a sua configuração contém ou os tipos de entidade que um analisador Presidio que chama deteta, ou a recusar um pedido a que um padrão corresponda, e period-budget: cost, com preços da lista de preços por modelo com que o seu middleware de quotas é fornecido, que pode em alternativa contar os tokens que cada resposta reporta. core/gateway/agentgateway tem content-masking: pattern-list e prompt-guard: pattern-list, com a sua proteção de expressões regulares a mascarar ou recusar as correspondências dos padrões que a sua configuração contém, sem reconhecer tipos de entidade, e period-budget: cost, os orçamentos que mantém por chave de API em dólares americanos, com preços do seu catálogo de custos de modelos, ou em tokens. core/gateway/higress tem content-masking: pattern-list, com o seu plugin ai-data-masking a mascarar as correspondências dos padrões que a sua configuração contém no texto das mensagens de um pedido de chat, sem reconhecer tipos de entidade, e period-budget: tokens, que conta em conjunto os tokens de prompt e de conclusão que cada resposta reporta, sem atribuir preço a nada. core/gateway/azure-api-management tem period-budget: tokens, que conta em conjunto os tokens de prompt e de conclusão que cada resposta reporta, com uma contagem separada em cada gateway da instância, sem atribuir preço a nada. core/security/nemo-guardrails e core/security/trustyai-guardrails-gateway, duas proteções que se colocam no caminho de um modelo e avaliam um pedido com um classificador treinado, têm prompt-guard: classifier, que os sockets guard do AI gateway e do gateway NGINX selecionam. Os AI gateways 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 — têm semantic e os restantes não têm nenhum valor gateway.aggrega.ai/intelligence, o que é a separação a funcionar e não uma exceção a ela: uma Feature que precise de um espelho alcança os três componentes que o têm, e um seletor de nível de produto alcançaria apenas o Envoy Gateway entre eles, por uma razão que não diz nada sobre espelhamento; uma Feature que precise de uma proteção de prompts, de mascaramento de conteúdo ou de um orçamento por período alcança um AI gateway pelo que ele consegue fazer e não pelo nível em que está, enquanto uma que limite os pedidos em curso alcança o gateway NGINX, que não tem nenhum valor de nível, tal como alcança o Envoy Gateway e o AI gateway, e uma que recuse um pedido com base numa lista de padrões alcança o Kong open source, que também não tem nenhum, tal como alcança o APISIX. Um componente sem nada a descrever num destes eixos não tem aí nenhum valor, em vez de ter o mais fraco, pelo que um seletor que nomeie qualquer valor desse eixo corretamente não se anexa a ele.

12. security.aggrega.ai/text-anonymization

  • Quem a escreve? O arquiteto de plataforma, num serviço que participa no mascaramento de texto sensível. Quando esse trabalho está dividido entre dois serviços, analyzer vai no que encontra segmentos sensíveis num texto e os reporta, e anonymizer no que reescreve os segmentos que recebe; sanitizer vai num serviço que faz ambas as coisas numa só chamada, encontrando os segmentos sensíveis no texto que lhe é enviado e reescrevendo-os ele próprio, respondendo com o texto reescrito.
  • Quem a consome? O analisador estático, através do seletor usesSchema de um socket.
  • Caso de uso no compilador: É a forma como 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, pelo que ligar qualquer dos serviços ao socket do outro interrompe a compilação com uma violação de seletor que indica 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 a sua Recipe de chart escreve para core/data-masking substitui ele próprio o que o analisador encontra. O compilador encaminha o endereço que o componente selecionado publica e não verifica nada sobre o que lá responde.
  • O que a biblioteca padrão transporta. core/security/presidio-analyzer tem analyzer e core/security/presidio-anonymizer tem anonymizer. Ambos falam a API HTTP do Presidio que o AI gateway chama quando uma anexação 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 anexação core/data-masking nesse gateway os lista. core/security/kong-ai-pii-service tem sanitizer e fala a API do serviço AI PII da Kong, que o AI PII Sanitizer do Kong Gateway Enterprise chama com todos os textos que mascara, incluindo as suas expressões regulares, enquanto houver uma anexação core/data-masking nesse gateway. O sanitizador não lhe apresenta nenhuma credencial e todos os textos lhe chegam sem máscara, pelo que o seu endereço é interno ao cluster e não se destina a ser exposto fora dele.

13. model.aggrega.ai/api

  • Quem a escreve? O arquiteto de plataforma, em todos os componentes da categoria de modelos e num gateway que serve uma API de modelos. O valor nomeia a API de modelos que 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 da Google, e native quando é a API própria do produto e nenhuma daquelas, que um consumidor alcança através do cliente desse produto. Cada valor é lido da referência do próprio produto, e um componente tem-no independentemente do que uma dada Release configure.
  • Quem a consome? O analisador estático, através do seletor usesSchema de um socket, e as asserções do AI gateway, 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 ligação aos seus sockets models.
  • Caso de uso no compilador: É o que permite a um socket aceitar tanto um modelo como um gateway que serve modelos. O socket model de todos os agentes, exceto os cinco runtimes indicados 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 apenas os componentes entre elas que tenham a etiqueta, pelo que ligar um desses sockets a um gateway que não serve nenhuma API de modelos interrompe a compilação com uma violação de seletor que indica o socket. Os requisitos de um seletor têm todos de se verificar e as suas alternativas vivem dentro do conjunto de uma única chave, pelo que a única chave a que ambos os tipos de componente respondem tem de estar em todos os componentes de modelo, bem como no gateway — e é por isso que a etiqueta nomeia uma API em vez de marcar apenas os gateways. Um gateway que a tenha publica as chaves endpoint e model que um modelo publica, pelo que a Recipe de um consumidor lê qualquer um deles da mesma forma. Um agente cujas Recipes entregam as variáveis de uma API de modelos nomeia antes o seu valor: 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, pelo que ligar um deles a um modelo ou a um gateway que sirva outra API interrompe a compilação com uma violação de seletor que indica o socket. O socket de core/ai-agent/google-adk restringe também a categoria a ai-model, recusando todos os gateways, porque o cliente do ADK não lê nenhum endereço e enviaria a credencial de um gateway para o próprio endereço da Google. O AI gateway lê o valor em vez de selecionar com base nele: o seu socket models seleciona component.aggrega.ai/category=ai-model, admitindo todos os modelos, e, como o gateway descreve ao seu proxy um modelo aí ligado apenas através da API da OpenAI, a asserção do seu Component interrompe a compilação numa ligação cujo destino tenha qualquer valor que não openai, indicando a ligação e dizendo para escrever antes esse upstream no mapa de modelos escrito à 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 leem-no da mesma forma nos seus próprios sockets models, porque cada um escreve a rota de um modelo ligado, ou, no agentgateway, a sua entrada de modelo, apenas para a API da OpenAI. O compilador trata o valor como uma cadeia opaca e não verifica nada sobre o que responde no endereço.
  • O que a biblioteca padrão transporta. 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 têm openai, tal como os servidores autoalojados core/ai-model/vllm, ollama, docker-model-runner, tgi, tei, nvidia-nim e litellm, as APIs geridas core/ai-model/openai, openai-embedding e nvidia-api, e o intermediário core/ai-model/openai-compatible, que é apontado para um serviço que fala essa API. core/ai-model/anthropic tem anthropic, e core/ai-model/gemini tem gemini. Todos os outros componentes de modelo têm native.

14. tool.aggrega.ai/transport

  • Quem a escreve? O arquiteto de plataforma, numa ferramenta que um consumidor alcança através de um transporte que tem de falar. O valor nomeia esse transporte.
  • Quem a consome? O analisador estático, através do socket de ferramentas de um consumidor.
  • Caso de uso no compilador: É a forma como um consumidor recebe apenas as ferramentas com que consegue 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, pelo que ligar esse socket a uma ferramenta que não tenha essa etiqueta interrompe a compilação com uma violação de seletor que indica o socket. A forma como uma ferramenta é alcançada tem de ser uma etiqueta e não um valor publicado, porque um seletor lê etiquetas e nunca o conteúdo de um valor. O compilador trata o valor como uma cadeia opaca e não verifica nada sobre o que responde no endereço.
  • O que a biblioteca padrão transporta. core/ai-tool/mcp tem http. Anexa um servidor Model Context Protocol a um agente, e o Manifest escolhe como esse servidor é concretizado: 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 só fala stdio por trás de uma ponte fixada que o serve por HTTP; helm/mcp-remote e compose/mcp-remote alcançam um servidor que outra pessoa executa, e não executam nada. Todas as concretizações publicam os mesmos host, port, endpoint, protocol e credential_header, pelo que as ligações de um consumidor não mudam com a concretização. As credenciais próprias de um servidor são variáveis de ambiente, detidas 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 são entregues, onde uma referência a uma variável do Compose mantém a credencial fora do ficheiro; a credencial de um servidor remoto é detida pelo consumidor na sua própria ligação à ferramenta e apresentada sob o cabeçalho que credential_header nomeia, Authorization a menos que a Release nomeie outro. Quando um servidor remoto lê a sua chave a partir do seu próprio endereço, o consumidor detém também o endereço completo nessa ligação, num 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, pelo que a chave não chega a nenhum ficheiro renderizado, enquanto o infra.endpoint da ferramenta contém o endereço sem a parte que transporta a chave; examples/mcp-address-from-secret constrói ambos. 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 fluxos core/ai-agent/flowise e core/ai-agent/n8n, declaram um socket de ferramentas desta forma, tools, e entregam o endereço de cada ferramenta ligada, e a credencial da ligação por referência, sob variáveis com o nome do alias da ligação, enquanto uma ligação que escreva um bloco inject: recebe o que esse bloco dita em vez das variáveis derivadas do que a ferramenta publica, ficando o que os seus slots credential e endpoint contêm sob o nome do alias; um consumidor próprio declara um da mesma forma. Cada uma das três plataformas de fluxos leva para a plataforma, na implantação, um fluxo criado no Aggregate, em ambos os destinos: o Langflow carrega a definição transportada a partir do seu diretório de fluxos em cada arranque, o chatflow do Flowise é semeado por um passo único autenticado como a conta de proprietário que a Release nomeia, e o workflow do n8n é importado por um passo de inicialização antes de a plataforma arrancar. core/ai-agent/langflow declara um socket tools da mesma forma, que não admite nenhum bloco inject:, e entrega antes cada ligação através desse fluxo, porque o componente MCP Tools do Langflow só obtém o endereço de um servidor das próprias definições do Langflow ou do fluxo, nunca de uma variável: as suas Recipes escrevem o endereço da ferramenta no nó MCP Tools cujo servidor tem o nome do alias da ligação, entregam a credencial da ligaçã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 passar os hosts das ferramentas e dos armazenamentos ligados pela proteção do Langflow contra endereços privados. As três plataformas declaram também um socket vector_store que seleciona datastore.aggrega.ai/engine in (vector, semantic-memory, search), que entrega o endereço de cada armazenamento ligado — o endpoint que publica, para core/datastore/pgvector um URI de ligação sem palavra-passe, ou um composto a partir do seu protocolo, host e porta — e a credencial da ligação por referência, da mesma forma; um armazenamento que publique também a sua base de dados e o seu utilizador, como faz core/datastore/pgvector, chega ao Flowise e ao n8n também nessas partes, já que o nó vetorial PostgreSQL de nenhuma das plataformas aceita uma cadeia de ligação; o Langflow, cujo componente PGVector aceita uma cadeia, recebe esse armazenamento como AGGREGA_VECTOR_STORE_<ALIAS>_CONNECTION_STRING, sendo a credencial da ligação a sua palavra-passe, por referência no Kubernetes e tal como é entregue no Docker Compose. Um chatflow do Flowise lê uma variável entregue através de uma variável Runtime com o mesmo nome criada na página Variables do Flowise, e um workflow do n8n lê uma através de $env apenas quando o Aggregate define o valor allow_env_access_in_nodes da plataforma, já que, por predefinição, as suas Recipes mantêm o bloqueio do n8n ao acesso ao ambiente nos nós.

2. Abstração de portas (a convenção Zero-Port)

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

  • A predefiniçã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 publicam-na como uma chave provides nomeada, que os consumidores a jusante leem através do contrato de injeção .context.uses.
  • A via de escape legada (declaração explícita): Quando um componente legado tem uma porta codificada e inalterável, o arquiteto de plataforma expõe explicitamente um campo port na declaração schema: do Component. Isto dá ao programador uma forma validada de declarar a restrição física. O compilador transporta o valor ao longo da pipeline sem alterações; a Recipe consome-o através de {{ .values.port }}.
  • Portas operacionais (fora de banda): As portas usadas estritamente pela infraestrutura do cluster (por exemplo, recolha do Prometheus, métricas de sidecars Envoy) permanecem ocultas da camada cognitiva do programador. São injetadas fora de banda pelo Platform Ops através de Features (por exemplo, anexando a Feature core/prometheus-exporter, cuja porta de recolha é infra do operador).

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

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

  • Ligações entre agentes (arrays de dependências): O esquema partilhado de parâmetros de agente da biblioteca padrão contém tools_allowed e agents_allowed como arrays de values que nomeiam os Components do catálogo que um agente pode invocar ou em que pode delegar — uma convenção documentada que o compilador não avalia. Uma ligação que o compilador estabelece como aresta topológica é um socket uses que o Component do agente declara no seu usesSchema, e é o seletor desse socket que a compilação 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 ligações mapeiam as memórias semântica, episódica e procedimental para destinos de infraestrutura distintos como arestas topológicas explícitas, pelo que os motores de políticas podem avaliar e impor barreiras de acesso granulares (por exemplo, garantir que um agente consegue ler a memória semântica, mas não a pode substituir se for sequestrado). A biblioteca padrão não declara nenhum socket desse tipo.
  • Pipelines multimodais: O schema: de um Component pode declarar fases de execução explícitas como document_chunking, embedding_generation e storage_routing como values tipados, pelo que um fluxo de dados declarativo é validado antes de qualquer coisa ser renderizada. A biblioteca padrão não declara nenhuma fase desse tipo.

4. Inteligência e encaminhamento nos gateways

Os AI gateways da biblioteca padrão transportam os controlos para encaminhar pedidos para APIs de LLM: core/gateway/litellm, que corre no cluster, e dois serviços alojados — core/gateway/cloudflare-ai-gateway, o gateway alojado da Cloudflare, que a sua Recipe terraform cria numa conta Cloudflare, e core/gateway/azure-api-management, o AI gateway do Azure API Management, cuja Recipe terraform acrescenta uma API que serve um modelo, com o seu backend e a sua política, a uma instância do API Management que já existe. As Recipes helm e compose de cada gateway alojado referenciam-no onde já está configurado. Alguns controlos são valores no próprio gateway e outros são Features anexadas a ele, e cada Feature abaixo indica em que gateway a biblioteca padrão a concretiza. Num gateway alojado, cada controlo é escrito na própria configuração do gateway — uma definição do recurso do gateway da Cloudflare, um elemento da política da API no Azure API Management —, pelo que só a sua Recipe terraform o pode transportar, e as suas Recipes helm e compose interrompem a compilação em qualquer anexação. Abaixo, «o AI gateway» é core/gateway/litellm, «o gateway alojado» é core/gateway/cloudflare-ai-gateway, e o gateway do Azure API Management é indicado por extenso.

Fora do Aggrega, em tempo de execução

agente

o seu socket model, ligado ao gateway

gateway de IA

com os controlos que lhe estão associados

orçamento de tokens

cache semântica

escudo contra injeção de prompts

modelo

um fornecedor por trás do gateway

Os pedidos de um agente passam pelo gateway a que está ligado o seu socket model, pelo que cada controlo associado ao gateway fica entre o agente e o modelo. Os três aqui desenhados 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 indicam que gateway realiza cada controlo e o que interrompe a compilação.

  • Os modelos por trás dele: o mapa de modelos do AI gateway — os aliases que serve, cada um com o upstream para onde é enviado um pedido para ele — tem duas partes. Um componente de modelo ligado ao socket models do gateway, gerido ou autoalojado, é servido sob o alias da ligação, com a sua entrada escrita a partir do endpoint e do model que o modelo publica, cadeias que o compilador encaminha para a configuração do gateway e nunca resolve; o modelo é, portanto, um componente do grafo, alcançado através de uma aresta própria. O gateway descreve esse modelo ao seu proxy apenas através da API da OpenAI, pelo que uma ligação a um modelo cujo model.aggrega.ai/api não seja openai interrompe a compilação, indicando a ligação. A outra parte são os values.models do gateway, entradas escritas à mão na notação fornecedor/modelo do próprio proxy: para um upstream que o catálogo não modela, para um fornecedor cuja API própria não é a API da OpenAI, e para várias entradas que partilham um alias, o que os modelos ligados não conseguem fazer, já que cada um é servido sob o alias da sua própria ligação. Uma entrada ligada apresenta a credencial que a sua própria ligação transporta, como descreve «A chave que um chamador apresenta» abaixo, e nunca a provider_key do gateway; todas as entradas escritas à mão apresentam a única credencial desse slot. Um alias publicado por ambas as partes interrompe a compilação, indicando-o, e o mesmo acontece com um gateway a que nenhuma das partes dá um modelo.

  • No caminho de um agente: o gateway publica um endpoint e um model, as chaves que um componente de modelo publica, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente aceita diretamente o gateway e todos os controlos anexados a ele ficam entre esse agente e os fornecedores por trás dele. O model que publica é o alias que o seu values.model nomeia, sobre o qual a compilação se interrompe quando nenhuma parte do mapa o publica; só pode ser omitido quando o gateway serve um único alias e uma entrada de values.models o publica, sendo então esse o publicado. Um chamador que queira outro alias que o mapa publica pede-o 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 Cloudflare e do id do gateway, e o modelo que um chamador pede, que o gateway reencaminha sem verificar — mas não tem model.aggrega.ai/api, pelo 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, reencaminhado sem verificação — e também não tem model.aggrega.ai/api: a API responde ao pedido de chat completions da OpenAI, mas, por predefinição, um chamador apresenta uma chave de subscrição do API Management no seu próprio cabeçalho em vez do bearer token da OpenAI, pelo que um cliente OpenAI simples não basta para a chamar.

  • Kong à frente dos modelos: core/gateway/kong, o gateway Kong open source, serve os modelos ligados ao seu próprio socket models através do proxy de IA do Kong e, dos controlos abaixo, concretiza apenas os padrões de recusa de prompts, como o AI Prompt Guard do Kong em todas as rotas de cada modelo ligado. Cada modelo ligado obtém 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 as suas Recipes importam essas rotas para o backend PostgreSQL do gateway antes de este arrancar. A rota escolhe o modelo, pelo que um pedido é enviado para o modelo que o seu caminho nomeia, seja qual for o nome de modelo que transporte. O gateway apresenta a credencial própria de cada ligação como um bearer token que a sua configuração lê do ambiente do gateway pelo nome, e uma ligação a um modelo cujo model.aggrega.ai/api não seja openai interrompe a compilação. Publica a rota do alias que o seu values.model nomeia como o seu endpoint e esse alias como o seu model, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente o aceita como aceita o AI gateway. Sem nada ligado a esse socket, o gateway não serve nenhum modelo e publica ambas as chaves vazias, e um agente ligado a ele não lê então nenhum endereço nem nenhum nome de modelo. A importação acrescenta e atualiza rotas e não remove nenhuma, pelo que uma rota cuja ligação é removida continua a responder, e a proteção de prompts que uma anexação core/prompt-deny-patterns escreveu continua a recusar depois de a anexação ser removida, até cada uma ser eliminada através da Admin API do Kong. Pela mesma razão, o gateway não declara nenhum chamador, e as suas rotas de modelos não verificam a chave de nenhum chamador: o Kong só distingue os chamadores como os consumidores que um plugin de autenticação nomeia, e um consumidor e a sua chave, uma vez importados, continuariam a poder autenticar-se depois de o chamador ser removido da Release, e uma chave rodada deixaria a antiga a funcionar; uma chave key-auth também não pode ser detida por referência, pelo que a chave de um chamador só poderia chegar ao Kong como um literal num ficheiro renderizado.

  • Kong Gateway Enterprise à frente dos modelos: core/gateway/kong-enterprise, a edição paga da Kong do mesmo gateway apoiado em base de dados, serve os modelos ligados ao seu próprio socket models nas rotas que core/gateway/kong serve, escritas a partir da mesma configuração e importadas para o seu backend PostgreSQL por um passo no próprio pod do gateway antes de este arrancar, e publica o seu endpoint e o seu model como o Kong. A sua única concretização é uma Recipe de chart sobre o chart Helm oficial do Kong; não há concretização compose. Executa a imagem que a Release nomeia em infra.image, incluindo a tag de versão, porque a Kong distribui a imagem enterprise nos seus próprios termos e o catálogo não nomeia, por isso, nenhuma; a compilação interrompe-se enquanto essa chave não estiver definida ou a sua tag não tiver versão. A licença chega ao gateway por referência ao Secret vinculado ao seu slot obrigatório license, nunca como valor, e a compilação interrompe-se enquanto nada vincular esse slot. O compilador não valida nenhuma licença nem contacta nenhum fornecedor, pelo que uma Release que compile sem erros não diz nada sobre ela: o Kong lê a licença quando um nó arranca, e um nó sem licença válida comporta-se como com uma expirada, com a configuração das entidades apenas de leitura e o tráfego do proxy servido com a configuração já existente. A Kong vende os seus plugins de IA como a sua oferta AI Gateway Enterprise, um direito incluído na licença que nenhuma compilação consegue ver, e ignora esse plugin em vez de o recusar quando a licença não inclui esse direito, pelo que anexar core/semantic-caching, core/period-budget, core/data-masking, core/fallback-chain, core/retry-policy ou core/target-selection interrompe a compilação até a Release definir infra.ai_gateway_entitled como true, afirmando que a licença o inclui. Dos controlos abaixo, concretiza o orçamento por período e a cadeia de fallback, cada um escrito nas rotas que o gateway importa, e concretiza core/data-masking como descreve «Exfiltração de dados e interceção de payloads» abaixo; as suas concretizações da cache semântica, da política de novas tentativas e da seleção de destinos interrompem todas as anexações, indicando cada uma porquê, e o limite de concorrência, o registo de auditoria, a triagem de injeção de prompts, a validação de respostas e os padrões de recusa de prompts não têm aí concretização, pelo que uma anexação de qualquer deles interrompe a compilação. Um conjunto de rotas alterado reinicia o gateway, e a importação acrescenta e atualiza rotas e não remove nenhuma, pelo que uma rota cuja ligação é removida, e um plugin que uma Feature de IA escreveu depois de a Feature ser removida, ficam na base de dados até serem eliminados através da Admin API do Kong; pelas razões indicadas no ponto acima, também não declara nenhum chamador, e as suas rotas de modelos não verificam a chave de nenhum chamador. Nenhuma compilação observa que um gateway em execução imponha qualquer um destes controlos.

  • APISIX à frente dos modelos: core/gateway/apisix, o gateway Apache APISIX open source, serve os modelos ligados ao seu próprio socket models através do proxy de IA do APISIX quando o Manifest vincula a sua Recipe de chart, que executa o APISIX 3.18.0. Cada modelo ligado obtém uma rota de chat e uma rota de completion sob /<alias>/v1 — apenas a rota de chat enquanto estiverem anexados um orçamento por período ou padrões de recusa de prompts, já que o APISIX não conta tokens num pedido de completion e a sua proteção de prompts não lê nenhum —, escritas a partir do endpoint e do model que o modelo publica num ficheiro de rotas renderizado com o gateway, que este lê no arranque e de novo sempre que o ficheiro muda. Um gateway que lê as suas rotas desse ficheiro não lê nenhum etcd e não executa nenhuma Admin API, pelo que, com um modelo ligado, uma ligação etcd ou uma anexação admin_key interrompe a compilação e, sem nada ligado, ambas são obrigatórias. A rota escolhe o modelo. O gateway apresenta a credencial própria de cada ligação como um bearer token que as suas rotas leem do ambiente do gateway pelo nome, e uma ligação a um modelo cujo model.aggrega.ai/api não seja openai interrompe a compilação. Publica a rota do alias que o seu values.model nomeia como o seu endpoint e esse alias como o seu model, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente o aceita como aceita o AI gateway; sem nada ligado, publica ambas as chaves vazias. Uma rota cuja ligação é removida desaparece da renderização seguinte. Uma Release pode nomear os chamadores do gateway em infra.callers e as suas chaves através do slot caller_keys, um Secret que contém uma chave de dados por nome de chamador: cada chamador é então um consumidor no ficheiro de rotas cuja chave é lida desse Secret pelo nome, e todas as rotas recusam com HTTP 401 um pedido que não apresente nenhuma chave declarada, como Authorization: Bearer <key> — a forma como um cliente OpenAI apresenta uma —, e removem a chave do pedido que reencaminham. Sem chamadores, as rotas estão abertas. A sua Recipe de carga de trabalho, com o APISIX 3.17.0, mantém as suas rotas no etcd, não renderiza nenhuma e interrompe-se numa ligação a esse socket e com infra.callers. Dos controlos abaixo, concretiza o orçamento por período, uma cache semântica para os chamadores que declara e os padrões de recusa de prompts.

  • Envoy Gateway à frente dos modelos: core/gateway/envoy-gateway, o Envoy Gateway open source, serve os modelos ligados ao seu próprio socket models através do Envoy AI Gateway, cujo controlador, core/gateway/envoy-ai-gateway-operator, o gateway chama como o seu servidor de extensão através do seu socket extension. Um modelo ligado sem nada nesse socket interrompe a compilação e, com o controlador ligado, a Release coloca o gateway em envoy-gateway-system, ou a compilação interrompe-se. Cada modelo ligado torna-se uma regra de uma rota de IA anexada ao gateway, escolhida pelo nome de modelo que um pedido transporta, com um backend escrito a partir do endpoint e do model que o modelo publica, pelo que todos os modelos ligados são servidos sob /v1 no próprio endereço do gateway. O gateway apresenta a credencial própria de cada ligação como um bearer token, que o controlador do Envoy AI Gateway lê do Secret que a credencial nomeia, e uma ligação a um modelo cujo model.aggrega.ai/api não seja openai interrompe a compilação. Enquanto houver um modelo ligado, todas as rotas no gateway recebem o buffer de pedidos de 50Mi por ligação que o Envoy AI Gateway configura. Publica o seu endereço, qualificado com envoy-gateway-system para que se resolva a partir de qualquer namespace, como o seu endpoint e o alias que o seu values.model nomeia como o seu model, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente o aceita como aceita o AI gateway; sem nada ligado, publica ambas as chaves vazias. O webhook do controlador serve um certificado que o cert-manager emite, pelo que o cert-manager tem de já estar em execução no cluster, a menos que a Release nomeie, no infra.webhook_tls_secret do controlador, um Secret com um certificado que o operador fornece, que o webhook passa então a servir. Dos controlos abaixo, concretiza o orçamento por período, a política de novas tentativas e o limite de concorrência, cada um escrito na única política de tráfego da rota que serve os seus modelos. Não concretiza a cache semântica nem a validação de respostas, já que o Envoy AI Gateway não guarda nenhuma resposta para responder a um pedido posterior e não verifica nenhuma resposta contra um esquema, nem a cadeia de fallback: o Envoy AI Gateway faz fallback tentando de novo em backends adicionais da regra de um modelo, e o gateway escreve o número de novas tentativas da sua única política de tráfego em todas as regras da rota que serve os seus modelos, pelo que uma lista de fallback só obteria exatamente os seus envios quando a lista de todos os modelos ligados tivesse o mesmo comprimento. Concretiza core/audit-logging como o seu registo de acessos, como descreve «Registo de auditoria» abaixo, e recusa pelo nome o que esse registo não consegue guardar: o custo de um pedido, já que o custo por pedido 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 registo não tem armazenamento nem definição de retenção. examples/envoy-ai-gateway-token-budget constrói o caminho completo, com um agente a alcançar o modelo gerido da OpenAI através do gateway.

  • agentgateway à frente dos modelos: core/gateway/agentgateway, o agentgateway open source, serve os modelos ligados ao seu próprio socket models a partir de um ficheiro de configuração que as suas Recipes renderizam. Cada modelo ligado é uma entrada desse ficheiro, com o nome do alias da ligação e escrita a partir do endpoint e do model que o modelo publica como um fornecedor de chat completions compatível com OpenAI, pelo que todos os modelos ligados são servidos sob /v1 no próprio endereço do gateway e é o nome de modelo que um pedido transporta que o escolhe: o pedido chega ao modelo a pedir o nome de modelo que o modelo publica, e um nome que nenhuma ligação transporte recebe a resposta HTTP 404. O gateway apresenta a credencial própria de cada ligação como um bearer token, que o ficheiro nomeia como uma variável que o gateway lê do seu ambiente quando lê o ficheiro, e uma variável em falta aí impede-o de arrancar; uma ligação a um modelo cujo model.aggrega.ai/api não seja openai interrompe a compilação. Publica esse URL base /v1 como o seu endpoint e o alias que o seu values.model nomeia como o seu model, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente o aceita como aceita o AI gateway; sem nada ligado, publica ambas as chaves vazias. Duas Recipes executam a mesma imagem, fixada por digest: agentgateway-chart renderiza o chart Helm autónomo do projeto, obtido do registo do projeto, e concretiza os controlos abaixo, e agentgateway executa a imagem como um único serviço Docker Compose e não concretiza nenhum deles, nem chamadores, pelo que uma anexação aí interrompe a compilação indicando o seu tipo; recorrer ao chart no Kubernetes, onde a compilação consegue alcançar esse registo. No chart, uma Release pode nomear os chamadores do gateway em infra.callers e as suas chaves através do slot caller_keys, como no APISIX: cada chamador é uma chave de API do ficheiro, verificada em modo estrito e lida desse Secret pelo nome, pelo que um pedido de modelo que não apresente nenhuma chave declarada como Authorization: Bearer <key> é recusado com HTTP 401, e a chave é removida do pedido reencaminhado; sem chamadores, as rotas de modelos estão abertas. O agentgateway coloca cada chave que o ficheiro nomeia desta forma, a de um modelo ligado em qualquer das Recipes e a de um chamador no chart, no texto do ficheiro antes de o ler como YAML, pelo que uma chave tem de 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 volta a ler o ficheiro quando este muda, pelo que um chamador removido da Release é recusado assim que o ficheiro montado é atualizado. Enquanto core/audit-logging, ou core/period-budget com o âmbito caller, estiver anexado, a Recipe de chart dá ao gateway um armazenamento, um ficheiro SQLite num volume próprio, e executa uma réplica. Dos controlos abaixo, concretiza o mascaramento de dados, os padrões de recusa de prompts, o orçamento por período, o registo de auditoria e a política de novas tentativas, cada um escrito no ficheiro, e recusa pelo nome cada valor que não consegue manter. O mascaramento de dados substitui cada correspondência dos padrões que a anexação lista por <masked>, ou, com refuse, responde ao pedido ou à resposta com HTTP 403, nos prompts de sistema e de programador de um pedido, nas suas outras mensagens e nos argumentos e resultados das suas chamadas de ferramentas, e no texto da mensagem de uma resposta que chega inteira; não reconhece tipos de entidade e não restaura nada. O agentgateway não mascara uma resposta em streaming, pelo que, enquanto as respostas são mascaradas, um pedido de modelo que peça uma resposta em streaming é recusado com HTTP 403 antes de ser reencaminhado, tal como qualquer pedido de modelo cujo corpo seja maior do que os 2 MiB que o gateway lê para essa verificação, em streaming ou não. Uma recusa por uma proteção, incluindo a de um padrão de recusa, é HTTP 403 com o corpo «The request was rejected due to inappropriate content» (O pedido foi rejeitado devido a conteúdo inadequado). O orçamento, os registos e as novas tentativas são descritos em «Orçamento por período», «Registo de auditoria» e «Resiliência» abaixo. As suas concretizações da cadeia de fallback, da seleção de destinos, da cache semântica, da validação de respostas e da triagem de injeção de prompts interrompem todas as anexações, indicando cada uma porquê, e o limite de concorrência não se anexa a ele, já que não tem nenhum valor dataplane.aggrega.ai/concurrency-cap.

  • Traefik Hub à frente dos modelos: core/gateway/traefik-hub, o gateway pago da Traefik, serve os modelos ligados ao seu próprio socket models através do middleware Chat Completion do Traefik Hub. A sua única concretização é uma Recipe de chart sobre o próprio chart Helm da Traefik; não há concretização compose. Executa a imagem que a Release nomeia em infra.image, incluindo a tag, porque a Traefik distribui o Traefik Hub nos seus próprios termos e o catálogo não nomeia, por isso, nenhuma; a compilação interrompe-se enquanto essa chave não estiver definida ou não nomear nenhuma tag. O token da 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 a compilação interrompe-se enquanto nada vincular esse slot ou este publicar outra chave de dados. A Traefik exige HTTPS de saída para api.traefik.io, onde o gateway valida o seu token; a partir do Traefik Hub v3.21, o gateway serve enquanto esse host não puder ser alcançado, tentando de novo em segundo plano, e um token dura um ano por predefinição, deixando o gateway de funcionar quando expira. A Recipe de chart desativa a exportação, pelo chart, dos registos de erros do gateway para a plataforma da Traefik e a sua verificação de uma versão mais recente. O compilador não valida nenhum token nem contacta nenhum fornecedor, pelo que uma Release que compile sem erros não diz nada sobre se o gateway arranca. Cada modelo ligado obtém uma rota em /<alias>/v1/chat/completions, enviada para o endpoint que o modelo publica através de um Service do tipo ExternalName e a pedir o model que publica, seja qual for o nome de modelo que um pedido transporte, pelo que é o caminho que escolhe o modelo; serve apenas chat completions. O gateway apresenta a credencial própria de cada ligação como um bearer token, que o Traefik Hub lê do Secret que o middleware Chat Completion da ligação nomeia, e uma ligação a um modelo cujo model.aggrega.ai/api não seja openai, ou cujo endpoint nomeie um endereço em vez de um host, interrompe a compilação. Publica a rota do alias que o seu values.model nomeia como o seu endpoint e esse alias como o seu model, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente o aceita como aceita o AI gateway; sem nada ligado, publica ambas as chaves vazias. Uma Release pode nomear os chamadores do gateway em infra.callers e os hashes htpasswd das suas chaves através do slot caller_keys: o middleware API Key do Traefik Hub passa então a estar à frente de todas as rotas de modelos e recusa um pedido que não apresente nenhuma chave declarada como Authorization: Bearer <key>, e a chave é removida do pedido reencaminhado; sem chamadores, as rotas estão abertas. O que o Traefik Hub faz com a entrada de um chamador que nomeie um Secret ou uma chave de dados inexistente não está indicado na sua referência, pelo que, no pior caso, as rotas ficam tão abertas como sem chamadores. Dos controlos abaixo, concretiza o orçamento por período, a cache semântica para os chamadores que declara, os padrões de recusa de prompts e o mascaramento de dados, através de middlewares do AI gateway do Traefik Hub, e a cadeia de fallback e a política de novas tentativas, através do failover e das novas tentativas do próprio Traefik, cada um escrito nas rotas que a sua Recipe de chart renderiza. O AI gateway é um direito incluído na licença, que nenhuma compilação consegue ver, e o que o Traefik Hub faz com um token válido cuja licença não o inclua não está documentado, pelo que anexar qualquer um dos quatro primeiros interrompe a compilação até a Release definir infra.ai_gateway_entitled como true. As suas concretizações da triagem de injeção de prompts, do registo de auditoria, da seleção de destinos e da validação de respostas interrompem todas as anexações, indicando cada uma porquê, e o limite de concorrência não se anexa a ele, já que não tem nenhum valor dataplane.aggrega.ai/concurrency-cap. Nenhuma compilação observa que um gateway em execução imponha qualquer um destes controlos.

  • Higress à frente dos modelos: core/gateway/higress, o gateway Higress open source, construído sobre o Envoy e configurado através de recursos Kubernetes, serve os modelos ligados ao seu próprio socket models através do proxy de IA do Higress. A sua única concretização é uma Recipe de chart sobre o próprio chart Helm higress-core do projeto, que executa o controlador do Higress, com o seu serviço de descoberta, e o gateway; não há concretização compose, já que o projeto destina a sua distribuição compose sobretudo a testes locais e essa distribuição executa vários serviços cooperantes configurados através 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 com que a sua configuração está comprovada; o gateway obtém esses módulos do registo de plugins do Higress em tempo de execução, que o cluster tem de conseguir alcançar e que a compilação não consegue verificar. O controlador observa apenas o namespace da Release, sob uma IngressClass com o nome do gateway e desse namespace, pelo que dois gateways Higress num mesmo namespace colidem. Cada alias obtém uma rota em /<alias>/v1, enviada para o endpoint que o modelo do alias publica através de uma entrada do registo próprio do gateway e a pedir o model que publica, seja qual for o nome de modelo que um pedido transporte, pelo que é o caminho que escolhe o modelo; as ligações que nomeiam um mesmo alias no seu valor serves partilham os seus pedidos em partes iguais. O gateway apresenta a credencial própria de cada ligação como um bearer token, que o controlador do Higress lê do Secret que a configuração do proxy de IA nomeia, no namespace do gateway, e entrega ao gateway, pelo que a chave não está em nenhum ficheiro renderizado; um nome de Secret que contenha um ponto interrompe a compilação, já que o Higress lê o nome até ao primeiro ponto, e uma ligação que não transporte nenhuma credencial passa adiante a chave que o pedido apresenta. O proxy de IA do Higress copia também o cabeçalho Authorization que um cliente envia para um cabeçalho X-HI-ORIGINAL-AUTH, e todas as rotas de modelos removem essa cópia antes de o pedido chegar ao modelo, pelo que uma chave que um cliente apresente nunca viaja ao lado da credencial própria de uma ligação. Por https, o gateway verifica que o certificado de um modelo encadeia até às âncoras de confiança do sistema e nomeia o host do modelo, seja qual for 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 ligações são todas https com a anotação higress.io/backend-protocol: HTTPS do Higress, para que o gateway obtenha o nome do servidor a partir do host que o proxy de IA escreve em cada pedido — o do modelo, qualificado com o namespace do modelo quando não tem nenhum ponto — e verifique o certificado contra ele. Essa anotação aplica-se a todas as ligações de um alias, pelo que um alias que misture ligações http e https interrompe a compilação, indicando ambas; servi-las sob dois aliases resolve a situação. Uma ligação a um modelo cujo model.aggrega.ai/api não seja openai, ou cujo endpoint nomeie um endereço em vez de um host, interrompe a compilação. Publica a rota do alias que o seu values.model nomeia como o seu endpoint e esse alias como o seu model, e tem model.aggrega.ai/api: openai, pelo que o socket model de um agente o aceita como aceita o AI gateway; sem nada ligado, publica ambas as chaves vazias. Não declara nenhum chamador, pelo que as suas rotas de modelos não verificam a chave de nenhum chamador, e um valor que precise de um chamador verificado pelo gateway é recusado pelo nome. Dos controlos abaixo, concretiza o orçamento por período, o registo de auditoria e a política de novas tentativas, cada um escrito nas rotas de modelos, e concretiza core/data-masking como descreve «Exfiltração de dados e interceção de payloads» abaixo. As suas concretizações da validação de respostas, da cadeia de fallback, da cache semântica, da triagem de injeção de prompts e da seleção de destinos interrompem todas as anexações, indicando cada uma porquê, e nem os padrões de recusa de prompts nem o limite de concorrência se anexam a ele, já que não tem nenhum valor dataplane.aggrega.ai/prompt-guard ou dataplane.aggrega.ai/concurrency-cap. Nenhuma compilação observa que um gateway em execução imponha qualquer um destes controlos.

  • Azure API Management à frente de um modelo: core/gateway/azure-api-management, o AI gateway do Azure API Management, um serviço alojado, serve uma API de modelos através de uma API numa instância do API Management que já existe. A sua Recipe terraform lê a instância e acrescenta a API, a sua operação de chat completions, o backend para onde reencaminha e a política da API, que remove a chave de subscrição do chamador daquilo que reencaminha e se autentica na API de modelos como infra.backend_authentication indica: com a identidade gerida da instância, com uma chave de fornecedor guardada no Key Vault, ou com nada. As suas Recipes helm e compose referenciam uma API configurada fora da Release e interrompem a compilação em qualquer anexação. Dos controlos abaixo, a sua Recipe terraform concretiza a cache semântica, o orçamento por período, a triagem de injeção de prompts e a política de novas tentativas, cada um escrito na política da API. Não concretiza o limite de concorrência, já que a Microsoft diz que o limite que a sua política de concorrência impõe nunca é totalmente exato, e é mais baixo quando várias unidades de capacidade correm numa região, nem a cadeia de fallback, já que a API reencaminha para um único backend e o fallback do próprio Azure, os grupos de prioridade de um pool de backends, desvia os pedidos posteriores de um backend cujo disjuntor disparou, em vez de enviar um pedido falhado para outro modelo. A sua concretização de core/audit-logging interrompe todas as anexações, indicando o que está fora do seu alcance: o próprio registo, que uma definição de diagnóstico na instância ativa; o custo de um pedido, enquanto require_cost estiver ativo, já que o registo de pedidos de modelos do Azure regista contagens de tokens e o modelo, e nenhum preço; e uma retenção, quando retention_days é indicado, já que uma linha dura tanto quanto o espaço de trabalho do Log Analytics onde chega a mantiver. Nenhuma compilação observa que as políticas se apliquem e imponham como a Microsoft documenta.

  • A chave que um chamador apresenta: Um servidor que verifica a chave que os seus chamadores apresentam detém essa chave num slot próprio, chamado api_key em cada destino de serviço de modelos que verifica uma — core/ai-model/vllm, tei e tgi, o modelo LiteLLM e o AI gateway, onde é a chave a que o LiteLLM chama master key — e cada uma das suas Recipes entrega a chave como a variável que o servidor lê. core/gateway/apisix e core/gateway/agentgateway detêm cada um uma chave por cada chamador que a sua Release nomeia em infra.callers, no seu slot caller_keys: um Secret que contém a chave de cada chamador sob o nome desse chamador. core/gateway/traefik-hub detém os seus chamadores da mesma forma, exceto que o seu Secret contém o hash htpasswd da chave de cada chamador, com o qual a sua verificação de chaves compara uma chave apresentada, pelo que não é o Secret a partir do qual o chamador apresenta a sua chave. Um chamador detém a chave que apresenta do seu próprio lado, na ligação em que a apresenta, num slot que o seu socket declara: os agentes da biblioteca padrão declaram um no seu socket model, credential; o AI gateway no seu socket models e no seu socket cache_store, onde é a palavra-passe que a cache semântica do gateway apresenta ao seu armazenamento; core/gateway/kong e core/gateway/kong-enterprise nos seus sockets models; core/gateway/apisix no seu socket models e no seu socket cache_store, onde é igualmente a palavra-passe que a sua cache semântica apresenta ao seu armazenamento; core/gateway/agentgateway no seu socket models; core/gateway/envoy-gateway no seu socket models e no seu socket cache, onde é a palavra-passe que o serviço de limitação de taxa do gateway apresenta ao armazenamento que guarda a contagem de um orçamento por período; core/gateway/higress no seu socket models e no seu socket cache, onde é a palavra-passe que o seu limite de tokens apresenta ao armazenamento que guarda a contagem de um orçamento por período; e core/gateway/traefik-hub no seu socket models, no seu socket cache, onde é a palavra-passe que a sua quota apresenta ao armazenamento que guarda a contagem de um orçamento por período, e no seu socket cache_store, onde é a palavra-passe que a sua cache semântica apresenta ao seu armazenamento — pelo que um agente que alcança um modelo, ou um gateway que alcança um modelo que serve, detém aí a chave dessa ligação. O AI gateway, os dois Kong, o APISIX e o agentgateway entregam a chave de cada modelo ligado sob uma variável própria, que a entrada ou a rota desse modelo na 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ê dele a chave; o Traefik Hub nomeia o Secret e a chave de dados no middleware Chat Completion da rota do modelo, e lê dele a chave. Uma ligação a um modelo com a etiqueta component.aggrega.ai/hosting: managed transporta uma, ou diz nos seus próprios values que o modelo não precisa de nenhuma, unauthenticated: true; sem nenhuma das duas, a asserção do chamador interrompe a compilação indicando a ligação e o seu destino, e um modelo com outra etiqueta não provoca essa interrupção. Uma chave que o Component de um chamador declare antes num slot próprio é uma única chave para todas as ligações que faz. Nenhuma das extremidades vê as anexações da outra, pelo que o servidor não sabe nada da chave de um chamador, e as duas correspondem porque o Aggregate alimenta ambas a partir de um mesmo parâmetro: quando ambas as extremidades resolvem segredos num mesmo âmbito — um namespace Kubernetes, um projeto Compose —, referenciam um único segredo e, caso contrário, cada uma detém o seu, concretizado a partir da mesma entrada do cofre. O vLLM, o TEI e o TGI verificam cada um uma única chave, pelo que todos os chamadores apresentam a mesma chave e o servidor não consegue distinguir os seus chamadores, e o TGI compara a sua chave sem distinguir maiúsculas de minúsculas; o APISIX, o agentgateway e o Traefik Hub verificam cada um a chave de cada chamador declarado e distinguem os seus chamadores por ela; os dois Kong não declaram nenhum chamador nem verificam a chave de nenhum, pelas razões indicadas em «Kong à frente dos modelos» acima; o modelo LiteLLM e o AI gateway aceitam também as chaves que emitem, enquanto a sua base de dados de contabilidade estiver anexada. Modelo de credenciais desenvolve esta forma num único Aggregate.

  • Escolher entre destinos: core/target-selection declara como um gateway escolhe entre vários destinos que podem servir o mesmo pedido, com uma strategy de latency (o destino observado a responder mais depressa) ou cost (o destino mais barato de chamar). A estratégia faz parte do que a aplicação pede ao seu gateway, pelo que o programador a anexa no Aggregate. No AI gateway, os destinos são as entradas dos seus values.models que publicam o mesmo alias — um modelo ligado é servido sob o alias da sua ligação, que nenhuma outra entrada pode publicar — e a biblioteca padrão concretiza latency escrevendo o latency-based-routing do proxy na configuração de encaminhamento que a Recipe do gateway renderiza: o proxy envia cada pedido para a entrada cujas últimas dez respostas demoraram, em média, menos tempo, por token de saída quando uma resposta reporta os seus tokens, ou até ao primeiro token num pedido em streaming, e uma entrada ainda não experimentada conta como a mais rápida. Sem a anexação, a configuração não nomeia nenhuma estratégia, e o proxy escolhe entre essas entradas ao acaso. cost é aí recusado pelo nome: o proxy atribui preço a uma entrada procurando o seu destino, exatamente como está escrito, numa tabela de preços que nomeia os modelos da OpenAI e da Anthropic sem o prefixo de fornecedor que os destinos do gateway têm, e atribui a uma entrada que não encontra um preço fixo de recurso, pelo que as entradas que partilham um alias teriam o mesmo preço e seriam escolhidas pela sua ordem. Em core/gateway/kong-enterprise, todas as anexações interrompem a compilação, porque cada modelo ligado a ele é servido em rotas próprias que transportam esse único modelo, o que não deixa nada entre que escolher. Em core/gateway/agentgateway, todas as anexações interrompem também a compilação, indicando porquê: o agentgateway sorteia dois dos destinos de um nome de modelo e escolhe aquele cuja saúde, dividida pelo tempo que demorou a responder, tem a pontuação mais alta, pelo que o destino mais rápido só é escolhido quando é sorteado, e não escolhe nenhum destino pelo custo. Em core/gateway/higress, todas as anexações interrompem também a compilação, indicando porquê: o Higress consegue medir a latência de um serviço, mas o seu plugin de balanceamento de carga é executado depois do proxy de IA — que já definiu o modelo, o endereço e a credencial do pedido para o candidato que a rota resolveu — e escreve a sua escolha num cabeçalho de pedido pelo qual nada encaminha sem um filtro Envoy que este catálogo não renderiza, pelo que a escolha não produz efeito, e não escolhe nenhum destino pelo custo. Em core/gateway/traefik-hub, todas as anexações interrompem também a compilação, indicando porquê: o Traefik escolhe pelo tempo de resposta mais baixo apenas entre os servidores de um Service, que um único nome de modelo e uma única credencial abrangem, e entre Services equilibra por peso ou por um hash do endereço do cliente, nunca pela latência, e nenhuma das suas estratégias escolhe um destino pelo custo; e cada modelo ligado ao gateway é servido numa rota própria que transporta esse único modelo, o que não deixa nada entre que escolher. Em qualquer outro gateway, uma anexação interrompe a compilação.

  • Resiliência: core/fallback-chain envia um pedido cujo modelo falha para outros modelos: chains nomeia, para cada alias de modelo que faz fallback, os aliases a tentar por ordem até um responder, seguindo um fallback que falha a sua própria entrada por sua vez, e max_hops limita até onde, ao longo dessa cadeia, um pedido é passado. A biblioteca padrão concretiza-o no AI gateway escrevendo ambos na configuração de encaminhamento que a Recipe do gateway renderiza, e interrompe a compilação num nome que o mapa de modelos do gateway não publique. Um pedido só faz fallback quando o gateway desistiu do alias que pediu: quando um alias é publicado mais do que uma vez, uma chamada falhada passa primeiro para outra das suas entradas como nova tentativa, limitada pelo número de novas tentativas do gateway. core/retry-policy define esse número — quantas vezes o gateway pode enviar um pedido, incluindo o primeiro envio (max_attempts), para uma falha que tem êxito ao ser enviada de novo, como uma ligação recusada, um limite de taxa ou um tempo limite esgotado — e a biblioteca padrão concretiza-o no AI gateway escrevendo-o na configuração de encaminhamento que a Recipe do gateway renderiza. Em core/gateway/envoy-gateway, é concretizado como a nova tentativa da política de tráfego na rota que serve os modelos ligados, a mesma política que transporta o limite de taxa de um orçamento por período, porque o Envoy Gateway anexa uma única política de tráfego a uma rota: um pedido é enviado de novo após uma ligação ou um stream recusados, um reset ou uma resposta 429, 503 ou 504, até max_attempts envios, e um modelo que não responda nada dentro do tempo limite de pedido da rota não é enviado de novo, porque esse tempo limite abrange todos os envios. Em core/gateway/azure-api-management, é concretizado como a nova tentativa do Azure em torno do reencaminhamento, na secção backend da política da API: um pedido respondido com HTTP 429 ou com um estado 5xx é enviado de novo, com o seu corpo retido para poder ser reenviado, um segundo após o envio anterior, até max_attempts envios. Uma ligação recusada ou interrompida, e um modelo que não responda nada dentro do tempo limite do reencaminhamento, não são enviados de novo, porque o Azure termina a nova tentativa perante esse erro e entrega-o à secção on-error da política. O Azure tenta de novo 1 a 50 vezes após o primeiro envio, pelo que um max_attempts de 1 não escreve nenhuma nova tentativa e um acima de 51 é recusado pelo nome. A nova tentativa ocupa o lugar do reencaminhamento que a API herdaria, pelo que, enquanto estiver anexada, uma definição de reencaminhamento feita num âmbito mais amplo da instância, como um tempo limite, não se aplica à API, que reencaminha com as predefinições do Azure. No gateway alojado, core/retry-policy é concretizado escrevendo no recurso do gateway o seu número de novas tentativas, que nomeia os envios após o primeiro, de 1 a 5, pelo que um max_attempts de 2 a 6 é respeitado e qualquer outro valor é recusado; core/fallback-chain não é aí concretizado, porque esse gateway só faz fallback entre modelos dentro de uma rota que um pedido nomeia no lugar de um modelo, pelo que um pedido para um modelo nunca faz fallback. Em core/gateway/kong-enterprise, core/fallback-chain é concretizado na sua Recipe de chart: as rotas de chat e de completion de cada alias a que chains dá uma entrada transportam o AI Proxy Advanced do Kong no lugar do seu proxy de IA, com o modelo do alias e os modelos para os quais o seu percurso faz fallback como destinos por ordem de prioridade — o alias, depois os fallbacks da sua entrada por ordem, seguindo-se por sua vez a entrada própria de um fallback apenas enquanto tiverem sido contados menos de max_hops. O balanceador envia um pedido a cada destino do percurso uma vez, por ordem, até um responder, avançando após um erro ou um tempo limite de ligação, um cabeçalho de resposta inválido ou uma resposta 429, 500, 502, 503 ou 504, e devolve todas as outras respostas tal como chegaram. A compilação interrompe-se num nome que o socket models não transporte, num percurso que alcance um alias duas vezes, ao lado de core/retry-policy, já que o Kong mantém um único número de novas tentativas para todo o percurso e não consegue enviar de novo a um modelo antes de fazer fallback, e numa imagem do gateway anterior à 3.12. core/retry-policy não é aí concretizado, e a sua concretização interrompe todas as anexações indicando porquê: cada modelo ligado é servido em rotas próprias que transportam esse único modelo, pelo que uma nova tentativa tem de enviar o pedido de novo a esse mesmo destino, e a referência do Kong pode ler-se nos dois sentidos quanto a se o seu balanceador o faz. Em core/gateway/agentgateway, core/retry-policy é concretizado na Recipe de chart como uma política de novas tentativas da própria configuração do gateway, anexada ao listener onde chegam os seus pedidos de modelos: um pedido é enviado de novo, de imediato e para o mesmo modelo, após uma resposta 429, 500, 502, 503 ou 504, uma ligação recusada ou reiniciada, uma ligação que demore mais de 11 segundos a abrir ou uma falha na resolução de nomes, até max_attempts envios. O agentgateway envia um pedido mais uma vez do que as tentativas da sua política, pelo que a política é escrita como max_attempts menos um, um max_attempts de 1 não escreve nenhuma, e um acima de 256 é recusado pelo nome. Um pedido cujo corpo seja maior do que 64 KiB é enviado uma única vez, e a configuração não define nenhum tempo limite, pelo que se espera por um modelo que aceite a ligação e não responda nada, em vez de o enviar de novo. core/fallback-chain não é aí concretizado, e a sua concretização interrompe todas as anexações indicando porquê: o agentgateway faz failover entre modelos expulsando um que falhou para os pedidos seguintes, enquanto o pedido que falhou é respondido com a sua falha, pelo que nenhum pedido percorre uma cadeia. Em core/gateway/higress, core/retry-policy é concretizado como a nova tentativa própria da rota, escrita como anotações Ingress em todas as rotas de modelos: um pedido é enviado de novo após uma ligação recusada ou reiniciada, uma resposta 5xx ou um 429, incluindo um POST, até max_attempts envios; um max_attempts de 1 desativa a nova tentativa, substituindo a nova tentativa que o plano de controlo do Higress dá a uma rota sem anotação, e um acima de 2147483648 é recusado pelo nome. Um modelo que aceite a ligação e depois não responda nada, ou responda lentamente, não é enviado de novo, já que a rota não define nenhum prazo por tentativa, e um pedido em streaming só é enviado de novo antes de a sua resposta ter começado. core/fallback-chain também não é aí concretizado, e a sua concretização interrompe todas as anexações indicando porquê: o Higress envia um pedido falhado adiante no máximo uma vez, para um único outro destino — o backend predefinido de uma rota, ou a única rota de fallback que a sua consola escreve para uma rota de IA —, pelo que nenhum pedido percorre uma cadeia. Em core/gateway/traefik-hub, ambos são concretizados na Recipe de chart, e cada um interrompe a compilação numa imagem do Traefik Hub anterior à v3.20, cujo failover não aceita middlewares nos serviços que tenta e cuja nova tentativa não consegue enviar de novo um POST com base no estado de uma resposta — exceto uma política de novas tentativas de um único envio. core/fallback-chain envia a rota de cada alias a que chains dá uma entrada através de failovers aninhados do próprio Traefik, tentando por ordem os modelos do percurso do alias — o alias, depois os fallbacks da sua entrada por ordem, seguindo-se por sua vez a entrada própria de um fallback apenas enquanto tiverem sido contados menos de max_hops —, cada um com o seu próprio nome de modelo, credencial, quotas e nova tentativa. Uma resposta 429 ou de 500 a 504 de um modelo, após qualquer nova tentativa desse modelo, passa o pedido ao seguinte; qualquer outra resposta é devolvida tal como chegou, a do último modelo seja ela qual for, e um corpo de pedido acima de 1 MiB é recusado com HTTP 413 em vez de enviado. A compilação interrompe-se num nome que o socket models não transporte e num percurso que alcance um alias duas vezes. core/retry-policy é o middleware de novas tentativas do Traefik, o último em cada rota de modelo, ou em cada modelo que um percurso tenta: um pedido é enviado de novo de imediato após uma ligação que não levou nada ao modelo e após uma resposta 429 ou de 500 a 504, incluindo um POST, até max_attempts envios, incluindo o primeiro, e um max_attempts de 1 não escreve nada. Uma resposta que o próprio gateway forma — uma recusa da sua verificação de chaves, de uma proteção, do mascaramento ou de uma quota — nunca é enviada de novo, e uma resposta em streaming também não, depois de ter começado.

  • Orçamento por período: core/period-budget limita o que o tráfego que atravessa um gateway pode consumir ao longo de um período: um limit, o period que abrange, um scope — tudo o que o gateway serve, cada chamador ou cada modelo — e uma unit — um custo em dólares americanos ou tokens — e, assim que o que o gateway contou ao longo do período excede o limite, os pedidos seguintes ao modelo são recusados. Anexa-se a qualquer componente que declare dataplane.aggrega.ai/period-budget. A biblioteca padrão realiza-o no AI gateway, cujo orçamento abrange tudo o que o gateway serve, é 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 do 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, âmbito ou período — 30d entre eles, que o gateway conta como um mês de calendário — e interrompe a compilação a menos que os slots de credenciais database_url e api_key do gateway estejam ambos anexados, porque sem a sua base de dados de contabilidade o gateway não mantém nenhuma contagem e sem uma chave administrativa não verifica nenhum chamador face ao orçamento. Assim que a contagem excede o limite, o gateway recusa os pedidos ao modelo da chave administrativa, bem como os de todos os chamadores; a listagem de modelos e a gestão de chaves continuam a responder a essa chave. No gateway alojado, é realizado como uma regra de limite de gastos no recurso do gateway, contada em dólares americanos ao longo de uma janela que avança com o tempo — o último period, para os modelos cujo preço o gateway conhece — para tudo o que o gateway serve: 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, é realizado na Recipe de chart, escrito nas rotas dos modelos ligados como a limitação de taxa por tokens do APISIX: contado nos tokens que a resposta de cada modelo reporta — total_tokens, prompt_tokens ou completion_tokens — ao longo de uma janela fixa de period que abre com o primeiro pedido ao modelo após o fecho da janela anterior, e não segundo o relógio, para tudo o que o gateway serve, para cada modelo ligado em separado, ou para cada chamador que a sua Release declara em infra.callers em separado, distinguindo-os o gateway pela chave que cada um apresenta. Assim que a contagem atinge o limite, o gateway responde aos pedidos ao modelo com HTTP 503 até a janela fechar; os tokens de um pedido são somados assim que a sua resposta termina, pelo que o pedido que atinge o limite é servido, e uma resposta servida pela sua cache semântica não conta nada e é servida para além do limite. O APISIX não conta tokens num pedido de completion, pelo que, enquanto o orçamento estiver anexado, cada modelo ligado recebe apenas a sua rota de chat, e mantém a contagem na memória do processo do gateway, pelo que o chart executa uma réplica e um reinício abre uma nova janela. Um orçamento em dólares americanos, um por chamador enquanto infra.callers não declarar nenhum, um mês de calendário e um segundo orçamento num mesmo gateway são recusados pelo nome, tal como um anexo na sua Recipe de carga de trabalho, que não renderiza nenhuma rota. Em core/gateway/envoy-gateway, é realizado como o limite de taxa baseado em utilização do Envoy Gateway, na rota de IA que serve os modelos ligados 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 política de tráfego nessa rota cobra-o quando a resposta termina, contra limit tokens por unidade do limite de taxa do Envoy Gateway, para tudo o que o gateway serve ou para cada modelo ligado em separado. Cada janela é fixa 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, ao abrigo de uma definição do serviço de limite de taxa do Envoy Gateway que passa então a valer para todos os limites de taxa mensais que essa instalação mantém. A contagem é mantida pelo serviço de limite de taxa que o plano de controlo do Envoy Gateway cria e ativa para cada gateway que serve, no armazenamento de protocolo Redis ligado ao socket cache do gateway. Assim que a contagem excede o limite, o gateway responde aos pedidos ao modelo com HTTP 429 até a janela terminar; os tokens de um pedido são somados assim que a sua resposta termina, pelo que o pedido que ultrapassa o limite é servido. Enquanto o armazenamento ou o serviço de limite de taxa não puderem ser alcançados, ou uma verificação demorar mais do que o tempo limite de limitação de taxa do Envoy, os pedidos ao modelo são recusados com HTTP 500, ao abrigo de uma definição do plano de controlo do Envoy Gateway que passa então a valer para todos os limites de taxa que essa instalação mantém, pelo que um limite de taxa aplicado manualmente também falha fechado; um pedido admitido imediatamente antes de uma falha continua a ser servido e não é contado, porque os seus tokens são cobrados após a resposta, e um armazenamento que mantém a contagem em memória recomeça todas as janelas quando reinicia. Um orçamento em dólares americanos, um por chamador — o gateway distingue os chamadores apenas por um cabeçalho que o próprio chamador escreve, e nada nesse caminho o verifica —, qualquer outro período e um segundo orçamento num mesmo gateway são recusados pelo nome, tal como um anexo sem nada ligado ao socket models ou ao socket cache. Em core/gateway/azure-api-management, é 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 reporta, em conjunto, para tudo o que a API serve ou para cada subscrição do API Management, cuja chave o gateway verifica — seja uma quota ao longo de uma janela fixa no relógio UTC, uma hora, um dia, uma semana, um mês de calendário ou um ano civil (1h, 1d, 7d, 1mo ou 12mo; a Microsoft não indica em que dia começa uma semana), respondida com HTTP 403 quando excedida, seja uma taxa ao longo de um minuto (1m), respondida com HTTP 429 e contada numa janela deslizante nos escalões clássicos e como um token bucket nos escalões v2. A contagem é a utilização que cada resposta reporta, pelo que pedidos concorrentes podem ultrapassar o limite, e cada gateway da instância mantém a sua própria contagem. Um orçamento em dólares americanos ou só em tokens de prompt ou de completion, um por modelo — o modelo que um pedido nomeia é escrito pelo chamador, e vários nomes podem chegar a um mesmo modelo —, um por subscrição numa API que não exige chave de subscrição, qualquer outro período e um limite que não seja um número inteiro são recusados pelo nome. O escalão Consumption não executa nenhum limite de tokens. Em core/gateway/kong-enterprise, é realizado na Recipe de 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 reporta — total_tokens, prompt_tokens ou completion_tokens — em janelas fixas de period, um número de segundos, minutos, horas ou dias, sendo cada pedido contado na única janela em que cai o seu momento, para tudo o que o gateway serve ou para cada modelo ligado em separado, sendo um pedido sob o âmbito model contado contra o alias que nomeou, qualquer que seja o modelo que lhe respondeu. Assim que a contagem atinge o limite, o pedido seguinte ao modelo é respondido com HTTP 429 até a janela terminar, pelo que o pedido que ultrapassa o limite é servido; o Kong também pode recusar um pedido antecipadamente, com base na sua própria estimativa dos tokens de prompt que transporta. A contagem é mantida no backend PostgreSQL do gateway, partilhada por todas as réplicas e preservada após um reinício. Um orçamento em dólares americanos — o Kong só conta custos a partir de um preço que a sua configuração atribui a cada modelo, e o catálogo não fornece nenhum —, um por chamador — o Kong distingue os chamadores apenas como os consumers que um plugin de autenticação nomeia, e o gateway não declara chamadores, pelas razões que «O Kong à frente dos modelos» acima indica —, um mês de calendário, um segundo orçamento num mesmo gateway e uma imagem do gateway anterior à 3.15 são recusados pelo nome, tal como um anexo sem nada ligado ao socket models. Em core/gateway/agentgateway, é realizado na Recipe de chart, escrito na configuração do gateway e contado no total de tokens que cada resposta reporta: sob o âmbito caller, como um orçamento sobre a chave de API de cada chamador que a sua Release declara em infra.callers, ao longo de janelas fixas de period alinhadas com a época Unix, começando um dia à meia-noite UTC, mantido num armazenamento SQLite num volume que a Recipe renderiza, com uma réplica; sob o âmbito gateway ou model, como um token bucket para tudo o que o gateway serve ou para cada nome de modelo que um pedido solicita, reabastecido até ao limite a cada period a partir do momento em que o gateway leu a sua configuração e mantido na sua memória, pelo que um reinício ou uma configuração alterada volta a enchê-lo. Assim que o que foi contado atinge o limite, os pedidos ao modelo são respondidos com HTTP 429 até a janela terminar ou o bucket ser reabastecido; o pedido que o atinge é servido. Um orçamento em dólares americanos — o catálogo de custos de modelos do gateway não atribui preço a nenhum dos modelos a ele ligados, pelo que o orçamento não contaria nada —, só em tokens de prompt ou de completion, um por chamador enquanto infra.callers não declarar nenhum, um mês de calendário, um limite que não seja um número inteiro e um segundo orçamento num mesmo gateway são recusados pelo nome, tal como um anexo sem nada ligado ao socket models; a sua Recipe compose não tem nenhuma realização dele. Em core/gateway/traefik-hub, é realizado na Recipe de chart como o middleware de quota do Traefik Hub na rota de cada modelo ligado, mantendo a contagem no armazenamento de protocolo Redis ligado ao socket cache do gateway: conta os tokens que cada resposta reporta — total_tokens, prompt_tokens ou completion_tokens — ou, sob usd, o seu custo em dólares americanos, com preços tirados de uma lista de modelos que acompanha o middleware, sendo um modelo sem preço recusado com HTTP 422, ao longo de uma janela que desliza com o tempo, libertando-se o que foi contado num momento um período mais tarde, para cada modelo ligado em separado, ou para tudo o que o gateway serve enquanto estiver ligado um só modelo. Assim que a contagem atinge o limite, os pedidos ao modelo são recusados com HTTP 429; a contagem de um pedido é somada assim que a sua resposta termina, pelo que o pedido que ultrapassa o limite, e qualquer outro servido ao mesmo tempo, é servido, e uma resposta servida pela cache semântica não conta nada. A referência do Traefik diz que a quota serve pedidos sem os contar enquanto o armazenamento não puder ser alcançado. Um orçamento por chamador — a quota distingue os pedidos pelo endereço do cliente, por um cabeçalho do pedido ou pelo host do pedido, e nenhum deles é o chamador que a verificação de chave do gateway verificou —, um para todo o gateway enquanto estiverem ligados vários modelos, uma vez que a referência do Traefik não diz se rotas que nomeiam uma mesma quota partilham a 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 perfaçam horas inteiras, são recusados pelo nome, tal como um limite que não seja um número inteiro de tokens e um anexo sem nada ligado ao socket models ou ao socket cache. Em core/gateway/higress, é realizado na Recipe de chart como o plugin de limite de tokens do Higress na rota de cada modelo ligado, mantendo a contagem no armazenamento de protocolo Redis ligado ao socket cache do gateway: soma os tokens de prompt e de completion que cada resposta reporta, em conjunto, assim que a resposta termina, ao longo de uma janela fixa de period — um segundo, um minuto, uma hora ou um dia — que abre quando a primeira resposta nela é contada, para tudo o que o gateway serve ou para cada alias em separado. Enquanto a contagem exceder o limite, os pedidos ao modelo são respondidos com HTTP 429 até a janela terminar, pelo que o pedido que ultrapassa o limite é servido. Uma resposta que não reporta utilização não conta nada, pelo que a Recipe pede ao modelo de um pedido em streaming que reporte a sua utilização e recusa com HTTP 403 um pedido em streaming que desative esse relatório, um pedido cujo tipo de conteúdo nem contenha application/json nem comece por multipart/form-data, que o proxy de IA encaminha sem pedir o relatório, e um pedido cujo corpo os plugins do gateway não leem — um corpo comprimido, um tipo de conteúdo que contenha octet-stream ou grpc, um upgrade; um cliente que envie deliberadamente um corpo que a validação do gateway não consegue descodificar passa essas recusas, e esse pedido em streaming fica por contar. Sem mascaramento anexado, um pedido cujo corpo exceda o buffer de 32 KiB do gateway pode ser recusado com HTTP 413, consoante o momento em que o armazenamento responde. Enquanto o armazenamento não puder ser alcançado, os pedidos ao modelo são servidos e não contados: o plugin não tem nenhuma definição que os recuse nesse caso. Um orçamento em dólares americanos ou só em tokens de prompt ou de completion, um por chamador — o gateway não declara chamadores, pelo que não verifica nenhum —, qualquer outro período, um limite que não seja um número inteiro e um segundo orçamento num mesmo gateway são recusados pelo nome, tal como um anexo sem nada ligado ao socket models ou ao socket cache.

  • Concorrência: core/concurrency-limit limita quantos pedidos um gateway transporta em simultâneo (max_in_flight), o que impede que uma rajada de chamadores se torne uma fila no modelo que está por trás dele. scope diz o que um limite conta: gateway, a predefinição, conta em conjunto todos os pedidos que o gateway encaminha; model dá a cada destino para o qual o gateway envia pedidos uma contagem própria, sendo um destino cada entrada upstream para a qual o gateway encaminha, pelo que, quando um nome de modelo tem várias entradas, cada uma é contada em separado. O limite e o seu âmbito são um dimensionamento de capacidade que o operador decide, definido no infra do anexo, pelo que é o operador que o anexa na Release. O limite é contado por proxy em execução, pelo que, quando correm várias réplicas, cada uma delas admite esse número. Anexa-se a qualquer componente que declare dataplane.aggrega.ai/concurrency-cap, e uma realização recusa pelo nome o âmbito que o seu gateway não conta. Em core/gateway/nginx, o âmbito gateway é realizado como o limit_conn do NGINX, com uma chave formada por uma palavra igual para todos os pedidos, pelo que o NGINX conta todos os pedidos que está a processar como um único total, mantido em memória partilhada pelos seus processos de trabalho, e responde com HTTP 503 a um pedido que ultrapasse o limite; o âmbito model é recusado, uma vez que o NGINX não mantém nenhuma contagem por destino upstream, tal como um max_in_flight acima de 65535, o máximo que o limit_conn aceita. Em core/gateway/envoy-gateway, o âmbito model é realizado como o circuit breaker da política de tráfego na rota que serve os modelos ligados, a política que também transporta o limite de taxa de um orçamento por período e o retry da política de retry: o Envoy Gateway aplica-o ao backend de cada regra dessa rota, e cada modelo ligado tem uma regra própria, pelo que são enviados no máximo max_in_flight pedidos a cada modelo ligado em simultâneo, e um pedido que ultrapasse o limite é respondido com HTTP 503 e não é reenviado; um envio que a política de retry repete conta para o limite como o primeiro. As threads de trabalho do Envoy verificam a contagem e só depois a incrementam, pelo que pedidos que chegam em conjunto podem levá-la brevemente acima do limite. O âmbito gateway é recusado, uma vez que o Envoy Gateway mantém um limite por backend e nenhum sobre o seu total, tal como um anexo sem nada ligado ao socket models. No AI gateway, o âmbito model é realizado como o max_parallel_requests de cada entrada do seu mapa de modelos, escrita à mão ou ligada: estão em curso no máximo max_in_flight pedidos para cada entrada em simultâneo, e um pedido que encontre a sua entrada cheia é respondido com HTTP 429 — após os retries do gateway quando o seu alias tem uma entrada, e de imediato quando tem várias, mesmo que outra delas tenha espaço, uma vez que o proxy escolhe a entrada antes de contar — a menos que core/fallback-chain indique fallbacks para o seu alias, para os quais é então reencaminhado. O proxy mantém cada contagem em memória, onde, por predefinição, um registo caduca dez minutos depois de ser criado e uma nova contagem começa então do zero, pelo que o anexo também define esse tempo de vida como um século, mantendo cada contagem enquanto o proxy correr. Por causa desse tempo de vida, o gateway recusa um pedido que transporte priority enquanto o limite estiver anexado, mesmo quando a Release admite o campo, uma vez que o proxy mantém uma entrada de fila para cada pedido desses até o seu registo caducar; e a compilação é interrompida perante um mapa de modelos com mais de 100 entradas, a partir do qual o armazenamento em que as contagens são mantidas, que guarda 200 registos e descarta um sempre que está cheio, poderia descartar uma contagem. O âmbito gateway é aí recusado, uma vez que o único total do proxy só é lido por um limitador de pedidos que uma variável de ambiente ativa, e que conta um pedido durante o seu primeiro segundo. Também o gateway alojado não o realiza: o limite de pedidos que a sua Recipe terraform escreve no recurso do gateway é uma taxa, um número de pedidos ao longo de um intervalo, e não um limite aos pedidos em curso.

  • Registo de auditoria: core/audit-logging faz com que um gateway mantenha um registo de cada pedido ao modelo que serve, indicando o modelo que respondeu e os tokens que a resposta reporta, e cada realização diz onde o registo fica. Anexa-se a qualquer componente que transporte gateway.aggrega.ai/intelligence: semantic, e os seus três valores são do operador, definidos no seu infra, pelo que é o operador que o anexa na Release. require_cost, ativo por predefinição, faz com que o registo também indique quanto custou cada pedido, numa moeda que a realização nomeia. require_verified_caller, ativo por predefinição, faz com que nomeie o chamador que o gateway verificou, uma chave que o gateway emitiu ou verificou. retention_days, não definido por predefinição, faz com que o gateway elimine um registo assim que este tiver esse número de dias; sem ele, o próprio gateway não elimina nenhum registo, e um registo dura tanto quanto o local onde fica o mantiver. Um gateway que não consiga manter um valor recusa o anexo na compilação, nomeando o valor, pelo que um anexo que deixe require_cost e require_verified_caller nas suas predefinições obtém o custo e o chamador verificado, ou uma interrupção. Desativar require_verified_caller aceita um registo cujo chamador é o que o próprio pedido alega, ou nenhum chamador: qualquer pessoa que envie um pedido pode então fazer com que fique registado em nome de outro chamador, pelo que esse registo não mostra quem enviou um pedido. No AI gateway, o registo é uma linha na base de dados de contabilidade do gateway, e todos os valores são respeitados: a linha indica quanto custou o pedido em dólares americanos, com o preço tirado da tabela que o gateway mantém por modelo — um modelo sem preço na tabela é registado como não tendo custado nada — e nomeia a chave que o gateway verificou, com o utilizador e a equipa a que a chave pertence, enquanto o utilizador final que uma linha nomeia é o que o pedido escrever, sem verificação. Sem a sua base de dados de contabilidade, o gateway não escreve nenhuma linha, e sem uma chave administrativa não verifica nenhum chamador nem escreve nenhuma linha para um pedido que não apresente chave nem nomeie utilizador final, pelo que a compilação é interrompida a menos que os slots de credenciais database_url e api_key do gateway estejam ambos anexados; enquanto o values.log_masking do gateway listar o que mascarar, regista apenas os pedidos respondidos. Em core/gateway/envoy-gateway, o registo é uma linha do registo de acessos do gateway, que a sua Recipe escreve enquanto o anexo estiver presente: uma linha JSON por pedido na saída padrão do plano de dados, com os campos que o Envoy Gateway escreve por predefinição, o modelo que o pedido nomeou, o modelo que respondeu e os tokens de prompt, de completion e totais que a resposta reporta, declarando a rota que serve os modelos essas contagens para que o Envoy AI Gateway as registe. Um pedido a que o modelo não respondeu não transporta nenhum modelo que tenha respondido nem tokens, e o registo de acessos não guarda nada por si, pelo que quanto tempo dura uma linha depende do que recolher essa saída. Nenhum campo nomeia um chamador que o gateway tenha verificado: o endereço do cliente e os cabeçalhos que envia são escritos tal como chegam. O gateway não mantém preços, nada na rota que a sua Recipe renderiza verifica o chamador e o registo de acessos não guarda nenhum registo que possa eliminar, pelo que a sua realização compila um anexo que desative require_cost e require_verified_caller e não indique retention_days, e caso contrário interrompe a compilação nomeando cada valor que não consegue manter, todos numa única falha; também a interrompe sem nada ligado ao socket models. Em core/gateway/agentgateway, o registo é uma linha que o gateway escreve num armazenamento SQLite num volume que a sua Recipe de chart renderiza enquanto o anexo estiver presente, com uma réplica, para cada pedido ao modelo que passe as suas verificações de chave, de orçamento e de autorização, incluindo a recusa de uma guarda: o modelo que o gateway pediu ao servidor de modelos — o nome que o modelo ligado 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 reporta, o seu estado e os seus tempos e, para cada chamador que a sua Release declara em infra.callers, o nome desse chamador, a partir da chave de API que o gateway verificou. Um pedido recusado pela sua chave, por uma regra de autorização ou pelo orçamento de um chamador não deixa nenhuma linha. Não é guardado nenhum texto de prompt nem de resposta, e as linhas são lidas através da 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, uma vez que o catálogo de custos de modelos do gateway não atribui preço a nenhum dos modelos a ele ligados, tal como require_verified_caller sem nenhum chamador declarado e retention_days, uma vez que o gateway não elimina nenhum registo; a sua Recipe compose não tem nenhuma realização dele. Em core/gateway/higress, o registo é o campo ai_log da linha do registo de acessos 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 reporta, na saída padrão do gateway, sem texto de prompt nem de resposta. O gateway não declara chamadores, não atribui preços e não guarda nenhum registo que possa eliminar, pelo que a sua realização compila um anexo que desative require_cost e require_verified_caller e não indique retention_days, e caso contrário interrompe a compilação nomeando cada valor que não consegue manter, todos numa única falha; também a interrompe sem nada ligado ao socket models. Em core/gateway/traefik-hub, todos os anexos interrompem a compilação, indicando porquê: o Traefik Hub só mantém um registo de um pedido ao modelo como um span OpenTelemetry que os seus middlewares de IA exportam para um backend de tracing — nomeando o modelo e, no seu nível detalhado, os tokens e o seu custo em dólares americanos — e a sua realização não liga nenhum backend de tracing, pelo que o registo não ficaria em lado nenhum; e o span também não nomeia um chamador, pelo que não pode nomear aquele que a verificação de chave do gateway verificou. Em core/gateway/azure-api-management, todos os anexos interrompem a compilação, como diz o ponto do gateway acima, e nenhum outro gateway da biblioteca padrão o realiza, pelo que um anexo em qualquer outro gateway interrompe a compilação nomeando o tipo.

  • Cache semântica: core/semantic-caching declara uma cache que responde a um prompt com a resposta guardada para um prompt anterior suficientemente próximo em significado, em vez de voltar a chamar o modelo. embedding_model nomeia o modelo que transforma cada prompt num vetor, tal como o gateway o publica; uma resposta guardada é servida quando os dois prompts são semelhantes pelo menos em similarity_threshold, e continua utilizável durante ttl_seconds. scope decide quem partilha uma cache: end_user, a predefinição, mantém separado cada utilizador final que o gateway identifica, enquanto key serve a partir de uma única cache todos os chamadores que apresentem uma mesma chave, pelo que um utilizador final por trás dessa chave pode receber uma resposta gerada para outro. core/data-masking declara um conflito com ele, pelo que a compilação é interrompida num componente que tenha ambos. A biblioteca padrão realiza-o no AI gateway, que mantém as respostas num core/datastore/redis ligado ao seu socket cache_store, apresentando ao armazenamento a palavra-passe que a credencial nessa ligação contém, quando o armazenamento a exige, removendo o armazenamento cada resposta passados ttl_seconds, e coloca em cache pedidos de chat, responses e messages, não de completions nem de embeddings. A realização interrompe a compilação a menos que o slot api_key do gateway esteja anexado, porque sem uma chave administrativa o gateway não verifica nenhum chamador, perante um embedding_model que o mapa de modelos do gateway não publica, e quando nada está ligado a cache_store. Uma resposta guardada só é servida a um pedido que corresponda àquilo sob que foi guardada: a chave que o pedido apresenta, que o gateway verifica, com a equipa e a organização dessa chave; sob end_user, o utilizador final que o pedido nomeia; e o modelo que o pedido solicita, com os seus outros parâmetros. O gateway escreve a chave, a equipa, a organização e o utilizador final no próprio pedido, por cima de qualquer valor que um chamador tenha enviado para eles num pedido de chat; num pedido de responses ou de messages, remove dos metadados do próprio pedido um campo de equipa, de organização ou de utilizador final e recusa um que aí nomeie a chave, pelo que nenhum pedido consegue, nomeando-as, chegar às respostas de outra chave. Os metadados do próprio pedido ainda o podem mover entre as respostas da chave que apresenta: num pedido de responses, model_group substitui o modelo que solicita naquilo sob que a sua resposta é guardada; num pedido de responses ou de messages, caching_groups permite que pedidos que nomeiem o mesmo grupo de aliases de modelos partilhem respostas entre eles; e num pedido de responses ou de chat, redis_namespace mantém os pedidos que nomeiam um namespace separados dos que não nomeiam nenhum. O gateway lê um utilizador final a partir de um cabeçalho ou de um campo do corpo que o próprio pedido nomeia, e não verifica nenhum deles: sob end_user, um chamador que nomeie outro utilizador final recebe as respostas desse utilizador final, e os pedidos que não nomeiam nenhum utilizador final partilham uma cache com todos os outros pedidos desse tipo sob a chave que apresentam. O gateway alojado não o realiza: a sua cache só responde a um pedido idêntico a um anterior. Em core/gateway/azure-api-management, é realizado como a consulta e o armazenamento da cache semântica do Azure, escritos 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 a sua identidade gerida, e a instância precisa de uma cache Redis com RediSearch configurada como a sua cache externa, nenhuma das quais a compilação consegue ver, pelo que a compilação é interrompida até que o operador afirme que a cache serve RediSearch, definindo o infra.cache_serves_vector_search do gateway; o armazenamento guarda uma resposta durante ttl_seconds; e similarity_threshold é escrito como o limiar de pontuação do Azure, um menos o limiar, lendo essa pontuação como uma distância de cosseno, uma vez que a Microsoft indica o seu intervalo e o seu sentido — valores mais baixos exigem prompts mais próximos — mas não a sua medida. Uma resposta é guardada e servida em separado por API e por subscrição do API Management, cuja chave o gateway verifica, pelo que a realização mantém key, recusa-o numa API que não exige chave de subscrição e recusa end_user: a API que a sua Recipe renderiza não valida o token de nenhum utilizador final, pelo que o gateway não tem nenhum utilizador final verificado a manter separado. core/gateway/contour e core/gateway/nginx também não o realizam, uma vez que não oferecem cache semântica. Em core/gateway/agentgateway, a sua realização interrompe todos os anexos, indicando porquê: o agentgateway não mantém nenhuma cache de respostas, e o seu prompt caching apenas assinala onde um fornecedor que coloca prompts em cache por si pode fazê-lo. Em core/gateway/kong-enterprise, a sua realização interrompe todos os anexos, nomeando o âmbito pedido: o AI Semantic Cache do Kong não tem nenhuma definição que mantenha as respostas guardadas 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 chamadores, pelas razões que «O Kong à frente dos modelos» acima indica, pelo que, sob end_user tal como sob key, todos os pedidos partilhariam uma cache. Em core/gateway/higress, a sua realização interrompe todos os anexos, nomeando o âmbito pedido: a cache semântica do Higress guarda cada resposta sob um prefixo de chave seguido do texto do prompt, e nada nessa chave nomeia um chamador ou um utilizador final, enquanto o gateway não declara chamadores, pelo que todos os pedidos partilhariam uma cache. Em core/gateway/apisix, é realizado na Recipe de chart, escrito na rota de chat de cada modelo ligado como a cache semântica do APISIX 3.18.0, para os chamadores que a sua Release declara em infra.callers: uma resposta é guardada por rota e por chamador, sob a chave que o chamador apresentou, que o gateway verifica, pelo que nenhum chamador recebe uma resposta guardada para outro; a realização mantém key e recusa end_user pelo nome, porque o gateway não consegue distinguir os utilizadores finais por trás de uma mesma chave. embedding_model nomeia uma ligação no socket models do gateway, com cujo endpoint, modelo e credencial a cache calcula os embeddings. A cache calcula o embedding da última mensagem do utilizador de um pedido e serve uma resposta guardada cuja mensagem seja semelhante pelo menos em similarity_threshold e cujas mensagens anteriores — um prompt de sistema, turnos anteriores — sejam as mesmas. As respostas ficam durante ttl_seconds num core/datastore/redis ligado ao socket cache_store do gateway, ao qual a cache apresenta a palavra-passe que a credencial nessa ligação contém, e uma resposta servida por significado volta a ser guardada sob esse pedido durante mais ttl_seconds. Os pedidos de completion não são colocados em cache, e uma falha do armazenamento ou do embedding é um miss: o pedido continua a ser respondido. A realização interrompe a compilação sem nenhum chamador declarado, sem nada ligado a cache_store ou ao socket models, e perante um embedding_model que nenhuma ligação aí transporta. O APISIX identifica uma resposta guardada pela rota e pelo chamador, e não pelo gateway, pelo que dois gateways APISIX ligados a um mesmo armazenamento, ou duas Releases de um mesmo Aggregate que apontem o seu gateway para um mesmo armazenamento externo, podem servir uma resposta em cache a um chamador com o mesmo nome, no mesmo alias e modelo. A sua Recipe de carga de trabalho, no APISIX 3.17.0, não inclui qualquer cache semântica. Em core/gateway/traefik-hub, é realizado na Recipe de chart como a cache semântica do Traefik Hub na rota de cada modelo ligado, para os chamadores que a sua Release declara em infra.callers: uma resposta é guardada por modelo ligado e por chamador, sob o chamador que a verificação de chave do gateway verificou, cada um pela sua própria chave, pelo que nenhum chamador recebe uma resposta guardada para outro; a realização mantém key e recusa end_user pelo nome, porque o gateway não consegue distinguir os utilizadores finais por trás de uma mesma chave. embedding_model nomeia uma ligação no socket models do gateway, com cujo endpoint, modelo e credencial a cache calcula o embedding do texto de um pedido. similarity_threshold é escrito como o limite de distância da cache, um menos o limiar, lido como uma distância de cosseno, uma vez que a referência do Traefik indica o sentido do limite mas não a sua medida. Uma resposta é guardada durante ttl_seconds num core/datastore/redis ligado ao socket cache_store do gateway, e um pedido demasiado grande para calcular o embedding é respondido sem cache. A realização interrompe a compilação sem nenhum chamador declarado, sem nada ligado a cache_store ou ao socket models, perante um embedding_model que nenhuma ligação aí transporta, e perante uma imagem do Traefik Hub cuja tag não nomeie nenhuma versão a partir da v3.19.11 dentro da 3.19 ou a partir da v3.20.6, uma vez que uma versão anterior partilha uma cache entre todos os chamadores de uma rota.

  • Filtragem de injeção de prompts: core/prompt-injection-shield declara que os pedidos ao modelo que um gateway encaminha são verificados, antes de o modelo ser chamado, quanto a uma tentativa de substituir as instruções que foram dadas ao modelo, com uma sensitivity de standard ou strict — recusando strict mais tentativas destas e, com elas, mais pedidos legítimos. A verificação é o veredicto de um classificador probabilístico: falha alguns ataques — entre eles, ataques reformulados, codificados ou com outra grafia —, recusa alguns pedidos legítimos e é conhecidamente contornável, pelo que é um controlo ao lado de outros, e não avalia a resposta do modelo, os argumentos das chamadas de ferramentas nem imagens. Anexa-se a qualquer gateway, e uma realização ou envia os pedidos do gateway através de uma guarda ligada ao seu socket guard, o que não exige nada do gateway além de encaminhar para um endereço com que esteja configurado, ou ativa uma verificação que o próprio gateway executa. Através de uma guarda, a guarda verifica cada pedido e encaminha para o modelo o que admite, e anexar a Feature sem nada nesse socket interrompe a compilação, nomeando-o. A biblioteca padrão realiza-o no AI gateway e no gateway NGINX, cada um com core/security/nemo-guardrails como guarda: um serviço que fala a API de chat completions da OpenAI, cujo rail envia a última mensagem do utilizador de um pedido para o classificador do core/security/trustyai-huggingface-detector a ele ligado e recusa o pedido quando a pontuação desse classificador atinge o limiar da guarda. Um pedido recusado é respondido pela própria guarda, com uma completion normal, e nada dele chega ao modelo; quando a guarda ou o seu detetor não podem ser alcançados, o pedido também é recusado. Cada um dos dois interrompe a compilação a menos que a guarda seja essa, a executar o limiar que a sensibilidade nomeia — 0,5 para standard e 0,001 para strict, os dois valores medidos para o classificador predefinido do detetor, cujo modelo o gateway, que vê a guarda e não o detetor por trás dela, não consegue verificar. No AI gateway, todos os aliases do mapa de modelos são enviados para a guarda, sendo cada destino escrito openai/<model>, pelo que o mapa é o que é escrito à mão: um modelo ligado ao socket models do gateway seria enviado para o seu próprio endpoint com a credencial da sua própria ligação, contornando a guarda, e a realização interrompe a compilação enquanto esse socket contiver uma ligação, nomeando-a. O AI gateway recusa todos os pedidos exceto uma chat completion, o único tipo que a guarda verifica; no gateway NGINX, a sua única location encaminha para a guarda em vez do upstream, e a guarda não responde a nenhuma outra rota de modelo. Em core/gateway/azure-api-management, é realizado como o prompt shield do próprio Azure, ativado na política da API através do backend Azure AI Content Safety da instância que infra.content_safety_backend_id nomeia, e a compilação é interrompida enquanto essa chave não estiver definida: o Azure AI Content Safety verifica cada pedido quanto a um ataque do utilizador antes de o modelo ser chamado, antes da consulta de uma cache semântica, e o gateway responde com HTTP 403 a um que detete, tal como responde a um pedido mais longo do que o serviço aceita. O shield está ligado ou desligado, pelo que standard é mantido e strict é recusado pelo nome, e corre com a sensibilidade da própria Microsoft, não medida face ao limiar que standard nomeia nas guardas. A instância alcança esse backend com a sua identidade gerida, que precisa da função Cognitive Services User no serviço; a compilação não vê nenhum dos dois. Nenhum gateway da biblioteca padrão além destes três o realiza, e anexá-lo a outro interrompe a compilação nomeando o tipo: a maioria não renderiza nenhuma rota que uma realização pudesse enviar através de uma guarda — mantêm as suas rotas num armazenamento próprio, obtêm-nas dos serviços por trás deles ou são um serviço alojado no qual a biblioteca padrão não ativa nenhuma verificação deste tipo — e core/gateway/apisix, cuja Recipe de chart renderiza as rotas dos modelos a ele ligados, e core/gateway/envoy-gateway, cuja Recipe renderiza a rota de IA dos modelos a ele ligados, não têm nenhuma realização dele. Em core/gateway/agentgateway, cujas Recipes renderizam uma entrada para cada modelo a ele ligado, a realização interrompe todos os anexos, indicando porquê: o agentgateway só avalia um pedido quanto a uma tentativa destas através de um serviço que chama — um webhook que o operador executa, ou o Azure AI Content Safety, o Google Model Armor ou o AWS Bedrock Guardrails — e a realização não liga nenhum deles. Em core/gateway/higress, a realização também interrompe todos os anexos, indicando porquê: o Higress só avalia uma tentativa destas através de um serviço que chama — o serviço de segurança de conteúdos da Alibaba Cloud ou, através de um plugin que o seu código-fonte contém mas que a sua versão de plugins 2.2.5 não publica, um serviço de modelo Qwen3Guard que o operador executa —, deixando cada um passar o pedido quando essa chamada falha, e a realização não liga nenhum dos dois. Em core/gateway/traefik-hub, a realização interrompe igualmente todos os anexos, indicando porquê: o Traefik Hub só avalia uma tentativa destas através de um serviço que chama — os seus middlewares LLM Guard e Parallel LLM Guard, que chamam um serviço de guarda ou um modelo com um pedido e com condições que a realização teria de escrever, e cujo funcionamento com um detetor de ataques a prompts não está medido, pelo que nenhuma sensibilidade corresponde aí a uma verificação; ou os seus middlewares Azure Prompt Shield, Amazon Bedrock Guardrails e GCP Model Armor, que chamam serviços alojados que a realização não liga. A guarda lê apenas a última mensagem do utilizador, pelo que uma mensagem de sistema, um turno anterior ou o resultado de uma ferramenta chegam ao modelo sem serem lidos, e só é filtrado o tráfego que atravessa o gateway: uma carga de trabalho que chame diretamente o endereço do modelo contorna-o.

  • Validação de respostas e avaliações: core/response-validation declara uma verificação da resposta de um modelo face a um JSON Schema antes de esta chegar ao chamador: schema contém o próprio esquema, e uma resposta que não lhe corresponda é recusada em vez de ser transmitida — ou, com invert ativo, uma resposta que lhe corresponda. O esquema é do anexo, o mesmo para todos os pedidos, e não um que o chamador envie com o seu próprio pedido, pelo que é o programador que o anexa no Aggregate, escrevendo o esquema nos seus values. Nenhuma realização da biblioteca padrão o mantém: em core/gateway/agentgateway, a sua realização interrompe todos os anexos, indicando porquê — as guardas de resposta do agentgateway comparam padrões ou chamam um serviço de segurança de conteúdos ou um webhook, e nenhuma delas aceita um esquema —, tal como a sua realização em core/gateway/higress, cuja verificação de respostas responde a uma resposta que passe com o JSON simples que encontra na mensagem da resposta, em vez da chat completion que a sua rota OpenAI devolve, é ignorada por qualquer cliente que envie o cabeçalho de pedido X-HIGRESS-AI-JSON-RESP: true e deixa por verificar um esquema aninhado a mais de seis níveis de profundidade; e tal como a sua realização em core/gateway/traefik-hub, uma vez que nenhum middleware na referência do Traefik Hub verifica uma resposta face a um esquema — o seu middleware Chat Completion verifica pedidos face ao esquema de chat completion, a sua gestão de APIs verifica corpos de pedidos face a um documento OpenAPI e o seu LLM Guard envia uma resposta para um serviço externo, que a realização não liga; em qualquer outro gateway, um anexo interrompe a compilação nomeando o tipo. core/traffic-shadowing copia pedidos em direto para um segundo serviço e descarta as respostas desse serviço, para que um modelo ou serviço candidato possa ser avaliado com tráfego real sem que nenhum chamador veja o seu resultado. Anexa-se a qualquer componente que declare dataplane.aggrega.ai/request-mirroring, o que o AI gateway não faz; a biblioteca padrão realiza-o no gateway NGINX, que copia o fluxo inteiro em vez de uma parte dele, e interrompe a compilação perante uma parte menor, nomeando-a.

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

O Aggrega trata frameworks com interação humana (como o AutoGen e o LangGraph) como nós de trabalho. Para suportar agentes «adormecidos» à espera de input humano sem perder estado, os Platform Architects podem declarar sockets usesSchema nos Components desses agentes que impõem estritamente a ligação explícita de componentes da categoria datastore a eles, selecionados pela etiqueta de motor de datastore — datastore.aggrega.ai/engine in (vector, semantic-memory, search) para um armazenamento do qual o agente obtém dados por semelhança, ou datastore.aggrega.ai/engine=kv para um no qual guarda checkpoints do estado da sua execução. O socket liga-se pela etiqueta de motor e não por um nome de produto, pelo que um autor escolhe que 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), um papel de veredicto de governação pode ser configurado para rejeitar a arquitetura a menos que esteja anexado um componente Gateway declarado explicitamente, para que os webhooks de callback entrem por uma fronteira de entrada declarada.

Os 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 nomeia a imagem da aplicação, que o catálogo não fixa. Um socket model leva o que o framework lê do modelo ligado — o seu endereço e o nome do seu modelo, quando o framework os lê, e a credencial da ligação, por referência — para as variáveis que esse framework lê. Quando o framework não define nenhum servidor próprio, o componente é um worker e não abre nenhuma porta: core/ai-agent/crewai e core/ai-agent/langgraph assumem esta forma, tal como core/ai-agent/openai-agents-sdk, cujo socket model só aceita um modelo ou gateway que transporte model.aggrega.ai/api: openai, core/ai-agent/claude-agent-sdk, cujo socket só aceita um que transporte model.aggrega.ai/api: anthropic, e core/ai-agent/agent-framework, para uma aplicação construída sobre o Microsoft Agent Framework, que por si não serve nada, cujo socket só aceita um que transporte model.aggrega.ai/api: openai e entrega as variáveis que os clientes OpenAI em Python do Agent Framework leem; estes três interrompem a compilação, nomeando infra.image, até que a Release o defina. O OpenAI Agents SDK envia por predefinição um trace de cada execução para a OpenAI, pelo que core/ai-agent/openai-agents-sdk desativa esse envio a menos que o Aggregate defina o seu valor upload_traces_to_openai como true. Quando o framework serve HTTP por si, o componente é um server na porta do próprio framework e publica o endereço que um chamador alcança como host, port, endpoint e protocol, e também interrompe a compilação, nomeando 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 para a API Gemini, aceitando o seu socket model apenas um modelo que transporte 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 a sua rota /health responde, aceita um modelo ou gateway que transporte model.aggrega.ai/api: openai e, quando o Aggregate nomeia um dos agentes da aplicação no seu valor agent_id, publica o endereço do cartão Agent2Agent desse agente, para que core/ai-tool/agent-invocation lhe possa delegar. As rotas de ambos os servidores respondem a qualquer chamador a menos que a aplicação as autentique, pelo que um anexo core/public-ingress ou core/http-route em qualquer um deles interrompe a compilação até que a Release defina o seu infra.routes_authenticated como true, afirmando que a aplicação autentica todos os pedidos que as 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 ligada, e a credencial da ligação por referência, em variáveis com o nome do alias da ligação. Como a aplicação é o código próprio da Release, as variáveis que estes agentes entregam para esse código ler são predefinições: cada um dos seus sockets admite um bloco inject:, através do qual o Aggregate nomeia as variáveis, ou os ficheiros, que a aplicação lê em vez delas, enquanto uma variável que o framework lê por si e o que um anexo na ligação entrega se mantêm. O mesmo se aplica aos valores próprios do agente: cada componente admite em si próprio um bloco inject: de entradas env e file, e uma entrada cujo template lê um dos seus valores próprios e nada mais do componente — nenhum outro valor, nem o seu infra, os seus metadados ou a sua identidade — substitui o nome predefinido 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 cria rascunhos destes agentes — core/ai-agent/crewai, core/ai-agent/langgraph, core/ai-agent/google-adk e core/ai-agent/agent-framework — ligados ao datastore que a configuração nomeia, e ao modelo que nomeia quando o socket model do agente o aceita, ao lado de um rascunho de Release que deixa ao operador a indicação da imagem em que o programa corre, e lê apenas a configuração, nunca o programa, como descreve Importer Plugins.

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

Como as cargas de trabalho de IA introduzem novos vetores de ataque (como a injeção de prompts e a exfiltração autónoma de dados), protegê-las exige ligar a governação arquitetural estática à aplicação ativa em tempo de execução. Enquanto compilador Ahead-of-Time (AOT), o Aggrega não interceta tráfego de rede em direto nem avalia prompts de IA. Em vez disso, resolve requisitos de segurança complexos através de um handshake arquitetural em duas partes: compilação estática da arquitetura (tempo de compilação) e passagem da execução (tempo de implementação).

A. Tempo de compilação: validação de políticas e geração de artefactos

O compilador constrói um grafo plano de Representação Intermédia (IR) que contém todos os nós, arestas e Features anexadas. Antes de ser gerada qualquer infraestrutura física, a postura de segurança da empresa é aplicada avaliando este grafo JSON estático face a motores de políticas de referência no setor, num papel de veredicto de governação.

Como o socket avalia dados JSON genéricos, não está preso a uma única linguagem de políticas. As empresas podem compilar e aplicar as suas regras arquiteturais com a norma que melhor se adequa ao seu ecossistema:

  • Open Policy Agent (OPA/Rego): uma linguagem amplamente utilizada para avaliar relações de grafo complexas e com vários saltos e calcular o acesso de privilégio mínimo em topologias distribuídas. O motor Rego compilado na CLI executa ficheiros .rego tal como estão; uma política que precise de toda a superfície de builtins do OPA é compilada com a toolchain do próprio OPA e corre atrás de um guest adaptador.
  • Common Expression Language (CEL): o motor CEL compilado na CLI executa regras escritas como expressões únicas sobre um documento, tal como se escreve uma validating admission policy do Kubernetes.
  • Kyverno: avalia manifestos JSON/YAML estáticos, permitindo às equipas escrever políticas em YAML nativo em vez de aprender Rego. Nenhum guest Kyverno é distribuído com o compilador, que executa políticas apenas como guests WebAssembly e nunca invoca a CLI do Kyverno, pelo que as regras do Kyverno correm atrás de um guest que encapsula o motor.
  • Validação personalizada em Rust/TypeScript: as equipas de segurança podem escrever políticas organizacionais à medida em linguagens comuns e compilá-las para Wasm para servirem de barreira de validação.

Depois de o motor de políticas validar o grafo, o compilador traduz esses requisitos de segurança abstratos em configuração física. Quando um programador anexa uma Feature de segurança — core/data-masking no AI gateway, por exemplo —, o compilador executa o passo de pipeline que a sua realização nomeia, um plugin WebAssembly (Wasm) isolado, e esse passo escreve a definição de que o controlo precisa na configuração que a própria Recipe do gateway já renderiza. Em alternativa, uma realização pode deixar a escrita à própria Recipe do gateway, que lê o anexo e escreve ela própria a definição, como faz core/data-masking em core/gateway/kong-enterprise, e uma realização para outro tipo de controlo pode emitir um recurso próprio; em qualquer dos casos, o resultado é um artefacto estático escrito a partir do que o programador anexou.

B. Tempo de implementação e tempo de execução: passagem da execução e aplicação

A responsabilidade do Aggrega termina no exato momento em que acaba de processar o input e escreve os artefactos estáticos configurados no diretório de saída. É um compilador puro: escreve a configuração e, depois, o controlo regressa inteiramente ao sistema que o invocou.

A forma como essas configurações são executadas é altamente flexível e fica inteiramente ao critério da empresa:

  • A passagem de artefactos (tempo de implementação): controladores de implementação externos assumem o controlo para levar os artefactos à realidade. Isto pode ser um controlador GitOps estrito (como o ArgoCD ou o Flux) a sincronizar ficheiros num cluster Kubernetes, mas pode igualmente ser um pipeline de CI/CD comum a executar terraform apply, ou um programador a correr um script de shell local contra o Docker Compose.
  • Aplicação em tempo de execução: assim que as configurações são aplicadas ao ambiente de destino, a infraestrutura física assume o controlo. As ferramentas especializadas configuradas pelo Aggrega (como um sidecar de guardrails, uma service mesh ativa ou firewalls nativas da cloud) arrancam e começam o seu trabalho ativo: intercetar fisicamente payloads, verificar JWTs ou descartar injeções de prompts maliciosas.

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

Ao desacoplar a validação arquitetural da execução em tempo de execução, as equipas de plataforma podem utilizar o Aggrega para modelar, validar e gerar explicitamente soluções de configuração para as vulnerabilidades de IA descritas a seguir.

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

  • O problema: um agente autónomo pode tentar divulgar dados empresariais restritos a uma API externa não autorizada.
  • A solução do Aggrega:
    1. Tempo de compilação (validação e geração): a equipa de plataforma escreve uma política (por exemplo, em Rego) avaliada num papel de veredicto de governação que estabelece: «Todos os caminhos que passam por um AI gateway têm de transportar core/data-masking.» Se faltar, o compilador interrompe a compilação. Se estiver presente, a realização que o Manifest associa escreve o mascaramento na configuração que o gateway já renderiza: em core/gateway/litellm, entradas de guardrail que correspondem às expressões regulares que o anexo lista e que enviam o texto para um analyzer e um anonymizer Presidio ligados aos sockets pii_analyzer e pii_anonymizer do gateway, para os tipos de entidades que lista; em core/gateway/kong-enterprise, o AI PII Sanitizer do Kong nas rotas de chat e de completion de cada modelo ligado, escrito pela Recipe de chart do gateway, que envia o texto que mascara, com as expressões regulares e os tipos de entidades que o anexo lista, para o serviço Kong AI PII ligado ao socket pii_sanitizer do gateway; em core/gateway/agentgateway, as próprias guardas de expressões regulares do gateway, escritas na 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 ao pedido ou à resposta com HTTP 403, e não reconhecem tipos de entidades; essas guardas não mascaram uma resposta em streaming, pelo que, enquanto as respostas forem mascaradas, a mesma Recipe escreve uma regra que recusa com HTTP 403, antes de ser encaminhado, um pedido que peça uma, e qualquer pedido cujo corpo seja maior do 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 AI gateway do Traefik Hub na rota de cada modelo ligado, escrito pela sua Recipe de chart, que mascara as correspondências dos padrões que o anexo lista através do seu motor de expressões regulares, ou dos tipos de entidades que lista através do analyzer Presidio ligado ao socket pii_analyzer do gateway, um motor por anexo; em core/gateway/higress, o plugin ai-data-masking do Higress na rota de cada modelo ligado, escrito pela sua Recipe de chart, que substitui cada correspondência dos padrões que o anexo lista nas mensagens de um pedido de chat pelo nome do padrão entre parênteses retos, e não reconhece tipos de entidades. Uma política também pode fazer a pergunta mais restrita — se o mascaramento se situa entre os dados restritos e o fornecedor — lendo os anexos de cada componente ao longo da rota, em vez dos anexos da rota no seu conjunto, como faz examples/policy-data-class-route.
    2. Tempo de execução (aplicação física): assim que o orquestrador implementa os artefactos gerados, o gateway substitui cada correspondência no texto do pedido que mascara por um marcador antes de o encaminhar, pelo que o fornecedor do modelo recebe o marcador; com action: refuse, o anexo não encaminha nada de um pedido que contenha uma correspondência e responde-lhe, em vez disso, com um erro. Um reconhecedor que não possa ser alcançado ou que dê erro faz falhar o pedido, pelo que o seu texto não é transmitido. O que o mascaramento não alcança é decidido por dois valores cujas predefinições são a proteção. No AI gateway, enquanto o anexo também mascarar as respostas, o gateway mascara o texto da resposta e as partes que um modelo ou o seu fornecedor acrescentam 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 fornecedor — ou, sob refuse, não envia nada de uma resposta que contenha uma correspondência; uma resposta em streaming que mascara por padrão chega ao chamador inteira, no final. Por predefinição, aquilo que o seu mascaramento não alcança num pedido — uma rota como a geração de imagens, um campo como safety_identifier, uma imagem ou um ficheiro na conversa, uma ferramenta que o próprio fornecedor executa — o AI gateway recusa com HTTP 400 antes de encaminhar o que quer que seja; um operador que aceite que esse texto chegue ao fornecedor sem máscara define allow_unmasked_text no anexo na Release, listando a realização exatamente o que passa nesse caso, e o conteúdo que não é texto continua regido por allow_non_text_content. Por predefinição, aquilo que uma resposta mascarada transporta e que o seu mascaramento não consegue ler — áudio falado e a sua transcrição, uma imagem, as probabilidades dos tokens que o modelo escolheu — é retido, e uma chamada falhada chega ao chamador com uma mensagem fixa em vez da que o fornecedor devolveu; allow_unmasked_reply_parts deixa que essas partes cheguem ao chamador sem máscara. O próprio texto de uma resposta nunca é deixado passar por ele, mas as partes que deixa passar podem conter as palavras da resposta: a transcrição de uma resposta falada, os tokens por trás das probabilidades de tokens, uma mensagem de erro do fornecedor que cite a resposta. Em core/gateway/kong-enterprise, cada correspondência é substituída por um marcador numerado, pelo que um anexo que liste padrões em redact define placeholder_shows_name: false; refuse alcança apenas pedidos, a partir do Kong 3.12, que responde com HTTP 400 a um pedido que contenha uma correspondência; e as respostas são mascaradas a partir da 3.12, sendo então recusado, antes de ser encaminhado, um pedido que peça uma resposta em streaming, e recusado allow_streamed_replies. O sanitizer do Kong lê o texto dos turnos do utilizador, o prompt de uma completion e o texto da mensagem de uma resposta, e a referência do Kong não nomeia nenhuma definição que recuse um pedido por aquilo que o sanitizer não lê ou que retenha o resto de uma resposta, pelo que, nesse gateway, cada proteção é recusada pelo nome no momento da compilação enquanto mantiver a sua predefinição, e um anexo compila assim que a Release as atenuar — allow_unmasked_text e allow_non_text_content quando os pedidos são mascarados, allow_unmasked_reply_parts e mask_reasoning: false quando o são as respostas —, com data-masking-kong-enterprise a listar o que cada uma deixa então passar. Aí, uma resposta cujo texto não chegue como a cadeia única que a API da OpenAI devolve passa sem ser lida, chegando o seu próprio texto ao chamador sem máscara; a salvaguarda é a verificação da compilação sobre cada modelo ligado a esse gateway, que a interrompe perante um cujo model.aggrega.ai/api não seja openai. Em core/gateway/traefik-hub, cada correspondência é substituída por uma sequência de * com o comprimento da correspondência, pelo que um anexo que liste padrões em redact define placeholder_shows_name: false; refuse responde com HTTP 403 em vez do pedido ou da resposta; e uma resposta mascarada é retida inteira e enviada no final, incluindo uma em streaming, pelo que um anexo que mascare tipos de entidades nas respostas define allow_streamed_replies. A referência do Traefik não diz que campos de um pedido ou de uma resposta de chat o Content Guard lê, e não nomeia nenhuma definição que recuse um pedido, ou retenha parte de uma resposta, por aquilo que não lê, pelo que, nesse gateway, cada proteção é recusada pelo nome no momento da compilação enquanto mantiver a sua predefinição, e um anexo compila assim que a Release as atenuar — allow_unmasked_text e allow_non_text_content quando os pedidos são mascarados, allow_unmasked_reply_parts e mask_reasoning: false quando o são as respostas —, com data-masking-traefik-hub a listar o que cada uma deixa então passar. Um anexo que liste tanto padrões como tipos de entidades, e um segundo anexo de mascaramento num mesmo gateway, são recusados, uma vez que a referência do Traefik não diz se um segundo Content Guard numa rota lê o texto que o primeiro mascarou ou o pedido tal como o chamador o enviou. Em core/gateway/higress, o plugin ai-data-masking do Higress substitui cada correspondência dos padrões que o anexo lista, no conteúdo e no raciocínio de cada mensagem de um pedido de chat, pelo nome do padrão entre parênteses retos; mascara apenas pedidos, pelo que scope response e both são recusados, e não reconhece tipos de entidades. O plugin não lê mais nada de um pedido, pelo que, enquanto as proteções mantiverem as suas predefinições, a Recipe de chart do gateway também escreve o plugin de validação de pedidos do Higress para recusar com HTTP 403, antes de qualquer encaminhamento, um pedido que contenha aquilo 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 nulo, 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 próprias ferramentas, formato de resposta e sequências de paragem do programador — e, seja o que for que o anexo atenue, um pedido cujo corpo os plugins do Higress ignoram — um corpo comprimido, um tipo de conteúdo que contenha octet-stream ou grpc, um upgrade — e um corpo que contenha o carácter de substituição Unicode U+FFFD, que é como essa validação lê um byte que não é UTF-8 válido, uma vez que o plugin de mascaramento encaminha sem máscara um corpo que não seja UTF-8 válido. Um pedido cujo corpo exceda o buffer de 32 KiB do gateway é recusado com HTTP 413. A validação só lê um corpo que o seu descodificador JSON aceite, pelo que um cliente que envie deliberadamente JSON válido que o descodificador recusa — um número para além do que um double comporta, por exemplo — passa todas as recusas do seu corpo: o plugin de mascaramento mascara então apenas o conteúdo simples e o raciocínio de cada mensagem, pelo que um valor listado em qualquer outro ponto do corpo — os argumentos de uma chamada de ferramenta, um nome, qualquer outro campo — é encaminhado sem máscara, tal como o conteúdo escrito com sequências de escape JSON, e, se esse corpo também não for UTF-8 válido, é encaminhado todo sem máscara. Um cliente que aninhe 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 descodifica e admite, mas o leitor JSON do plugin de mascaramento para nessa profundidade, pelo que o conteúdo escrito com sequências de escape JSON nesse corpo também é encaminhado sem máscara. O mascaramento não é suficiente por si só: o texto a que nenhum padrão corresponde e que nenhum reconhecedor deteta passa inalterado; no AI gateway, os argumentos das chamadas de ferramentas e os resultados das ferramentas são mascarados valor a valor, mas os nomes das suas chaves não; as próprias definições de ferramentas, formatos de resposta e sequências de paragem do programador passam tal como foram enviados; o gateway e os serviços de reconhecimento veem o texto original; aquilo que o gateway regista sobre uma chamada — no seu próprio registo, ou no que entrega a uma integração de registo — pode ainda conter esse texto; e o tráfego que não atravessa o gateway não é tocado.

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

  • O problema: se um agente for comprometido através de uma ferramenta Model Context Protocol (MCP) envenenada, pode executar autonomamente ações destrutivas (como eliminar uma base de dados ou autorizar uma transferência).
  • A solução do Aggrega:
    1. Tempo de compilação (validação e geração): o programador anexa uma Feature de barreira de aprovação à ferramenta sensível no seu Aggregate.yaml. A biblioteca padrão não inclui nenhuma Feature deste tipo, pelo que esta é escrita no próprio catálogo da empresa, juntamente com a FeatureRecipe que a renderiza. O compilador valida o grafo e traduz o anexo na configuração de um proxy L7 ou de um gateway de webhooks.
    2. Tempo de execução (aplicação física): quando o agente sequestrado tenta invocar a ferramenta, o proxy implementado coloca o pedido em pausa e bloqueia fisicamente a execução até ser recebida uma aprovação assinada criptograficamente por um operador humano.

C. Resolver o «Confused Deputy» (propagação de contexto)

  • O problema: em cadeias multiagente, um agente exposto ao público pode ser sequestrado e ordenar a um agente interno com privilégios elevados que obtenha dados sensíveis. As firewalls comuns só veem que «o Agente A está a falar com o Agente B» e permitem o tráfego, perdendo por completo o contexto do utilizador malicioso original.
  • A solução do Aggrega: as empresas podem sobrepor dois padrões específicos:
    1. Propagação da identidade do chamador, em dois saltos: a identidade do chamador original tem de sobreviver a dois saltos diferentes, e cada um é protegido num local diferente. No salto do gateway, o programador anexa core/context-propagation ao gateway por onde um pedido entra, que seleciona por dataplane.aggrega.ai/caller-identity. Em tempo de compilação, o anexo é realizado na própria configuração desse gateway — no Envoy Gateway, uma política de tráfego de cliente que verifica o certificado de cada cliente face a uma autoridade que a Release nomeia e encaminha os detalhes do certificado; no AI gateway LiteLLM, um hook de pedidos que remove qualquer cabeçalho de identidade fornecido por um chamador e acrescenta o utilizador e a equipa da chave virtual que o gateway verificou, e a sua organização quando a chave nomeia uma, nos pedidos aos aliases de modelos que o anexo lista em destinations. Em tempo de execução, o serviço por trás do gateway recebe quem chamou, e não apenas que foi o gateway a chamar. No salto da carga de trabalho, um pedido que um agente faz diretamente a outro nunca atravessa esse gateway, pelo que é verificado na própria entrada do agente recetor, onde uma service mesh rejeita qualquer pedido a que falte um token assinado que prove a intenção do utilizador original (por exemplo, uma AuthorizationPolicy JWT do Istio). A biblioteca padrão inclui a Feature do salto do gateway e nenhuma Feature do salto da carga de trabalho, pelo que anexar core/context-propagation protege o tráfego que passa por um gateway e deixa as chamadas de agente para agente à configuração de mesh que a própria empresa fornece. Um agente que outra parte executa, que core/ai-tool/agent-invocation alcança por A2A como core/ai-agent/a2a-remote, fica totalmente fora da Release: essa parte verifica cada chamada face ao esquema de segurança que o Agent Card do agente declara, e a ferramenta apresenta a credencial guardada na sua ligação, lida de um Secret por referência, no cabeçalho de pedido que o agente publica. Quando o cartão exige credenciais de cliente OAuth 2.0 ou OpenID Connect, a ligação guarda, em vez disso ou adicionalmente, um segredo de cliente, com o client id que o operador nela escreve, e o agente publica o endereço do token ou de descoberta e os scopes que o seu cartão declara; o próprio contentor da ferramenta obtém o token com eles, renova-o e apresenta-o em cada chamada; o catálogo entrega apenas esses inputs, e nenhuma compilação consegue verificar o que o contentor faz com eles. Quando o cartão exige TLS mútuo, a ligação guarda 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 contentor da ferramenta como ficheiros de um Secret que a ligação nomeia, e o próprio contentor apresenta o certificado no handshake TLS. Assim, a ferramenta alcança um agente cujo cartão declare uma chave de API num cabeçalho ou num cookie, um esquema de autenticação HTTP cujo valor seja fixo, como Bearer ou Basic, contendo o Secret o valor completo do cabeçalho, OAuth 2.0 ou OpenID Connect com a concessão de client credentials, ou TLS mútuo. Não alcança um cujo cartão exija uma chave na query string, um esquema HTTP que responda a um desafio do agente, como o Digest, ou um fluxo OAuth 2.0 que não seja o de client credentials. Também não apresenta uma credencial a um agente que outra parte executa por HTTP simples: quando o endereço desse agente é http, uma credencial ou um segredo de cliente na ligação interrompe a compilação, nomeando a ligação, porque a credencial, ou o token obtido com o segredo, viajaria até ele sem cifragem. Um agente que corre dentro da Release continua alcançável por http com qualquer um deles, e a credencial atravessa então a rede do cluster sem cifragem.
    2. Inspeção de payloads entre agentes: um pedido que um agente envia diretamente a outro nunca atravessa o AI gateway, pelo que é inspecionado na própria entrada do agente recetor, por um motor de guardrails que corre ao lado desse agente (por exemplo, o NeMo Guardrails). Em tempo de compilação, a FeatureRecipe que realiza uma Feature anexada ao agente recetor renderiza a configuração do motor. Em tempo de execução, o motor avalia cada pedido face a regras que a empresa escreve e recusa um que essas regras rejeitem; a capacidade de distinguir um pedido sequestrado de um legítimo pertence ao motor e às regras, porque o Aggrega compila configuração e nunca avalia um prompt. A biblioteca padrão não inclui nenhuma Feature que coloque um motor destes, pelo que este padrão é escrito no próprio catálogo da empresa. A guarda de padrões do próprio gateway, dataplane.aggrega.ai/prompt-guard: pattern-list, é mais restrita, e core/prompt-deny-patterns ativa-a — no AI gateway, lendo todas as mensagens de um pedido e ignorando maiúsculas e minúsculas; em core/gateway/apisix e core/gateway/kong, lendo todas as mensagens de todos os papéis como um único texto, distinguindo maiúsculas de minúsculas e respeitando uma lista de padrões a que um pedido também tem de corresponder; em core/gateway/agentgateway, lendo em separado cada mensagem, argumento de chamada de ferramenta e resultado de ferramenta, distinguindo maiúsculas de minúsculas; e em core/gateway/traefik-hub, lendo o pedido como uma chat completion, da qual a referência do Traefik não lista os campos lidos, distinguindo maiúsculas de minúsculas: recusa um pedido ao modelo cujo texto corresponda literalmente a uma das expressões que o anexo lista — uma paráfrase, outra língua ou uma codificação passam por ela — e apenas no tráfego que passa pelo gateway, pelo que um pedido enviado diretamente entre agentes nunca a encontra. core/prompt-injection-shield é a sua contraparte baseada num classificador no mesmo salto, enviando cada pedido ao modelo que um gateway encaminha através de uma guarda NeMo Guardrails ligada ao socket guard desse gateway, ou através do prompt shield do Azure AI Content Safety no Azure API Management, e também abrange apenas o tráfego que atravessa o gateway.

D. Análise de risco topológico

  • O problema: arquiteturas de IA complexas, com dezenas de modelos, vetores e ferramentas interligados, são demasiado vastas para que um humano as audite manualmente quanto a vulnerabilidades transitivas (por exemplo, «Pode o Agente A falar com a Ferramenta B, que fala com o Agente C, que tem acesso à Base de Dados D?»).
  • A solução do Aggrega: esta verificação corre antecipadamente. Como o Aggrega constrói em memória um grafo IR completo da topologia pretendida, um papel de veredicto de governação pode executar regras avançadas de procura de caminhos sobre toda a arquitetura. Se a política detetar uma cadeia contínua e transitiva de arestas que tenha origem num nó público e termine numa base de dados altamente sensível sem nenhum dos controlos que a empresa exige anexado em ponto algum ao longo dela, interrompe imediatamente a compilação. A arquitetura insegura é bloqueada antes de ser gerada uma única linha de código de infraestrutura.

8. Observabilidade e conformidade

Para satisfazer requisitos regulamentares exigentes (por exemplo, o AI Act da UE), os Platform Architects podem utilizar o sistema de features do Aggrega para impor a observabilidade da IA como um requisito estrutural da infraestrutura, em vez de depender do código da aplicação:

  • Registo de auditoria: Plugins Wasm escritos pela empresa podem configurar sidecars de gateway para transmitir de forma assíncrona prompts e respostas em bruto, sem redação, para um bucket de armazenamento WORM (Write Once, Read Many) seguro, contornando os registos normais da aplicação.
  • Tracing de LLM: features de proxy podem configurar o plano de dados para extrair e encaminhar cabeçalhos de span OpenTelemetry específicos de IA, garantindo que ciclos complexos de raciocínio de agentes possam ser visualizados em ferramentas externas.

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

Como o compilador central é agnóstico em relação à mecânica da infraestrutura física, 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 em interoperability, das Features ao lado das quais não pode ser anexada. O compilador compara-a com as Features que cada componente acaba por transportar depois de todos os âmbitos terem contribuído — os anexos do próprio componente, os escritos num subsistema ou numa fronteira que o contenha, os da sua entrada de componente na Release e os produzidos pela expansão guiada por anotações — e interrompe a compilação antes de renderizar quaisquer artefactos físicos quando um componente transporta ambas (isto é, quando um autor anexa, diretamente ou através de um âmbito, duas Features que o autor de uma Feature declarou explicitamente incompatíveis). Basta uma declaração, e as Features são comparadas pelo nome, quaisquer que sejam as suas versões. O compilador não interpreta os 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, elas próprias, a ser um contrato social — nada verifica que uma Feature faz uma única coisa.

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

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

  • Arestas uses: os programadores ligam componentes no bloco uses de cada instância, nomeando o componente de destino num socket, e todas as arestas do grafo provêm 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: cada destino de uses tem de nomear um componente que a compilação contém; um destino que não existe interrompe a compilação, nomeando o socket ao qual estava ligado.
  • Segurança de tipos entre nós: as cadeias de seletor de usesSchema funcionam como instruções explícitas fora de banda, avaliadas nativamente pelo motor de correspondência de etiquetas do compilador Go durante a análise estática. Garantem que os programadores não ligam acidentalmente componentes comuns a um socket declarado que exige uma capacidade nativa de IA ou uma etiqueta de conformidade específica. Por construção, a garantia restringe-se aos sockets declarados: um seletor vive numa entrada de usesSchema, pelo que um socket ad hoc não tem nenhum para avaliar. Cada aresta regista se o seu socket foi declarado no catálogo, pelo que um operador que precise de que a garantia seja total pode exigi-la como um veredicto de governação.

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

Os sistemas de IA avançados incluem Meta-Agents que escrevem código para inventar e implementar novos agentes em tempo real. Como o Aggrega exige uma arquitetura estática ahead-of-time (AOT), resolve a evolução da infraestrutura em tempo de execução através de duas fronteiras explícitas:

  • A fronteira de sandbox pré-aprovisionada: para ferramentas efémeras inventadas em tempo de execução, o Architect define uma feature (por exemplo, dynamic-execution-environment). Quando anexada, o plugin de renderização Wasm gera a configuração para aprovisionar um conjunto de computação bloqueado (como um runtime WebAssembly). O Meta-Agent injeta código novo nesta sandbox, mas o seu raio de impacto fica limitado pelas políticas de rede estáticas geradas.
  • O Meta-Agent no papel de «Developer» (o ciclo GitOps): se o Meta-Agent precisar de infraestrutura física genuinamente nova, atua como um Developer. Escreve um novo Aggregate.yaml e faz commit dele no Git. Isto desencadeia o pipeline de CI/CD normal. Um papel de veredicto de governação analisa estaticamente a topologia pedida pela IA, interrompendo em segurança a compilação se a IA tiver alucinado uma vulnerabilidade.

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

Implementar um modelo open source significa muitas vezes descarregar ficheiros .pkl ou .gguf opacos que podem conter payloads de código malicioso. As empresas podem tratar a segurança da cadeia de abastecimento de modelos como um problema de configuração da plataforma de destino. Ao definir uma feature model_provenance no catálogo, o plugin de renderização Wasm de uma empresa pode avaliar a configuração e traduzi-la em artefactos de tempo de execução (como políticas Kyverno do Kubernetes), para que o cluster de destino fique configurado para impedir o orquestrador de obter pesos de modelos não assinados ou não verificados.