48 · agent.yaml e gateway.yaml, chave por chave

Idiomas

O seletor lê turnos escritos em inglês e em português do Brasil (pt-BR). O idioma é escolhido, nunca adivinhado a partir do turno: na página Settings do console (Language the selector reads), em language numa requisição de plano, ou no settings.language do seu arquivo de vocabulário; sem nenhum deles, inglês. Um turno em português pode ser digitado com os acentos ou sem eles. O português europeu não é uma gramática que o seletor tenha, e um turno em qualquer outra língua não é lido.

Este capítulo lista cada chave que os dois arquivos aceitam, com o que cada uma quer dizer. Cada tabela é gerada das listas contra as quais o pacote stalwart-agents confere um arquivo, então uma chave está aqui se e somente se o pacote a lê. Uma chave que o pacote não conhece é um erro na sua linha, nunca ignorada: uma palavra escrita errado nunca é uma configuração deixada em silêncio no seu valor padrão. O capítulo 30 mostra os arquivos em uso; este capítulo é o lugar de consultar uma chave.

O topo do agent.yaml

Chave	O que diz
agents	os agentes, por nome; o primeiro é aquele com que uma conversa começa
tools	de onde vêm as ferramentas: python: as funções públicas de um módulo, mcp: o tools/list de um servidor, openapi: cada operação de um documento, http: as chamadas de um serviço web listadas à mão, code: o seu próprio código num espaço próprio e fechado, ou name: as palavras de uma ferramenta
rulebook	as regras contra as quais toda chamada de ferramenta é verificada e o grafo é provado -- um arquivo Colang, uma planilha de regras ou a pasta compilada dela
facts	o que é cada fato que o rulebook lê ($order_paid), lido de um campo do resultado de uma ferramenta: {from: get_order.status == paid, same: order_id} (capítulo 45)
runs	atomic (o padrão): uma execução que falha é desfeita, da última escrita para a primeira; stop: uma execução que falha fica como está
storage	onde as execuções e as confirmações pendentes são guardadas: sqlite:///runs.db, ou postgres://... para vários workers; em memória quando não informado
stores	os armazenamentos que as ferramentas leem e escrevem, como uma memória ou um índice de busca, e como cada um é compartilhado
budget	limites para o laço de uma execução, que a regra do caçador de bugs sobre laços sem limite lê
modules	os módulos que o código escrito por um modelo pode importar, que as regras do caçador de bugs sobre código escrito por modelo leem
replies	as configurações da verificação de respostas (capítulo 42)
answers	respostas fundamentadas a partir dos seus documentos (capítulo 44)
vocabulary	as palavras do próprio bot, que o construtor de bots deriva do dicionário para as ferramentas que você escolheu: um arquivo que ele grava ao lado do agent.yaml, recusado se foi alterado depois (capítulo 20)
job	a descrição do trabalho do bot: title, purpose, a quem ele atende em serves (customers, staff ou ambos), o seu manager e escalates_to (cada um, um papel), a sua team e o seu horário em hours
tasks	as tarefas do bot, por nome: cada uma com o seu title, as tools que usa, o seu output (reply, document, draft ou action), onde começa na escada (watch ou suggest), os triggers que a iniciam, e se as suas mudanças rodam in_order ou all_at_once (steps)
triggers	como o trabalho chega sozinho, por nome: cada um do kind email, form, schedule, webhook, change ou message; o timing de um agendamento é around, exact ou always_on; o where de uma mudança aceita condições ou um filtro; uma mensagem chega in teams, slack, whatsapp, instagram, messenger, sms ou custom, numa account; um webhook ou uma mensagem custom pode vir de um dos own_apps do bot
ladder	a régua que uma tarefa precisa ultrapassar para subir na escada (no mínimo proposals 50, agreement 0,95 e drift_free_days 14: pode subir, nunca descer) e a sample das execuções em Agir e avisar que uma pessoa revisa
drift	quando o trabalho passado é repetido para vigiar desvios (replay: weekly ou on_model_change) e os thresholds a partir dos quais um sinal é relatado
site	a página do próprio bot: on, off, ou o seu title e language
own_apps	programas que o dono executa nesta máquina ou na rede local, por nome: cada um com o address do seu servidor MCP e o seu secret; nos planos pago e empresarial
withdrawn	ferramentas que o agente não chama mais: recusadas antes de qualquer outra coisa e nunca oferecidas, até o arquivo deixar de citá-las
settings	as configurações da verificação de ferramentas, levadas em cada verificação: taint_policy (confirm, ou refuse para uma chamada que leva um rótulo em que não se confia) e confirmation_ttl_seconds, quanto tempo vale o sim de uma pessoa

job, tasks, triggers, ladder, drift e site descrevem o trabalho do bot para o host que o executa (abaixo); o pacote as confere e as repassa.

Um agente

Em agents:, cada agente pelo seu nome:

Chave	O que diz
agents.<name>.model	o modelo do agente, provedor:modelo, usado com a sua própria chave do seu ambiente; deixe-o de fora e nenhum modelo é chamado
agents.<name>.tools	as ferramentas que este agente pode chamar, por nome
agents.<name>.hands_off_to	os agentes para os quais este pode passar a conversa
agents.<name>.on_unread	o que acontece com um turno que nada lê, depois de a pessoa ter sido convidada a dizê-lo de outra forma: refuse, model, ask ou answer; a configuração do console quando não informado
agents.<name>.privilege	low, standard ou high: o grau de confiança dado a uma transferência vinda deste agente
agents.<name>.remote	como uma transferência para este agente viaja quando ele roda em outro lugar, e como esse canal é autenticado
agents.<name>.budget	os limites próprios deste agente para uma execução: max_steps, max_tool_calls e max_model_calls, no lugar dos do arquivo
agents.<name>.system	o que é dito ao modelo antes da conversa
agents.<name>.job	a descrição do trabalho deste agente, com as mesmas palavras do job do topo
agents.<name>.defaults	valores que os argumentos das ferramentas recebem sempre que um turno não os dá, pelo nome do parâmetro -- a conta em que uma ferramenta age, por exemplo --, para que o roteador nunca os pergunte

budget

No topo do arquivo, ou num agente no lugar do do arquivo:

Chave	O que diz
budget.max_steps	o máximo de passos que uma execução dá; num agente, o dele, senão o do arquivo, senão 60. A regra do caçador de bugs sobre laços sem limite (QG023) lê este valor
budget.max_tool_calls	o máximo de chamadas de ferramenta que um turno faz; a chamada além dele não é feita, e o turno para com BudgetSpent
budget.max_model_calls	o máximo de chamadas ao modelo que um turno faz; a chamada além dele não é feita, e o turno para com BudgetSpent

remote

Chave	O que diz
agents.<name>.remote.transport	como uma transferência para este agente viaja quando ele roda em outro lugar, como a2a
agents.<name>.remote.authentication	como o outro lado prova quem é, como mtls; um agente remoto sem nenhuma é QG107

Ferramentas e de onde elas vêm

Cada entrada de tools: é uma fonte, nomeada pela chave que diz de que tipo ela é, ou as palavras de uma ferramenta em name:. Uma entrada de cada tipo aceita só as chaves da sua tabela.

python:

Chave	O que diz
tools[].python	um módulo seu, importado no processo do agente e confiável; toda função pública é uma ferramenta, com o esquema vindo das anotações de tipo

mcp:

Chave	O que diz
tools[].mcp	o endereço de um servidor MCP, ou um arquivo que lista as suas ferramentas; cada ferramenta listada é uma ferramenta, com as indicações que o servidor dá
tools[].url	o endereço para onde vão as chamadas, quando mcp: nomeia um arquivo que lista as ferramentas
tools[].version	a versão do servidor em que as ferramentas são fixadas
tools[].digest	o digest da lista de ferramentas do servidor em que as ferramentas são fixadas
tools[].headers	cabeçalhos enviados em cada requisição, cada ${NAME} lido do seu ambiente quando a requisição é feita; é assim que um agente envia o seu token do gateway
tools[].receipts	true atrás de um gateway que admite cada chamada pela verificação do próprio agente, que então viaja com a chamada como recibo
tools[].tools	apenas estas ferramentas do servidor; todas, quando não informado
tools[].env	quando mcp: é python -m <module>, um servidor Python iniciado com o próprio Python do bot: o que é acrescentado ao ambiente dele, cada ${NAME} lido do seu

openapi:

Chave	O que diz
tools[].openapi	um documento OpenAPI; cada operação é uma ferramenta, GET e HEAD leem, qualquer outro método escreve, a menos que o seu x-stalwart diga o contrário
tools[].headers	cabeçalhos enviados em cada requisição, cada ${NAME} lido do seu ambiente quando a requisição é feita; é assim que um agente envia o seu token do gateway
tools[].receipts	true atrás de um gateway que admite cada chamada pela verificação do próprio agente, que então viaja com a chamada como recibo

Uma operação pode dizer na sua extensão x-stalwart o que o seu documento não diz, com as palavras de ferramenta abaixo e uma só sua:

Chave	O que diz
x-stalwart.undo	nomeia a ferramenta que desfaz esta escrita; uma execução que falha a chama, verificada como qualquer chamada
x-stalwart.irreversible	a escrita não pode ser desfeita; a sua confirmação diz isso, e um rollback a deixa no lugar
x-stalwart.retry_safe	chamá-la duas vezes com os mesmos argumentos faz o que chamá-la uma vez faz, então uma chamada de resultado desconhecido pode ser repetida
x-stalwart.reads_outside	o que ela devolve vem de fora, um e-mail ou uma página web, e não é confiável; o que vem depois carrega essa marca
x-stalwart.sends_out	ela pode enviar para uma URL ou outro destino; um argumento de destino é recusado em qualquer ferramenta que não diga isso
x-stalwart.after	a ferramenta só roda depois de cada ferramenta nomeada, na mesma sessão
x-stalwart.not_after	a ferramenta nunca roda depois de uma ferramenta nomeada, ou depois de qualquer coisa de fora quando ela nomeia untrusted
x-stalwart.at_most	a ferramenta roda no máximo este número de vezes numa sessão; {count, per}, ou uma lista deles, um por período, que o seu host conta e a verificação recusa além do limite
x-stalwart.requires_privilege	só um agente com pelo menos este privilégio pode chamá-la
x-stalwart.argument_kinds	o que um argumento é, como code, sql, path ou url, que as regras do caçador de bugs sobre valores escritos pelo modelo leem
x-stalwart.confidential	o que a ferramenta devolve é confidencial, e para quem
x-stalwart.subject_argument	o argumento que nomeia de quem são os dados que a ferramenta devolve
x-stalwart.idempotency	{header: <name>}: o cabeçalho em que a chave de idempotência de uma chamada é enviada
x-stalwart.also_called	palavras que uma pessoa usa para aquilo sobre o que a ferramenta age, lidas como as palavras do seu nome

http:

Chave	O que diz
tools[].http	o endereço de uma API REST sem documento OpenAPI, começando com https://
tools[].headers	cabeçalhos enviados em cada requisição, cada ${NAME} lido do seu ambiente quando a requisição é feita; é assim que um agente envia o seu token do gateway
tools[].operations	as chamadas da API, listadas à mão, cada uma uma ferramenta (a próxima tabela)
tools[].receipts	true atrás de um gateway que admite cada chamada pela verificação do próprio agente, que então viaja com a chamada como recibo

Cada uma das suas operations:, além de qualquer palavra de ferramenta:

Chave	O que diz
tools[].operations[].name	o nome da ferramenta
tools[].operations[].method	GET, uma leitura, ou POST, PUT, PATCH ou DELETE, cada um dos quais precisa dizer se escreve
tools[].operations[].path	o caminho depois do endereço da API
tools[].operations[].schema	o JSON Schema dos argumentos; ao lado dele, qualquer palavra de ferramenta

code:

Chave	O que diz
tools[].code	o seu próprio código, para rodar isolado no seu próprio sandbox, cada função uma ferramenta; uma pasta ao lado do agent.yaml, ou uma URL Git fixada num commit. Verificado e guardado; executá-lo no sandbox ainda está por vir
tools[].language	a linguagem do código; python, por enquanto
tools[].requirements	o arquivo de dependências fixadas (name==1.2.3), instaladas quando o sandbox é montado
tools[].functions	apenas estas funções; todas as públicas, quando não informado
tools[].state	uma pasta dentro do projeto mantida entre as chamadas
tools[].mode	call, uma execução por chamada de ferramenta, ou service, que o host mantém rodando
tools[].sandbox	os limites do sandbox (a tabela do sandbox)

O seu sandbox::

Chave	O que diz
tools[].sandbox.level	standard, o padrão, que só pode apertar os limites padrão, ou advanced, que deixa o dono ampliá-los, cada ampliação aceita por uma pessoa no host
tools[].sandbox.network	os hosts que o código pode alcançar; nenhum, quando não informado; any apenas no nível advanced
tools[].sandbox.secrets	variáveis de ambiente passadas apenas a este sandbox, pelo nome, nunca pelo valor; nunca uma das do próprio Stalwart
tools[].sandbox.limits	o tempo, a memória e os processos que uma execução pode usar (a tabela de limites)
tools[].sandbox.mounts	pastas do host que o código pode ver, apenas no nível advanced
tools[].sandbox.allow	os relaxamentos que a lista de permissões do host nomeia, apenas no nível advanced

Os limits: do sandbox:

Chave	O que diz
tools[].sandbox.limits.seconds	os segundos que uma execução pode levar; no máximo 60 no nível standard, e 0, sem limite, apenas com mode service
tools[].sandbox.limits.memory_mb	a memória que uma execução pode usar, em megabytes; no máximo 1024 no nível standard
tools[].sandbox.limits.cpus	os processadores que uma execução pode usar; no máximo 1 no nível standard
tools[].sandbox.limits.processes	os processos que uma execução pode iniciar; no máximo 32 no nível standard

Cada um dos seus mounts::

Chave	O que diz
tools[].sandbox.mounts[].path	a pasta do host; nunca a raiz do host, as suas pastas de sistema, as do próprio Stalwart ou a do projeto, e nunca um caminho relativo
tools[].sandbox.mounts[].write	true quando o código pode escrever ali

O piso. Estas são recusadas em todo nível, onde quer que apareçam, porque alcançariam a própria Stalwart ou os outros bots do dono:

Chave	O que diz
privileged	um contêiner privilegiado
capabilities	capabilities do Linux adicionadas
devices	os dispositivos do host
docker_socket	o socket do Docker
host_network	a rede do host
gate	desligar o gate
audit	desligar a auditoria
stop_button	desligar o botão de parada

As palavras de uma ferramenta

Em name:, ou como @tool(...) em Python, ou ao lado de uma operação http::

Chave	O que diz
writes	a ferramenta muda alguma coisa, então a sua chamada é verificada contra as suas regras, e espera por uma pessoa onde elas mandam ou onde nada a permite
undo	nomeia a ferramenta que desfaz esta escrita; uma execução que falha a chama, verificada como qualquer chamada
irreversible	a escrita não pode ser desfeita; a sua confirmação diz isso, e um rollback a deixa no lugar
retry_safe	chamá-la duas vezes com os mesmos argumentos faz o que chamá-la uma vez faz, então uma chamada de resultado desconhecido pode ser repetida
reads_outside	o que ela devolve vem de fora, um e-mail ou uma página web, e não é confiável; o que vem depois carrega essa marca
sends_out	ela pode enviar para uma URL ou outro destino; um argumento de destino é recusado em qualquer ferramenta que não diga isso
after	a ferramenta só roda depois de cada ferramenta nomeada, na mesma sessão
not_after	a ferramenta nunca roda depois de uma ferramenta nomeada, ou depois de qualquer coisa de fora quando ela nomeia untrusted
at_most	a ferramenta roda no máximo este número de vezes numa sessão; {count, per}, ou uma lista deles, um por período, que o seu host conta e a verificação recusa além do limite
confirm_with	o que se pergunta a uma pessoa antes de a chamada rodar, nas suas palavras; sobre uma ferramenta irreversível que não dê nenhuma, pergunta-se Run <tool>? Nothing undoes it once it has run.
requires_privilege	só um agente com pelo menos este privilégio pode chamá-la
description	o que a ferramenta faz, contra o que o seletor lê os turnos; a primeira linha da docstring quando não informado
checks	condições que cada chamada precisa cumprir, como uma quantidade no máximo igual ao estoque; uma chamada que não as cumpre é recusada, em palavras, antes de rodar
filter	numa leitura, quais registros ela repassa: each nomeia a lista, keep as condições que cada registro cumpre; os outros nunca chegam ao agente
spend	o máximo que um campo pode somar por período, com as ferramentas do mesmo pool dividindo uma contagem; uma chamada que passaria do limite é recusada antes de rodar
currency	a moeda dos valores da ferramenta, como USD ou BRL; obrigatória com spend
outcome	numa escrita, a leitura que a acompanha até o fim e como são feito e falhou; uma escrita que falha segue a política de falha da tarefa, e uma nunca confirmada vira uma pergunta
personal_data	se o que a ferramenta devolve são dados pessoais: none, personal ou special; uma ferramenta que não diz nada é tratada como personal, que um modelo só lê no plano enterprise e nunca num modelo gratuito na nuvem
argument_kinds	o que um argumento é, como code, sql, path ou url, que as regras do caçador de bugs sobre valores escritos pelo modelo leem
sandboxed	o código que a ferramenta roda é contido, o que baixa a severidade de um achado sobre ele
sanitised_by	a verificação que limpa um argumento antes de a ferramenta usá-lo
confidential	o que a ferramenta devolve é confidencial, e para quem
confidential_fields	quais campos do que ela devolve são confidenciais
subject_argument	o argumento que nomeia de quem são os dados que a ferramenta devolve
retrieves	o armazenamento de onde a ferramenta lê, e o argumento que delimita as suas leituras
persists	o armazenamento em que a ferramenta escreve
source	de onde vem o código da ferramenta, que a regra do caçador de bugs sobre fontes não fixadas lê
server	o servidor MCP que serve a ferramenta, com a sua versão ou digest
also_called	palavras que uma pessoa usa para aquilo sobre o que a ferramenta age, lidas como as palavras do seu nome
working	uma escrita só nos arquivos de trabalho do próprio bot, para uso do dono, que roda sem a aprovação de uma pessoa, como uma resposta; só as ferramentas do próprio Stalwart podem dizer isso
named_by	os nomes pelos quais uma pessoa chama esta fonte, quando ela só é buscada se a mensagem a nomear
otherwise	a ferramenta buscada no lugar desta quando a mensagem não diz nenhum dos nomes dela

Condições e limites numa ferramenta

Os checks, o filter, o at_most, o spend e o outcome de uma ferramenta dividem uma gramática. Cada condição trata de uma coisa e tem exatamente um operador:

Chave	O que diz
checks[].field	o valor de que a condição trata: um argumento, ou um campo do resultado, por nome ou caminho com pontos, como order.total; um caminho por uma lista, como items[].price, vale só onde todo item vale
checks[].total	a soma sobre os itens de uma lista, como legs[].cost; compara como um número
checks[].count	quantos itens uma lista tem, como legs[]; compara como um número
checks[].any	uma lista de condições, das quais qualquer uma basta; uma lista simples de condições quer dizer todas elas
checks[].is	o valor é igual a este
checks[].is_not	o valor é diferente deste
checks[].one_of	o valor é um de uma lista, ou do que uma chamada anterior devolveu, como {from: get_slots.slots[].start}
checks[].none_of	o valor não é nenhum de uma lista, ou do que uma chamada anterior devolveu
checks[].at_least	o número é este ou mais; o operando pode ser {from: <ferramenta>.<campo>}, o que uma chamada anterior na execução devolveu
checks[].at_most	o número é este ou menos, como uma quantidade no máximo {from: check_stock.in_stock}
checks[].under	o número é menor que este
checks[].over	o número é maior que este
checks[].between	o número, a data ou a hora está entre dois limites, o menor primeiro, como [10, 20]
checks[].before	a data ou a hora é anterior a esta, escrita como 2026-10-16, 17:30 ou 2026-10-16T17:30
checks[].after	a data ou a hora é posterior a esta
checks[].contains	o valor contém este texto
checks[].because	o motivo nas suas palavras, mostrado quando a condição barra algo
checks[].unknown	o que faz um valor que ninguém conseguiu ler: fail, o padrão, ou pass, que só um filtro e o where de um trigger de mudança podem dizer, nunca uma verificação que deixa uma chamada passar

filter:, numa leitura:

Chave	O que diz
filter.each	a lista no resultado cujos registros a leitura repassa, terminando em [], como jobs[]
filter.keep	as condições que cada registro precisa cumprir para ser repassado; dentro delas, {from_row: <campo>} é outro campo do mesmo registro

at_most: é um número de chamadas por sessão, ou um destes, ou uma lista deles:

Chave	O que diz
at_most.count	o máximo de chamadas no período, um número inteiro a partir de 1
at_most.per	o período contado: call, run, session, minute, hour, day, week ou month; um limite por período

Cada um de spend:, com a currency da ferramenta:

Chave	O que diz
spend[].field	o campo do valor, como amount, ou legs[].cost para os itens juntos
spend[].at_most	o máximo que os valores podem somar no período, um número acima de 0, na currency da ferramenta
spend[].per	o período contado, como day ou month; os mesmos períodos de at_most
spend[].pool	um nome; ferramentas com o mesmo pool dividem um contador

outcome:, numa escrita:

Chave	O que diz
outcome.follow	a ferramenta de leitura que informa como a escrita terminou; obrigatória, e precisa ser uma ferramenta declarada que não escreve
outcome.same	o campo que liga a escrita e a leitura, como order_id
outcome.done_when	as condições sobre o resultado da leitura que dizem que a escrita terminou; obrigatórias
outcome.failed_when	as condições sobre o resultado da leitura que dizem que a escrita falhou
outcome.give_up_after	os minutos de espera, pelo menos 1, antes de o desfecho ser desconhecido

Stores e módulos

Cada um de stores:, pelo nome do store:

Chave	O que diz
stores.<name>.persistent	true quando o que o armazenamento guarda sobrevive à execução, o que as regras do caçador sobre texto plantado leem (QG021)
stores.<name>.multi_tenant	true quando vários tenants compartilham o armazenamento, então o que um escreve outro pode ler

Cada um de modules:, pelo caminho do módulo:

Chave	O que diz
modules.<path>.version	a versão em que um módulo de ações Colang é fixado
modules.<path>.digest	o digest em que um módulo de ações Colang é fixado

Fatos

Cada um de facts:, pelo nome sob o qual o rulebook o lê:

Chave	O que diz
facts.<name>.from	o resultado de ferramenta de onde o fato é lido, como tool.field == value ou tool.field; nunca uma ferramenta que lê de fora
facts.<name>.same	o argumento, a lista de argumentos ou o mapeamento de argumentos que liga o fato à chamada verificada, para que o status de um pedido nunca permita o reembolso de outro

Respostas e respostas prontas

replies::

Chave	O que diz
replies.rules	o arquivo de regras de resposta, como a página Reply rules do console o salva
replies.phrasings	o arquivo de frases de resultado
replies.composer	model: o modelo escreve a resposta e a verificação a confere; template: a resposta são as frases, e nenhum modelo a escreve
replies.language	a língua das frases padrão: en ou pt
replies.temperature	true: as palavras do próprio bot numa resposta (aberturas, ligações e fechos, e as suas palavras para o verbo de uma ferramenta) variam conforme a conversa e o turno, então uma conversa repetida sai igual; um valor, uma negação, uma resposta exata ou as palavras de uma fonte nunca variam. false, o padrão: toda resposta nas próprias palavras das frases
replies.audience	para quem são as respostas. customer, o padrão: um valor que nenhum registro de ferramenta tem sai da resposta; staff: ele fica, destacado. Em ambos os casos cada valor é rastreado até a chamada e o campo de onde veio, e o rastro vai junto da mensagem da resposta

answers::

Chave	O que diz
answers.index	o índice de fontes que o stalwart sources build escreve
answers.k	no máximo este número de trechos; 3 quando nem o arquivo nem o console dizem
answers.floor	nenhum trecho com pontuação abaixo disto é usado, de 0 a 1; 0,3 quando nenhum dos dois diz
answers.composer	extract, as próprias frases dos documentos; ou compose, o seu modelo escreve a partir delas

O trabalho do bot: job, tasks e triggers

Estas chaves descrevem o bot para o host que o executa. O pacote confere cada uma delas ao ler o arquivo; o que cada uma faz é com o host.

Chave	O que diz
job	a descrição do trabalho do bot: title, purpose, a quem ele atende em serves (customers, staff ou ambos), o seu manager e escalates_to (cada um, um papel), a sua team e o seu horário em hours
tasks	as tarefas do bot, por nome: cada uma com o seu title, as tools que usa, o seu output (reply, document, draft ou action), onde começa na escada (watch ou suggest), os triggers que a iniciam, e se as suas mudanças rodam in_order ou all_at_once (steps)
triggers	como o trabalho chega sozinho, por nome: cada um do kind email, form, schedule, webhook, change ou message; o timing de um agendamento é around, exact ou always_on; o where de uma mudança aceita condições ou um filtro; uma mensagem chega in teams, slack, whatsapp, instagram, messenger, sms ou custom, numa account; um webhook ou uma mensagem custom pode vir de um dos own_apps do bot
ladder	a régua que uma tarefa precisa ultrapassar para subir na escada (no mínimo proposals 50, agreement 0,95 e drift_free_days 14: pode subir, nunca descer) e a sample das execuções em Agir e avisar que uma pessoa revisa
drift	quando o trabalho passado é repetido para vigiar desvios (replay: weekly ou on_model_change) e os thresholds a partir dos quais um sinal é relatado
site	a página do próprio bot: on, off, ou o seu title e language
own_apps	programas que o dono executa nesta máquina ou na rede local, por nome: cada um com o address do seu servidor MCP e o seu secret; nos planos pago e empresarial

job

Chave	O que diz
job.title	o nome do job
job.purpose	para que o bot serve, numa frase
job.serves	a quem ele atende: customers, staff ou both
job.manager	o papel que o gerencia; o host nomeia a pessoa
job.team	quem lhe dá trabalho e quem aprova (a tabela da equipe)
job.hours	o seu horário de trabalho (a tabela de horário)
job.escalates_to	o papel para o qual vai um cartão parado
job.help	a página que explica o que ele faz e como pedir, com exemplos, com link na conversa (um endereço https, ou um por idioma)

O seu team::

Chave	O que diz
job.team.gives_work	os papéis que lhe dão trabalho
job.team.approves	os papéis que aprovam o que ele propõe

As suas hours::

Chave	O que diz
job.hours.days	os dias de trabalho, de mon a sun
job.hours.from	a hora em que o trabalho começa, como HH:MM
job.hours.to	a hora em que o trabalho termina, como HH:MM
job.hours.time_zone	o fuso horário das horas, como Europe/London

tasks

Cada tarefa, pelo seu nome:

Chave	O que diz
tasks.<name>.title	o nome da tarefa em palavras; obrigatório
tasks.<name>.tools	as ferramentas que a tarefa usa, cada uma declarada em tools
tasks.<name>.agent	o agente que a executa; o primeiro, quando não informado
tasks.<name>.serves	a quem a tarefa atende: customers, staff ou both
tasks.<name>.output	o que ela produz: reply, document, draft ou action
tasks.<name>.starts_at	o nível da escada em que ela começa: watch ou suggest; nenhuma tarefa começa mais alto
tasks.<name>.triggers	os gatilhos que a iniciam, cada um declarado em triggers
tasks.<name>.run_window	os minutos em que um host adormecido ainda pode iniciar uma execução devida, de 1 a 1440
tasks.<name>.form	true quando as pessoas podem iniciar a tarefa à mão
tasks.<name>.steps	in_order, ou all_at_once: todas as escritas acontecem juntas, ou nenhuma acontece
tasks.<name>.example	o que uma pessoa poderia escrever para ela, por idioma, que o chat oferece para experimentar: {pt: reembolsa o pedido 1042}

triggers

Cada trigger, pelo seu nome, é um kind e as chaves que esse tipo aceita:

Chave	O que diz
triggers.<name>.kind	como o trabalho chega: email, form, schedule, webhook, change ou message; ele decide as chaves ao lado
triggers.<name>.inbox	o nome da caixa de entrada
triggers.<name>.urgent	true quando o trabalho não espera o horário de trabalho

Chave	O que diz
triggers.<name>.kind	como o trabalho chega: email, form, schedule, webhook, change ou message; ele decide as chaves ao lado
triggers.<name>.audience	quem preenche o formulário: customers ou staff
triggers.<name>.urgent	true quando o trabalho não espera o horário de trabalho

Chave	O que diz
triggers.<name>.kind	como o trabalho chega: email, form, schedule, webhook, change ou message; ele decide as chaves ao lado
triggers.<name>.at	a hora em que é devido, como HH:MM
triggers.<name>.days	os dias em que é devido, de mon a sun
triggers.<name>.timing	around (por volta da hora), exact ou always_on
triggers.<name>.urgent	true quando o trabalho não espera o horário de trabalho

Chave	O que diz
triggers.<name>.kind	como o trabalho chega: email, form, schedule, webhook, change ou message; ele decide as chaves ao lado
triggers.<name>.secret	a variável de ambiente do segredo de assinatura, como ${NAME}; nunca o próprio segredo
triggers.<name>.app	o app próprio que o chama, desta máquina, assinado com o segredo do app no lugar de secret
triggers.<name>.urgent	true quando o trabalho não espera o horário de trabalho

Chave	O que diz
triggers.<name>.kind	como o trabalho chega: email, form, schedule, webhook, change ou message; ele decide as chaves ao lado
triggers.<name>.tool	a ferramenta que ele consulta; ele nomeia esta ou resource, não as duas
triggers.<name>.resource	o recurso que ele assina; ele nomeia este ou tool, não os dois
triggers.<name>.every	os minutos entre consultas, de 1 a 1440
triggers.<name>.where	condições sobre os campos do resultado consultado, como {field: open_count, at_least: 1}
triggers.<name>.urgent	true quando o trabalho não espera o horário de trabalho

Chave	O que diz
triggers.<name>.kind	como o trabalho chega: email, form, schedule, webhook, change ou message; ele decide as chaves ao lado
triggers.<name>.in	o canal: teams, slack, whatsapp, instagram, messenger, sms, ou custom para o de um app próprio
triggers.<name>.account	a página, o número ou o workspace: um nome, ou ${NAME} para um que o host guarda
triggers.<name>.app	para in: custom, o app próprio cujas conversas ele lê
triggers.<name>.urgent	true quando o trabalho não espera o horário de trabalho

ladder, drift e site

Chave	O que diz
ladder.bar	o que uma tarefa precisa mostrar para subir um nível: proposals, agreement e drift_free_days, que podem ser elevados, nunca reduzidos abaixo de 50, 0,95 e 14
ladder.sample	a fração das execuções Act-and-tell que uma pessoa revisa; 0,1 quando não informado

Chave	O que diz
drift.replay	weekly, ou apenas on_model_change
drift.thresholds	quanto cada sinal pode mudar antes de ser drift: tools, plan_shape, decisions, plan_lock_stops, refusals, untraced_claims
drift.baseline_days	os dias de execuções contra os quais os sinais são comparados, de 1 a 90

Chave	O que diz
site.title	o título do site
site.language	o idioma do site: en ou pt
site.colour	a cor principal do site
site.logo	o logotipo do chat: um endereço https, ou a imagem que o dono enviou; o da Stalwart quando não há nenhum
site.greeting	o que o bot diz primeiro no chat dele
site.contact	como falar com o dono, que o bot passa a quem ele não puder ajudar
site.privacy	o endereço do aviso de privacidade do dono, que o chat traz como link
site.groups	um título que o chat mostra sobre as ferramentas que nenhuma tarefa nomeia, com elas: {Pedidos: [get_order]}

own_apps

Cada app próprio, pelo seu nome: um programa que o dono executa nesta máquina ou na rede local, com o qual o bot trabalha sem que nada passe pela Stalwart. Um gatilho webhook que nomeia o seu app, e um gatilho message com in: custom, são o que o app envia ao bot, assinados com o seu segredo e admitidos somente desta máquina. No plano gratuito, nada dele é executado.

Chave	O que diz
own_apps.<name>.address	o seu servidor MCP, como http(s):// num endereço IP ou localhost: esta máquina, ou a rede local com lan: allow; nunca a internet
own_apps.<name>.secret	a variável de ambiente com o segredo com que as suas chamadas são assinadas, como ${NAME}; nunca o próprio segredo. Se omitida, o host cria um, guarda-o selado e o mostra uma vez
own_apps.<name>.lan	allow admite um endereço, e chamadas, na rede local; refuse quando não informado
own_apps.<name>.channel	verdadeiro quando ele mantém conversas pelo bot: as respostas do bot saem pelo seu send_message

Um template

Um template é um agent.yaml do qual uma pessoa parte. Ele acrescenta:

Chave	O que diz
first_bot	true quando o modelo inicia Make my first bot
needs	as entradas de catálogo que o modelo usa, cada uma com o seu login (a próxima tabela)
optional	entradas que ele oferece e sem as quais funciona

Cada uma das suas needs::

Chave	O que diz
needs.<name>.entry	o id da entrada de catálogo; obrigatório
needs.<name>.sign_in	como a entrada faz login: oauth, service ou none
needs.<name>.why	por que o modelo precisa dela, numa frase que o dono lê
needs.<name>.route	como os seus dados são alcançados: api, aggregator, owner_feed ou owner_browser

gateway.yaml

O gateway (capítulo 37) lê estas do arquivo com que é iniciado, e se recusa a iniciar com qualquer outra:

$ stalwart gateway --config gateway.yaml

Chave	O que diz
catalogue	o catálogo do tenant contra o qual o gateway verifica cada chamada, no formato do modelo extraído; obrigatório
rules	as regras contra as quais cada chamada é verificada: uma planilha de regras, a pasta compilada dela ou um arquivo Colang, sobrepostas ao catálogo
upstreams	qual servidor MCP guarda cada ferramenta, pelo nome da ferramenta; "*" para as demais
agents	um token por agente, cada ${NAME} vindo do ambiente; cada agente se conecta com o seu, e pelo menos um é obrigatório
admin_token	o token que a rota de rollback aceita; a rota fica desligada quando ele não está definido
audit	o arquivo ao qual cada decisão é acrescentada
elicitation_timeout	os segundos que uma pessoa tem para responder a uma pergunta que a chamada faz; 600 quando não informado
listen	o endereço e a porta em que ele serve; 127.0.0.1:8800 quando não informado
storage	o banco de dados em que ficam os recibos que ele já gastou, compartilhado por todos os processos do gateway; em memória quando não informado
people_key	a chave do host, como ${NAME}, com que a pessoa de uma sessão é nomeada, para servidores que fazem o login de cada pessoa por si
egress	para onde uma chamada pode enviar: metadata (o serviço de metadados de uma nuvem), private (a rede da própria empresa) e schemes (um endereço que não é da web: file:, javascript:, data: ...), cada um allow ou refuse, e allow, hosts e faixas admitidos mesmo assim; refuse quando não informado
withdrawn	ferramentas que o gateway recusa e deixa fora da lista de cada agente, até o arquivo deixar de citá-las
settings	as configurações da verificação de ferramentas, levadas em cada verificação: taint_policy (confirm ou refuse) e confirmation_ttl_seconds

Cada item de upstreams:, quando não é só um endereço:

Chave	O que diz
upstreams.<tool>.url	o endereço do servidor MCP: HTTP com streaming, ou HTTP com SSE; ele nomeia este ou command, não os dois
upstreams.<tool>.headers	cabeçalhos que toda requisição ao servidor leva; um valor ${NAME} é lido do ambiente
upstreams.<tool>.sign_in	true, ou o login OAuth 2.1 do servidor, com os seus tokens selados no storage do gateway nesta máquina
upstreams.<tool>.command	o comando que inicia o servidor ao lado do gateway, com quem se fala por stdio; ele nomeia este ou url, não os dois
upstreams.<tool>.env	variáveis acrescentadas ao ambiente do comando
upstreams.<tool>.cwd	a pasta em que o comando roda

O seu sign_in:, quando não é só true:

Chave	O que diz
upstreams.<tool>.sign_in.client_id	o id do cliente, quando ele já está registrado no servidor; registrado no primeiro uso, caso contrário
upstreams.<tool>.sign_in.client_secret	o segredo do cliente registrado, como ${NAME}
upstreams.<tool>.sign_in.scopes	os escopos pedidos
upstreams.<tool>.sign_in.per_user	verdadeiro quando cada pessoa faz login na sua própria conta, conforme o host as nomeia
upstreams.<tool>.sign_in.grant	client_credentials para uma credencial de serviço; o login de uma pessoa quando não informado
upstreams.<tool>.sign_in.redirect_uri	para onde o servidor devolve a pessoa depois do login

Os limites

• A tabela de uma chave diz o que o pacote lê. Algumas chaves são conferidas e guardadas mas ainda não aplicadas -- checks, filter, spend e outcome numa ferramenta, e o código de uma fonte code:, que ainda não é executado -- e as suas linhas o dizem.
• As chaves de fundação são conferidas aqui e aplicadas pelo host que executa o bot.