← Voltar ao início

Arquitetura

Agent Orchestration

Workspace auto-hospedado onde pessoas e agentes de IA trabalham juntos, com limite duro no que o agente consegue ver, gastar e fazer.

1. O problema

Você quer que agentes de IA façam trabalho de verdade: gastar dinheiro em chamada de modelo, rodar código, executar ação. Três coisas dão errado, e nenhuma delas é o modelo responder mal.

A chave da API vaza, porque foi parar no ambiente de um serviço que não precisava dela. O orçamento estoura, porque ninguém sabe o custo de uma chamada antes de ela terminar. E o agente executa uma ação irreversível que ninguém autorizou, porque o texto que a pessoa leu antes de aprovar foi escrito pelo próprio modelo.

O problema de engenharia não é fazer o agente funcionar. É garantir que ele não consiga fazer essas três coisas, mesmo que o modelo seja conduzido por texto injetado e mesmo que um dos serviços seja comprometido.

2. Os números

Contados no repositório. A suíte de ataques e os testes rodam no CI a cada push.

20.152
linhas de Rust em 6 crates: gateway 6.950, server 6.448, engine 3.711, bench 1.558, sandbox 1.197, protocol 288
135
testes em Rust
7
ataques nomeados, cada um com teste que precisa passar
18
triggers de auditoria escritos no banco
13
migrations
3
papéis do Postgres, um por serviço. O sandbox não tem nenhum
3
níveis de limite de gasto: workspace por mês, agente por mês e tarefa
127.0.0.1
endereço onde todos os serviços escutam

3. O desenho

O desenho é sobre fronteira de confiança: onde a chave vive, quem nunca a recebe, e o que o modelo não tem permissão de escrever.

127.0.0.1 — tudo localWebNext.jsServercontas, sessões, papéisEngineexecuções, ferramentas, aprovaçõesSandboxsem rede · sem bancorun_pythonpedido sem chaveGatewaycofre: a chave vive só aquiPostgreSQL3 papéis, um por serviço · 18 triggers de auditoriacom a chaveProvedoresAnthropic · OpenAI · Gemini

A chave do provedor cruza a fronteira externa em um único ponto, saindo do gateway. Engine, sandbox e web nunca a recebem, e se recusam a iniciar se encontrarem uma no próprio ambiente. O sandbox é o serviço com menos privilégio do sistema: sem rede e sem papel no banco.

Os sete ataques, e o que barra cada um

O THREAT_MODEL.md descreve o modelo. O ATTACKS.md nomeia cada ataque, e todo ataque nomeado tem um teste que precisa passar antes do merge.

Ataque 01

Ler a chave do provedor

O que barra

A chave vive cifrada no cofre do gateway. Engine, sandbox e web nunca recebem chave nenhuma, e se recusam a iniciar se acharem uma no ambiente.

Ataque 02

Gastar mais do que o permitido

O que barra

Cada chamada reserva o custo máximo antes de começar. Sem saldo reservado, a chamada não acontece.

Ataque 03

Sair da pasta permitida

O que barra

O sandbox roda em container somente leitura, sem capabilities, com limite de memória, CPU, processos e tempo.

Ataque 04

Alcançar endereços não permitidos

O que barra

O sandbox não tem rede.

Ataque 05

Agir sem permissão, ou ser conduzido por texto injetado

O que barra

Ferramenta marcada como irreversível para a tarefa e espera uma pessoa. O texto que explica o que vai acontecer é escrito pelo desenvolvedor na definição da ferramenta, nunca pelo modelo.

Ataque 06

Se passar por alguém ou roubar uma sessão

O que barra

Cookies __Host- com Secure, HttpOnly e SameSite Strict, verificados pelo servidor em Rust a cada requisição, sob CSP estrita com nonce por requisição.

Ataque 07

Adulterar registros

O que barra

Log append-only encadeado por hash, escrito por trigger do banco. Alterar ou apagar quebra a cadeia.

4. As decisões

Toda decisão tem preço. Abaixo está o que escolhi, o que descartei, por quê, e o que isso custa.

01. Reservar o custo máximo antes da chamada

Escolhi
Cada chamada de modelo reserva o custo máximo possível antes de começar. Tarefa sem saldo para reservar para e espera um administrador.
Em vez de
Medir o gasto depois que a resposta volta.
Porque
O custo de uma chamada só é conhecido quando ela termina, e aí o dinheiro já saiu. Medir depois detecta o estouro, não impede. Reservando o máximo antes, estourar o limite deixa de ser possível por construção, não por vigilância.
Preço que pago
O orçamento fica subutilizado. Uma tarefa pode ser interrompida com saldo real sobrando, porque a reserva assumiu o pior caso e a resposta real custou menos.

02. O texto da aprovação é escrito pelo desenvolvedor, nunca pelo modelo

Escolhi
O que vai acontecer está na definição da ferramenta, escrito à mão por quem a implementou. A pessoa aprova lendo esse texto.
Em vez de
Deixar o modelo explicar o que está prestes a fazer.
Porque
Se o modelo escreve a explicação, um modelo conduzido por texto injetado escreve uma explicação tranquilizadora. A pessoa aprova uma mentira e a culpa cai nela. Tirar essa caneta do modelo é o que faz a aprovação humana valer alguma coisa.
Preço que pago
Toda ferramenta nova precisa do texto escrito à mão, e o agente não consegue criar ferramenta por conta própria. A flexibilidade some de propósito.

03. Auditoria por trigger do banco, não pelo código

Escolhi
18 triggers escrevem toda mudança no log, independente de quem fez a escrita.
Em vez de
Registrar o evento no código do serviço.
Porque
Log em nível de aplicação é contornável: um bug, uma conexão direta no banco, um serviço futuro que esqueça de chamar. O trigger dispara de qualquer jeito. A garantia deixa de depender de disciplina.
Preço que pago
Lógica em SQL, mais difícil de testar e de mudar, e migrations mais pesadas. Toda tabela nova precisa do trigger junto, senão o buraco é silencioso.

04. Log append-only encadeado por hash

Escolhi
Cada registro carrega o hash do anterior. Nada é atualizado nem apagado.
Em vez de
Uma tabela normal com carimbo de tempo.
Porque
Tabela comum pode ser editada por qualquer um com permissão de escrita, e depois não dá para provar que não foi. Encadeando, qualquer edição ou remoção quebra a cadeia e fica detectável.
Preço que pago
Não dá para apagar nada, inclusive o que entrou por engano. Pedido de remoção de dado pessoal deixa de ser uma consulta e vira um problema de projeto.

05. Serviço se recusa a iniciar se achar chave de provedor no ambiente

Escolhi
Engine, sandbox e web verificam o próprio ambiente no boot e falham se encontrarem uma chave.
Em vez de
Simplesmente não ler a variável.
Porque
O caso perigoso não é código que lê a chave. É um deploy que passa a chave para todo mundo sem querer. Falhar fechado transforma uma configuração errada silenciosa em erro barulhento de inicialização.
Preço que pago
Ambiente compartilhado legítimo quebra, e o desenvolvimento local exige cuidado para não derrubar o próprio serviço sem entender o motivo.

06. Um papel do Postgres por serviço, com os grants que o código usa

Escolhi
ao_gateway, ao_server e ao_engine, cada um com suas permissões, verificadas por teste. O sandbox não tem papel nenhum.
Em vez de
Uma string de conexão para todos os serviços.
Porque
Se o sandbox for comprometido, ele não pode ler a tabela de contas. Como ele nem conexão tem, essa classe de ataque some em vez de ser mitigada.
Preço que pago
Migration tem que manter os grants. Uma consulta nova falha em teste até o grant ser adicionado, o que é exatamente o objetivo, mas atrasa o trabalho.

07. Provedor falso e banco descartável para o teste de ponta a ponta

Escolhi
Um provedor mock e um banco separado, para a pilha inteira subir e ser testada sem custo e sem tocar no banco de desenvolvimento.
Em vez de
Testar de ponta a ponta contra o provedor real.
Porque
Teste de ponta a ponta contra provedor real custa dinheiro a cada execução e não é determinístico, então ninguém roda com a frequência necessária. Teste que ninguém roda não protege nada.
Preço que pago
O mock não entende texto. O teste prova encanamento, permissão e fluxo de aprovação, e não prova nada sobre comportamento do modelo.

5. O que quebra

Incluindo o que está mal resolvido hoje. O próprio README diz que o sistema ainda não está pronto para produção.

A reserva é uma estimativa de pior caso

Ela depende de uma tabela de custo máximo por modelo. Se o provedor muda preço, ou entra um modelo com custo de token diferente, a reserva fica errada nos dois sentidos: ou segura orçamento demais e para tarefa à toa, ou segura de menos e a garantia deixa de valer. Hoje nada verifica se a tabela ainda bate com a realidade.

Tarefa parada por orçamento espera para sempre

Ela aguarda um administrador. Se ninguém estiver olhando, ela simplesmente fica ali. Não existe prazo, escalonamento, nem comportamento padrão depois de um tempo.

Aprovação tem o mesmo problema, e é pior

Uma ação irreversível aguardando decisão segura a execução inteira, e a execução parada continua com orçamento reservado. Quanto mais tempo ninguém decide, mais saldo fica preso sem nada acontecer.

A cadeia de hash prova adulteração, mas ninguém confere

O encadeamento torna qualquer edição detectável. Detectável não é detectada: nada verifica a cadeia de forma contínua. Uma quebra só aparece quando alguém resolve olhar, que normalmente é tarde demais.

Sandbox sem rede fecha a fuga e fecha o uso

Não ter rede elimina a principal via de escape, e também impede qualquer tarefa legítima que precise da internet. Essa tensão não está resolvida: hoje a escolha é segurança total com capacidade reduzida.

Tudo em 127.0.0.1

É a decisão certa para uso auto-hospedado numa máquina, e deixa em aberto como um time em máquinas diferentes usaria isso. A história de implantação para mais de uma pessoa ainda não foi desenhada.

6. O que eu mudaria em 100x

Cenário: 100 agentes rodando ao mesmo tempo, milhares de tarefas por dia e vários workspaces na mesma instalação.

O que sobrevive sem mudar nada

As fronteiras de confiança. A chave continua saindo apenas do gateway, os papéis por serviço continuam valendo e o sandbox continua sem rede e sem banco, independente do volume. Segurança desenhada por fronteira não se degrada com escala.

O que quebra primeiro

O worker único do engine, que processa pedidos em sequência. Com 100 agentes, a fila cresce mais rápido do que ele consome, e tudo passa a esperar por um processo só.

Na ordem em que eu mudaria

  1. 1

    Vários workers pegando tarefa com SELECT FOR UPDATE SKIP LOCKED. O desenho de fila em Postgres já permite isso, então é mudança no laço do worker e não no modelo de dados.

  2. 2

    Resolver a disputa na reserva de orçamento. Toda chamada do mesmo workspace tranca a mesma linha, e com 100 agentes isso vira o novo gargalo. Reserva por agente em linhas separadas, com consolidação periódica, tira a disputa do caminho quente.

  3. 3

    Particionar o log de auditoria. Dezoito triggers em cada escrita multiplicam a gravação, e em volume o log vira a tabela mais pesada do banco. Partição por mês, com as antigas movidas para fora, mantendo o hash da cadeia.

  4. 4

    Dar política para as aprovações: prazo, escalonamento e comportamento padrão ao expirar. Sem isso, cada ação irreversível esquecida é uma execução parada segurando orçamento reservado, e em escala isso trava o sistema inteiro sem nenhum erro aparecer.

Esta página descreve o sistema como ele está hoje, incluindo o que ainda não está resolvido. As fases 1 a 4 estão concluídas e o projeto não está pronto para produção.