Orçamento de latência de aprovação para ações de agentes

As aprovações de agentes falham de duas formas opostas. Faça cada ação pedir autorização a uma pessoa, e o agente passará o dia esperando atrás de uma fila de revisão. Remova o ponto de decisão porque esperar atrapalha, e o agente receberá uma autoridade que ninguém consegue supervisionar de verdade.

Um orçamento de latência de aprovação evita os dois problemas. Ele define quanto tempo uma decisão humana pode levar para determinada classe de ação do agente, mede para onde esse tempo vai e força uma reformulação quando o trabalho rotineiro não cabe nesse limite. O orçamento não é uma meta para as pessoas clicarem mais rápido. É uma restrição sobre o fluxo e sobre a autoridade entregue ao agente.

Já vi equipes tratarem um prompt de aprovação como prova de controle e depois descobrirem que um desenvolvedor aprovava vinte solicitações quase idênticas enquanto tentava terminar o próprio trabalho. Essa pessoa não estava revisando. Estava funcionando como um retransmissor lento. A solução raramente é uma notificação de lembrete melhor. Em geral, é uma autoridade menos ambígua, menos chamadas desnecessárias e um caminho de escalonamento mais claro para as ações que realmente merecem atrito.

Um orçamento de latência de aprovação é um prazo para uma decisão humana

Um orçamento de latência de aprovação é o tempo máximo aceitável entre uma solicitação se tornar revisável e uma decisão final de permitir ou negar. Ele deve variar por classe de ação, porque ler uma pull request, criar um recurso de teste temporário e alterar uma configuração de acesso em produção não têm a mesma urgência nem a mesma consequência.

Trate o orçamento como parte do contrato da ação. Se o agente precisa de uma resposta em até dois minutos para manter uma tarefa interativa em andamento, o sistema deve tornar essa ação fácil de avaliar em dois minutos ou evitar pedir essa decisão durante o trabalho normal. Se uma tarefa pode esperar com segurança até a manhã seguinte, não finja que ela precisa de um prompt que interrompa o trabalho.

O orçamento tem três partes:

• Espera na fila: tempo entre a criação da solicitação e a abertura por um revisor.
• Tempo de decisão: tempo entre a abertura da solicitação e a decisão de permitir ou negar.
• Tempo de despacho: tempo entre a decisão e o início ou a falha da ação.

Muitas equipes juntam tudo em um número e o chamam de tempo de aprovação. Isso esconde o reparo necessário. Uma espera de vinte minutos na fila pede mudanças de roteamento, responsabilidade ou agendamento. Vinte minutos de decisão significam que falta contexto, que a solicitação contém autoridade demais ou que ela pede um julgamento que nunca deveria ter chegado a uma pessoa com pressa.

Defina os orçamentos em torno dos prazos do trabalho, não de um nível de segurança abstrato. Uma tabela inicial razoável poderia ser assim:

Esses são exemplos, não uma política universal. Uma equipe de implantação com escala de plantão pode ter uma janela diferente da de uma pessoa desenvolvedora trabalhando sozinha. O importante é nomear a expectativa antes de a fila se formar.

Não use um acordo de nível de serviço para isso, a menos que consiga oferecer a equipe necessária. Um orçamento é um limite de projeto. Ele mostra que uma tarefa não pode depender de uma decisão interativa se as pessoas capazes de decidir estiverem dormindo, em reuniões ou lidando com um incidente. O agente também deve saber disso. Ele pode preparar a solicitação, escolher um caminho alternativo seguro ou parar com uma explicação compreensível. Não deve continuar emitindo a mesma solicitação a cada minuto.

Meça o ciclo de vida da solicitação, não apenas um clique

Não é possível melhorar o atraso de aprovação se os seus registros de tempo começam quando uma notificação chega ao telefone. Comece quando o sistema cria uma ação revisável e registre cada mudança de estado usando um identificador de solicitação que sobreviva a novas tentativas e atualizações da interface.

Use um registro de eventos pequeno como este. Os campos são deliberadamente simples. Registros simples podem ser ordenados, associados e consultados depois de um incidente.

{
  "request_id": "req_7f31",
  "run_id": "run_241",
  "action_class": "bounded_write",
  "target": "issue tracker/project-amber",
  "created_at": "2025-03-08T14:02:01Z",
  "presented_at": "2025-03-08T14:02:03Z",
  "opened_at": "2025-03-08T14:09:18Z",
  "decided_at": "2025-03-08T14:10:06Z",
  "decision": "allow",
  "executed_at": "2025-03-08T14:10:07Z",
  "outcome": "success"
}

Com esse formato, calcule a espera na fila como opened_at - presented_at, o tempo de decisão como decided_at - opened_at e o tempo de despacho como executed_at - decided_at. Mantenha também created_at. Ele detecta um defeito mais silencioso: um intermediário que segura a solicitação antes que alguém possa vê-la.

Uma consulta pode expressar as medições sem uma pilha de análise complicada:

SELECT
  action_class,
  percentile_cont(0.50) WITHIN GROUP (ORDER BY opened_at - presented_at) AS p50_queue_wait,
  percentile_cont(0.95) WITHIN GROUP (ORDER BY opened_at - presented_at) AS p95_queue_wait,
  percentile_cont(0.95) WITHIN GROUP (ORDER BY decided_at - opened_at) AS p95_decision_time,
  count(*) FILTER (WHERE decision = 'deny') AS denied,
  count(*) AS total
FROM approval_requests
WHERE created_at >= current_timestamp - interval '14 days'
GROUP BY action_class;

A sintaxe exata dos percentis varia entre bancos de dados. A medição não. Informe p50 e p95 para cada classe de ação, junto com a quantidade e a taxa de negação. Uma média faz uma experiência de cinco segundos parecer boa ao lado de algumas solicitações que ficaram paradas por noventa minutos. O p95 mostra se a cauda lenta interrompe tarefas reais.

Registre também se o agente cancelou, tentou novamente ou abandonou a tarefa antes de a decisão chegar. Uma aprovação tardia que é executada depois de o agente ter escolhido outro caminho é pior que uma negação comum. Ela cria uma ação que já não corresponde ao trabalho diante da pessoa desenvolvedora.

Não recompense revisores apenas por reduzir o tempo de decisão. Isso transforma negações cuidadosas em um aparente problema de desempenho. Analise juntos a distribuição de permissões, negações, expirações e retiradas. Uma queda repentina nas negações combinada com tempos de leitura muito curtos geralmente significa que as pessoas aprenderam que clicar em permitir elimina um incômodo.

O tempo de espera e o tempo de revisão apontam para defeitos diferentes

A espera na fila e o tempo de decisão compartilham um relógio, mas têm causas e responsáveis diferentes. Tratá-los como uma coisa só gera correções ruins.

A espera na fila aumenta quando as solicitações chegam à pessoa errada, muitas pessoas presumem que outra decidirá, as notificações chegam fora do horário de trabalho ou o revisor não tem motivo para interromper a tarefa atual. Adicionar mais notificações costuma piorar isso. A mesma responsabilidade ambígua é espalhada por mais pessoas.

O tempo de decisão aumenta quando o cartão obriga o revisor a reconstruir a intenção do agente. Uma solicitação como "POST /v1/resources" não é revisável. O revisor precisa saber o destino, a operação, a quantidade de objetos, a autoridade usada e a consequência visível. Não deveria precisar abrir um terminal, inspecionar o código-fonte e inferir se a solicitação cria um rascunho ou envia uma mensagem aos clientes.

Um bom cartão de aprovação responde a cinco perguntas em linguagem simples:

1. Qual execução do agente fez a solicitação e qual processo assinado iniciou essa execução?
2. Qual destino externo receberá a ação?
3. O que mudará ou quais dados sairão da máquina?
4. Qual autoridade limitada permite a ação?
5. O que acontece se o revisor negar ou não fizer nada?

Não confunda mais detalhes com contexto melhor. Um payload bruto completo pode esconder o único campo importante. Mostre primeiro uma consequência concisa e permita que o revisor inspecione o comando, o endpoint, os cabeçalhos sem segredos e o payload quando necessário. Quem aprova uma exclusão precisa dos nomes dos objetos afetados. Quem aprova uma leitura HTTP precisa do host, do caminho e do escopo da consulta. Cada ação precisa de evidências compatíveis com seu risco.

O erro recorrente é otimizar a espera na fila concedendo uma aprovação ampla para a sessão, embora o revisor estivesse lento porque a ação não era clara. Isso transforma um problema de contexto em um problema de autoridade. Primeiro, corrija a descrição e o limite da ação.

O erro inverso também aparece: equipes exigem uma confirmação separada para cada uma de cem leituras comuns porque a fila parece insegura. A fila é insegura porque cria habituação. Prompts repetidos de baixo impacto treinam o revisor a aprovar pelo formato e pelo momento, não pelo conteúdo. Esse hábito permanece quando surge uma solicitação importante.

Uma fila de revisão é uma evidência de que o fluxo precisa de outro formato

Uma fila não apenas atrasa o trabalho. Ela muda o comportamento do agente e da pessoa. O agente tenta novamente, divide a tarefa em chamadas menores ou mantém um plano incompleto. A pessoa vê uma pilha crescente e começa a limpá-la em lotes. Cada resposta faz a fila parecer menos alarmante, até que uma solicitação incomum fica escondida entre outras familiares.

Considere uma falha comum. Um agente recebe a tarefa de preparar uma nota de versão a partir de dados de um issue tracker. Primeiro, ele lê a lista de projetos, depois busca cada issue, lê os comentários das issues selecionadas e cria uma nota em rascunho. Um fluxo que exige aprovação para cada chamada HTTP transforma uma tarefa modesta em dezenas de prompts.

Às 9h30, uma pessoa desenvolvedora aprova as primeiras leituras com cuidado. Às 9h45, ela entra em uma reunião. Às 10h30, o agente acumulou novas tentativas e chamadas relacionadas. A pessoa retorna, vê uma parede de solicitações para o mesmo serviço e as aprova rapidamente. Uma solicitação cria um comentário público em vez de uma nota em rascunho, porque o endpoint e o resultado pretendido estavam escondidos no texto bruto. Não havia uma chance realista de distinguir essa solicitação naquela fila.

A decisão ruim começou antes do comentário público. O fluxo fez leituras rotineiras competirem com uma gravação visível. Também obrigou a pessoa a manter o contexto durante uma longa interrupção. Isso é um defeito de projeto, não uma falha do revisor.

Corrija o problema agrupando o trabalho de acordo com a intenção relevante. Uma sessão de leitura pode cobrir um serviço identificado e a duração da tarefa se sua autoridade não puder alterar nada. A criação de um rascunho pode pedir uma decisão explícita com o local e o público do rascunho. A publicação pública deve permanecer separada porque sua consequência muda a pergunta da revisão.

Não resolva isso com uma instrução ampla para o agente "usar o issue tracker". Essa frase esconde informação demais. Ela não diz ao revisor se o agente pode ler issues privadas, editar rótulos, comentar publicamente ou excluir dados. Os nomes dos escopos devem corresponder a ações que as pessoas consigam reconhecer depois.

A mesma lógica vale para SSH. Uma solicitação para inspecionar o log de um serviço e outra para executar uma migração podem viajar pela mesma conexão, mas não pertencem à mesma classe de aprovação. A identidade da conexão não é a identidade da ação.

O escopo da aprovação deve seguir a consequência, não o transporte

Um bom limite de aprovação descreve aquilo com que a pessoa está concordando. HTTP e SSH, um comando e uma chamada de API, um processo local e um remoto são detalhes de transporte. Eles importam para a implementação, mas não dizem ao revisor se a ação é reversível, externa ou dispendiosa.

Comece pelas classes de consequência. Operações de leitura podem divulgar dados, portanto "leitura" não significa automaticamente algo inofensivo. As gravações também são diferentes: criar um rascunho privado, alterar uma configuração de produção e enviar uma mensagem modificam o estado, mas exigem níveis distintos de análise. Separe essas ações antes de decidir quais interações podem compartilhar uma aprovação.

Depois, limite o escopo nas dimensões que um revisor consegue verificar:

• Destino: um host, repositório, projeto ou ambiente identificado.
• Operação: ler, criar um rascunho, atualizar um campo especificado ou executar uma família de comandos identificada.
• Conjunto de objetos: os registros, arquivos ou serviços específicos envolvidos.
• Duração: uma ação, uma execução do agente ou uma janela agendada curta.
• Consequência: privada, reversível, visível externamente ou destrutiva.

Evite escopos baseados em detalhes de implementação. "Permitir solicitações POST" é uma regra de transporte, não um limite de aprovação. Um POST pode criar um rascunho ou remover uma conta. "Permitir acesso à linha de comando" tem o mesmo defeito. Ele concede um meio de ação, não um resultado compreendido.

As pessoas costumam defender uma aprovação ampla de sessão porque as solicitações individuais interrompem o fluxo. Elas têm razão sobre a interrupção, mas erram no remédio quando a sessão pode misturar operações sem relação. Uma sessão só é adequada quando seu destino e sua consequência permitida permanecem claros durante toda a sua existência. Se um agente passa de reunir notas de versão a alterar permissões do repositório, precisa de uma nova decisão.

Use confirmação por ação quando a consequência continuar alta mesmo dentro de uma execução confiável. Publicar, excluir, alternar material de acesso, alterar a conectividade da rede e enviar informações para fora da equipe normalmente pertencem a essa categoria. Não use confirmação por ação como punição para trabalho desconhecido. Use-a quando cada ocorrência exigir julgamento humano.

Reformule o trabalho rotineiro antes de afrouxar os controles de revisão

Quando a latência de aprovação ultrapassar o orçamento, primeiro remova as solicitações que nunca deveriam ter se tornado interativas. Isso não significa permitir ações arbitrárias. Significa limitar o trabalho rotineiro o suficiente para que a pessoa aprove a execução ou a tarefa, em vez de cada chamada mecânica.

Analise uma classe lenta nesta ordem:

1. Selecione as solicitações no p95 e leia a sequência completa ao redor de cada uma. Conte as novas tentativas e chamadas duplicadas separadamente das chamadas necessárias.
2. Marque a primeira ação em que a consequência muda. Esse costuma ser o ponto correto para uma decisão explícita.
3. Consolide leituras determinísticas sob um escopo de tarefa limitado, com destino conhecido e expiração no fim da execução.
4. Separe publicação externa, exclusão, alterações de permissão e exportações amplas de dados em solicitações distintas.
5. Teste novamente a tarefa com uma pessoa revisora que não tenha projetado o fluxo. Se ela não conseguir declarar o resultado esperado antes de aprovar, restrinja a solicitação outra vez.

Agrupar ajuda apenas quando o próprio lote é revisável. "Criar estas quatro issues em rascunho no projeto Amber" é um lote razoável se o cartão nomear as quatro issues e seu destino. "Executar todo o trabalho restante da versão" não é um lote. É uma delegação aberta.

Não faça o agente decidir o limite do lote apenas por conveniência. Entregue a ele um objeto de tarefa: destino, resultado solicitado, fontes de dados permitidas e expiração. O agente pode reunir as chamadas sob esse objeto, mas uma mudança de destino ou consequência deve fechar o lote. Isso também melhora a análise de incidentes, porque o log representa uma unidade real de trabalho, não uma longa sequência de solicitações anônimas.

O trabalho agendado exige uma reformulação diferente. Se uma pessoa precisa aprovar uma manutenção noturna durante a madrugada, a equipe criou uma falha previsível. Agende uma janela de revisão antes da execução, atribua um responsável de plantão com um orçamento adequado ou adie o trabalho. Não disfarce uma aprovação sem supervisão como automação.

A capacidade de tentar novamente merece atenção especial. O agente deve reutilizar o mesmo identificador de solicitação pendente quando a ação subjacente não tiver mudado. Criar um novo cartão de aprovação para cada nova tentativa produz volume artificial na fila e destrói a percepção de sequência do revisor. Se o destino, o payload, a autoridade ou a consequência pretendida mudar, crie uma nova solicitação e diga o que mudou.

A tela de aprovação deve facilitar a decisão correta

O revisor precisa de uma declaração compacta de intenção, não de um convite para fazer engenharia reversa de uma execução do agente. Construa a tela em torno da decisão que precisa ser tomada agora e ofereça evidências mais profundas sem obrigar a pessoa a procurá-las.

Coloque o resultado da ação primeiro: "Criar uma nota de versão privada em rascunho no projeto Amber" diz mais que um método e um caminho. Mostre o destino ao lado. Informe se a ação lê, altera, exclui ou envia dados. Se usar SSH, nomeie o host e mostre o comando de forma que redirecionamentos, gravações de arquivos e mudanças de privilégios fiquem claros.

Mostre também o contexto da autoridade. O revisor deve saber se a solicitação veio de um processo novo do agente ou de uma execução já aprovada e se essa ação exige uma confirmação especial. A identidade do processo importa porque a aprovação de um processo do agente não deve autorizar silenciosamente outro processo sem relação que por acaso use o mesmo protocolo.

O Sallyport usa uma sequência fixa de decisões para isso: um cofre bloqueado nega todas as ações, um processo novo do agente recebe autorização de sessão por padrão e uma credencial pode exigir aprovação a cada uso. O primeiro cartão da sessão começa pela autoridade de assinatura do código do processo, que é o detalhe certo para mostrar a uma pessoa que decide se aquela é a execução que pretendia iniciar.

Não transforme a tela em um editor de regras. Uma pessoa sob pressão de prazo deve aprovar, negar ou inspecionar uma solicitação concreta. Se a equipe pede repetidamente uma exceção, reformule o escopo da tarefa ou o limite da credencial fora do momento da interrupção. Colocar uma pequena linguagem de políticas no caminho de aprovação apenas pede que pessoas cansadas programem decisões de segurança sob pressão.

A negação deve ser informativa. Retorne uma categoria de motivo que o agente possa usar, como expirada, destino incorreto, necessidade de um escopo mais restrito ou revisão humana obrigatória. Por padrão, não retorne comentários privados do revisor a um agente não confiável. O agente precisa de informação suficiente para parar de tentar novamente ou escolher uma tarefa alternativa segura, não de uma transcrição da deliberação interna.

Defina responsabilidade e escalonamento antes que uma solicitação urgente chegue

Um orçamento de aprovação sem responsável vira um desejo. Cada classe de ação precisa de uma pessoa ou escala responsável pela decisão durante o período em que pode ser executada. Uma equipe pode delegar a revisão, mas não pode delegar o fato de que alguém precisa tomar a decisão.

Defina o que acontece em cada limite do orçamento. Na metade do orçamento, o sistema pode notificar uma vez o revisor designado se a solicitação continuar sem ser vista. No limite, uma solicitação de baixo impacto pode expirar. Uma solicitação de alto impacto deve expirar e notificar a pessoa responsável pela tarefa ou a escala de plantão, em vez de permanecer pendente para sempre. O momento exato é menos importante que tornar o estado visível e finito.

Use o horário comercial com honestidade. Se uma pessoa executa um agente localmente à noite e a ação precisa da aprovação de um colega, a tarefa talvez precise esperar. Isso é aceitável. O problema é quando a interface sugere progresso imediato e deixa o agente tentando novamente em uma fila sem supervisão.

O escalonamento nunca deve ampliar a autoridade. Uma solicitação escalada vai para um revisor mais bem posicionado, não para um caminho de autorização automática. Essa distinção importa durante incidentes, quando a urgência tenta as pessoas a ignorar todos os controles de uma vez. Procedimentos de emergência pré-aprovados podem existir, mas devem descrever uma ação limitada, uma responsabilidade identificada e uma revisão posterior. "A produção está quebrada" não é um escopo de aprovação.

Analise o custo para as pessoas junto com o atraso do agente. Se uma pessoa desenvolvedora recebe quase todos os prompts, há um problema de roteamento mesmo quando a latência mediana parece boa. Se todos os revisores veem todas as solicitações, a equipe criou uma caixa de entrada compartilhada com rótulos de segurança. Os dois padrões produzem fadiga e responsabilidade fraca.

Audite a fila como uma sequência de decisões

Um bom histórico de auditoria permite reconstruir mais que a ação final. Ele deve mostrar a execução do agente, a solicitação apresentada ao revisor, a decisão, a chamada externa real e qualquer cancelamento ou nova tentativa. Sem essa sequência, a equipe não consegue saber se uma aprovação tardia causou uma ação obsoleta ou se o agente mudou de plano depois da negação.

Mantenha as evidências da aprovação e da ação conectadas por identificadores, mas não as confunda. A aprovação responde quem autorizou uma intenção declarada. O registro da ação responde o que foi realmente tentado e o que o destino retornou. Um investigador precisa dos dois quando a solicitação do agente falha no meio ou quando um serviço remoto interpreta um payload de forma inesperada.

O Sallyport projeta um diário Sessions e um diário Activity a partir de um único registro de auditoria criptografado e encadeado por hash. O comando sp audit verify verifica a cadeia offline sobre o texto cifrado, sem precisar da chave do cofre. Isso é útil quando alguém precisa testar a integridade do log sem abrir as credenciais do agente.

Use o registro de auditoria em uma revisão semanal das exceções, não como um depósito de dados que ninguém consulta. Extraia as solicitações expiradas, os exemplos mais lentos do p95, as ações negadas e as ações executadas depois de uma longa espera. Para cada uma, faça uma pergunta concreta: o atraso veio da responsabilidade, da intenção pouco clara, do escopo amplo demais ou de uma tarefa que deveria ter sido agendada de outra forma?

Não avalie pessoas pela velocidade de aprovação. Avalie o fluxo por sua capacidade de colocar uma decisão compreensível nas mãos de alguém responsável antes do prazo da tarefa. Se a revisão repetida produz apenas permissões habituais, elimine essa repetição. Se uma ação rara exige reflexão cuidadosa, ofereça o tempo, o contexto e a responsabilidade que essa reflexão requer.

Comece coletando uma semana de registros de tempo do ciclo de vida. Escolha a classe de ação com a pior espera de fila no p95, inspecione dez sequências completas de solicitações e altere o limite que criou mais prompts duplicados. Esse trabalho ensinará mais que outro painel.