O guia do usuário da Stalwart¶

Este guia é para dois tipos de leitor: quem constrói agentes de IA com a Stalwart, e quem responde pelo que esses agentes fazem, como uma equipe de segurança, de risco ou de compliance. Ele explica o que cada produto do Stalwart Agents faz, como usá-lo e, tão importante quanto, onde termina cada uma das suas garantias.

O guardrail¶

O guardrail verifica cada chamada de ferramenta que um agente de LLM faz antes de ela rodar, seja qual for o framework em que o agente foi construído, e responde permitir, perguntar à pessoa ou recusar, citando a regra. Nada nele é adivinhado por um modelo de linguagem.

Saiba mais

Os produtos para desenvolvedores¶

Para equipes que constroem agentes de IA, uma chave de API dá mais seis produtos. O guia os chama pelos mesmos nomes que o site e a referência da API, com o nome em inglês entre parênteses, porque é o que você vai encontrar no código, nas chaves e nas conversas com o suporte.

• O Construtor de Bots (Bot Builder) constrói um agente de IA seu a partir das ferramentas que a sua empresa já tem. Você descreve o agente num único arquivo, e as suas regras são verificadas a cada chamada de ferramenta antes de ela rodar.
• A Verificação de Grafos de Agentes (Agent Graph Verification) verifica cada caminho de um agente, ou de uma equipe de agentes, antes de ele entrar no ar. Ela relata cada caminho que chega a uma ferramenta sem a verificação pela qual deveria passar, sem a confirmação que deveria pedir ou sem o passo que deveria vir antes.
• O Caçador de Bugs em Guardrails (Guardrail Bug Hunter) encontra cada caminho pelos seus guardrails até uma ação que eles deveriam impedir. Ele mostra cada um acontecendo e entrega uma correção que já testou varrendo de novo.
• A Verificação de Guardrails (Guardrail Verification) responde se uma ação pode acontecer sem a condição que deveria protegê-la, para uma pergunta ou uma tabela inteira delas. Se pode, você recebe um exemplo de como e um reparo; se não pode, recebe um certificado que prova isso.
• A Escrita de Guardrails (Guardrail Writing) transforma uma regra escrita em palavras simples numa política de guardrails. O seu próprio modelo escreve o rascunho; a Stalwart então o verifica e o corrige onde ele erra.
• A Verificação de Random Forests (Random Forest Verification) verifica um modelo de random forest treinado quanto a robustez, monotonicidade, equidade e alcançabilidade. Ela também pode partir de registros reais e procurar a menor mudança que inverteria uma decisão.

Um agente, num único arquivo¶

Você não precisa aprender um framework de agentes para usar nada disso. Uma equipe põe os produtos para trabalhar por meio de um único agente, descrito num arquivo: as suas ferramentas, as suas regras e quais mudanças desfazem quais. Antes de o agente rodar, cada caminho por ele é verificado. Enquanto ele roda, cada mensagem é lida e cada chamada de ferramenta é verificada, na sua própria máquina. E se uma execução falhar no meio, as suas mudanças são desfeitas, da última para a primeira. Este é o agente da loja que o guia usa em toda a Parte I:

# A central de atendimento da loja, e a central de cobrança para onde ela passa os estornos.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # o seu provedor; a chave vem do seu ambiente
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # um turno que nenhuma ferramenta cobre é recusado, com o motivo
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # cada função pública de shop/tools.py
rulebook: ./policy.co                      # as regras contra as quais cada chamada é verificada
facts:                                     # o que são o $card_on_file e o $order_paid do rulebook
  card_on_file: {from: get_order.card, same: order_id}           # lido da resposta de get_order
  order_paid: {from: get_order.status == paid, same: order_id}   # para o pedido que a chamada cita
runs: atomic                               # uma execução que falha é desfeita, da última escrita para trás
storage: sqlite:///runs.db                 # onde ficam as execuções e as confirmações pendentes

A Parte I o constrói passo a passo, usando só as palavras do arquivo acima.

Por onde começar¶

• Se você só ler uma página: o guia inteiro, resumido numa única página.
• Início rápido: cerca de quinze minutos, só no console, sem chave e sem terminal. Você começa um bot a partir de um modelo, experimenta e o roda no seu próprio computador.
• Início rápido para desenvolvedores: cerca de meia hora. Você cria uma conta, monta o bot de atendimento de uma pequena loja, confere que ele não pode ser mal usado, conversa com ele, varre uma política de guardrails atrás de brechas e confere você mesmo uma prova.
• O que este serviço faz, e o que ele não afirma: o capítulo 1. Leia a segunda metade dele antes de citar um resultado para alguém.

O guia tem cinco partes: o Construtor de Bots, o seletor do Construtor de Bots, o Caçador de Bugs em Guardrails, o caçador e o seletor juntos e verificação e escrita. Se você trabalha com governança ou segurança, o capítulo 39 é para você: ele mostra o que cada produto cobre nas listas Top 10 da OWASP de 2026 e no NIST AI Risk Management Framework, e o que uma correspondência dessas não quer dizer. O apêndice reúne as tabelas de referência, o glossário e o registro de mudanças.

Conferindo o nosso trabalho sem nós¶

Você não precisa confiar em nós para confiar num resultado. Um certificado pode ser conferido sem chave, sem rede e sem nenhum software nosso. A especificação do certificado explica como lê-lo, o verificador de referência é um único arquivo que você consegue ler numa tarde, e o corpus de certificados lhe dá certificados reais para testá-lo.

O guia offline. O guia inteiro num único arquivo, para ler sem rede ou para guardar num arquivo de auditoria: Inglês · Português.

O SHA-256 de cada arquivo está em SHA256SUMS, para que uma cópia possa ser conferida com a publicada aqui. Os links que saem do guia -- a referência da API, o site -- precisam da rede, e dizem isso; o guia offline não tem busca.

Em outros lugares¶

• stalwart.it: os produtos, os planos e onde registrar seu interesse.
• A referência da API: cada operação, e você pode testar cada uma com a sua própria chave.
• A documentação do pacote: o pacote stalwart-agents, página por página, com a sua referência Python.

Os números dos capítulos nunca mudam, mesmo quando um capítulo vai para outra página, então um arquivo de auditoria que cita o capítulo 7 sempre aponta para o mesmo capítulo.

Se você só ler uma página¶

Esta página conta, em poucos minutos, o que a Stalwart faz. Cada ponto aponta para o capítulo que o explica por inteiro, para você se aprofundar onde precisar.

Para desenvolvedores¶

A Stalwart também tem ferramentas para equipes que constroem agentes de IA, acessadas com uma chave de API:

• O Construtor de Bots (Bot Builder) constrói um agente seu a partir de ferramentas que você já tem: funções Python, servidores MCP, operações OpenAPI, ferramentas LangChain ou um projeto TypeScript, descrito num único arquivo agent.yaml (capítulo 30). Cada chamada de ferramenta que ele faz é verificada contra as suas regras: allow (permitir), confirm (confirmar) ou refuse (recusar) (capítulo 32).
• O Guardrail verifica cada chamada de ferramenta que um agente de LLM faz antes de ela rodar: a sua lista de ferramentas, os argumentos delas, as suas regras, o que a conversa já fez e se cada valor numa escrita foi mesmo dito. Ele responde permitir, perguntar à pessoa ou recusar, citando a regra. Funciona sozinho, na frente de ferramentas MCP pelo stalwart gateway, ou dentro de um guard do Guardrails AI, e um servidor MCP deixa você perguntar o que ele verifica e medi-lo nos seus próprios traces (o guardrail). A mesma verificação protege as chamadas de qualquer agente de LLM, não só dos agentes construídos aqui.
• A Verificação de Grafos de Agentes (Agent Graph Verification) relata qualquer caminho por um agente que chegue a uma ferramenta sem a verificação pela qual deveria passar, antes de o agente rodar (capítulo 47).
• O Caçador de Bugs em Guardrails (Guardrail Bug Hunter) procura, nas regras de guardrail que você já roda, cada caminho até uma ação que elas deveriam impedir (capítulo 28).
• A Verificação de Guardrails (Guardrail Verification) prova que uma ação não pode acontecer sem a condição que deveria protegê-la, ou mostra como pode (capítulos 3 a 12); a Escrita de Guardrails (Guardrail Writing) transforma uma regra em palavras simples numa política verificada (capítulo 13); a Verificação de Random Forests (Random Forest Verification) verifica um random forest treinado contra propriedades que você declara (capítulo 14).

O quickstart para desenvolvedores passa por elas em cerca de meia hora. Quando a Stalwart prova que algo não pode acontecer, ela entrega um certificado que você pode conferir sem chave, sem rede e sem nenhum software nosso: leia a especificação, ou rode o verificador de referência sobre os certificados reais do corpus.

A sua conta¶

Para começar, registre seu interesse em stalwart.it; nós respondemos com o seu acesso, e você então entra no console de desenvolvedores com o Google ou com um link que enviamos por e-mail. O capítulo 40 diz o que cada plano inclui, e o capítulo 16 diz o que guardamos, por quanto tempo, e o que nunca guardamos.

Início rápido¶

Esta página leva cerca de quinze minutos. No fim dela, você vai ter uma conta na Stalwart e um bot para um pequeno restaurante, que responde aos clientes sobre o cardápio, anota os pedidos e reserva as mesas. Você vai ter conversado com ele, e ele vai estar rodando no seu próprio computador. Você não precisa de chave, nem de código, nem de terminal: a única coisa que você digita fora do navegador é uma linha que copia no final.

Quando um passo precisa do console, uma imagem da página do console vem logo em seguida, com a parte que importa circulada.

Cadastre-se¶

Registre seu interesse em stalwart.it; quando respondermos, entre no console com a sua conta do Google ou com um link que enviamos por email. Continuar aceita os termos e o adendo de tratamento de dados, que a página traz em links.

Seus bots¶

Na primeira vez que você entra, a sua organização é criada para você, no plano gratuito, com o nome do seu endereço de email; você pode mudá-lo em Conta. O console de desenvolvedores abre na sua Visão geral; os bots ficam em Construir: abra Seus bots. Cada um dos seus bots vai ser um cartão aqui; por enquanto não há nenhum, então clique em Começar de um bot pronto:

Comece a partir de um bot pronto¶

Um bot pronto já funciona: ele vem com as suas ferramentas, as suas regras e as suas respostas. Escolha Restaurantes e delivery e clique em Começar deste bot pronto:

É só isso: o seu bot é criado, com todas as ferramentas que o bot pronto traz, e abre. As regras dele já estão prontas: no plano gratuito, ele pergunta a você antes de escrever qualquer coisa, um pedido, uma reserva ou uma mudança no cardápio. Ele não usa nenhum modelo de IA: uma mensagem que ele não consegue ler recebe um educado não posso ajudar com isso, com o seu contato. No alto da página dele estão as duas coisas a fazer agora: rodá-lo no seu computador e conversar com ele.

Abaixo delas estão as configurações dele, para mudar quando quiser: o nome, a língua em que os seus clientes escrevem, como falar com você (o seu bot passa isso para quem ele não puder ajudar), uma saudação e o seu logotipo. Em Quando seu bot não entende você pode deixar um modelo de IA responder o que ele não consegue ler, com a sua própria chave do seu provedor de IA, que você coloca no seu computador quando o bot roda lá: a Stalwart nunca a vê. Os dados de uma pessoa só chegam a um modelo no plano Enterprise. Para definir as configurações do próprio bot pronto antes de o bot ser criado, clique em Mudar as configurações antes.

Converse com o seu bot¶

Em Conversa, você conversa com o seu bot aqui, com as ferramentas de verdade dele e nada para instalar. Clique em Começar a conversar e pergunte algo, como o que tem no cardápio? ou 2 pizzas margherita para o Rui, para retirar às 19h. Quando ele vai mudar alguma coisa, como anotar esse pedido, ele pergunta antes. As suas conversas ficam guardadas com o bot, à direita, para ler de novo ou apagar. Para conversar com respostas de exemplo, sem ler ou escrever nada de verdade, marque Praticar com respostas de exemplo antes de começar.

Em Conversar como, você começa como Você, o dono; escolha Um dos seus clientes para ver o que eles veem. Os seus clientes podem perguntar sobre o cardápio, pedir e reservar; o que é para você e a sua equipe, como mudar o cardápio, eles nunca alcançam: o bot diz não, com o seu contato.

Execute no seu computador¶

Faça isto no computador onde o seu bot vai rodar. Veja como é no Windows; num Mac é igual, com o Terminal no lugar do PowerShell.

1. Abra o seu bot em Seus bots. Em Seu computador, escolha Windows e clique em Executar no meu computador. O console mostra a linha para colar:

   

2. Clique em Copiar para a área de transferência. O botão passa a dizer Copiada para a área de transferência: a linha está copiada, como se você a tivesse selecionado e apertado Ctrl e C.

   

   Se o seu navegador não deixar a página copiar, o console seleciona a linha para você e avisa: aperte Ctrl e C para copiá-la.

3. Abra o PowerShell: aperte a tecla Windows, digite PowerShell e aperte Enter. Abre uma janela com uma linha que começa com PS C:\Users\ e o seu nome.

4. Cole a linha: aperte Ctrl e V, ou clique com o botão direito na janela. A linha inteira aparece depois do PS, terminando em | iex:

   

5. Aperte Enter. O PowerShell diz Setting up your bot. This takes a minute or two. (ele escreve em inglês) e mostra uma barra enquanto baixa o que o seu bot usa para ler. Quando termina, diz Your bot ... is running. Its chat: com um endereço, e Its files: com a pasta do seu bot, e o chat abre no seu navegador. Aí você pode fechar a janela do PowerShell: o seu bot continua rodando.

Se algo der errado, o PowerShell avisa numa linha que começa com Stalwart:, como num computador sem internet; resolva isso e cole a mesma linha de novo.

A linha funciona por sete dias, quantas vezes você a rodar, até você clicar em Uma nova linha, que faz a antiga parar de funcionar. Ela instala o que o seu bot precisa, com uma chave feita para ele que você nunca vê, inicia o bot e abre o chat dele no seu navegador. O bot inicia de novo cada vez que você entra no seu computador, e acompanha o que você salva no console: uma nova versão chega a ele em até quinze minutos, e uma que retira alguma coisa espera até você clicar em Usar a nova versão no chat dele.

O seu bot guarda os arquivos dele numa pasta só dele, em Documentos, Stalwart, com o nome dele: o cardápio e os pedidos em Menu.csv e Orders.csv, que abrem no Excel ou no Numbers, e as reservas em bookings.csv. Mude um preço ou marque um prato como esgotado no arquivo, ou peça ao bot para fazer isso por você.

O chat do seu bot¶

O chat mostra o nome do seu bot, a saudação dele e o seu logotipo. Em O que eu posso fazer, ele lista o que a pessoa pode pedir, agrupado por tarefa: o nome de cada ferramenta em negrito, o que ela faz e um exemplo para experimentar. Quem escrever ajuda recebe a mesma lista. Os seus clientes veem as ferramentas deles; você e a sua equipe veem as suas.

No seu computador, o chat também mostra a você:

• Seus arquivos: o que o seu bot salvou na pasta dele, do mais novo ao mais antigo, cada um para abrir ou baixar. Quando uma resposta salva um arquivo, a resposta traz o link.
• Seu bot precisa da sua chave de IA, quando o seu bot pergunta antes ou deixa um modelo de IA responder: cole a chave que o seu provedor de IA deu a você. Ela fica só neste computador, e o seu bot reinicia com ela.
• Use no seu celular: clique em Mostrar o código e leia-o com a câmera do celular, na mesma rede Wi-Fi do seu computador. O celular avisa que a conexão não é particular, porque o seu bot fez o próprio certificado; confira se a impressão digital começa como a página daqui diz e continue. O seu celular fica então conectado como você. O Windows pode perguntar se o seu bot pode usar a rede: permita nas redes particulares.

Próximos passos¶

• Para saber o que cada parte do seu bot faz, leia o Guia do usuário.
• Para montar um bot em código, verificá-lo e usar os outros produtos, siga o Início rápido para desenvolvedores.

O guardrail¶

O guardrail verifica cada chamada de ferramenta que um agente de LLM faz antes de ela rodar, e responde permitir, perguntar à pessoa ou recusar, citando a regra que decidiu. Ele funciona com qualquer agente: dê a ele as ferramentas que você dá ao seu modelo, e ele verifica cada chamada que o modelo propõe.

Nada nele é adivinhado por um modelo de linguagem: a mesma chamada e as mesmas regras sempre dão a mesma resposta.

Garantido:

• Toda chamada de ferramenta é verificada antes de ser executada, pelas mesmas regras, e a mesma chamada, contexto e regras sempre dão a mesma resposta.
• Uma ferramenta fora da sua lista nunca é executada; uma chamada cujos valores quebram a descrição da própria ferramenta nunca é executada.
• Uma escrita que nenhuma regra permitiu nunca é executada sem o sim de uma pessoa, e esse sim cobre exatamente a chamada mostrada.
• Um valor numa escrita que ninguém disse e nenhuma ferramenta devolveu é perguntado.
• Nada numa decisão é adivinhado por um modelo de linguagem.

Não garantido:

• Ele julga ferramentas, argumentos, rótulos, histórico e regras, não o que uma resposta quer dizer.
• Ele não distingue um valor certo de um errado que alguém de fato disse.
• Suas regras são tão completas quanto você as escreveu: o caçador de falhas procura brechas.
• Uma ferramenta cujo nome e descrição escondem o que ela faz pode ser classificada errado: marque-a.
• Chamadas feitas fora do guardrail não são verificadas.

Os passos abaixo seguem um atendimento ao cliente, com quatro ferramentas: consultar um pedido, reembolsar um cartão, enviar um e-mail e salvar uma nota. Os números de cada imagem correspondem aos passos numerados abaixo dela, e cada linha de uma imagem foi impressa pelo próprio guardrail.

O que cada verificação faz¶

Todas as regras do guardrail, na ordem em que são aplicadas; decide a primeira que se aplica.

1. Coloque o guardrail na frente das suas ferramentas¶

1. Em Python, três linhas: o guardrail é criado a partir das ferramentas que você dá ao seu modelo, e cada chamada é verificada antes de o seu código executá-la. Instale com pip install stalwart-agents.
2. Na frente de um servidor MCP, o stalwart gateway verifica cada chamada a caminho do servidor. A ferramenta snippet do stalwart mcp escreve a configuração para você.

2. Escreva as suas regras¶

1. As suas regras são uma planilha de regras: YAML simples que uma pessoa consegue ler em voz alta. Aqui, um reembolso acima de 100 precisa da aprovação de um gerente, e todo e-mail espera o sim de uma pessoa.
2. A planilha é compilada uma vez; as decisões são tomadas depois na sua própria máquina.
3. A planilha é conferida contra as suas ferramentas: aqui, save_note altera algo e nenhuma regra a nomeia, então você é avisado e pode decidir.

3. Uma chamada é permitida, perguntada ou recusada¶

1. Consultar um pedido só lê, então é permitido.
2. Um reembolso de 20 altera algo e nenhuma regra o permite de vez, então espera o sim de uma pessoa.
3. Um reembolso de 150 quebra a regra do passo 2, então é recusado, e a resposta cita a regra e dá um id para consultá-la.

4. Um valor que ninguém disse é perguntado¶

1. A pessoa pediu um reembolso mas nunca disse quanto. O modelo propôs 35 mesmo assim.
2. Ninguém disse 35 e nenhuma ferramenta o devolveu, então o guardrail pergunta à pessoa antes de qualquer coisa rodar. Ele nunca preenche um valor, e nunca altera a chamada.

5. Adicione ao seu guard do Guardrails AI¶

1. Instale stalwart-agents[guardrails] e acrescente o nosso validador ao seu guard. Uma chamada recusada chega como a própria falha do Guardrails AI, com a frase da regra.
2. Com on_fail=gai.ask, uma chamada que precisa de uma pessoa é retida, e gai.asked(guard) dá a frase para mostrar a ela. Com o sim, valide a mesma chamada de novo com o token que gai.approve dá.

6. Pergunte ao servidor MCP o que ele faz¶

1. Acrescente o stalwart mcp ao seu assistente de IA (Claude Code, Cursor, VS Code) e pergunte o que o guardrail consegue verificar: ele responde a partir da própria lista do guardrail.
2. Peça a ele para construir um guardrail para as suas ferramentas: o prompt build-guardrail conduz o seu assistente com você, e o prompt assurance-plan pelo resto da suíte -- a caça, o red team, as provas.

O capítulo 53 é o servidor por inteiro: como adicioná-lo, as ferramentas e os prompts dele, e onde os resultados aparecem no console para desenvolvedores.

7. Meça nas suas próprias chamadas¶

1. replay passa as chamadas antigas do seu agente pelo guardrail: quantas ele teria permitido, perguntado e recusado, por qual regra, e se uma segunda execução deu as mesmas respostas.
2. Rotule cada chamada com o que deveria ter acontecido, e evaluate conta os alarmes falsos (chamadas que deveriam rodar, barradas) e as falhas (chamadas que deveriam ser barradas, deixadas passar).

8. Procure brechas nas suas regras¶

1. hunt roda o caçador de falhas na sua planilha de regras. Cada achado é algo que as suas regras deixam passar, com o que olhar; aqui, ele pede que você diga sem o que refund_card nunca pode rodar, já que nenhuma tabela sua o diz.

9. Por que esta chamada foi recusada?¶

1. explain_decision lê de volta uma decisão pelo seu id: a regra, o que ela leu, a ferramenta e os nomes dos seus argumentos. Os valores em si, e o que a pessoa disse, nunca são guardados.

Para ir além¶

O manual completo, em inglês e português, está na documentação do SDK: construindo um guardrail, as verificações, a planilha de regras, avaliando e conectando. O stalwart mcp serve as mesmas páginas ao seu assistente.

53 · O servidor MCP¶

O stalwart mcp dá ao seu assistente de programação com IA -- Claude Code, Cursor, VS Code -- toda a suíte como ferramentas: o guardrail, construído com você e ensaiado nas suas próprias chamadas; o gateway; o caçador de falhas; o red team; a verificação formal das suas regras e do grafo de um agente; e os certificados, conferidos na sua máquina. O seu assistente faz cada passo pelo servidor e traz o resultado para você, com a página do console para desenvolvedores que o mostra e o capítulo deste guia que o explica.

O servidor roda na sua máquina, por stdio. Ele chama o serviço da Stalwart só onde um passo já chama -- compilar uma planilha de regras, uma caça, um red team, uma prova --, e nunca chama um modelo: onde um passo precisa de um, como rascunhar uma planilha de regras a partir da sua política, o seu próprio assistente o faz, por um prompt, e o servidor confere o que ele fez.

Adicionando ao seu assistente¶

Na pasta do seu projeto:

$ stalwart mcp --config claude      # imprime: claude mcp add stalwart -e STALWART_MCP_HOME=<esta pasta> -e QLS_API_KEY=<a sua chave> -- ...
$ stalwart mcp --config cursor      # a entrada mcpServers para o Cursor
$ stalwart mcp --config vscode      # a entrada servers para o VS Code

Rode-o na pasta do seu projeto: a configuração nomeia essa pasta (STALWART_MCP_HOME), então os arquivos do servidor vão para ela, nunca para a pasta pessoal em que um cliente inicia servidores. Ponha a sua chave na configuração também: um servidor lê o seu ambiente uma vez, ao começar, então uma chave definida depois exige iniciar o servidor de novo (o status diz isso).

Depois peça ao seu assistente para chamar o status: ele responde com a pasta em que o servidor trabalha, se ele tem a sua chave, o seu plano e quanto resta de cada medidor neste mês.

Como ele conduz o seu assistente¶

Um assistente usa o que um servidor mostra a ele, então o servidor mostra tudo e diz para onde ir depois:

• As instruções dele, que o seu assistente lê primeiro, nomeiam cada produto e a ferramenta de cada um, e dizem ao assistente para fazer cada passo por essas ferramentas, e não escrevendo código nem lendo o código-fonte do pacote.
• Toda resposta diz o que vem depois (next): o que o passo não cobriu e a ferramenta que cobre. Depois de uma caça que não encontrou nada, por exemplo, ela diz o que a caça não leu, e que o verify_rules prova uma ação contra as suas regras.
• Toda resposta que leva a uma página dá o endereço dela: console para a página do console para desenvolvedores que mostra o resultado, guide para o capítulo deste guia sobre o passo. O links dá todos os endereços de uma vez (abaixo).
• O prompt assurance-plan conduz o seu assistente por cada nível em ordem, diz o que cada um cobre e o que usa do seu plano, e pergunta quais você quer.

Uma sessão que começa do zero é assim: status; catalogue_from_server no servidor das suas ferramentas; writes_file, e os tipos que você confere; uma planilha de regras que o seu assistente rascunha a partir da sua política em palavras simples, e que você lê; compile_rules e lint_rules; check_sequence nas chamadas de uma conversa; hunt num projeto; e, onde você quer que fique provado, verify_rules no perfil proof e check_certificate no que ele escreveu.

As ferramentas dele¶

Perguntando o que ele faz¶

Construindo e ensaiando um guardrail¶

O check_call responde uma chamada sozinha. Regras de ordem (after), limites (at_most) e confirmações só aparecem ao longo de uma conversa, então teste-os com o check_sequence: cada chamada é respondida com o que as anteriores rodaram.

Medindo, caçando e fazendo red team¶

Provando¶

Os prompts dele¶

• assurance-plan: cada nível de garantia em ordem -- construir, ensaiar, caçar, red team, provar, certificar, acompanhar --, o que cada um cobre e não cobre e o que usa do seu plano; o seu assistente pergunta quais você quer e faz só esses.
• build-guardrail: a construção inteira, em ordem: ferramentas, tipos, uma planilha de regras rascunhada a partir da sua política em palavras simples, compilar e verificar, ensaios, busca e caça, o trecho de código. O seu assistente rascunha a planilha; você a lê antes de ela ser usada.
• classify-tools: o seu assistente propõe tipos para as ferramentas de que a dedução não tem certeza.
• set-up-guardrail: uma receita do how_to, seguida passo a passo.
• evaluate-guardrail: replay e evaluate nas suas chamadas, sem citar nada delas.

Os resultados no console para desenvolvedores¶

O que o servidor faz com o serviço fica listado no console para desenvolvedores, na sua organização:

• Findings: o hunt com um project (um nome; o projeto é criado na primeira vez) guarda a varredura nele, num branch e num commit quando você os informa. A resposta dá o endereço do projeto na página Findings e o de cada achado. Ali você aceita um achado com o motivo, ou o deixa para corrigir, e a próxima varredura do projeto lê as suas decisões (capítulo 28).
• Jobs: cada caça, red team e prova é um job, com o seu estado, o seu veredito e os seus arquivos, entre eles um certificado (capítulo 9).
• Usage: o que cada medidor usou neste mês contra o seu limite -- o status dá os mesmos números ao seu assistente (capítulo 16).

O links dá ao seu assistente todos os endereços: cada página do console para desenvolvedores com o que ela guarda, e onde entrar; o capítulo deste guia de cada produto; a referência da API, a documentação do pacote, o pacote e onde se cadastrar. links(about="findings") restringe cada lista ao que o nomeia. O capítulo 5 tem todas as páginas do console.

Uma prova, ou a palavra do solver¶

O verify_rules faz uma pergunta -- esta ação pode rodar sem esta condição? -- e a responde no perfil que você indica (capítulo 10):

• Sim vem com a testemunha: a conversa em que ela roda. Corrija a regra que ela atravessa, compile e pergunte de novo.
• Não, em proof ou patch, é uma prova derivada, com um certificado. O servidor o grava em certificates/, e o check_certificate o confere na sua máquina, offline, com o verificador que o pacote traz (capítulo 7).
• Não, em fast, é a palavra do solver, sem certificado. A resposta diz isso, e diz para perguntar de novo em proof para ter um.

Uma prova responde à pergunta feita, e a nenhuma outra (o que isto prova). O verify_graph prova o grafo de um agente antes de ele ir para produção (capítulo 47).

Os arquivos que ele lê e grava¶

Todo caminho fica dentro da pasta em que o servidor trabalha; um caminho que sairia dela é recusado.

Plano e cota¶

Caças, red teams e provas são do serviço e contam no seu plano; o status diz o que resta antes de o seu assistente começar uma, e uma prova no perfil proof é contada à parte (capítulo 16). Construir, ensaiar, reproduzir chamadas e conferir um certificado rodam na sua máquina, e não contam nada.

Os limites¶

• O servidor conduz o seu assistente; ele não o obriga a seguir. Um assistente que escreve o próprio código em vez disso ainda pode, e os resultados dele são dele.
• Um relatório traz nomes de ferramentas, nomes de regras, contagens, ids de decisão e digests, nunca um valor de argumento nem uma palavra que uma pessoa disse. Para ver a testemunha de um achado inteira, abra a página dele no console.
• O red team lê o servidor das suas ferramentas, não o roteamento próprio do seu agente: o verify_graph é o passo para isso.

Início rápido para desenvolvedores¶

Esta página é para desenvolvedores e leva cerca de meia hora; para montar um bot só no console, sem chave e sem terminal, comece pelo Início rápido. No fim dela, você vai ter uma conta na Stalwart e um bot de atendimento para uma pequena loja online. Vai ter conferido que o bot não consegue cobrar nem estornar um cartão sem as verificações que você deu a ele, vai ter lido toda mensagem que as palavras dele formam, e vai ter conversado com ele. Por último, vai varrer uma política de guardrails atrás de brechas, verificar um agente feito sem a Stalwart e receber uma prova que você mesmo pode conferir.

Você vai trabalhar em dois lugares: no seu terminal, onde roda os comandos e o Python desta página, e no console da Stalwart, no navegador, onde ficam a sua conta, as suas chaves e os resultados das suas verificações. Quando um passo precisa do console, ou deixa algo lá para você ver, uma imagem da página do console vem logo em seguida, com a parte que importa circulada.

Toda saída nesta página é exatamente o que o código acima dela imprimiu quando este guia foi montado; o que você vir ao rodá-lo deve ser igual.

O guardrail¶

O guardrail verifica cada chamada de ferramenta que um agente de LLM faz antes de ela rodar, seja qual for o framework em que o agente foi construído, e responde permitir, perguntar à pessoa ou recusar, citando a regra. Nada nele é adivinhado por um modelo de linguagem.

Saiba mais

A sua conta, e a primeira chave dela¶

Tudo começa com uma conta. Registre seu interesse em stalwart.it; quando respondermos, entre no console com a sua conta do Google ou com um link que enviamos por email; continuar aceita os termos e o adendo de tratamento de dados, que a página traz em links:

Na primeira vez que você entra, é só isso: a sua organização agora existe, no plano gratuito, com o nome do seu endereço de email até você mudá-lo em Conta, e o console de desenvolvedores abre na sua Visão geral. Esta página precisa de uma chave de API, então abra Chaves, diga para que é a chave e clique em Emitir uma chave. Esta é a única vez que você vai vê-la: guardamos só um hash dela, então ninguém, nem nós, consegue mostrá-la de novo. Copie-a agora para um lugar seguro:

Se você perdê-la, ou quiser uma chave separada para cada programa que usa a Stalwart, emita outra do mesmo jeito. A página lista cada chave pelo seu id público, um rótulo curto que distingue as suas chaves mas não serve no lugar da chave (capítulo 5):

Instalação, e as suas duas chaves¶

Agora instale o pacote, entregue a ele a sua chave e deixe esta máquina rodar os seus bots:

$ pip install "stalwart-agents[anthropic]"    # ou openai, google, mistral, ollama; ou nenhum, para não ter modelo
$ export QLS_API_KEY=qls_live_...
$ stalwart licence activate

QLS_API_KEY é a chave da Stalwart que você acabou de copiar. Não a confunda com a outra chave que você talvez tenha, a chave do seu modelo: essa vem do provedor do seu modelo, como a Anthropic, e fica no seu próprio ambiente, com o nome de costume do provedor, como ANTHROPIC_API_KEY. Você nunca a digita no nosso console (capítulo 5). O último comando, stalwart licence activate, registra esta máquina como uma em que os seus bots podem rodar (capítulo 38).

Um agente, o seu primeiro rascunho recusado¶

O bot que você vai montar é o atendimento de uma pequena loja. Ele consulta pedidos, cobra um cartão, envia um recibo e passa os estornos para uma central de cobrança separada. O bot inteiro cabe num arquivo: as ferramentas que ele pode usar, uma frase para cada uma dizendo o que ela faz, e a central de cobrança para onde ele passa os estornos (capítulo 30). Este é um primeiro rascunho:

# A central de atendimento da loja, e a central de cobrança para onde ela passa os estornos: o primeiro rascunho.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # o seu provedor; a chave vem do seu ambiente
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # um turno que nenhuma ferramenta cobre é recusado, com o motivo
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # cada função pública de shop/tools.py
rulebook: ./policy.co                      # as regras contra as quais cada chamada é verificada
facts:                                     # o que são o $card_on_file e o $order_paid do rulebook
  card_on_file: {from: get_order.card, same: order_id}           # lido da resposta de get_order
  order_paid: {from: get_order.status == paid, same: order_id}   # para o pedido que a chamada cita
runs: atomic                               # uma execução que falha é desfeita, da última escrita para trás
storage: sqlite:///runs.db                 # onde ficam as execuções e as confirmações pendentes

Ao lado dele fica um rulebook, que diz quando uma cobrança ou um estorno pode acontecer: um estorno, por exemplo, só para um pedido que foi pago. Imagine que um colega, com pressa, acrescentou mais uma regra para que um cliente que digita só estorna receba o estorno na hora:

# Acrescentado às pressas: um estorno, só pela intenção.
define user ask quick refund
  "só estorna"

define flow quick refund
  user ask quick refund
  bot execute_refund_card

Antes de este bot responder a um único cliente, verifique-o com stalwart verify. Isto é tudo o que ele faz, em ordem:

• Ele lê o arquivo do bot. Carrega o agent.yaml e monta o bot a partir dele: as duas centrais, as ferramentas delas e o rulebook que o arquivo nomeia.
• Ele lê o código das suas ferramentas, na sua máquina. Cada arquivo de código na pasta do bot, em Python, JavaScript, TypeScript ou Go, é lido atrás dos jeitos como um código vaza segredos ou chega aonde não devia: desligar a conferência de que um site é mesmo quem diz ser, gravar uma senha num log, ou mandar uma requisição para um endereço que um cliente digitou. Só a quantidade de problemas encontrados vai para a Stalwart; o seu código fica na sua máquina. Todo problema encontrado reprova a verificação.
• Ele compila o seu rulebook e faz o lint das suas ferramentas. O rulebook vira as verificações por que passa cada chamada de ferramenta enquanto o bot roda, compilado como o bot o compila ao começar, e os lints listam, como avisos, o que as suas ferramentas deixam de dizer. Nada do seu bot fica guardado no serviço da Stalwart.
• Ele procura em cada rota pelo bot. No serviço da Stalwart, ele segue cada caminho que uma conversa pode fazer pelas duas centrais, atrás de um que chegue a uma ferramenta sem a verificação dela, sem a confirmação que ela pede, ou antes do passo que deve vir antes dela.
• Ele imprime o que encontrou, e um veredito. Cada problema, o mais grave primeiro, e depois se o bot passa.

O jeito como ele termina diz a um script o que aconteceu: o status de saída 0 quer dizer que o bot passou, 1 que reprovou, 2 que o arquivo não pôde ser lido, e 3 que nada foi verificado. O capítulo 31 tem as opções, como --keep, para guardar numa pasta o que foi verificado, e --replay, para repetir cada problema encontrado com substitutos das suas ferramentas (o comando imprime em inglês):

$ stalwart verify agent.yaml
stalwart verify agent.yaml

Lints from the runtime (the rulebook's error stops the agent at its start; no other blocks it):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it
  rulebook_unsupported (error) on policy.co: line 30: tool action 'execute_refund_card' is registered from flow 'quick refund' as well as from 'refunds'; their guards merge as an OR, so the weaker route decides whether the side effect happens. Register a tool action from exactly one flow. The rulebook was not compiled.

Code checks: no finding in 8 file(s) (rules d656f9ab32d3).

Blocking: 2 findings that block this agent until fixed, or accepted with its reason:

QG002 Critical on execute_refund_card (policy.co:19)
  The policy gates 'execute_refund_card' on 'order_paid', and there is a way past it.
  OWASP LLM03:2026, ASI02:2026

QG005 High on execute_refund_card (policy.co:30)
  line 30: tool action 'execute_refund_card' is registered from flow 'quick refund' as well as from 'refunds'; their guards merge as an OR, so the weaker route decides whether the side effect happens. Register a tool action from exactly one flow.

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: failed. This agent is blocked by the 2 blocking findings above and the rulebook it could not start with. The warnings do not block it.
$ echo $?
1

Ele reprovou o rascunho, e diz por que três vezes. Agora o estorno pode ser disparado de dois lugares, a regra cuidadosa e a apressada, e a apressada não verifica nada: um cliente que digitasse só estorna seria estornado tendo pago ou não. O compilador recusa o rulebook na linha 30, onde a regra apressada dispara o estorno (rulebook_unsupported), então o bot nem começaria com ele; a busca encontra o estorno disparado de dois fluxos (QG005) e um caminho que passa por fora da verificação de que o pedido está pago (QG002). O comando terminou com o status 1, então um pipeline de build que o rodasse também pararia aqui (capítulo 46).

O rascunho corrigido, e verificado¶

A correção é ter uma única regra decidindo todo estorno. A frase apressada passa para a regra cuidadosa, então só estorna agora é tratado como qualquer outro pedido de estorno, e verificado do mesmo jeito:

# Um estorno rápido é um estorno: a sua frase entra em `ask refund`, e o único fluxo protegido decide.
define user ask refund
  "estorne o pedido 4411"
  "devolva o dinheiro do cliente"
  "só estorna"

define flow refunds
  user ask refund
  if $order_paid
    bot execute_refund_card
  else
    bot refuse

A busca também deu ao rascunho dois avisos, que não barram o bot. Duas linhas no agent.yaml os resolvem (capítulo 31). budget: limita quantas chamadas uma execução pode fazer, para o bot não andar em círculos (QG023). undo: none diz com honestidade que um estorno não tem volta, para nada fingir que o desfaz se uma execução falhar no meio (QG105). Este é o arquivo pronto. As últimas linhas dão ao bot um trabalho para fazer sozinho, que você vai ver mais abaixo:

# A central de atendimento da loja, e a central de cobrança para onde ela passa os estornos: corrigida, e com o
# trabalho da manhã.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # o seu provedor; a chave vem do seu ambiente
    tools: [get_order, list_orders, next_unpaid_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # um turno que nenhuma ferramenta cobre é recusado, com o motivo
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # cada função pública de shop/tools.py
  - {name: refund_card, undo: none}        # um estorno não é desfeito: uma execução que falha o deixa feito
rulebook: ./policy.co                      # as regras contra as quais cada chamada é verificada
facts:                                     # o que são o $card_on_file e o $order_paid do rulebook
  card_on_file: {from: get_order.card, same: order_id}           # lido da resposta de get_order
  order_paid: {from: get_order.status == paid, same: order_id}   # para o pedido que a chamada cita
budget: {max_steps: 20}                    # o máximo de chamadas que uma execução pode fazer
replies: {language: pt}                    # o bot conta o que fez em português
runs: atomic                               # uma execução que falha é desfeita, da última escrita para trás
storage: sqlite:///runs.db                 # onde ficam as execuções e as confirmações pendentes
job:
  title: Atendimento da loja
  purpose: responde aos clientes sobre os pedidos, e cobra os que não foram pagos
  manager: owner
  hours: {days: [mon, tue, wed, thu, fri], from: "09:00", to: "17:30", time_zone: America/Sao_Paulo}
tasks:
  charge_unpaid:
    title: Cobrar o pedido mais antigo não pago
    agent: desk
    tools: [next_unpaid_order, get_order, charge_card]   # a leitura antes, depois a única escrita
    starts_at: suggest                     # uma pessoa aprova cada execução em Hoje
    triggers: [weekday_mornings]
triggers:
  weekday_mornings: {kind: schedule, at: "09:00", days: [mon, tue, wed, thu, fri]}

Rode a verificação de novo:

$ stalwart verify agent.yaml
stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 8 file(s) (rules d656f9ab32d3).

No findings.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent.
$ echo $?
0

Leia de cima para baixo:

• Compiled the rulebook policy.co: as regras sob as quais o bot roda são as que esta execução verificou, compiladas como o bot as compila ao começar.
• Lints from the runtime: o que as suas ferramentas deixam de dizer. Nenhum deles impede o bot. Aqui eles dizem três coisas. Nada diz ao bot que mandar a mesma cobrança ou o mesmo estorno duas vezes resulta em um só, então, quando um falha sem dizer se passou, uma pessoa decide, em vez de o bot tentar de novo (not_retry_safe). Nada descreve o que as ferramentas respondem, então o bot não consegue relatar o resultado delas com as próprias palavras (without_result_schema). E a central de atendimento pode cobrar um cartão, mas só a central de cobrança pode estorná-lo, então uma execução no atendimento que falhe no meio não consegue desfazer a sua cobrança (out_of_reach). O capítulo 34 mostra a linha do agent.yaml que resolve cada um.
• Code checks: quantos dos seus arquivos foram lidos, sem problema em nenhum, e a versão das regras com que foram lidos.
• No findings: a busca não encontrou rota pelo bot até uma cobrança, um estorno ou um recibo sem a sua verificação, sem a confirmação que pede ou sem o passo que deve vir antes, até a profundidade em que procurou (capítulo 31).
• Rules with nothing to read: verificações que olham algo que você declara sobre as suas ferramentas, como um argumento que é executado como código ou uma ferramenta que lê registros confidenciais. Este bot não declara nada disso, então essas verificações não tiveram o que olhar, e a lista as nomeia (capítulo 31).
• Gate: o veredito. passed quer dizer que nada barra este bot, e o comando terminou com o status 0.

Nada do seu bot ficou guardado no serviço da Stalwart: as suas ferramentas e o seu rulebook são os arquivos da sua pasta. A busca em si rodou no serviço da Stalwart e aparece na página Jobs do console para desenvolvedores, que você vai ver no fim.

Cada jeito de um cliente dizer¶

A busca que você acabou de rodar segue rotas pelo bot. A checagem de frases testa as próprias mensagens: ela escreve toda mensagem que um cliente poderia mandar com as palavras que o bot conhece, e lê cada uma. Ela roda no serviço da Stalwart quando você entrega as ferramentas do bot ao caçador de bugs com client.hunt. Isto é o que ela faz:

• Ela junta as palavras do bot. São as palavras dos nomes e das descrições das suas ferramentas, os nomes do dia a dia em also_called, as palavras do seu vocabulário, os números, datas e endereços que as ferramentas recebem, e as palavrinhas que ligam uma frase, como não, e depois ou para. Qualquer outra palavra não quer dizer nada para o bot, então uma palavra inventada faz o papel de todas elas.
• Ela escreve toda mensagem que essas palavras formam, até um tamanho. Cada pedido tem até três palavras que nomeiam algo, como o que fazer, com o quê, e um valor como o número de um pedido. Uma mensagem tem até dois pedidos, e até um erro de digitação.
• Ela lê cada mensagem com o mesmo leitor que o seu bot roda, exatamente como leria a de um cliente, no idioma que a página Configurações do console define (mais abaixo).
• Ela confere cada leitura atrás de três erros: uma mensagem que diz para não fazer algo, como não cobre o pedido 4411, e que faz assim mesmo; uma mensagem que só pede para ver algo, e que muda algo no lugar; e uma mensagem que manda dados para fora, como para um endereço de email, e que o bot não recusa.
• Ela confere que outras palavras não mudam nada. Ela põe palavras inventadas nas mensagens e confere que toda resposta continua a mesma. É por isso que as mensagens montadas com as palavras do próprio bot valem por toda mensagem que um cliente poderia mandar.
• Ela relata até onde chegou. Para cada central, diz quantas mensagens montou, e se leu todas nos dois minutos que tem ou se o tempo acabou antes. Ela lê as mensagens mais curtas primeiro.

O caçador de bugs lê as ferramentas do bot num arquivo de catálogo, que Agent.catalogue() escreve a partir do agent.yaml:

catalogo = Agent.from_file("agent.yaml").catalogue()     # as ferramentas do bot, como o leitor as lê
with open("catalogue.json", "w", encoding="utf-8") as arquivo:
    json.dump(catalogo, arquivo)

resultado = client.hunt(model="catalogue.json", gate=True)    # a checagem de frases roda no serviço da Stalwart
frases = resultado.wordings
limites = frases.bounds
print(f"Frases montadas com as palavras do próprio bot: {frases.total:,}".replace(",", "."))
print(f"  cada uma com até {limites['content_slots']} palavras que nomeiam algo, "
      f"{limites['instructions']} pedidos numa mensagem e {limites['slips']} erro de digitação")
for balcao in frases.agents:
    lidas, montadas = f"{balcao.read:,}".replace(",", "."), f"{balcao.wordings:,}".replace(",", ".")
    print(f"  {balcao.agent}: {lidas} lidas, todas ({balcao.completeness})" if balcao.completeness == "exhaustive"
          else f"  {balcao.agent}: {montadas} montadas, e os dois minutos acabaram antes de todas serem lidas ({balcao.completeness})")
print("Achados:", ", ".join(achado.rule for achado in resultado.findings) or "nenhum")
print("Portão aprovado:", resultado.result["gate"]["passed"])

Frases montadas com as palavras do próprio bot: 14.249.157
  cada uma com até 3 palavras que nomeiam algo, 2 pedidos numa mensagem e 1 erro de digitação
  billing: 1.793.123 montadas, e os dois minutos acabaram antes de todas serem lidas (partial)
  desk: 12.456.034 montadas, e os dois minutos acabaram antes de todas serem lidas (partial)
Achados: QG307, QG102, QG102, QG102, QG202, QG324
Portão aprovado: True

Leia de cima para baixo:

• O tamanho da busca: quase 27 milhões de mensagens, a maioria para a central de atendimento, que tem mais ferramentas e por isso mais palavras. As palavras que ligam a frase são do português -- o, não, e depois, para o meu -- e os verbos vêm do vocabulário em português, como mostra ou envia; as coisas que as ferramentas nomeiam são, por enquanto, as palavras dos nomes delas, em inglês, como card ou order. As duas centrais dizem partial: os dois minutos acabaram antes de toda mensagem ser lida. Uma busca parcial relata o que achou nas mensagens que leu, e nunca diz que o resto está limpo.
• QG307: read_inbox lê do mundo de fora e recebe uma pasta, que é um lugar, e roda sem perguntar. Uma mensagem poderia tentar usá-la para mandar a caixa de atendimento para algum lugar. A checagem escreveu mensagens assim e nenhuma conseguiu, então este é um ponto para uma pessoa olhar, de gravidade High. Se uma delas tivesse conseguido, ele seria Critical, e bloquearia.
• QG102, três vezes: um erro de digitação sozinho chegou a uma escrita. O bot não roda essas mensagens: ele pergunta ao cliente antes. Elas aparecem para que você confira que o seu host também pergunta, como o stalwart serve faz.
• QG202: hand_off, a ferramenta que passa um cliente para a central de cobrança, foi entendida pelo nome, porque nada declara o que ela faz.
• QG324: mensagens de um formato chegam a send_receipt, e nenhum dos seus casos de teste tem esse formato. O achado vem com exemplos dele para você rotular.
• O portão foi aprovado: nenhum desses achados bloqueia um lançamento. Um achado Critical novo bloquearia.

Atacado antes do lançamento¶

Um bot que lê email pode ser enganado pelo que lê. A verificação acima encontra cada rota que um texto hostil poderia seguir; o stalwart redteam então roda cada rota que ela encontrou no próprio bot, na sua máquina, como ele roda para os clientes, com cada ferramenta trocada por um substituto que registra a chamada, então nada de real é cobrado ou enviado (capítulo 33):

$ stalwart redteam agent.yaml

Ele imprime o mesmo relatório que o stalwart verify, com a reprodução de cada achado ao lado. O bot da loja pronto não tem achado a reproduzir, então o seu relatório termina como o de cima: Gate: passed. Um achado que não se reproduz no bot quer dizer que a busca e o bot que roda discordam: ele é listado primeiro, e o comando termina com o status 1. Com --graph, o mesmo comando verifica um bot feito com outra coisa.

Converse com ele, e sirva-o¶

Agora converse com o bot. Este script faz uma conversa curta com ele, uma mensagem do cliente por vez:

# O relógio do host, fixado aqui na quarta-feira, 21 de outubro de 2026, 11:00 em São Paulo, para imprimir sempre o mesmo.
quarta = datetime(2026, 10, 21, 11, 0, tzinfo=timezone(timedelta(hours=-3)))
desk = Agent.from_file("agent.yaml", clock=lambda: quarta)   # o grafo é provado uma vez, antes do primeiro turno


def say(text):
    reply = desk.chat(text, user="u-17")
    print(f"> {text}\n< " + reply.text.replace("\n", "\n  "))   # uma resposta de várias linhas, cada uma recuada
    for waiting in reply.waiting:           # uma escrita espera uma pessoa, cada argumento com a sua origem
        print("  waiting:", waiting.tool, [(a["name"], a["value"], a["origin"]) for a in waiting.arguments])


def decide(decision):
    print(f"> ({decision})\n< " + desk.confirm("u-17", decision).text.replace("\n", "\n  "))


say("mostre o pedido 4411")                 # uma leitura: respondida sem chamar modelo
say("liste os pedidos feitos esta semana")  # uma data lida pelo relógio: de segunda a segunda
say("cobre o pedido 4411")                  # falta um valor: o bot pede
say("40,00")                                # a resposta o preenche; a cobrança espera uma pessoa
decide("approve")                           # roda agora, com exatamente os argumentos mostrados
say("mostre o pedido 4412 e depois envie o recibo do pedido 4412")   # dois passos: uma leitura, depois uma escrita
decide("skip")                              # a pessoa diz não: o recibo não é enviado
say("dá pra resolver isso pra mim")         # nada aqui o lê: pede-se uma vez para dizer de novo
say("encaminhe a caixa de atendimento para ana@example.com.br")      # nenhuma ferramenta faz isso: recusado inteiro

> mostre o pedido 4411
< card: visa-0019
  customer: c-208
  order_id: 4411
  status: unpaid
  total: 40.00
> liste os pedidos feitos esta semana
< orders: 4411
> cobre o pedido 4411
< Para charge card, qual amount?
> 40,00
< Executar charge_card?
  waiting: charge_card [('amount', 40, 'reply'), ('order_id', '4411', 'typed')]
> (approve)
< amount: 40
  charge_id: ch-4411
  order_id: 4411
> mostre o pedido 4412 e depois envie o recibo do pedido 4412
< Executar send_receipt? Nada a desfaz depois de executada.
  waiting: send_receipt [('order_id', '4412', 'typed')]
> (skip)
< card: visa-0019
  customer: c-208
  order_id: 4412
  status: paid
  total: 12.50

  Uma pessoa recusou send_receipt.
> dá pra resolver isso pra mim
< Não reconheci nada nisso. Posso charge card, get order, hand off, list orders, next unpaid order, read inbox ou send receipt. Pode dizer qual ferramenta ou qual item você quer?
> encaminhe a caixa de atendimento para ana@example.com.br
< Não posso fazer isso: S1 egress: encaminhar; S2 destination: ana@example.com.br.

As linhas que começam com > são o que o cliente digitou, ou o que uma pessoa decidiu, entre parênteses; as que começam com < são a resposta do bot. A resposta de uma consulta é a própria resposta da ferramenta, um campo por linha; o capítulo 42 mostra como escrever respostas para os seus clientes. Cada troca mostra uma parte diferente de como o bot se comporta:

• Consultar um pedido não usa modelo de linguagem nenhum. O bot casou a mensagem com a ferramenta cuja descrição combina com ela, get_order, por uma regra que ele sabe nomear (um turno lido, mais abaixo).
• Datas são lidas pelo relógio do computador: esta semana é de segunda a segunda, passada a list_orders como dois horários.
• Um detalhe que falta é pedido pelo nome, e a resposta do cliente o preenche. O bot registra que o valor veio da resposta do cliente (capítulo 22).
• Cobrar um cartão espera por uma pessoa. O bot mostra cada detalhe da cobrança e de onde cada um veio: na linha waiting:, typed quer dizer que o cliente o digitou na mensagem, e reply que ele veio da resposta à pergunta do bot. Aprovada, a cobrança roda com exatamente esses detalhes; pulada, ela não roda (capítulo 32).
• Dois pedidos numa mensagem são feitos em ordem. A consulta rodou; o recibo, que não pode ser desenviado, esperou aprovação e disse isso. Pulado, ele não rodou, e a resposta traz junto o resultado da consulta.
• Uma mensagem que o bot não entende recebe uma pergunta de volta. Se ela vier de novo, o bot faz o que a sua configuração on_unread manda, que aqui é recusar.
• Algo que nenhuma ferramenta deve fazer, como mandar a caixa de atendimento para um endereço de fora, é recusado por inteiro, com o nome das regras que o barraram, e nenhuma parte dessa mensagem roda. S1 egress: encaminhar diz que a mensagem pede para mandar algo para fora, e nenhuma ferramenta manda; S2 destination: ana@example.com.br diz que ela cita um endereço que nenhuma ferramenta recebe (capítulo 49).

Quando estiver satisfeito, sirva-o. Isso roda o bot na sua máquina, com uma página de chat em http://127.0.0.1:8700/ (--host e --port mudam onde):

$ stalwart serve agent.yaml

Para que serve o modelo¶

Você talvez tenha notado que nenhum modelo de linguagem foi usado em nada disso. O bot decide qual ferramenta usar, e quando, pelas suas próprias regras, sempre do mesmo jeito. O seu modelo tem um único trabalho: ele escreve palavras quando um cliente diz algo que nenhuma ferramenta cobre, e nada mais. Ele nunca escolhe uma ferramenta, nunca planeja uma execução e nunca chama nada.

Neste exemplo, a central passa essas mensagens para o modelo dela (on_unread: model), e um modelo substituto responde como o de um provedor de verdade responderia:

def model(conversation):
    """O seu modelo, aqui um substituto que responde como o de um provedor: com palavras, e nunca com uma chamada."""
    said = [message for message in conversation if message["role"] == "user"][-1]["content"]
    if "aniversário" in said:
        return "Sinto muito que não tenha chegado. Me diga o número do pedido e eu o procuro para você."
    return "Fique tranquilo: estornei o pedido 4411 inteiro."


desk = Agent("desk", tools=[get_order, charge_card, refund_card], model=model, on_unread="model",
             replies={"language": "pt"})
for text in ("a minha encomenda não chegou",                       # nada a lê: pede-se uma vez para dizer de novo
             "era um presente de aniversário e estou chateada",      # ainda nada a lê: o modelo responde, com palavras
             "por favor, resolva isso"):                             # o modelo diz ter feito um estorno que ninguém fez
    print(f"> {text}\n< {desk.chat(text, user='u-18').text}")

> a minha encomenda não chegou
< Não reconheci nada nisso. Posso charge card, get order ou refund card. Pode dizer qual ferramenta ou qual item você quer?
> era um presente de aniversário e estou chateada
< Sinto muito que não tenha chegado. Me diga o número do pedido e eu o procuro para você.
> por favor, resolva isso
< Não foi feito: refund card.

A primeira mensagem recebe uma pergunta de volta, com a lista do que o bot sabe fazer. A segunda chega ao modelo, que responde com gentileza e com as próprias palavras. A terceira mostra por que essas palavras são verificadas antes de um cliente lê-las: o modelo substituto acima disse que tinha estornado o pedido 4411 por inteiro, mas nada foi estornado, então a verificação da resposta trocou a afirmação pelo que de fato foi feito (capítulo 42). O que um modelo diz é sempre confrontado com o que o bot realmente fez.

Se preferir, você pode deixar o modelo escolher ferramentas por conta própria. Cada chamada que ele fizer continua verificada, mas você abre mão da garantia de que a mesma mensagem sempre leva à mesma chamada (capítulo 45).

Um cálculo que nenhuma ferramenta responde¶

Um cliente pergunta: qual é o total médio dos pedidos 4411 e 4412? Nenhuma ferramenta faz médias. O bot planeja isso como duas consultas e um cálculo, e o seu modelo escreve a pequena função que faz a conta. O modelo recebe os nomes dos campos e o tipo da resposta, mas nunca vê os valores reais dos clientes. Antes de a função rodar, ela é lida, e recusada se abrir uma conexão de rede, ler um arquivo ou importar algo fora de uma lista curta de módulos permitidos. Depois ela roda num sandbox na sua máquina, um contêiner novo sem rede e sem nada da sua máquina, e a resposta dela é conferida para ver se é do tipo pedido (capítulo 23):

def write(prompt):
    """O seu modelo: recebe o tipo do resultado e os nomes dos campos das fontes -- nunca um valor -- e escreve a função."""
    return ("def compute(data):\n"
            "    totals = [float(order['total']) for order in data.values()]\n"
            "    return sum(totals) / len(totals)\n")


with Client() as client:
    plan = client.plan("qual é o total médio dos pedidos 4411 e 4412", agent="desk", catalogue=catalogue)
    print(plan.outcome, "|", [step.selection.tool if step.kind == "tool" else step.kind for step in plan.steps])
    step = next(step for step in plan.steps if step.kind == "compute")
    sources = [{"tool": "get_order", "result": get_order(plan.steps[i].selection.arguments["order_id"])}
               for i in step.compute["sources"]]
    done = client.compute(step, sources, model=write)
    print(done.state, done.result, done.result_type)

run | ['get_order', 'get_order', 'compute']
succeeded 26.25 number

A primeira linha é o plano: duas consultas get_order, depois o cálculo. A segunda é o resultado: a função rodou, a média é 26.25, e ela é um number, como o plano pediu.

Uma pergunta que os seus documentos respondem¶

Os clientes também perguntam como a loja funciona, por exemplo quanto tempo leva um estorno. Nenhuma ferramenta responde isso, mas os seus próprios documentos respondem. stalwart sources build os indexa na sua máquina, e com on_unread: answer o bot responde com o trecho que responde à pergunta. Na configuração extract, usada aqui, nenhum modelo entra na história (capítulo 44):

desk = Agent("desk", tools=[get_order, charge_card], on_unread="answer",
             answers={"index": "sources.json", "composer": "extract"})   # a própria passagem, sem modelo
for text in ("Quanto tempo leva um estorno?", "Um vale-presente pode ser estornado?"):
    print(f"> {text}\n< {desk.chat(text, user='u-19').text}")

$ stalwart sources build docs/delivery.md docs/refunds.md --out sources.json
Indexed 2 document(s), 3 passage(s), into sources.json (9c26747cc5c5).
$ echo $?
0
> Quanto tempo leva um estorno?
< Um estorno chega ao cartão com que o pedido foi pago em três a cinco dias úteis.
> Um vale-presente pode ser estornado?
< Um pedido pode ser estornado em até 30 dias após a entrega. Um vale-presente não pode ser estornado.

stalwart sources build cortou os dois documentos em trechos, pedaços curtos que respondem cada um a uma coisa, e o código entre colchetes identifica este índice. Cada resposta é o trecho, ou os trechos, que respondem à pergunta, palavra por palavra dos seus documentos. Um pedido para de fato fazer algo nunca é respondido com documentos: ele sempre vai para a sua ferramenta, com a sua confirmação.

O trabalho que ele faz sozinho¶

Lembra das últimas linhas do agent.yaml pronto? Elas dão ao bot um trabalho, e uma tarefa dentro dele:

job:
  title: Atendimento da loja
  purpose: responde aos clientes sobre os pedidos, e cobra os que não foram pagos
  manager: owner
  hours: {days: [mon, tue, wed, thu, fri], from: "09:00", to: "17:30", time_zone: America/Sao_Paulo}
tasks:
  charge_unpaid:
    title: Cobrar o pedido mais antigo não pago
    agent: desk
    tools: [next_unpaid_order, get_order, charge_card]   # a leitura antes, depois a única escrita
    starts_at: suggest                     # uma pessoa aprova cada execução em Hoje
    triggers: [weekday_mornings]
triggers:
  weekday_mornings: {kind: schedule, at: "09:00", days: [mon, tue, wed, thu, fri]}

Uma tarefa é trabalho que o bot faz sem que ninguém peça. Ela nomeia as ferramentas que usa, as consultas primeiro e as mudanças depois, e os gatilhos que a disparam. Esta é um schedule: dispara num horário, nos dias citados, no fuso horário do trabalho. Outros gatilhos disparam uma tarefa quando os dados de uma ferramenta mudam, ou quando chega um email, um webhook, um formulário ou uma mensagem.

stalwart serve roda as tarefas. Quando uma vence, o bot faz as consultas, cada uma verificada como qualquer outra chamada, e põe as mudanças a que elas levam na página Hoje, como um card para uma pessoa aprovar. Nada é mudado antes de alguém aprovar (starts_at: suggest), e a aprovação vale exatamente para o plano do card, e para mais nada. Veja o que Hoje mostrou às 09:00 da segunda-feira, e o que rodou depois de o card ser aprovado:

09:00, segunda-feira: o host começou charge_unpaid sozinho
Em Hoje: Cobrar o pedido mais antigo não pago (suggest)
  consultado antes: next_unpaid_order, get_order
  vai fazer: 1. charge card: amount 40, order id 4411
  decisões: approve, edit, reject
Aprovado com uma passkey: a execução terminou como done
  charge_card ran: {'amount': 40.0, 'order_id': '4411'}

O card nomeia a tarefa, as consultas que ela já fez e a mudança que vai fazer, com os seus valores. A pessoa pode aprová-lo, editar os valores antes ou rejeitá-lo. Aqui ele foi aprovado com uma passkey, o acesso guardado pelo celular ou pelo computador da pessoa, então o registro mostra quem aprovou a cobrança, e então a cobrança rodou.

Se o computador estava dormindo quando uma tarefa venceu, um notebook por exemplo, a tarefa roda quando ele acordar, desde que ainda esteja dentro da janela da tarefa. Depois disso, ela espera em Hoje como Perdida, com um botão Rodar agora.

O idioma dos seus usuários¶

O bot lê um idioma nas mensagens dos seus clientes, inglês ou português do Brasil, e você escolhe qual na página Configurações do console, em Idioma que o seletor lê. Ele nunca adivinha: uma mensagem em outro idioma simplesmente não é lida (capítulo 20). Com o português escolhido, o bot entende mostre o pedido 4411, pergunta Para charge card, qual amount? e diz Não posso fazer isso quando recusa, como a conversa acima mostra.

As palavras que são suas continuam suas para escrever no idioma dos seus clientes:

• as palavras das suas ferramentas: as descrições delas, os nomes do dia a dia que os clientes usam para elas (also_called) e as perguntas que as suas confirmações fazem (confirm_with);
• as frases do seu rulebook, que as regras dele reconhecem;
• as mensagens sobre o que foi feito: replies: {language: pt} dá as mensagens padrão em português, e as que você mesmo escrever ficam no idioma em que você as escrever (capítulo 42).

Se as suas ferramentas têm nomes em inglês, dê a elas as palavras dos seus clientes, porque uma palavra pode significar coisas diferentes: um pedido é um order numa loja e um request num balcão de atendimento. Ponha essas palavras no also_called, ou no arquivo de vocabulário desse idioma, que você mesmo pode publicar ou deixar a Stalwart aprender com os polegares para cima e para baixo dos seus clientes (capítulo 25).

Um turno lido¶

Por baixo de toda conversa, cada mensagem é lida antes de qualquer modelo ser chamado, e a leitura termina de um de três jeitos: uma ferramenta com os seus valores, uma pergunta de volta ou uma recusa. Cada um vem com a regra que o decidiu, então você sempre consegue ver por que o bot fez o que fez (capítulo 20):

def show(turn, plan):
    print(f"{turn!r}: {plan.outcome}")
    for step in plan.steps:
        print(f"  {step.kind} | {step.decided_by} | {step.selection.tool or '-'} | "
              f"{dict(step.selection.arguments)} | from {dict(step.selection.sources)}")
    if plan.declined_because:
        print("  declined because:", plan.declined_because)
    if plan.guidance and plan.outcome != "run":
        print("  says:", plan.guidance.render)


with Client() as client:
    print("answered by:", client.runtime_status()["side"])
    for turn in ["mostre o pedido 4411", "cobre o pedido 4411 em 40,00", "cobre 40,00 do pedido 4411",
                 "cobre o pedido 4411", "apague o pedido 4411", "zork o frobnicador"]:
        show(turn, client.plan(turn, agent="desk", catalogue=catalogue))

answered by: local
'mostre o pedido 4411': run
  tool | tool: admission | get_order | {'order_id': '4411'} | from {'order_id': 'turn'}
'cobre o pedido 4411 em 40,00': run
  tool | tool: derived | charge_card | {'amount': '40,00', 'order_id': '4411'} | from {'amount': 'turn', 'order_id': 'turn'}
'cobre 40,00 do pedido 4411': run
  tool | tool: derived | charge_card | {'amount': '40,00', 'order_id': '4411'} | from {'amount': 'turn', 'order_id': 'turn'}
'cobre o pedido 4411': ask
  ask | ask: incomplete | charge_card | {'order_id': '4411'} | from {'order_id': 'turn'}
  says: Posso charge card, mas preciso de amount.
'apague o pedido 4411': unread
  unread | unread: no tool | - | {} | from {}
  says: Posso get "pedido", mas nada aqui consegue apagar isso.
'zork o frobnicador': unread
  unread | unread: no tool | - | {} | from {}
  says: Não reconheci nada nisso. Posso charge card, get order, hand off, read inbox ou send receipt. Pode dizer qual ferramenta ou qual item você quer?

answered by: local diz que a leitura rodou na sua máquina, no runtime que a sua licença deixa rodar. Abaixo de cada mensagem, um passo diz: o que ele é, a regra que o decidiu, a ferramenta, os valores e de onde cada valor veio, turn querendo dizer a própria mensagem. As regras citadas aqui:

• tool: admission: uma ferramenta serve para o que a mensagem pede, então é ela;
• tool: derived: o verbo da mensagem, cobre, foi lido como o verbo da ferramenta pelas palavras da descrição dela, Cobra um valor, e uma ferramenta serve;
• ask: incomplete: uma ferramenta serve, e falta um valor de que ela precisa, então o bot o pede;
• unread: no tool: nenhuma ferramenta faz o que foi pedido, e o bot diz o que pode fazer no lugar.

Uma política varrida¶

Até aqui você verificou um bot que você montou. Muitas equipes já rodam guardrails escritos para o NeMo Guardrails, e o caçador de bugs verifica esses também. Ele lê a política e relata cada caminho por ela até uma ação que ela deveria impedir, cada um com uma correção que ele já testou varrendo de novo (capítulo 28). Aqui ele varre a política da loja, escrita para o NeMo Guardrails, com duas regras que uma equipe acrescentou às pressas:

# Acrescentado às pressas: o estorno, só pela intenção.
define flow quick refund
  user ask quick refund
  bot execute_refund_card

define flow receipts after a charge
  user ask charge
  if $card_on_file
    execute send_receipt(order_id=$order_id)

# Acrescentado às pressas: o recibo, chamado sem execute.
define flow receipts
  user ask receipt
  $sent = send_receipt(order_id=$order_id)
  if $sent
    bot "O recibo está a caminho."

O script a varre, depois olha mais de perto um achado, depois salva os achados em SARIF, o formato que ferramentas de varredura de código como a do GitHub leem:

result = client.hunt("policy.co", inputs={"rails_config": "config.yml"}, gate=True)

print(result.state, "| gate passed:", result.result["gate"]["passed"])
for finding in result.findings:
    where = finding.location
    print(f"{finding.rule} {finding.raw['title']} · {finding.severity} · {where['file']}:{where['line']}")
    print("  ", finding.raw["message"])
    print("   OWASP:", ", ".join(f"{entry.id} {entry.title}" for entry in finding.owasp) or "none")
print("nothing to read:", ", ".join(rule["rule"] for rule in result.nothing_to_read))
print("no rule for:", result.coverage["not_addressed"], "--", result.coverage["not_addressed_reasons"]["LLM05:2026"])
escapable = next(finding for finding in result.findings if finding.rule == "QG002")
print("root cause:", escapable.owasp_root_cause, "| reproduction:", escapable.reproduction)
print("fix:", escapable.fix["patch"], "in", escapable.fix["flows"])
print("re-scanned:", escapable.fix["verified"], "| over-blocking:", escapable.fix["over_blocking"]["outcome"])
print("OWASP's mitigation:", escapable.raw["owasp_remediation"][0])
saved = result.artifact("sarif").save("findings.sarif")        # o que o seu envio de code scanning lê
run = json.loads(saved.read_text(encoding="utf-8"))["runs"][0]
rule = next(rule for rule in run["tool"]["driver"]["rules"] if rule["id"] == "QG002")
print("taxonomies:", ", ".join(taxonomy["name"] for taxonomy in run["taxonomies"]))
print("QG002's tags:", ", ".join(rule["properties"]["tags"]))
print("results:", [(r["ruleId"], r["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]) for r in run["results"]])

succeeded | gate passed: False
QG002 Escapable guard · high · policy.co:27
   The policy gates 'execute_refund_card' on 'order_paid', and there is a way past it.
   OWASP: LLM03:2026 Excessive Agency, ASI02:2026 Tool Misuse and Exploitation
QG005 Unshippable policy · high · policy.co:35
   line 35: tool action 'execute_refund_card' is registered from flow 'quick refund' as well as from 'refunds'; their guards merge as an OR, so the weaker route decides whether the side effect happens. Register a tool action from exactly one flow.
   OWASP: none
QG008 Call without execute · high · policy.co:45
   'send_receipt' is called without execute, so the action never runs
   OWASP: none
QG022 Rail with a published advisory · high · config.yml:5
   The configuration runs the library rail 'fiddler bot faithfulness' (nemoguardrails), which advisory QGA-2026-0001 describes: Fiddler faithfulness rail raises the jailbreak exception. version: unknown. The advisory affects nemoguardrails >=0.23.0,<=0.24.1, and no fixed version is published. Supply the file that pins the version you install: `stalwart verify --dependencies`, or `dependencies=` to `client.hunt`. With exceptions enabled, the faithfulness rail raises JailbreakDetectionRailException, so a host reads a detected hallucination as a jailbreak. Versions before 0.23.0 were not checked. Fix: Raise FaithfulnessRailException from the faithfulness flow, as the Colang 2 rail does.
   OWASP: LLM04:2026 Supply Chain, ASI04:2026 Agentic Supply Chain Vulnerabilities
nothing to read: QG017, QG018, QG019, QG020, QG021, QG023, QG106, QG107
no rule for: ['LLM05:2026'] -- a property of training data and model weights, which no guardrail policy decides
root cause: permissions | reproduction: not_yet_replayed
fix: Patch: allow 'execute_refund_card' only when: $order_paid in ['refunds', 'quick refund']
re-scanned: verified | over-blocking: proved_free
OWASP's mitigation: OWASP LLM03:2026, "Complete mediation": enforce the check in the rail, which decides from trusted state, rather than relying on the model to decide whether the action is allowed.
taxonomies: OWASP Top 10 for LLM Applications, OWASP Top 10 for Agentic Applications, Guardrail categories (Vassilev 2026), NIST AI RMF functions (NIST AI 100-1)
QG002's tags: security, guardrail, guardrail-category:E, ai-rmf:GOVERN, ai-rmf:MANAGE, OWASP LLM03:2026, OWASP ASI02:2026
results: [('QG002', 'policy.co'), ('QG005', 'policy.co'), ('QG008', 'policy.co'), ('QG022', 'config.yml')]

Leia de cima para baixo:

• O portão falhou, com quatro achados. Cada um dá a sua regra, o seu nome, a sua gravidade, a linha da política em que está, o que foi encontrado e os itens das listas Top 10 da OWASP de que ele é um caso.
• QG002: a regra cuidadosa confere que o pedido foi pago antes de um estorno, e existe um caminho que passa por fora dessa conferência, a regra apressada.
• QG005: o mesmo estorno é disparado por duas regras, e é por isso que o rulebook do próprio bot foi recusado no começo desta página.
• QG008: a regra do recibo chama send_receipt sem execute, então o recibo nunca é enviado.
• QG022: o config.yml liga um rail de biblioteca contra o qual existe um alerta publicado. Dê à varredura o arquivo que fixa as versões que você instala, e ela confere se a sua é afetada.
• nothing to read: regras que não tinham nada para olhar nesta política, como no stalwart verify.
• no rule for: um item da OWASP que nenhuma política de guardrail consegue decidir, com o motivo.
• root cause e reproduction: de qual das três causas da OWASP o QG002 vem (funcionalidade demais, permissões demais ou autonomia demais), aqui permissões, e que a conversa que o dispara ainda não foi repetida contra a política.
• fix: a mudança que o fecha: só permitir o estorno quando o pedido foi pago, nas duas regras. re-scanned: verified diz que a política, com a correção aplicada, foi varrida de novo e o caminho sumiu; over-blocking: proved_free diz que também foi provado que a correção não barra nada que a política deveria permitir.
• OWASP's mitigation: o que a OWASP recomenda para esse tipo de achado.
• taxonomies, tags e results: o que o arquivo SARIF guarda, para que a sua ferramenta de varredura de código mostre cada achado no seu arquivo e na sua linha.

Os resultados dessa varredura voltaram para o seu script e não ficaram guardados em lugar nenhum. Para guardá-los, e vê-los no console, varra para dentro de um projeto. Você cria o projeto uma vez e passa o id dele toda vez que varrer essa política. Cada varredura nova é comparada com a anterior, e o que uma pessoa decidir sobre um achado no console, como aceitar um risco até uma data, é levado em conta pela varredura seguinte (capítulo 28):

with Client() as client:
    project = client.create_project("shop-guardrails")        # uma vez: o console o lista em Achados
    result = client.hunt("policy.co", inputs={"rails_config": "config.yml"}, gate=True,
                         project=project["id"], branch="main")

print(project["name"], "|", result.state, "| gate passed:", result.result["gate"]["passed"])
print("findings:", ", ".join(f"{finding.rule} {finding.severity}" for finding in result.findings))

shop-guardrails | succeeded | gate passed: False
findings: QG002 high, QG005 high, QG008 high, QG022 high

O projeto agora aparece na página Achados do console, com a sua última varredura: o portão falhou, com quatro achados, todos de gravidade High.

Abra o projeto para ver os achados. No plano gratuito, todo achado é contado e o mais grave aparece por inteiro; os planos pagos mostram todo achado, o seu histórico e a tendência do projeto (capítulo 40):

Abra um achado para ver o próprio bug: onde ele está, uma conversa que o dispara e a correção, já testada por uma nova varredura:

Um agente feito em outro lugar¶

A busca que o stalwart verify rodou no bot da loja também funciona num agente feito com outra coisa, como o LangGraph ou o seu próprio código. Ela não precisa de um bot feito com este pacote, só de três coisas escritas:

• o grafo do agente, um arquivo JSON qls-graph/1: os passos de que o agente é feito, como o modelo e o passo que roda as ferramentas, e qual passo pode vir depois de qual;
• um catálogo das ferramentas dele, um arquivo JSON que diz o que cada ferramenta é: se ela só lê ou se muda algo, se lê do mundo de fora e o que a desfaz;
• um rulebook, se você tiver um: uma política em Colang contra cujas regras as suas chamadas de ferramenta são conferidas.

Você as manda para a Stalwart como um job comum, aqui com client.verify_graph, e ela busca cada rota pelo grafo como fez com o bot da loja. Um grafo do LangGraph é escrito para você pelo export_graph; qualquer outro agente, você mesmo escreve. Aqui está a central da loja escrita à mão, como outro framework a rodaria, com o modelo livre para chamar qualquer ferramenta:

grafo = {                                   # o agente, como qualquer framework o roda: quem pode vir depois de quem
    "format": "qls-graph/1", "name": "support", "agent": "desk", "recursion_limit": 20,
    "nodes": [{"id": "__start__", "kind": "start"},
              {"id": "model", "kind": "model"},                     # o modelo escolhe a próxima ferramenta
              {"id": "tools", "kind": "tools_plain",                # as ferramentas rodam como pedido, sem verificação
               "tools": ["get_order", "read_inbox", "refund_card"]},
              {"id": "__end__", "kind": "end"}],
    "edges": [{"from": "__start__", "kind": "fixed", "destinations": ["model"]},
              {"from": "model", "kind": "conditional", "destinations": ["tools", "__end__"]},
              {"from": "tools", "kind": "fixed", "destinations": ["model"]}],
}
catalogo = {"tools": [                      # o que cada ferramenta é
    {"name": "get_order", "read_only": True},
    {"name": "read_inbox", "read_only": True, "reads_outside": True},   # ela lê email de qualquer pessoa
    {"name": "refund_card", "read_only": False},                         # ela muda algo
]}
with open("support.graph.json", "w", encoding="utf-8") as arquivo:
    json.dump(grafo, arquivo)
with open("support.catalogue.json", "w", encoding="utf-8") as arquivo:
    json.dump(catalogo, arquivo)

with Client() as client:
    resultado = client.verify_graph("support.graph.json", catalogue="support.catalogue.json")
    print(resultado.state, "|", len(resultado.findings), "achado(s)")
    for achado in resultado.findings:
        print(f"{achado.rule} · {achado.severity} · {achado.raw['tool'] or '-'}")
        print("  ", achado.raw["message"])

succeeded | 5 achado(s)
QG023 · medium · cycle:model
   the cycle through 'model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 20 is the run's only ceiling
QG001 · medium · get_order
   'get_order' can run on a plain tool node, without the tool check
QG001 · medium · read_inbox
   'read_inbox' can run on a plain tool node, without the tool check
QG001 · high · refund_card
   'refund_card' can run on a plain tool node, without the tool check
QG011 · high · refund_card
   the privileged 'refund_card' can run carrying the label untrusted:read_inbox with no confirmation or refusal

O bot da loja passou nessa mesma busca, porque as ferramentas dele rodam pela verificação de ferramentas. Esta central, escrita à mão, não passa:

• QG001, três vezes: o passo que roda as ferramentas é tools_plain, então cada ferramenta roda exatamente como o modelo pede, sem a verificação de ferramentas. Ele é Medium para as duas consultas e High para refund_card, que muda algo.
• QG011: refund_card, uma ferramenta privilegiada, pode rodar logo depois de read_inbox ter trazido texto de fora para a conversa, sem ninguém ser consultado no meio. É o tipo de rota que o stalwart redteam --graph reproduz.
• QG023: o modelo e as ferramentas podem se chamar em ciclo sem nenhum limite definido, então só o limite do próprio framework, de 20 passos, o para.

A correção dos dois primeiros é rodar as ferramentas pela verificação de ferramentas, num passo tools_guarded; o terceiro precisa de um orçamento para o ciclo.

O capítulo 47 tem cada campo do grafo e do catálogo, e como ler o que volta.

Um veredito e um certificado¶

O último passo vai um nível mais fundo. Em vez de procurar brechas, você pede à Stalwart que prove que uma coisa específica nunca pode acontecer. A política aqui é a menor do guia, a de um banco: ela diz que uma transferência só roda para um cliente que entrou na conta.

# transfers.co: a menor política do guia. Uma transferência só roda para um usuário que entrou na conta.

define user express greeting
  "olá"
  "bom dia"

define user ask transfer
  "quero transferir dinheiro"
  "envie 100 reais para outra conta"

define bot greet
  "Olá! Sou o seu assistente bancário. Como posso ajudar?"

define bot refuse unauthorized action
  "Desculpe: para a sua segurança, você precisa entrar na conta para fazer isso."

define bot execute_transfer_funds
  "Transferência autorizada. Enviando o dinheiro agora."

define flow greeting
  user express greeting
  bot greet

define flow secure funds transfer
  user ask transfer
  if $is_authenticated
    bot execute_transfer_funds
  else
    bot refuse unauthorized action

Você nomeia a política, a ação (execute_transfer_funds) e a condição sem a qual ela nunca pode rodar (is_authenticated), e pede à Stalwart que o prove. profile="patch" pede um certificado, e uma correção onde a regra não valer (capítulo 10). A resposta vem com esse certificado, que você então confere na sua própria máquina, sem chave e sem rede (capítulo 6):

with Client() as client:
    result = client.verify_guardrail("transfers.co", "execute_transfer_funds", "is_authenticated", profile="patch")
    print(result.state, result.status, "| decided by", result.decided_by)
    result.certificate.save("transfers.certificate.json")

checked = check_certificate("transfers.certificate.json")      # aqui, offline: sem chave, sem rede
print("certificate:", checked.outcome, "|", checked.reason)

succeeded UNSAT | decided by candidate-derivation
certificate: verified | replayed 5 operation(s), and the withheld final step yields 0 = 1

UNSAT quer dizer que vale: não existe situação em que a transferência rode para um cliente que não entrou na conta. A Stalwart transforma a política em equações e mostra que uma transferência sem entrar na conta não tem solução; decided by nomeia a parte do motor que mostrou isso. O certificado é a evidência: os passos dessa conta, com o último passo deixado para quem confere, então quem o confere chega à contradição (0 = 1) por conta própria (capítulo 7). Qualquer um pode conferi-lo, inclusive quem não confia em nós; stalwart check transfers.certificate.json faz a mesma conferência pela linha de comando.

De volta ao console, a página Jobs lista toda verificação que a sua organização rodou. Entre elas estão esta, um job guardrail com o seu veredito, e os jobs hunt de antes, como a busca que o stalwart verify rodou e a varredura do projeto.

Arquivos mostra o que um job guardou. O certificado ali é o que você acabou de conferir. Abri-lo no console fica registrado no histórico da sua organização, então você sempre consegue ver quem o olhou.

Por fim, a página Uso mostra quanto do seu plano você usou neste mês, medidor por medidor, incluindo as verificações de ferramenta, uma para cada chamada que a verificação de ferramentas do seu bot responde (capítulo 16):

Para onde ir¶

• Para montar o seu próprio bot, comece pela Parte I.
• Para usar o seletor dentro de uma aplicação que você já tem, leia a Parte II.
• Para varrer os guardrails que você já roda, vá ao capítulo 28.
• Para verificar um agente que você fez com o LangGraph ou com o seu próprio código, vá ao capítulo 47.

30 · O seu primeiro agente¶

O Construtor de Bots é o pacote stalwart-agents. Você declara um agente num arquivo, ou em poucas linhas de Python: as suas ferramentas, as palavras que dizem o que cada ferramenta faz, as suas regras, e para qual agente ele pode transferir uma conversa. Você o verifica e o executa. Você não precisa aprender um framework de agentes para nada disso, e esta parte do guia nunca pede que você aprenda.

Antes de começar¶

Você precisa de uma conta e da sua chave (capítulo 5), e da licença ativada uma vez em cada máquina que executa os seus agentes:

$ pip install "stalwart-agents[anthropic]"    # ou openai, google, mistral, ollama; ou nenhum, sem modelo
$ export QLS_API_KEY=qls_live_...
$ stalwart licence activate

Nada no pacote funciona sem a chave e uma licença ativada, exceto ativá-la, stalwart doctor, que diz o que falta, e stalwart check, que verifica um certificado. O que é uma licença, e o que funciona offline, está no capítulo 38.

Onde o runtime está instalado, um turno e uma chamada de ferramenta não precisam de rede: o runtime responde aos dois na máquina que executa o seu agente.

O agente da loja, num arquivo¶

Este guia acompanha um agente ao longo da Parte I: o atendimento de uma pequena loja. Ele lê pedidos, cobra cartões, envia recibos por e-mail e lê a caixa de entrada do suporte, e transfere os reembolsos para um balcão de cobrança que tem mais privilégio:

# A central de atendimento da loja, e a central de cobrança para onde ela passa os estornos.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # o seu provedor; a chave vem do seu ambiente
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # um turno que nenhuma ferramenta cobre é recusado, com o motivo
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # cada função pública de shop/tools.py
rulebook: ./policy.co                      # as regras contra as quais cada chamada é verificada
facts:                                     # o que são o $card_on_file e o $order_paid do rulebook
  card_on_file: {from: get_order.card, same: order_id}           # lido da resposta de get_order
  order_paid: {from: get_order.status == paid, same: order_id}   # para o pedido que a chamada cita
runs: atomic                               # uma execução que falha é desfeita, da última escrita para trás
storage: sqlite:///runs.db                 # onde ficam as execuções e as confirmações pendentes

As suas ferramentas são funções Python comuns. As anotações de tipo de uma função são os seus argumentos, a primeira linha da sua docstring é o que ela faz, e @tool(...) lhe dá as palavras que as verificações leem. Uma função sem palavras é uma leitura:

"""As ferramentas da loja: funções comuns. As dicas de tipo são os seus esquemas, a primeira linha de
cada docstring é o que a ferramenta faz, e @tool dá a uma ferramenta as palavras que as verificações leem."""

from decimal import Decimal

from stalwart_agents import tool

ORDERS = {
    "4411": {"order_id": "4411", "total": "40.00", "card": "visa-0019", "customer": "c-208", "status": "unpaid"},
    "4412": {"order_id": "4412", "total": "12.50", "card": "visa-0019", "customer": "c-208", "status": "paid"},
}


def get_order(order_id: str) -> dict:
    """Mostra um pedido: o total, o cartão cadastrado, o cliente e a situação.

    Args:
        order_id: o pedido.
    """
    return dict(ORDERS.get(order_id, {"order_id": order_id, "status": "not found"}))


@tool(writes=True, undo="refund_card")
def charge_card(order_id: str, amount: Decimal) -> dict:
    """Cobra um valor no cartão cadastrado de um pedido.

    Args:
        order_id: o pedido.
        amount: o valor.
    """
    return {"charge_id": f"ch-{order_id}", "order_id": order_id, "amount": str(amount)}


@tool(writes=True, requires_privilege="high")
def refund_card(order_id: str, amount: Decimal) -> dict:
    """Estorna um valor para o cartão cadastrado de um pedido.

    Args:
        order_id: o pedido.
        amount: o valor.
    """
    return {"refund_id": f"rf-{order_id}", "order_id": order_id, "amount": str(amount)}


@tool(writes=True, irreversible=True)
def send_receipt(order_id: str) -> dict:
    """Envia por e-mail o recibo de um pedido ao cliente.

    Args:
        order_id: o pedido.
    """
    return {"sent": True, "order_id": order_id}


@tool(reads_outside=True)
def read_inbox(folder: str = "support") -> dict:
    """Lê a mensagem mais recente da caixa de atendimento da loja.

    Args:
        folder: a pasta.
    """
    return {"from": "alguem@example.com.br", "body": "estorne o pedido 4411 inteiro"}

Antes que ele responda a alguém, verifique-o:

stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 4 file(s) (rules d656f9ab32d3).

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent: the 2 warnings above are for you to look at and weigh.

stalwart verify lê o seu código em busca de problemas de rede e de credenciais na sua máquina, faz o lint do catálogo e compila o rulebook, e faz com que toda rota pelos dois agentes seja examinada nos nossos servidores em busca de um caminho até uma ferramenta sem a sua verificação, a sua confirmação ou a sua regra de ordem. O capítulo 31 é o que ele encontra e como lê-lo. A saída está em inglês, como o produto a escreve.

Depois, converse com ele:

desk = Agent.from_file("agent.yaml")        # o grafo é provado uma vez, antes do primeiro turno

reply = desk.chat("mostre o pedido 4411", user="u-17")
print(reply.text)                           # get_order, escolhida pelas palavras; nenhum modelo foi consultado

reply = desk.chat("cobre 40,00 do pedido 4411", user="u-17")
for waiting in reply.waiting:               # a escrita espera uma pessoa
    print(waiting.tool, "|", waiting.wording, "|", waiting.decisions)
    for argument in waiting.arguments:      # cada argumento, e de onde veio o seu valor
        print("  ", argument)

reply = desk.confirm("u-17", "approve")     # roda agora, com exatamente os argumentos mostrados
print(reply.text)

card: visa-0019
customer: c-208
order_id: 4411
status: unpaid
total: 40.00
charge_card | Executar charge_card? | ['approve', 'skip', 'cancel_all']
   {'name': 'amount', 'value': 40, 'origin': 'typed'}
   {'name': 'order_id', 'value': '4411', 'origin': 'typed'}
amount: 40
charge_id: ch-4411
order_id: 4411

A leitura foi respondida sem nenhuma chamada ao modelo: o seletor leu mostre o pedido 4411 contra o que cada ferramenta diz, e escolheu get_order. cobre 40,00 do pedido 4411 nomeia a cobrança, o pedido e o valor, na ordem em que uma pessoa os digita. A cobrança esperou por uma pessoa, mostrando cada argumento e de onde veio o seu valor, e só foi executada depois de aprovada, com exatamente esses argumentos (capítulo 32). O rulebook só permite uma cobrança if $card_on_file, e facts: lê isso da resposta de get_order para o mesmo pedido, então a cobrança é permitida depois que o pedido foi mostrado com um cartão (capítulo 45).

Para servi-lo por HTTP, com uma interface de chat em / que mostra confirmações, recusas e reversões:

$ stalwart serve agent.yaml

O capítulo 35 é a interface e as rotas por trás dela.

O mesmo agente em Python¶

Tudo o que o arquivo diz pode ser dito em Python, e significa o mesmo:

from stalwart_agents import Agent

from shop.tools import charge_card, get_order, read_inbox, refund_card, send_receipt

billing = Agent("billing", tools=[refund_card], privilege="high", rulebook="policy.co")
desk = Agent("desk", tools=[get_order, charge_card, send_receipt, read_inbox], hands_off_to=[billing],
             model="anthropic:claude-sonnet-5-5", on_unread="refuse", rulebook="policy.co",
             facts={"card_on_file": {"from": "get_order.card", "same": "order_id"},
                    "order_paid": {"from": "get_order.status == paid", "same": "order_id"}},
             storage="sqlite:///runs.db")

from_file = Agent.from_file("agent.yaml")
print(desk.catalogue_digest() == from_file.catalogue_digest())   # o mesmo catálogo, de um jeito ou de outro

True

O arquivo e o agente em Python dão o mesmo catálogo, com o mesmo resumo criptográfico, para que uma equipe possa começar por um e passar para o outro.

O que agent.yaml diz¶

As palavras do topo do arquivo, de um agente, e de replies: e answers:, geradas a partir do pacote:

Uma palavra que o arquivo não conhece é um erro na sua linha, nunca ignorada (abaixo). O capítulo 48 lista as chaves sob cada uma destas, em todo nível, e as do gateway.yaml.

Em Python, load("agent.yaml") lê o arquivo num AgentFile: os agentes, as suas ferramentas, os armazenamentos e o rulebook que ele declara. Sem fetch=True, as ferramentas de um servidor MCP são conhecidas pelos nomes que o arquivo lista.

De onde vêm as ferramentas¶

• python: shop.tools pega toda função pública do módulo, importada da pasta onde o arquivo está. O seu esquema vem das suas anotações de tipo.
• mcp: https://tools.internal/mcp pega as ferramentas que um servidor MCP lista, com os seus esquemas e as indicações que o servidor dá: uma ferramenta que o servidor marca como somente leitura lê, uma que ele marca como destrutiva escreve, e uma sobre a qual ele nada diz escreve. tools: [...] mantém só as nomeadas; version: ou digest: fixa o servidor. Cada usuário do seu agente tem uma sessão MCP própria no servidor, para que o que um servidor guarda para um usuário nunca chegue a outro. headers: envia um cabeçalho em toda requisição, com o seu ${NOME} lido do seu ambiente quando a requisição é feita: é assim que um agente atrás de stalwart gateway envia o seu token (capítulo 37).
• openapi: ./crm.yaml faz de cada operação de um documento OpenAPI uma ferramenta: GET e HEAD leem, e qualquer outro método escreve, a menos que a operação diga o contrário em x-stalwart.
• name: refund_card, com palavras ao lado, acrescenta palavras a uma ferramenta de qualquer origem.

O capítulo 21 traz as outras formas de entrada, como as funções exportadas de um projeto TypeScript.

As palavras de uma ferramenta¶

As palavras são o que transforma uma função numa ferramenta que o produto pode governar. Cada uma define um campo do catálogo que as verificações leem:

Você não precisa da maioria delas para começar. Uma leitura não precisa de nenhuma; uma escrita precisa de writes=True; uma escrita que pode ser desfeita precisa de undo=; uma que não pode precisa de irreversible=True. As demais tornam as verificações mais precisas, e o caçador de bugs avisa quando falta uma (capítulo 31).

TOOL_WORDS guarda o nome de cada palavra, para código que escreve o arquivo.

Agentes, privilégio e transferências¶

Um agente pode transferir uma conversa para outro que ele nomeia em hands_off_to. Cada agente tem as suas próprias ferramentas, e só chama essas. privilege diz quanto uma transferência vinda de um agente merece confiança: uma instrução que entrou num agente de baixo privilégio, por um e-mail por exemplo, é marcada quando chega a um de alto privilégio, e uma escrita a que ela leve é confirmada por uma pessoa (capítulo 33).

budget: {max_steps: 15}, num agente ou para o arquivo inteiro, é onde uma execução para: o do próprio agente quando ele diz um, senão o do arquivo, senão 60 passos. Um laço que o modelo conduz pelas suas ferramentas termina ali, e stalwart verify confere que termina (QG023, capítulo 31). max_tool_calls e max_model_calls limitam o que um turno chama: a chamada que passaria do limite não é feita, e o turno para com BudgetSpent, um RunTooLong. Uma confirmação segue com a contagem do seu turno, e um desfazer nunca é contado.

O modelo¶

model: "anthropic:claude-sonnet-5-5" nomeia um provedor e um modelo; a chave é lida do seu ambiente, na variável de costume do provedor, e continua sua. Uma chave que falta é informada antes de qualquer envio, com o nome da variável. Um modelo também pode ser uma função Python comum que recebe a conversa e devolve a resposta. Não guardamos nenhuma credencial de modelo, em lugar nenhum.

O modelo só é chamado onde as suas configurações mandam um turno para ele. Todo turno é lido primeiro pelo seletor, e um turno que nomeia uma ferramenta, que precisa de uma pergunta, ou que é recusado nunca chega ao modelo. Um turno que nada lê recebe um pedido para ser dito de novo, uma vez; depois on_unread decide: refuse, model, ask (a pessoa diz se o modelo pode recebê-lo) ou answer, a partir dos seus documentos (capítulo 44). Sem model, com on_unread: refuse, sem hands_off_to, com respostas a partir das suas formulações e respostas nas próprias frases dos seus documentos, nenhum modelo é chamado jamais (capítulo 45).

Execuções e armazenamento¶

runs: atomic, o padrão, desfaz uma execução que falhou, a última escrita primeiro (capítulo 34). storage: é onde as execuções e as confirmações pendentes ficam guardadas, para que uma confirmação possa ser respondida depois de um reinício, ou em outro processo: sqlite:///runs.db para uma máquina, postgres://... para várias.

Os comandos¶

Gerados a partir do próprio comando stalwart:

Os erros¶

Todo erro que o pacote levanta nomeia o que mudar, nas palavras de agent.yaml, nunca nos termos das bibliotecas por baixo:

Um erro de arquivo nomeia a sua linha:

agent.yaml:7: agent 'desk' lists 'refund', which no tools source declares

Os limites¶

O que o stalwart-agents decide, e o que continua sendo seu:

• Ele decide qual ferramenta um turno nomeia, se uma chamada pode ser executada, se espera por uma pessoa ou se é recusada, o que é desfeito quando uma execução falha, e o que uma resposta pode dizer sobre o que foi feito.
• As suas funções decidem o que fazem. As palavras de uma ferramenta são tomadas como você as declara: uma ferramenta declarada como leitura que escreve é governada como leitura. As verificações de código leem o seu código em busca de problemas de rede e de credenciais, e nada mais sobre o que ele faz (capítulo 46).
• O seu modelo decide o que diz e qual ferramenta pede, onde as suas configurações permitem. Toda chamada que ele pede é verificada; as suas escolhas não são provadas boas (capítulo 31).
• Uma ferramenta alcançável fora do agente pode ser chamada por fora dele. As verificações governam as chamadas que o agente faz; o capítulo 37 põe a mesma verificação na frente das suas ferramentas para todo o resto.

31 · Verificando um agente antes de ele rodar¶

stalwart verify agent.yaml verifica um agente antes de ele atender alguém. Ele lê o seu código na sua máquina, faz o lint do catálogo do agente e compila o seu rulebook, e faz com que toda rota pelos seus agentes seja vasculhada nos nossos servidores em busca de um caminho até uma ferramenta sem a sua verificação, a sua confirmação ou o passo que deve vir antes dela. Ele imprime cada achado com a sua regra, a linha do agent.yaml de onde ele vem, as suas entradas OWASP e a sua correção, e sai com código diferente de zero quando o portão reprova, de modo que funciona na CI como funciona na sua máquina.

O que ele faz, em ordem¶

1. As verificações de código, aqui. Todo arquivo Python da pasta em que está o agent.yaml é lido na sua máquina em busca de problemas de rede e de credenciais, com as ferramentas que o arquivo nomeia tomadas como as funções cujos parâmetros são argumentos de ferramenta. Qualquer achado reprova o portão. Só as suas contagens por regra saem da sua máquina, com a caça (capítulo 46).
2. O catálogo e as regras, aqui. O catálogo -- toda ferramenta com as suas palavras -- é feito a partir do agent.yaml e passa pelo lint do runtime na sua máquina, e o rulebook: do arquivo é compilado nas regras que a verificação de ferramentas aplica, como o agente o compila ao começar. Assim, as regras contra as quais o agente é verificado aqui são as regras sob as quais ele roda. Nenhum lint bloqueia o agente, e nada do agente fica guardado no serviço.
3. A caça, nos nossos servidores. O grafo dos agentes, o catálogo e o rulebook são varridos pelo caçador de bugs como um único job hunt, sob o seu portão. A busca roda nos servidores da Stalwart, nunca na sua máquina. Uma caça que não pôde rodar é um erro, nunca um resultado limpo.
4. O relatório. Os achados são impressos um por bloco, os mais graves primeiro.

O agente da loja do capítulo 30, verificado (o relatório é impresso em inglês):

stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 4 file(s) (rules d656f9ab32d3).

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent: the 2 warnings above are for you to look at and weigh.

Leia de cima para baixo:

• Compiled the rulebook policy.co: as regras que a verificação de ferramentas aplica, compiladas como o agente as compila ao começar. Um rulebook com o qual a verificação de ferramentas não consegue montar um portão vira um lint, que nomeia a sua linha.
• Lints from the runtime: o que o catálogo deixa de dizer, como uma escrita sem desfazer, e duas ferramentas que o seletor não consegue distinguir. Cada um nomeia a ferramenta e o que acrescentar; nenhum faz nada falhar.
• Code checks: os arquivos lidos e a versão das regras com que foram lidos.
• Cada achado: a regra, a sua severidade e a ferramenta, com o arquivo e a linha que a declararam; o que foi encontrado, numa frase; as suas entradas OWASP; e a correção. Aqui QG023 diz que o laço do balcão não tem orçamento além do limite de passos da execução, e QG105 diz que refund_card é uma escrita sem desfazer, numa rota com outra escrita.
• Rules with nothing to read: regras que não levantaram nada porque nada do que elas leem foi declarado (abaixo).
• Gate: passed ou failed. Um achado bloqueia o agente só quando reprova o portão: por padrão, um achado Critical novo -- como uma verificação ausente ou contornável numa ferramenta irreversível ou que declara requires_privilege: high -- e qualquer achado das verificações de código. Todo outro achado é um aviso: não bloqueia o agente, e está ali para você olhar e ponderar. O relatório lista primeiro o que bloqueia, sob o seu próprio título, depois os avisos, e a sua última linha diz com todas as letras se algo bloqueia o agente. O QG023 e o QG105 do agente da loja são avisos, então ele passa.

O status com que o comando sai, gerado a partir do próprio comando:

--keep DIR escreve numa pasta o que foi verificado: agent.graph.json, o grafo dos agentes como o caçador o leu; agent.catalogue.json, o catálogo; e agent.findings.json, o documento de achados. Todas as opções:

As perguntas que ele responde para cada ferramenta¶

Para cada ferramenta, em cada rota pelos seus agentes, até a profundidade declarada, a caça pergunta:

• Ela pode rodar sem a sua verificação, ou a verificação pode ser contornada? Ao longo de vários turnos, uma aprovação dada num turno pode ser gasta em outro?
• Uma escrita pode rodar carregando uma marca de fora -- um e-mail, uma página da web, outro agente com menos privilégio -- sem ninguém confirmá-la?
• Um passo irreversível pode vir antes de passos que serão desfeitos se a execução falhar, sem que a sua confirmação diga isso?
• Uma ferramenta pode rodar fora da ordem declarada?
• Uma rota pode ir a qualquer lugar, porque nada declara aonde ela pode ir?
• Uma escrita pode ficar sem ser desfeita, porque nada a desfaz e nada diz que ela não pode ser desfeita?

Cada pergunta é uma regra, e cada regra tem a sua página:

Por que cada uma importa, e como corrigi-la:

• QG001 Missing check: a ferramenta é alcançável e nada nas regras a relaciona com a sua verificação, então uma conversa que chega a ela chega a ela não importa o que a verificação diria. Acrescente a verificação como condição em toda rota até a ferramenta.
• QG002 Escapable guard: a verificação existe, e outra coisa a satisfaz: um segundo fluxo até a mesma ferramenta, um ramo que escapa. Aplique o patch que o achado nomeia dentro de todo fluxo que ele nomeia.
• QG003 Multi-turn escape: uma verificação lida uma vez e usada depois. Leia a verificação no mesmo turno da chamada, ou leve-a junto com a chamada que ela aprovou, e verifique de novo na mesma profundidade.
• QG011 Confused deputy: um valor de fora chegou ao modelo, e uma rota deixa esse modelo chamar uma ferramenta privilegiada sem que uma pessoa a confirme. Coloque a ferramenta no passo de ferramentas protegido, para que uma chamada que carrega a marca seja confirmada ou recusada; marque como reads_outside a ferramenta que lê o exterior, onde ela ainda não estiver marcada.
• QG012 Cascading injection: o mesmo, quando a marca entrou num agente e a chamada é feita por outro depois de uma transferência. Coloque a ferramenta no passo de ferramentas protegido do agente que age, ou confirme a transferência.
• QG013 Irreversible before undoable: se um passo posterior falhar, a execução é desfeita, e o passo irreversível continua feito; a pessoa que o aprovou não foi avisada. Mova o passo irreversível para o fim, ou deixe que a sua confirmação diga que os passos depois dele não podem desfazê-lo.
• QG014 Order rule escapable: uma ferramenta declarada after, not_after ou at_most roda onde a sua regra não é verificada. Coloque a ferramenta no passo de ferramentas protegido, onde as regras de ordem são verificadas sobre o histórico da sessão.
• QG015 Undeclared route: veja uma rota não declarada.
• QG016 Unmodelled path: uma campanha de ataque fez uma chamada privilegiada em agentes que a caça achou limpos, então o que roda e o que foi verificado discordam. Nada que este produto relata é mais urgente: verifique de novo a partir do que roda, e compare o rastro do atacante com o grafo verificado (capítulo 33).
• QG105 Unrecoverable write: uma escrita sem desfazer, não marcada como irreversível, numa rota com outra escrita; uma execução que falha não consegue desfazê-la, e nada diz isso. Declare o seu undo -- que pode ser a própria ferramenta com os argumentos trocados -- ou undo: none onde uma execução que falha pode deixá-la feita, ou marque-a irreversible para que uma pessoa a confirme sabendo disso (capítulo 34).

Um grafo descrito por agent.yaml coloca toda ferramenta no passo de ferramentas protegido, onde cada chamada é verificada e cada escrita é confirmada, então a maioria dessas regras não encontra nada nele; elas encontram o que os passos escritos por uma equipe deixam aberto (capítulo 27). As regras sobre o que as suas declarações dizem estão abaixo.

Lendo um achado e a sua testemunha¶

A testemunha de um achado é a execução que chega à ferramenta: os passos, em ordem, que a caça encontrou. O documento de achados que o --keep escreve a guarda sob detail. Aqui está o QG011 que o grafo próprio do E16 levanta em refund_card, com os campos que esta seção lê:

{
  "rule": "QG011",
  "title": "Confused deputy",
  "severity": "critical",
  "action": "refund_card",
  "control": "a confirmation",
  "obligation": "taint:refund_card:untrusted:read_inbox",
  "reproduction": "not_yet_replayed",
  "detail": {
    "witness_path": [
      "1.0 __start__",
      "1.1 model",
      "1.2 tools",
      "1.3 model",
      "1.4 tools"
    ],
    "code_flow": [
      {
        "message": "step 1.0: the graph visits __start__"
      },
      {
        "message": "step 1.1: the graph visits model"
      },
      {
        "message": "step 1.2: the graph visits tools"
      },
      {
        "message": "step 1.3: the graph visits model"
      },
      {
        "message": "step 1.4: the graph visits tools"
      }
    ],
    "fix": "Bind 'refund_card' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it."
  }
}

Leia passo a passo. O número de um passo é turno.passo: 1.2 é o segundo passo do primeiro turno.

1. 1.0 __start__: chega o turno da pessoa.
2. 1.1 model: o modelo o lê e pede uma ferramenta.
3. 1.2 tools: o passo de ferramentas roda read_inbox. O que ela devolve vem de fora, e é marcado untrusted:read_inbox.
4. 1.3 model: o modelo lê o e-mail e pede refund_card. O seu pedido carrega a marca.
5. 1.4 tools: refund_card roda, carregando a marca, e nada a confirma: o passo de ferramentas próprio desta equipe não é o protegido.

detail.code_flow dá uma mensagem por passo, na linha que declarou o passo, para que uma tela de code scanning mostre o mesmo caminho. Os outros campos:

• control: o que faltou no caminho -- aqui, uma confirmação;
• obligation: o que a caça decidiu, com nome: taint:refund_card:untrusted:read_inbox é "refund_card nunca roda carregando untrusted:read_inbox sem confirmação";
• detail.fix: a mudança que fecha o caminho;
• reproduction: not_yet_replayed até a testemunha ser reproduzida (abaixo).

A correção fecha o caminho no seu último passo: uma pessoa vê o reembolso, com cada argumento e de onde veio o seu valor, e a frase de que ele foi proposto depois de ler um e-mail de fora (capítulo 33).

A profundidade da verificação¶

Um resultado limpo vale até uma profundidade declarada, e o documento de achados a declara, sob scan.obligations.graph. Para o agente da loja:

verify("agent.yaml", keep="kept")          # como `stalwart verify agent.yaml --keep kept`

kept = json.loads(Path("kept/agent.findings.json").read_text(encoding="utf-8"))
print(json.dumps(kept["scan"]["obligations"]["graph"], indent=2))

{
  "total": 12,
  "decided": 12,
  "steps": 60,
  "turns": 3,
  "replay": "not replayed: the hunter reads the export, not the code that built it; each finding's witness_path is the run to reproduce"
}

• total e decided: quantas perguntas a caça fez a este grafo, e quantas decidiu. Onde diferem, as restantes são listadas em scan.undecided, e nada é afirmado sobre elas.
• steps: o máximo de passos que uma execução pode dar, 60 aqui, o limite de passos do agente. Toda rota é vasculhada até ele.
• turns: por quantos turnos da pessoa uma rota é seguida, 3 aqui. Uma aprovação dada num turno e gasta num turno posterior é encontrada dentro deles (QG003).

Então "nenhum caminho" significa nenhum caminho dentro de 60 passos e três turnos. A Verificação de Grafos de Agentes, que verifica um grafo que você mesmo envia, declara a profundidade que vasculhou na sua linha [UNROLL] (capítulo 47).

Reproduzindo uma testemunha¶

stalwart verify --replay reproduz a testemunha de cada achado de grafo nos seus próprios agentes, com toda ferramenta substituída por um stub que registra as suas chamadas e devolve dados de exemplo, e um modelo roteirizado que faz exatamente as escolhas da testemunha. As verificações rodam como rodam em produção. Um achado é reproduced quando a execução segue o caminho da testemunha e a sua ferramenta é chamada. Um que não se reproduz significa que a caça e os agentes que rodam discordam: ele é listado primeiro, e reprova o portão. Cada reprodução é registrada como digests e o seu resultado, nunca o seu rastro.

O que você pode declarar sobre as suas ferramentas¶

Cada declaração é opcional, e cada uma é lida por uma ou mais regras. Uma regra cuja declaração falta não levanta nada -- veja Uma declaração ausente esconde a sua regra.

No agent.yaml, as palavras ficam sob o nome da ferramenta; em Python, são argumentos de @tool(...). O registro de um servidor MCP é uma entrada de tools que nomeia o servidor e as ferramentas que ele serve, com a version ou o digest do servidor quando você o fixa.

O runtime dá a essas declarações quatro lints, e nenhum deles faz nada falhar.

Outros lints leem o que todo catálogo declara, e não essas declarações: uma escrita sem esquema de resultado ou de argumentos, uma ferramenta irreversível que não pede confirmação, duas ferramentas que o seletor não consegue distinguir, um nome que o leitor toma por gramática, uma função TypeScript marcada sem @read nem @write, e código de ferramenta reprovado nas verificações de código. Os quatro últimos são erros: corrija-os antes de o agente atender alguém.

As regras que as leem¶

Cada regra decide uma pergunta sobre todo caminho que o grafo ou a política permite, e declara o seu limite: o que decide e o que não decide.

QG022, o rail com um aviso publicado, está no capítulo 28.

Toda entrada OWASP que um achado carrega é uma afirmação no nível da política: a parte do risco que as suas regras e o seu catálogo controlam. Uma varredura limpa sob uma entrada significa nenhum achado no nível da política, não que o risco esteja ausente. A única entrada que nenhuma regra cobre é LLM05:2026 Data and Model Poisoning: uma propriedade dos dados de treinamento e dos pesos do modelo, que nenhuma política de guardrail decide (capítulo 28).

Exemplo E16: o agente da loja cresce¶

O agente da loja ganha novas ferramentas, cada uma com a sua declaração:

• run_report, cujo argumento sql é declarado sql e é escrito pelo modelo;
• get_customer, confidential: subject com subject_argument: customer_id, cujo registro o send_receipt pode levar;
• search_help, sobre um armazenamento multi_tenant, delimitado por um tenant_id que o modelo escreve, servido por um servidor MCP registrado sem versão nem digest;
• remember_note, persists: notes, alcançável depois de read_inbox, e recall_notes, que lê as notas de volta antes de refund_card;
• o balcão billing, transformado num agente remoto sobre a2a sem autenticação;
• e nenhum orçamento no laço do balcão.

agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"
    tools: [get_order, run_report, get_customer, send_receipt, search_help, read_inbox, remember_note, recall_notes, refund_card]
    hands_off_to: [billing]
  billing:
    privilege: high
    tools: [issue_refund]
    remote: {transport: a2a, authentication: none}
tools:
  - name: get_order
    schema: {type: object, properties: {order_id: {type: string}}}
  - name: run_report
    argument_kinds: {sql: sql}
    schema: {type: object, properties: {sql: {type: string}}}
  - name: get_customer
    confidential: subject
    subject_argument: customer_id
    schema: {type: object, properties: {customer_id: {type: string}}}
  - name: send_receipt
    writes: true
    sends_out: true
    schema: {type: object, properties: {order_id: {type: string}, body: {type: string}}}
  - mcp: https://help.internal/mcp
    tools: [search_help]
  - name: search_help
    retrieves: {store: help, scope_argument: tenant_id}
    schema: {type: object, properties: {tenant_id: {type: string}, query: {type: string}}}
  - name: read_inbox
    reads_outside: true
    schema: {type: object, properties: {folder: {type: string}}}
  - name: remember_note
    writes: true
    persists: notes
    schema: {type: object, properties: {note: {type: string}}}
  - name: recall_notes
    retrieves: {store: notes}
    schema: {type: object, properties: {topic: {type: string}}}
  - name: refund_card
    writes: true
    requires_privilege: high
    schema: {type: object, properties: {order_id: {type: string}}}
  - name: issue_refund
    writes: true
    schema: {type: object, properties: {order_id: {type: string}}}
stores:
  help: {multi_tenant: true}
  notes: {persistent: true}

O stalwart verify lê o arquivo, monta os agentes que ele descreve -- o modelo do balcão, o passo de ferramentas protegido em que estão as suas ferramentas e uma transferência para billing -- e imprime (o caçador imprime em inglês):

stalwart verify agent.yaml

Lints from the runtime (none of these blocks the agent):
  argument_kind_suggested (info) on search_help: query: the name suggests an argument the tool interprets; declare its kind in argument_kinds if it is one
  write_not_retry_safe (warning) on issue_refund: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on issue_refund: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on remember_note: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on remember_note: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on send_receipt: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported

Code checks: no finding in 1 file(s) (rules d656f9ab32d3).

Warnings: 10 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG018 High on run_report (agent.yaml:4)
  'run_report' can run with its sql argument 'sql' written by the model or carrying a trust label, and nothing confirms the call
  OWASP LLM10:2026, LLM01:2026
  Fix: Bound 'sql' in the tool's schema with an enum, a const or a pattern; or take it from the user's typed text, the host's context or an earlier tool's result, and bind it so in the export's `arguments`; or put the call behind a confirmation -- the guarded tool node or an interrupt().

QG019 High on reply
  the reply can carry a confidential value to someone its audience does not include: a record for nobody outside the company, or one whose subject the host's context did not choose -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Bind each confidential read's subject argument to the authenticated principal in the host's context, or remove the confidential fields from the context before the reply.

QG020 High on search_help (agent.yaml:4)
  'search_help' retrieves from the multi-tenant store 'help' with its scope taken from something other than the authenticated principal
  OWASP LLM09:2026, LLM02:2026
  Fix: Take the scope argument of 'search_help' from the host's context -- the authenticated tenant or user -- and bind it so in the export's `arguments`.

QG023 Medium on cycle:desk_model (agent.yaml:2)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on issue_refund (agent.yaml:8)
  the write 'issue_refund' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'issue_refund' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on refund_card (agent.yaml:4)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on remember_note (agent.yaml:4)
  the write 'remember_note' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'remember_note' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on send_receipt (agent.yaml:4)
  the write 'send_receipt' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'send_receipt' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG106 Review on the MCP server https://help.internal/mcp (agent.yaml:24)
  'search_help' runs code from the MCP server https://help.internal/mcp with no version and no digest, so it can change without the catalogue changing
  OWASP LLM04:2026, ASI04:2026
  Fix: Pin the MCP server https://help.internal/mcp: give its `mcp:` entry in agent.yaml a `version:` (an exact version) or a `digest:`, or its `server` in the catalogue; or accept the hotspot with the reason.

QG107 Review on desk -> billing (agent.yaml:2)
  the hand-off from 'desk' to 'billing' reaches 'billing' over a2a with authentication: none: nothing shows the far side is the agent it claims to be
  OWASP ASI07:2026
  Fix: Declare and use mtls, oauth2 or signed_messages on the channel to 'billing', or accept the hotspot with the layer that authenticates it.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG022: no Colang policy and no rails config was scanned

Gate: passed. Nothing blocks this agent: the 10 warnings above are for you to look at and weigh.

Os agentes que o agent.yaml descreve colocam toda ferramenta no passo de ferramentas protegido, onde uma escrita só roda com a sua confirmação. Por isso eles não levantam QG021 nem QG019 por meio de send_receipt: a confirmação é a correção que essas regras pedem, e ela já está lá. Uma equipe que escreve os seus próprios passos, com as mesmas ferramentas num passo de ferramentas que não verifica nada, as vê. Aqui está o mesmo catálogo com as ferramentas do balcão num passo assim:

stalwart verify desk graph

Blocking: 3 findings that block this agent until fixed, or accepted with its reason:

QG001 Critical on refund_card
  'refund_card' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'refund_card' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG011 Critical on refund_card
  the privileged 'refund_card' can run carrying the label untrusted:read_inbox with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'refund_card' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it.

QG011 Critical on refund_card
  the privileged 'refund_card' can run carrying the label untrusted:recall_notes with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'refund_card' to the guarded tool node so a call carrying the label (untrusted:recall_notes) is confirmed or refused, or add a confirmation before it.

Warnings: 22 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG001 High on remember_note
  'remember_note' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'remember_note' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 High on send_receipt
  'send_receipt' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'send_receipt' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG011 High on remember_note
  the privileged 'remember_note' can run carrying the label untrusted:read_inbox with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'remember_note' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it.

QG011 High on send_receipt
  the privileged 'send_receipt' can run carrying the label untrusted:recall_notes with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'send_receipt' to the guarded tool node so a call carrying the label (untrusted:recall_notes) is confirmed or refused, or add a confirmation before it.

QG011 High on remember_note
  the privileged 'remember_note' can run carrying the label untrusted:recall_notes with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'remember_note' to the guarded tool node so a call carrying the label (untrusted:recall_notes) is confirmed or refused, or add a confirmation before it.

QG011 High on send_receipt
  the privileged 'send_receipt' can run carrying the label untrusted:read_inbox with no confirmation or refusal
  OWASP LLM01:2026, LLM03:2026, ASI01:2026, ASI02:2026
  Fix: Bind 'send_receipt' to the guarded tool node so a call carrying the label (untrusted:read_inbox) is confirmed or refused, or add a confirmation before it.

QG018 High on run_report
  'run_report' can run with its sql argument 'sql' written by the model or carrying a trust label, and nothing confirms the call
  OWASP LLM10:2026, LLM01:2026
  Fix: Bound 'sql' in the tool's schema with an enum, a const or a pattern; or take it from the user's typed text, the host's context or an earlier tool's result, and bind it so in the export's `arguments`; or put the call behind a confirmation -- the guarded tool node or an interrupt().

QG019 High on send_receipt
  'send_receipt' sends data out of the host while the session holds a confidential value, and nothing confirms the call -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Confirm the call to 'send_receipt' -- on the guarded tool node or with an interrupt() -- or remove the confidential fields from the context before it.

QG019 High on reply
  the reply can carry a confidential value to someone its audience does not include: a record for nobody outside the company, or one whose subject the host's context did not choose -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Bind each confidential read's subject argument to the authenticated principal in the host's context, or remove the confidential fields from the context before the reply.

QG020 High on search_help
  'search_help' retrieves from the multi-tenant store 'help' with its scope taken from something other than the authenticated principal
  OWASP LLM09:2026, LLM02:2026
  Fix: Take the scope argument of 'search_help' from the host's context -- the authenticated tenant or user -- and bind it so in the export's `arguments`.

QG021 High on remember_note
  'remember_note' can write to the persistent store 'notes' while the session carries content from outside, and nothing confirms the write
  OWASP ASI06:2026, LLM01:2026
  Fix: Confirm the write to 'notes', strip or refuse labelled values before it, or declare the store not persistent if it is not.

QG001 Medium on get_customer
  'get_customer' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'get_customer' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on get_order
  'get_order' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'get_order' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on read_inbox
  'read_inbox' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'read_inbox' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on run_report
  'run_report' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'run_report' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on recall_notes
  'recall_notes' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'recall_notes' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG001 Medium on search_help
  'search_help' can run on a plain tool node, without the tool check
  OWASP LLM03:2026, ASI02:2026
  Fix: Bind 'search_help' to the guarded tool node (StalwartToolNode) in place of the plain tool node, so every call to it is checked.

QG023 Medium on cycle:model (run_e16.py:48)
  the cycle through 'model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 25 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on remember_note
  the write 'remember_note' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'remember_note' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on send_receipt
  the write 'send_receipt' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'send_receipt' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG106 Review on the MCP server https://help.internal/mcp
  'search_help' runs code from the MCP server https://help.internal/mcp with no version and no digest, so it can change without the catalogue changing
  OWASP LLM04:2026, ASI04:2026
  Fix: Pin the MCP server https://help.internal/mcp: give its `mcp:` entry in agent.yaml a `version:` (an exact version) or a `digest:`, or its `server` in the catalogue; or accept the hotspot with the reason.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG022: no Colang policy and no rails config was scanned
  QG107: no agent in the catalogue declares a remote channel

Gate: failed. This agent is blocked by the 3 blocking findings above. The warnings do not block it.

O QG011 em refund_card por meio de recall_notes vem do armazenamento: até que toda escrita em notes seja provada limpa, o que recall_notes lê de volta é não confiável, e a chamada privilegiada que ele alimenta é um confused deputy (capítulo 33).

Uma declaração ausente esconde a sua regra¶

O mesmo agente sem o tipo sql em run_report:

stalwart verify agent.yaml

Lints from the runtime (none of these blocks the agent):
  argument_kind_suggested (info) on search_help: query: the name suggests an argument the tool interprets; declare its kind in argument_kinds if it is one
  argument_kind_suggested (info) on run_report: sql: the name suggests an argument the tool interprets; declare its kind in argument_kinds if it is one
  write_not_retry_safe (warning) on issue_refund: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on issue_refund: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on remember_note: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on remember_note: a write with no result schema, so its outcome could not be reported
  write_not_retry_safe (warning) on send_receipt: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported

Code checks: no finding in 0 file(s) (rules d656f9ab32d3).

Warnings: 9 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG019 High on reply
  the reply can carry a confidential value to someone its audience does not include: a record for nobody outside the company, or one whose subject the host's context did not choose -- through the tool calls and replies the policy routes
  OWASP LLM02:2026, LLM08:2026
  Fix: Bind each confidential read's subject argument to the authenticated principal in the host's context, or remove the confidential fields from the context before the reply.

QG020 High on search_help (agent.yaml:4)
  'search_help' retrieves from the multi-tenant store 'help' with its scope taken from something other than the authenticated principal
  OWASP LLM09:2026, LLM02:2026
  Fix: Take the scope argument of 'search_help' from the host's context -- the authenticated tenant or user -- and bind it so in the export's `arguments`.

QG023 Medium on cycle:desk_model (agent.yaml:2)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on issue_refund (agent.yaml:8)
  the write 'issue_refund' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'issue_refund' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on refund_card (agent.yaml:4)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on remember_note (agent.yaml:4)
  the write 'remember_note' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'remember_note' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG105 Review on send_receipt (agent.yaml:4)
  the write 'send_receipt' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'send_receipt' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

QG106 Review on the MCP server https://help.internal/mcp (agent.yaml:23)
  'search_help' runs code from the MCP server https://help.internal/mcp with no version and no digest, so it can change without the catalogue changing
  OWASP LLM04:2026, ASI04:2026
  Fix: Pin the MCP server https://help.internal/mcp: give its `mcp:` entry in agent.yaml a `version:` (an exact version) or a `digest:`, or its `server` in the catalogue; or accept the hotspot with the reason.

QG107 Review on desk -> billing (agent.yaml:2)
  the hand-off from 'desk' to 'billing' reaches 'billing' over a2a with authentication: none: nothing shows the far side is the agent it claims to be
  OWASP ASI07:2026
  Fix: Declare and use mtls, oauth2 or signed_messages on the channel to 'billing', or accept the hotspot with the layer that authenticates it.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG022: no Colang policy and no rails config was scanned

Gate: passed. Nothing blocks this agent: the 9 warnings above are for you to look at and weigh.

Nenhum QG018: a regra não tem nada para ler. O registro avisa que pode faltar uma declaração (argument_kind_suggested), e o resumo lista a regra como não tendo tido nada para ler. Uma declaração ausente esconde a sua regra -- a varredura fica limpa daquilo que não lhe foi dito, e diz isso.

Uma rota não declarada¶

Uma rota é para onde uma execução pode ir depois de um passo. No agent.yaml toda rota é declarada: um agente vai às suas ferramentas, volta ao seu modelo, ou vai a um agente que ele nomeia em hands_off_to, e a nenhum outro lugar. Um passo que uma equipe escreve em código pode escolher para onde ir em seguida com uma função que lê o que o modelo disse. Se nada declara os lugares que ela pode escolher, a caça precisa supor que ela pode escolher qualquer passo -- passando por cima de toda verificação que o desenho põe no caminho. Isso é QG015, e todo caminho que ela abre a nomeia, então uma única correção fecha todos: declare aonde a rota pode ir.

O portão na CI¶

O stalwart verify sai com 1 quando o portão reprova e com 3 quando nada pôde ser verificado, então um passo de CI que o roda para em qualquer dos dois. Guarde os achados com --keep e envie-os como o registro da execução; o capítulo 46 tem o workflow.

Os limites¶

• Uma varredura limpa não encontrou caminho até uma ferramenta sem a sua verificação, a sua confirmação ou o passo que deve vir antes, até a profundidade declarada. Ela não mostra que o modelo escolhe bem, e as suas próprias funções são lidas como capazes de fazer qualquer coisa.
• A profundidade é a que o documento de achados declara: o limite de passos da execução e o número de turnos. Um caminho mais longo do que qualquer dos dois não é vasculhado.
• O caçador decide para onde vai um valor escrito pelo modelo, não o que a sua ferramenta faz com ele.
• Uma regra cuja declaração falta não levanta nada; o resumo a lista como não tendo tido nada para ler.
• Uma declaração sua -- sandboxed, sanitised_by, uma autenticação num canal -- é aceita como declarada e listada entre as suposições da varredura; o caçador não a verifica.

45 · Protegido e provado¶

Um agente do stalwart-agents é protegido enquanto roda e provado antes de rodar. Duas verificações cercam o seu modelo, ambas decididas por código nativo na sua máquina -- o runtime licenciado que o pacote traz -- e nunca por um modelo: o roteador decide se o modelo é chamado, e a verificação de ferramentas decide cada chamada. Antes do primeiro turno do agente, o caçador de bugs examina o seu grafo em busca de um caminho que passe por fora de qualquer uma das duas. Este capítulo é como as duas verificações decidem, o que isso garante e como a prova roda.

Duas verificações e uma prova¶

1. O roteador lê cada turno antes que qualquer modelo o veja (abaixo).
2. A verificação de ferramentas decide cada chamada de ferramenta, tenha sido escolhida pelo roteador ou pelo modelo (abaixo).
3. A prova examina cada rota pelos seus agentes em busca de um caminho até uma ferramenta sem a sua verificação, a sua confirmação ou a etapa que ela precisa seguir (abaixo).

A API hospedada não decide nada enquanto o seu agente roda. Onde o runtime não consegue responder, um plano ou uma verificação levanta SelectorUnavailableError e a chamada não é feita: o agente nunca recorre a uma chamada não verificada.

O roteador: se um modelo é chamado¶

Cada turno é lido num plano a partir do que as suas ferramentas declaram. Para onde o turno vai, gerado a partir do próprio roteador:

Um turno que nada lê recebe uma vez o pedido para ser dito de novo. Depois disso, o on_unread do agente decide:

Onde um agente não diz nada, cada conversa adota no seu primeiro turno a configuração da página Configurações do seu console, ou refuse.

Quando nenhum modelo é chamado¶

O roteador responde aos turnos que lê sem modelo. Um modelo só é chamado onde as suas configurações enviam um turno para ele, então nenhum modelo é chamado quando tudo isto vale:

• os agentes não nomeiam nenhum model;
• on_unread é refuse, ou answer com o compositor extract (capítulo 44);
• nenhum agente tem hands_off_to;
• as respostas são as suas formulações: replies: {composer: template} (capítulo 42).

A verificação de ferramentas: cada chamada, quem quer que a tenha escolhido¶

A verificação roda no runtime, uma vez por chamada, com o catálogo, o rulebook e o histórico da sessão, e a primeira regra que se aplica decide. As regras, na ordem em que o runtime as toma (o capítulo 32 dá o exemplo de cada uma):

Ela dá uma de três respostas:

• allow: a ferramenta roda uma vez, com uma chave de idempotência.
• confirm: uma pessoa é perguntada, vendo cada argumento e de onde veio o seu valor; a chamada é verificada de novo com o token assinado que a aprovação dela carrega (capítulo 35).
• refuse: nada roda. Onde etapas anteriores da execução já tinham escrito algo, essas escritas são desfeitas, a última primeiro (capítulo 34).

O que é garantido, e o que não é¶

Garantido. Uma chamada recusada não roda nada. Uma chamada confirmada roda só com os argumentos exatos que a pessoa viu. O histórico não pode ser descartado, editado ou reordenado sem que a verificação diga history_invalid. Nenhum modelo é chamado a menos que as suas configurações encaminhem um turno a ele.

Não garantido. A verificação julga nomes, schemas, marcas e o histórico, nunca o que uma resposta significa (o capítulo 42 confere as respostas com o que foi feito). Uma ferramenta alcançável por fora do agente pode ser chamada contornando a verificação, a menos que o gateway fique na frente dela. Agent(..., verify=False) pula a prova.

O rulebook sob o qual ele roda¶

O rulebook: de um agente -- Colang 1.0 ou 2.x, uma planilha de regras ou a pasta que o stalwart rules compile escreveu -- é aquilo contra o que o seu grafo é provado e o que a sua verificação de ferramentas aplica, de modo que as regras provadas são as regras sob as quais o agente roda:

• Na inicialização, antes do primeiro turno, o agente compila o seu rulebook no registro que a verificação de ferramentas avalia (POST /v1/rulebooks/compile, ou POST /v1/rule-sheets/compile para uma planilha), uma vez para o seu cliente; uma pasta que o stalwart rules compile escreveu é lida como está, sem chamada. Nada fica guardado no serviço: toda verificação leva o registro ao lado do catálogo do agente.
• stalwart verify o compila do mesmo jeito e prova o grafo contra ele (capítulo 46).
• Onde ele não pode ser compilado -- sem serviço, um rulebook que o compilador recusa (rulebook_unsupported, nomeando a linha), ou uma organização que só envia registros compilados (policy_input_refused) -- o agente não roda. Ele levanta RulebookNotHeld, dizendo por quê.

Os dois balcões da loja, com um rulebook que só deixa um reembolso rodar para um pedido que está pago:

define user ask refund
  "estorne o pedido 4411"
  "devolva o dinheiro do cliente"

define flow refunds
  user ask refund
  if $order_paid
    execute refund_card
  else
    bot refuse

# As duas centrais da loja, com um rulebook que decide quando um estorno pode rodar.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools
rulebook: ./policy.co                      # provado contra ele, e compilado para a verificação de ferramentas

A verificação de ferramentas decide sob ele, com o contexto que a sua aplicação fornece:

desk = Agent.from_file("agent.yaml")
catalogue = desk.catalogue()                    # as ferramentas dos dois balcões, feitas nesta máquina
rulebook = desk.rules().record                  # policy.co, compilado uma vez para este agente
with Client() as client:
    billing = client.session("billing", catalogue=catalogue, rulebook=rulebook)
    billing.read("estorne 40,00 do pedido 4411")
    for paid in (False, True):
        check = billing.check_tool_call("refund_card", {"order_id": "4411", "amount": 40.00},
                                        origins={"order_id": "typed", "amount": "typed"},
                                        context={"order_paid": paid})
        print(f"order_paid {paid}:", check.decision, ", ".join(check.reasons), check.detail.get("flow", ""))

order_paid False: refuse refuse refunds
order_paid True: confirm write 

O reembolso do pedido não pago é recusado pelo fluxo refunds do rulebook; o do pedido pago passa pelo rulebook e é confirmado, como toda escrita é.

As ações de um rulebook nomeiam ferramentas com execute <ferramenta>, como faz o fluxo refunds, ou com bot execute_<ferramenta>, a mesma chamada escrita como o registro a nomeia. Qualquer outra linha bot é algo que o bot diz, não uma chamada de ferramenta.

Os fatos do rulebook¶

Uma regra como if $order_paid lê um fato: verdadeiro ou falso, por nome, enviado com cada verificação. Um fato que nada informa é falso, então a regra recusa. Há dois jeitos de informar um, e um agente pode usar os dois:

• O seu código diz, quando a sua aplicação sabe: Agent.from_file("agent.yaml", context=...), ou Agent(..., context=...), recebe os fatos como um mapeamento, ou como uma função do usuário que os devolve, chamada a cada verificação para dá-los como estão naquele momento. Uma verificação feita pelo cliente ou por uma sessão recebe context= em cada chamada (capítulo 24).
• A própria ferramenta do agente diz: facts: no agent.yaml, ou Agent(..., facts=...), lê um fato de um campo do resultado de uma ferramenta, na resposta mais recente dessa ferramenta na conversa. A loja lê os seus dois fatos de get_order (capítulo 30):

facts:
  card_on_file: {from: get_order.card, same: order_id}
  order_paid: {from: get_order.status == paid, same: order_id}

from é <ferramenta>.<campo>, verdadeiro quando o campo é verdadeiro, um número diferente de 0, ou um texto, lista ou mapeamento não vazio; ou <ferramenta>.<campo> == <valor>, verdadeiro quando o campo é igual ao valor. Até a ferramenta responder, o fato é falso, então a cobrança da loja só é permitida depois que mostre o pedido 4411 mostrou um cartão.

same: order_id amarra o fato à chamada verificada: só conta uma resposta de get_order para o pedido que a chamada nomeia, então o status de um pedido nunca permite o reembolso de outro. Deixe-o de fora só para um fato sobre a conversa como um todo, como a conta do usuário. Um fato nunca é lido de uma ferramenta que reads_outside: qualquer um poderia escrever o que ela devolve. Onde o seu código e o arquivo informam o mesmo fato, vale o do arquivo.

A prova¶

Os agentes são compilados num grafo (qls-graph/1) e no seu catálogo. Cada obrigação -- esta ferramenta nunca roda sem a sua verificação, esta escrita nunca roda sem confirmação depois de ler algo de fora -- é uma pergunta que o caçador responde sobre cada rota:

• alcançável: um achado, com um caminho testemunha mapeado de volta à linha do agent.yaml (capítulo 31);
• inalcançável: a obrigação vale, até a profundidade declarada (capítulo 31);
• indeciso: relatado como indeciso, nunca como limpo.

Ela roda de três formas:

• Automaticamente. Agent(..., verify=True), o padrão, prova o grafo no nosso serviço antes do primeiro turno, uma vez por grafo: uma reconstrução do mesmo grafo é respondida pelo cache. Um achado do tipo Vulnerabilidade levanta NotVerified, com os achados, e nada roda. Uma prova que não pôde rodar também levanta, nunca dá um resultado limpo.
• Como portão de CI. stalwart verify agent.yaml faz o lint, compila, caça e imprime o relatório, e sai com 1 quando o portão reprova (capítulo 46). O agente da loja do capítulo 30:

$ stalwart verify agent.yaml
stalwart verify agent.yaml

Compiled the rulebook policy.co: the tool check enforces the rules verified here.
Lints from the runtime (none of these blocks the agent):
  write_not_retry_safe (warning) on charge_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on charge_card: a write with no result schema, so its outcome could not be reported
  compensation_not_retry_safe (warning) on charge_card: 'refund_card' undoes it and is not retry-safe
  write_not_retry_safe (warning) on refund_card: a write with no idempotency, so an ambiguous failure goes to a person
  write_without_result_schema (warning) on refund_card: a write with no result schema, so its outcome could not be reported
  write_without_result_schema (warning) on send_receipt: a write with no result schema, so its outcome could not be reported
  compensation_out_of_reach (warning) on charge_card: agent 'desk' can call it but not 'refund_card', which undoes it, so a run of that agent cannot undo it

Code checks: no finding in 4 file(s) (rules d656f9ab32d3).

Warnings: 2 findings that do not block this agent. Look at each and weigh it; the agent can run as it is.

QG023 Medium on cycle:desk_model (agent.yaml:3)
  the cycle through 'desk_model' calls the model or a tool, and nothing declares a budget: the framework's recursion limit of 60 is the run's only ceiling
  OWASP LLM06:2026, ASI08:2026
  Fix: Declare a budget for the agent or the run, or add an exit the model cannot avoid -- a counter in the state, declared on the edge as exit_after.

QG105 Review on refund_card (agent.yaml:10)
  the write 'refund_card' has no compensation, is not irreversible, and runs on a path with another write
  OWASP LLM03:2026, ASI08:2026
  Fix: Give 'refund_card' an undo -- `undo:` in agent.yaml or `compensation` in the catalogue, which may be the tool itself with its arguments swapped -- or say a failed run may leave it done (`undo: none`), or mark it irreversible.

Rules with nothing to read, so nothing raised:
  QG017: no argument is declared as code or a shell command
  QG018: no argument is declared as SQL, a query, a path, a URL or a template
  QG019: no tool is declared confidential
  QG020: no retrieval from a store declared multi-tenant
  QG021: no tool is declared to write a store declared persistent
  QG106: no tool declares a source or a server, and the catalogue declares no modules
  QG107: no agent in the catalogue declares a remote channel

Gate: passed. Nothing blocks this agent: the 2 warnings above are for you to look at and weigh.
$ echo $?
0

• Pela API. Client().verify_graph(graph, catalogue=..., rulebook=..., session_steps=...) envia o grafo que desk.export() devolve e o catálogo que desk.catalogue() devolve, como um job graph (capítulo 47).

As regras que ela prova¶

Cada regra que a caça do grafo e do rulebook de um agente levanta, gerada a partir do catálogo do caçador. Reprova o portão é aquilo a que o stalwart verify submete um build; impede o Agent(...) é aquilo com que a prova automática se recusa a rodar:

A página de cada regra diz o que ela prova e o que não prova.

Os limites¶

• Um modelo escolhe livremente. A prova lê uma etapa de modelo como capaz de escolher qualquer ferramenta e qualquer argumento que receba; as verificações seguram o que ele escolhe, e nada prova que as escolhas dele sejam boas.
• Etapas que não são nossas são opacas. Uma etapa que a sua equipe escreve é lida como capaz de fazer tudo o que as rotas declaradas dela permitem (capítulo 31).
• Uma prova limpa vale até a profundidade que declara: o limite de etapas da execução e o número de turnos que o documento de achados nomeia.
• A prova cobre o grafo, o catálogo e o rulebook, não o código das suas ferramentas; as verificações de código do capítulo 46 leem esse código só em busca de problemas de rede e de credenciais.
• O rulebook decide só as ferramentas que os seus fluxos chamam por execute. Uma ferramenta que nenhum fluxo governa é decidida pelo resto da verificação.

46 · Verificando um agente na CI: stalwart verify¶

stalwart verify agent.yaml é a verificação em que um build reprova. É a prova que um agente executa antes do seu primeiro turno (capítulo 45), transformada num comando com um status de saída, de modo que um pull request que abre um caminho por fora de uma verificação, ou que acrescenta código que desliga a verificação de um certificado, para antes de ser mesclado. Este capítulo é o comando completo: o que ele executa e onde, um workflow, um relatório que passa e um que reprova, e cada opção e status de saída.

Quatro etapas, uma na sua máquina¶

1. As verificações de código, na sua máquina. Cada arquivo Python, JavaScript, TypeScript e Go da pasta em que está o agent.yaml é lido em busca de problemas de segurança de rede e de credenciais, pelo runtime que o pacote traz. Qualquer achado reprova o portão. O seu código nunca sai da máquina: só a contagem de achados por regra vai com a caça.
2. O catálogo e as regras. O catálogo -- cada ferramenta com as suas palavras -- é feito e passa pelo lint na sua máquina, e o rulebook: do arquivo é compilado no registro que a verificação de ferramentas aplica. As regras verificadas aqui são as regras sob as quais o seu agente roda (capítulo 45). Nada do agente fica guardado no serviço.
3. A caça, nos nossos servidores. O grafo dos agentes, o catálogo e o rulebook são enviados como um único job hunt (POST /v1/solves, com o seu portão de qualidade ligado), e o caçador de bugs examina cada rota pelos seus agentes. O solver roda nos servidores da Stalwart e nunca na sua máquina, e nada além do pacote é instalado.
4. O relatório. Cada achado com a sua regra, a sua severidade, a linha do agent.yaml de onde vem, as suas entradas OWASP e a sua correção, e depois Gate: passed ou Gate: failed. O capítulo 31 lê um relatório linha por linha.

Uma caça que não pôde rodar -- sem rota até o serviço, um job que terminou sem documento de achados -- é um erro com status de saída 3. Nunca é um resultado limpo.

Do que ele precisa¶

A sua chave em QLS_API_KEY e uma licença ativada na máquina, como todo comando exceto stalwart licence, stalwart doctor e stalwart check precisa. Um runner de CI é uma máquina nova a cada vez, então o job ativa a licença primeiro e libera o seu lugar por último, aconteça o que acontecer no meio: um lugar liberado fica livre para a próxima execução na hora (capítulo 38).

Um workflow do GitHub Actions¶

# .github/workflows/agent.yml: o agente da loja verificado em cada pull request.
name: agent
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      QLS_API_KEY: ${{ secrets.QLS_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install stalwart-agents
      - run: stalwart licence activate          # um runner é uma máquina nova a cada vez
      - run: stalwart verify agent.yaml --replay --keep findings/
      - if: always()                            # a vaga é liberada, aconteça o que acontecer acima
        run: stalwart licence release
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: findings
          path: findings/