A licença e o runtime

O wheel do stalwart-agents traz o runtime da Stalwart, compilado: o leitor que transforma cada turno em um plano, a verificação de ferramentas, as verificações de respostas, as verificações de código, a licença e a sua concessão, e os medidores. Ele roda na máquina que executa os seus agentes, de modo que nada de que um turno precisa espera pela rede, e os turnos dos seus usuários, as chamadas dos seus agentes e os seus documentos ficam ali.

O que é uma licença

Uma licença é esta máquina, ativada na sua conta Stalwart com a sua chave de API. A ativação abre uma concessão: a permissão do runtime para rodar por um período, renovada enquanto a máquina alcança a Stalwart e mantida por um período de carência quando não alcança. O seu plano define quantas máquinas podem ter uma concessão ao mesmo tempo, quanto duram a concessão e a carência, e os limites mensais que todas as máquinas da sua conta consomem juntas. O que cada plano inclui está em stalwart.it.

Ativar uma máquina

$ export QLS_API_KEY=qls_live_...
$ stalwart licence activate        # once on each machine
$ stalwart licence status          # the licence, the lease, the grace and the quota left
$ stalwart licence release         # frees this machine's place, for another to take

Uma máquina que não alcança a Stalwart é ativada por meio de outra que alcança, onde o seu plano inclui ativação offline:

$ stalwart licence request                          # on the machine to activate: writes activation-request.json
$ stalwart licence answer activation-request.json   # on a machine that reaches Stalwart: writes activation-answer.json
$ stalwart licence install activation-answer.json   # back on the first machine

O que funciona sem chave

Nada no pacote funciona sem uma chave de API e uma licença ativada, exceto o que você precisa para obtê-las:

• stalwart licence ..., para ativar, consultar e liberar a licença;
• stalwart doctor, que diz que não há chave, ou licença, e como obter uma;
• stalwart --help e stalwart --version;
• stalwart check certificate.json, que verifica um certificado offline, com o verificador de referência incluído: quem lê um certificado pode não ter chave nenhuma.

Todo o resto precisa das duas: stalwart sources build e ask, trace, verify, serve, redteam, gateway, rules compile e catalogue import, e em Python Agent.chat, os planos e as verificações do cliente, a verificação de respostas, as respostas a partir de documentos e a verificação de código. Sem elas, cada um para com LicenceRequired (de stalwart_agents.errors), que nomeia stalwart licence activate e onde obter uma chave.

A biblioteca guarda as chaves

O runtime guarda a concessão na sua própria memória e a verifica dentro de cada operação que executa. As chaves que assinam os pacotes e os históricos do seu tenant nunca passam para o Python, e o próprio runtime lê o relógio e conta cada operação. stalwart_agents._runtime, o carregador por baixo, é interno: o cliente, os agentes e os comandos o chamam por você, e ele não é uma superfície sobre a qual construir.

Só contagens saem da máquina: quantos turnos foram lidos, chamadas verificadas e respostas retidas, informadas contra os limites mensais da sua conta. Um único total é mantido para a conta inteira, quantas máquinas a compartilharem.

Um processo guarda uma licença: cada verificação, resposta e plano nele é contado contra a concessão dessa licença. Um cliente de um segundo serviço (outro base_url) no mesmo processo é recusado, e a recusa diz isso; rode-o num processo próprio. Vários processos de uma máquina -- os workers de um servidor -- compartilham a concessão e o registro dela com segurança.

Cálculos

Um plano que precisa de um cálculo -- um total, uma média, uma diferença de datas -- o executa no seu próprio host, na imagem de contêiner qls-sandbox, quando um mecanismo de contêineres e a imagem estão presentes. Todo plano inclui execuções de cálculo: 100 execuções e 300 segundos por mês no plano gratuito, 10.000 execuções e 30.000 segundos no plano pago, e sem limite no enterprise. Client.compute, AsyncClient.compute e o nó de cálculo do LangGraph rodam pelo mesmo caminho. O runtime monta o prompt a partir da forma dos dados, nunca dos seus valores; o seu próprio modelo escreve a função; o runtime a admite -- nenhum socket, nenhum arquivo, nenhum import fora de uma lista curta -- e o sandbox a executa, sem rede. Nada disso sai do seu host: as execuções são contadas, e a contagem vai no relatório de uso. python -m stalwart_agents.sandbox baixa a imagem que esta versão executa. Onde a imagem não está, os planos trazem compute off: no seu motivo, e o on_unread do agente decide o que acontece com o turno (exemplos completos).

Onde o runtime não roda

O runtime é distribuído para Linux (x86-64 e arm64), macOS em Apple silicon e Windows (x86-64). Em qualquer outro lugar, planos e verificações de ferramentas vêm do qls-router enterprise que você executa no seu próprio ambiente: defina QLS_ROUTER_URL, ou Client(router_url=...). O roteador tem a sua própria concessão, de modo que o processo que o chama não precisa de uma local para planos e verificações. A mesma biblioteca vem embutida no roteador, que serve /v1/plans, /v1/tool-checks e /v1/tool-receipts, de modo que uma resposta é os mesmos bytes onde quer que seja calculada. A API hospedada da Stalwart não serve nenhuma das três.