Ir para o conteúdo

O guia do usuário da Stalwart

Este guia é para quem constrói agentes com a Stalwart e para quem responde por esses agentes. Ele diz o que cada produto faz, como usá-lo e onde termina cada garantia.

Os produtos

Uma única chave de API alcança todos eles. O guia os chama pelos nomes que o site e a referência da API usam, com o nome em inglês entre parênteses, porque é o que você encontra no código, nas chaves e nas conversas com o suporte.

  • O Construtor de Bots (Bot Builder) constrói o seu próprio agente de IA a partir das ferramentas que a sua empresa já tem, declarado num único arquivo, com as suas regras verificadas a cada chamada de ferramenta antes de ela rodar. Um componente dentro dele, o seletor, lê cada turno de uma conversa e escolhe a ferramenta por uma regra nomeada, sem chamar nenhum modelo.
  • 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, e devolve cada caminho que chega a uma ferramenta sem a sua verificação, a sua confirmação ou a sua regra de ordem.
  • O Caçador de Bugs em Guardrails (Guardrail Bug Hunter) encontra cada caminho através dos seus guardrails até uma ação proibida, mostra cada um acontecendo e entrega uma correção que ele já verificou varrendo de novo.
  • A Verificação de Guardrails (Guardrail Verification) responde se uma ação pode disparar sem o seu contexto de segurança, ou uma tabela inteira dessas perguntas, e devolve um contraexemplo com um reparo, ou um certificado.
  • A Escrita de Guardrails (Guardrail Writing) redige uma política de guardrails a partir de uma regra escrita em prosa, no seu próprio modelo, e depois verifica o rascunho e o repara onde ele está errado.
  • A Verificação de Random Forests (Random Forest Verification) verifica uma random forest treinada contra propriedades de robustez, monotonicidade, equidade e alcançabilidade, ou procura, em torno de registros reais, a menor mudança que inverte uma decisão.

O caçador e o seletor, juntos

Os dois foram feitos para serem usados juntos. Um guardrail pode fazer toda ação de ferramenta esperar pela decisão do seletor: o seletor lê o turno, e o guardrail só roda uma ferramenta quando o plano do seletor diz run para essa ferramenta. O Caçador de Bugs em Guardrails então examina cada caminho pelo guardrail em busca de um que chegue a uma ferramenta sem essa decisão, e reprova o pull request que adicione um. O capítulo 29 percorre esse exemplo. Uma varredura limpa prova que a política manda toda ferramenta pelo seletor; ela não prova que o seletor escolheu a ferramenta certa, o que o capítulo 20 explica.

Idiomas

O seletor entende turnos escritos em inglês. O português é a sua próxima gramática e ainda não foi lançado; até lá, um turno escrito em português não é lido como português.

Um agente, num único arquivo

Uma equipe põe os produtos para trabalhar por meio de um único agente, sem aprender um framework de agentes. Você declara o agente num único arquivo: as suas ferramentas, as suas regras e quais escritas desfazem quais. Antes de ele rodar, os seus caminhos são verificados; enquanto ele roda, cada turno é lido e cada chamada de ferramenta é verificada na sua própria máquina; e uma execução que falha é desfeita, da última escrita para a primeira. Este é o agente da loja que o guia usa em toda a Parte I:

# The shop's support desk, and the billing desk it hands refunds to.
agents:
  desk:
    model: "anthropic:claude-sonnet-5-5"   # your provider; the key comes from your environment
    tools: [get_order, charge_card, send_receipt, read_inbox]
    hands_off_to: [billing]
    on_unread: refuse                      # a turn no tool covers is refused, by name
  billing:
    privilege: high
    tools: [refund_card]
tools:
  - python: shop.tools                     # every public function of shop/tools.py
rulebook: ./policy.co                      # the rules every call is checked against
runs: atomic                               # a failed run is undone, last write first
storage: sqlite:///runs.db                 # where runs and waiting confirmations are kept

A Parte I o constrói passo a passo, nas palavras do arquivo acima e nas de nenhum framework. Os comentários do arquivo estão em inglês porque o arquivo é o mesmo que roda nos testes.

Por onde começar

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. O capítulo 39 é para as equipes de governança e de segurança: a que cada produto corresponde nas listas Top 10 da OWASP de 2026 e no NIST AI Risk Management Framework, e o que uma correspondência dessas não é. 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

Um certificado pode ser conferido sem chave, sem rede e sem nenhum software nosso. A especificação do certificado diz 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 rodá-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

Os números dos capítulos são identificadores: um capítulo mantém o seu número em qualquer página para onde se mova, então um arquivo de auditoria que cita o capítulo 7 continua apontando para o mesmo capítulo.