As operações em massa pela API devem mostrar primeiro seus alvos?

Um agente de IA nunca deve transformar uma solicitação vaga, como "arquivar contas inativas", em uma chamada de gravação sem limites. Antes de alterar muitos registros, ele deve mostrar o conjunto exato de alvos, preservar a seleção exibida e exigir uma confirmação que se aplique somente a essa seleção.

Isso parece excesso de cuidado até que um filtro errado corresponda ao primeiro cliente ativo, a um tenant de teste ou a uma conta com uma exceção que ninguém registrou no chamado. Uma pessoa pode cometer o mesmo erro, mas um agente consegue enviar a solicitação na velocidade de uma máquina e continuar depois do primeiro resultado incorreto. O controle importante não é um aviso educado antes da solicitação. É um limite verificável entre decidir quem será afetado e alterá-lo.

Uma contagem não descreve a área de impacto

Uma contagem informa quantos registros uma operação afetará. Ela não informa quais são. "482 assinaturas" pode parecer plausível e ainda incluir um tenant empresarial, contas suspensas que precisam ser mantidas por motivos legais ou registros de uma região que não foi mencionada na solicitação.

Exija um manifesto de alvos. Para uma operação pequena, o manifesto pode listar cada identificador com contexto suficiente para que um revisor reconheça erros. Para uma operação maior, mostre a lista completa em uma tela de revisão que permita exportação, além de agrupamentos úteis, como status, tenant, região ou responsável. Não obrigue a pessoa a deduzir a composição apenas a partir de uma string de filtro.

Uma boa visualização responde a cinco perguntas concretas:

• Qual recurso e ambiente da API receberão a gravação?
• Qual seletor produziu este conjunto?
• Quais registros fazem parte dele, identificados por IDs estáveis e campos compreensíveis?
• Qual alteração cada registro receberá?
• Quais registros foram excluídos por uma regra explícita?

O último item captura uma falha incômoda: uma solicitação pode estar tecnicamente correta e ainda violar a intenção porque uma exceção oculta nunca entrou no seletor. Se o operador disser "todas as faturas não pagas, exceto as contestadas", a visualização deve informar claramente a exclusão das faturas contestadas. O silêncio deixa o revisor tentando adivinhar se o agente entendeu a exceção ou simplesmente a esqueceu.

Não confunda uma amostra com um manifesto. Mostrar os primeiros 20 registros de uma atualização com 10.000 registros prova muito pouco. Amostras ajudam a encontrar problemas óbvios, mas a seleção armazenada precisa abranger todos os registros que podem ser alterados.

A visualização e o commit precisam estar vinculados à mesma seleção

Uma visualização só tem valor quando o commit consegue provar que age sobre o conjunto revisado. Se um agente visualiza uma busca às 14h e executa a mesma busca novamente às 14h05, antes da gravação, pode acabar afetando uma população diferente. Novos registros podem entrar no filtro, registros existentes podem mudar de estado e a paginação pode reordenar as linhas.

O desenho mais seguro de uma API cria um snapshot de seleção no servidor. O endpoint de visualização retorna um ID de seleção, seu prazo de validade, a quantidade de membros e uma revisão ou digest. O endpoint de commit aceita esse ID e o recusa quando o snapshot expirou ou mudou.

POST /v1/subscriptions/selections
Content-Type: application/json

{
  "filter": {
    "status": "past_due",
    "region": "eu",
    "exclude_tags": ["disputed", "legal_hold"]
  },
  "fields": ["id", "customer_name", "status", "amount_due", "tags"]
}

Uma resposta adequada teria esta estrutura:

{
  "selection_id": "sel_7f2c",
  "expires_at": "2025-03-08T15:00:00Z",
  "count": 482,
  "digest": "sha256:4c76...",
  "records": [
    {"id":"sub_104","customer_name":"Northwind Parts","status":"past_due","amount_due":3100,"tags":[]},
    {"id":"sub_219","customer_name":"Orchard Studio","status":"past_due","amount_due":450,"tags":[]}
  ]
}

A matriz records pode chegar por meio de um cursor, mas o ID de seleção precisa se referir à composição completa e congelada, não apenas à página atual. A interface de revisão pode percorrer o resultado sem mudar o objeto em análise.

Depois da aprovação, o agente envia a seleção salva em vez do filtro original:

POST /v1/subscriptions/bulk-actions
Content-Type: application/json
Idempotency-Key: 9b03c6f0-7dfa-4f22-b0e5-4b52ca4f1a51

{
  "selection_id": "sel_7f2c",
  "expected_digest": "sha256:4c76...",
  "action": {"type": "pause_collection", "reason": "approved credit hold review"}
}

O servidor deve recusar um digest diferente com uma resposta de conflito. Uma solicitação bem-sucedida deve retornar um ID de ação e locais dos resultados de cada registro, não apenas {"ok": true}. Uma mensagem genérica de sucesso esconde a conclusão parcial, que é o modo normal de falha em trabalhos em massa.

Se a API do fornecedor não puder criar snapshots, o agente ainda poderá vincular a operação armazenando uma lista ordenada de IDs, calculando o hash de uma representação canônica e enviando essa lista de IDs ao endpoint de gravação. Isso tem limitações: limites de URL e de corpo, registros desatualizados e APIs que aceitam apenas um filtro. Nesses casos, não finja que o controle é equivalente. Faça uma nova visualização imediatamente antes de cada lote limitado e pare quando a composição for diferente.

A paginação estável decide se a revisão significa alguma coisa

A paginação por offset é uma base ruim para uma decisão de aprovação sobre dados que estão sendo alterados. Suponha que o agente liste a primeira página, veja os registros de 1 a 100 e, em seguida, outro processo arquive 20 registros perto do início. Quando o agente solicitar o offset 100, poderá pular registros que subiram de posição. Inserções também podem causar duplicatas. A contagem revisada pode continuar parecendo normal, enquanto a composição individual muda.

Use um cursor emitido pelo serviço e pergunte ao provedor da API se esse cursor lê a partir de um snapshot. Um cursor que apenas codifica uma posição de ordenação ainda pode sofrer alterações se o campo ordenado mudar. Ordenar por um campo mutável como updated_at é especialmente ruim quando a própria ação proposta atualiza esse registro de data e hora.

Quando você controla a API, exponha explicitamente estas propriedades:

• Um identificador de snapshot ou uma marca d'água superior imutável.
• Uma ordenação determinística por um identificador imutável.
• Um prazo de validade que force uma nova visualização, em vez de retornar dados mais recentes silenciosamente.
• Um campo de resposta que informe se o chamador está lendo um snapshot consistente.

A RFC 9110 classifica métodos como POST, PUT, PATCH e DELETE como não seguros porque eles podem alterar o estado do servidor. Essa classificação não é um desenho de fluxo de trabalho, mas sustenta uma regra prática: não trate um endpoint de listagem seguido por um método não seguro como uma única operação atômica só porque o código coloca as duas chamadas lado a lado.

Para uma API externa que não ofereça cursores estáveis nem snapshots de seleção, reduza o escopo até que alguém possa revisar cada solicitação. É tentador contornar a limitação com um cache no agente e um loop longo. Essa solução frequentemente cria um segundo banco de dados sem limite transacional e sem uma resposta confiável quando um registro muda no meio da execução.

A aprovação precisa descrever a alteração, não apenas os registros

O revisor precisa aprovar tanto a composição quanto o efeito. "Aplicar alterações a 482 registros" não significa nada se a interface não disser se os registros serão excluídos, desativados, reatribuídos, cobrados, publicados ou terão um campo alterado. Inclua o valor anterior e o valor proposto depois da alteração para cada campo que mudará, com um resumo conciso quando todos os valores receberem a mesma atualização.

Diferencie gravações absolutas de gravações condicionais. Uma gravação absoluta diz status = archived, independentemente do que tenha acontecido depois da visualização. Uma gravação condicional diz "arquivar somente se o status ainda for inactive e a versão ainda for 17". Em geral, gravações condicionais são mais seguras porque falham de forma restritiva quando outra pessoa altera o registro.

Use uma versão, um ETag ou a última revisão conhecida em cada alteração quando a API oferecer esse recurso. Isso não substitui o manifesto de alvos. Ele resolve outro problema: um registro revisado pode já não estar elegível quando a execução começar.

Um registro compacto de aprovação pode ser representado assim:

{
  "request_id": "req_91a8",
  "selection_id": "sel_7f2c",
  "selection_digest": "sha256:4c76...",
  "target_count": 482,
  "action": {
    "type": "pause_collection",
    "precondition": {"status": "past_due"}
  },
  "approved_by": "operator account identifier",
  "approved_at": "2025-03-08T14:16:02Z"
}

Não permita que um agente reutilize essa aprovação para uma ação diferente contra o mesmo conjunto. Pausar uma cobrança, emitir créditos e excluir registros têm consequências diferentes, mesmo quando a lista de alvos é idêntica. Vincule a aprovação a uma carga de ação canônica, além do digest da seleção.

Os limites de tempo importam. Uma aprovação que continua válida até o momento em que o agente decide usá-la transforma uma revisão humana pontual em uma permissão permanente. Dê às aprovações um prazo curto, adequado à operação, invalide-as quando a seleção mudar e exija uma nova decisão depois que o agente alterar a ação de maneira relevante.

A conclusão parcial precisa de um registro e de uma regra de parada

Toda operação em massa acaba encontrando um limite de taxa, timeout, falha de validação ou interrupção de rede. A resposta perigosa é repetir o trabalho inteiro sem saber quais registros já foram alterados. Isso cria cobranças duplicadas, notificações repetidas ou uma trilha de auditoria enganosa.

Atribua um único ID de operação e uma única chave de idempotência à ação solicitada. Registre o resultado de cada alvo: concluído, falhou, ignorado porque uma pré-condição mudou ou desconhecido porque o serviço não retornou um resultado persistente. "Desconhecido" não é o mesmo que falhou. Trate-o como um estado de investigação antes de tentar novamente.

Defina uma regra de parada antes da execução. Uma regra sensata pode interromper o trabalho depois de um erro estrutural, como uma falha de autorização ou uma resposta com esquema inesperado, mas permitir que falhas isoladas de validação sejam reunidas para revisão. Evite uma configuração genérica de "continuar em caso de erro". Ela transforma uma mudança não reconhecida no contrato da API em uma longa lista de registros danificados.

Considere uma falha comum. Um agente visualiza 800 contas de usuário para uma alteração de função e começa um loop no cliente. As primeiras 300 solicitações funcionam. Uma implantação altera o endpoint, fazendo com que um campo ausente use administrator como padrão, em vez da função viewer pretendida. A resposta seguinte parece bem-sucedida. Se o loop continuar, o erro se espalhará. Se o agente registrar o formato de cada resposta e parar quando o contrato for diferente da ação aprovada, a área de impacto terminará na primeira resposta anômala.

Para trabalhos destrutivos, planeje a compensação antes da execução. Uma solicitação de compensação precisa capturar o valor anterior de cada registro, não fazer uma promessa vaga de que alguém poderá desfazer a alteração. Mesmo assim, não chame uma reversão de inofensiva. Uma edição legítima posterior pode tornar uma reversão cega incorreta, e efeitos externos, como e-mails ou exportações, talvez não possam ser revertidos.

O acesso de leitura pode expor tanto quanto uma gravação errada

As equipes costumam aplicar confirmação cuidadosa à exclusão e nenhuma à seleção. Isso ignora o fato de que um agente pode recuperar uma lista completa de clientes, endereços pessoais, estados de pagamento ou notas internas para montar sua visualização. A visualização deve expor dados suficientes para que uma pessoa reconheça os registros, não todos os campos oferecidos pela API subjacente.

Solicite deliberadamente um conjunto estreito de campos. ID estável, nome de exibição, status, responsável e os valores relevantes para a alteração proposta normalmente bastam. Mantenha segredos, tokens, notas de texto livre e dados pessoais sem relação com o caso fora da resposta de seleção. Isso torna a revisão menos ruidosa e reduz o que o agente pode repetir em mensagens posteriores.

O mesmo princípio se aplica aos filtros. Um agente não deve ampliar uma consulta porque não tem permissão para inspecionar um campo. Se não puder provar se um registro pertence à seleção, deverá expor a ambiguidade e aguardar que uma pessoa a resolva. Adivinhar não é julgamento operacional.

Trate o ambiente como parte do manifesto. Produção, staging e um sandbox podem expor nomes de recursos idênticos. Coloque o host de destino ou o identificador da conta ao lado da contagem de alvos e do resumo da ação. Engenheiros já aprovaram uma lista de registros perfeitamente razoável no ambiente errado porque a visualização tratava o ambiente como um detalhe secundário.

Os agentes precisam de autoridade sobre a chamada, não da posse das credenciais

Um agente que mantém um token amplo da API pode fazer a chamada em massa antes que alguém veja o conjunto de alvos. É possível adicionar prompts e registros a esse desenho, mas a credencial ainda dá ao processo uma rota de escape. Mantenha a credencial com um executor de ações capaz de recusar ou aprovar a solicitação antes que ela chegue à API externa.

O Sallyport adota essa abordagem para ações HTTP e SSH compatíveis: o agente solicita a ação pela conexão MCP, enquanto o aplicativo retém a credencial e executa a ação. Sua autorização por sessão e a aprovação opcional da chave por chamada são adequadas a um fluxo em que o agente pode preparar uma solicitação em massa, mas não deve obter material secreto reutilizável.

Essa aprovação não é todo o desenho de segurança para operações em massa. Um cartão de aprovação para uma chamada HTTP não consegue informar ao revisor se um filtro retornará 10 registros ou 10.000, a menos que o agente tenha primeiro produzido e preservado o manifesto de alvos. Use o gateway para controlar a autoridade e faça o fluxo da aplicação vincular visualização, seleção, aprovação e commit.

O registro de auditoria também precisa de dois níveis de detalhe. Um registro deve mostrar a execução do agente que solicitou o trabalho e quem o aprovou. Outro deve mostrar cada chamada externa, incluindo o digest da seleção, o ID da operação, o endpoint e o status do resultado. Se ocorrer um incidente, os investigadores precisarão responder tanto a "qual processo solicitou?" quanto a "quais registros mudaram?"

Um fluxo em massa deve falhar de forma restritiva quando a intenção ficar ambígua

Construa o fluxo do agente de modo que ele não possa passar de uma solicitação em linguagem natural diretamente para uma alteração. A sequência a seguir é deliberadamente sem graça, porque o que é previsível é mais fácil de investigar.

1. O agente converte a solicitação em um seletor, uma alteração proposta, um ambiente e exclusões. Ele pede esclarecimentos se algum desses itens continuar ambíguo.
2. Ele cria uma seleção estável e recupera os campos de revisão de todos os membros. Registra o ID da seleção, o digest, a consulta, o horário e a integridade das páginas.
3. Ele apresenta o manifesto e o efeito proposto. Uma pessoa aprova exatamente esse par ou o rejeita.
4. Ele envia uma solicitação de commit com a referência da seleção, o digest esperado, a carga da ação, a chave de idempotência e as versões dos registros, quando disponíveis.
5. Ele relata separadamente os resultados concluídos, falhos, ignorados e desconhecidos. Nunca transforma um resultado parcial em uma mensagem alegre dizendo que o trabalho terminou.

Não aprove um comando bruto como "executar o script de limpeza" quando o comando puder calcular seus alvos mais tarde. Essa prática é popular porque é rápida e familiar, especialmente em equipes que já confiam nos próprios scripts. Ela falha porque a aprovação abrange o texto do código, não o conjunto de dados ativo. Uma pequena mudança nos dados entre a confirmação e a execução pode fazer o comando aprovado realizar um trabalho que não foi aprovado.

Para trabalhos recorrentes, defina seletores restritos e uma quantidade máxima. Exija revisão sempre que a seleção ultrapassar esse limite ou incluir uma categoria desconhecida. Uma quantidade máxima é uma proteção, não uma autorização. O manifesto continua sendo a evidência de quais registros o trabalho realmente tocou.

A primeira tarefa de implementação é simples: faça seu endpoint em massa retornar um identificador de seleção e um digest, e depois recuse solicitações de commit que não repitam os dois valores. Quando esse contrato existir, agentes, painéis e scripts terão um limite rígido que poderão respeitar.