Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

Substrato para agentes

Requer o Substrato para agentes v1.0.0 e o Helm chart do Loom no mesmo cluster Kubernetes: o gateway de saída do Substrate adiciona o token do Loom de cada agente às suas chamadas MCP.

O token nunca faz parte do template do ator nem dos snapshots. O Substrate v1.0.0 exige Kubernetes 1.37 ou posterior, com um runtime gVisor ou microVM nos nós. Os passos abaixo também exigem o provedor de credenciais Kubernetes do Substrate, que o comando ate-setup deploy ... --credential-provider='{"name":"k8s.io"}' implanta.

Os passos do Substrate abaixo seguem a documentação do próprio Substrate para a v1.0.0; esta página não foi executada de ponta a ponta em um cluster real, portanto confira os passos com a sua versão do Substrate.

Como as peças se encaixam

Peça Onde roda O que faz
Loom helm install loom no namespace loom o servidor de memória; seu Service é loom.loom.svc.cluster.local:7777
Agente um ator do Substrate em um atespace chama o endpoint MCP do Loom, /mcp, com um cabeçalho Authorization de espaço reservado
Política de egress plano de controle do Substrate (kubectl ate), aplicada pelo atenet-egress permite que o ator acesse o Loom e nada além disso, a menos que você adicione regras
Token do Loom um Secret do Kubernetes um por agente; o gateway de egress o coloca no cabeçalho Authorization

Toda requisição sai do ator pelo gateway de egress do Substrate (atenet-egress em ate-system), que nega todo egress que a política de um ator não permita. Por isso, o Loom vê conexões dos pods do gateway, não dos atores. Cada linha registra o subject do token, o que distingue os atores entre si; o agent da linha é o nome do cliente MCP, que atores que executam o mesmo cliente compartilham.

1. Instale o Loom no cluster

Instale o chart conforme descrito em Kubernetes, no namespace loom com o nome de release loom, que dá ao Service o nome loom. Os agentes não precisam de Ingress: eles acessam o Service pelo nome DNS dele dentro do cluster.

A NetworkPolicy do chart admite qualquer origem enquanto networkPolicy.ingressFrom estiver vazio, que é o valor padrão. Se você listar peers ali (as sub-redes do balanceador de carga, por exemplo), adicione o gateway de egress à lista, pois uma lista que você define substitui o padrão em vez de acrescentar a ele:

networkPolicy:
  enabled: true
  ingressFrom:
    # ...the peers you already allow...
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: ate-system
      podSelector:
        matchLabels:
          app: atenet-egress

2. Um token por agente

Dê a cada agente o seu próprio token, com um subject de service account nomeado a partir do atespace e do ator do Substrate. O Loom registra esse subject em cada linha que o agente grava, e os namespaces e as roles do token determinam o que ele lê e grava (tokens e grants).

Gere o token em um pod do Loom, que guarda a chave de assinatura, e armazene-o em um Secret em um namespace que contenha apenas os tokens desse atespace:

TOKEN=$(kubectl -n loom exec deploy/loom -- \
  loom mint-token --subject sa:research.research-agent --org acme \
    --namespaces research --roles writer --ttl-days 30)
kubectl create namespace loom-tokens-research
kubectl -n loom-tokens-research create secret generic research-agent \
  --from-literal=token="$TOKEN"

O provedor de credenciais Kubernetes do Substrate lê um Secret apenas de namespaces que o atespace tenha permissão para acessar. Um administrador concede ao atespace o namespace de tokens na política de namespaces do provedor e reinicia o provedor, que lê a política na inicialização:

kubectl -n ate-system edit configmap k8s-credential-provider-namespace-policy
data:
  namespace-policy.yaml: |
    policies:
    - atespace: research
      allowedNamespaces:
      - loom-tokens-research
kubectl -n ate-system rollout restart deployment/k8s-credential-provider

O provedor concede a um atespace namespaces inteiros, não Secrets individuais, então um atespace com acesso a um namespace pode usar todos os tokens que há nele: um namespace por atespace mantém cada atespace restrito aos tokens dos seus próprios agentes.

O token expira após --ttl-days: antes disso, gere um novo e substitua o Secret. O provedor de credenciais lê o Secret a cada requisição, então a próxima chamada leva o novo token:

TOKEN=$(kubectl -n loom exec deploy/loom -- \
  loom mint-token --subject sa:research.research-agent --org acme \
    --namespaces research --roles writer --ttl-days 30)
kubectl -n loom-tokens-research create secret generic research-agent \
  --from-literal=token="$TOKEN" --dry-run=client -o yaml | kubectl apply -f -

3. Configure o agente e crie seu actor

A documentação do Substrate não descreve nenhuma configuração de MCP para actors: configure o cliente MCP do agente na imagem dele ou como valores literais de variável de ambiente no template do actor. A entrada do servidor é o endpoint do Loom com um header de espaço reservado, que o gateway substitui:

{
  "mcpServers": {
    "loom": {
      "type": "http",
      "url": "http://loom.loom.svc.cluster.local:7777/mcp",
      "headers": { "Authorization": "Bearer placeholder" }
    }
  }
}

Os nomes das chaves seguem o cliente (clientes MCP traz a entrada de cada um). Mantenha o token fora do template: o Substrate armazena templates e snapshots, e o ambiente do contêiner aceita apenas valores literais.

Em seguida, crie o atespace, o template de actor que carrega a imagem do agente e o actor a partir desse template. O guia da API do Substrate descreve os campos do template; aqui, seu metadata o nomeia como research-agent no atespace research. O workerSelector do template deve corresponder a um WorkerPool no cluster, e a imagem dele deve ser fixada por digest. Crie os três:

kubectl ate create atespace research
kubectl ate create actor-template -f template.yaml
kubectl ate create actor research-agent --template=research-agent -a research

4. Permita que o actor acesse o Loom, com o seu token

Um actor tem uma política de egress. Esta, para o actor criado acima, permite HTTP para o Service do Loom e substitui o cabeçalho Authorization que o agente envia por Bearer <token>, usando o valor do Secret:

kubectl ate create egress-policy research-agent -a research -f - <<'EOF'
rules:
- http:
    hostnames: ["loom.loom.svc.cluster.local"]
    ports:
      numbers: [7777]
    effects:
      replaceHeaders:
      - header: Authorization
        prefix: "Bearer "
        credentialUri: ate-secret://k8s.io/default/loom-tokens-research/research-agent/token
EOF
  • A regra confere com o host da requisição, então ela usa o host da URL da entrada MCP: loom.loom.svc.cluster.local.
  • O gateway substitui um cabeçalho que já existe. Uma requisição sem o cabeçalho Authorization sai sem alteração e o Loom a recusa.
  • Um Secret ausente, ou um atespace sem a permissão (grant), faz o gateway recusar a requisição.
  • A URL http:// e a regra deste guia exigem o chart sem tls.secretName, que faz a porta responder somente em HTTPS. Nesse caso, o chart serve HTTP dentro do cluster, então, nesta regra, o token trafega sem criptografia do gateway até o Loom. Para criptografar esse trecho, aponte o agente para um endpoint TLS na frente do Loom cujo certificado seja publicamente confiável, como o host do Ingress do chart, e permita esse host com uma regra https. O gateway então intercepta o TLS do agente, de modo que o actor monta o pacote de confiança de egress do Substrate e aponta o cliente MCP para ele (SSL_CERT_FILE, NODE_EXTRA_CA_CERTS ou REQUESTS_CA_BUNDLE, conforme o runtime do cliente), e o Loom vê conexões vindas do ingress controller, e não de atenet-egress.

As regras para tudo o mais de que o agente precisa, como o provedor de modelo, ficam na mesma política. kubectl ate update egress-policy substitui todas as regras e recusa uma política cujos metadados não sejam os atuais. Por isso, leia a política com kubectl ate get egress-policy research-agent -a research -o yaml, adicione as regras ao lado da regra do Loom e envie esse arquivo de volta com kubectl ate update egress-policy ... -f.

Com a política aplicada, inicie o actor:

kubectl ate resume actor research-agent -a research

Vários agentes

  • Agentes em um mesmo namespace do Loom compartilham tudo o que escrevem. Um subagente que deve ler o namespace de uma equipe, mas escrever apenas no seu próprio, recebe um token com um papel por namespace (--namespace-role team=viewer --namespace-role research=writer; gerar um token).
  • Cada ator recebe seu próprio token, Secret e política de egress; um ator em outro atespace recebe o token namespace e a concessão próprios desse atespace (passo 2).
  • Repasse o trabalho entre agentes com a caixa de entrada de tarefas.

Relacionados