Minimização de dados de agentes de IA para chamadas de ferramentas mais seguras

Um agente de IA não deve receber o registro de um cliente só porque talvez precise de uma informação dele mais tarde. Toda chamada de ferramenta precisa de um contrato menor: a ação, os campos mínimos necessários para executá-la e uma saída que informe ao agente o que aconteceu sem entregar uma nova pilha de dados do cliente.

As equipes costumam vazar dados na ligação entre um agente capaz e uma API interna conveniente. Elas dão ao agente uma consulta geral de clientes, retornam a resposta completa e chamam o resultado de contexto útil. Essa escolha transforma cada prompt posterior, transcrição, nova tentativa, rastreamento de depuração e resultado de ferramenta em um lugar onde o registro pode se espalhar.

A solução não é um prompt inteligente de remoção de dados. É uma disciplina de projeto: mapear cada ação antes de expô-la, impor uma solicitação restrita no limite de execução e impedir que respostas brutas dos serviços upstream cheguem ao agente.

A permissão de uma ferramenta não dá ao agente direito ao registro completo

A permissão para chamar uma API e a permissão para ver todos os campos que essa API pode retornar são decisões diferentes. As equipes misturam as duas porque uma conta de serviço muitas vezes consegue ler um objeto amplo, enquanto a ferramenta do agente precisa de apenas uma pequena parte dele.

Considere um agente que precisa decidir se deve enviar um lembrete de pagamento. O serviço de entrega pode precisar de um endereço do destinatário, um identificador de modelo e uma referência de fatura. O agente talvez precise apenas de eligible: true, um nome seguro para exibição e uma referência da ação. Ele não precisa do histórico de pagamentos, das notas do cliente, das informações fiscais nem do endereço que o remetente usa nos bastidores.

Uma ferramenta ampla como get_customer cria uma armadilha conveniente. Depois que ela existe, os prompts começam a usá-la para tarefas sem relação porque parece mais barato que criar uma ferramenta própria para a ação. As pessoas então tentam compensar com instruções como «não exponha campos sensíveis». Instruções não removem campos de uma resposta JSON.

Mantenha estas três perguntas separadas:

• Este processo de agente pode iniciar esta ação?
• Quais campos o executor precisa receber para executá-la?
• Quais fatos o agente precisa receber depois que ela terminar?

Cada pergunta deve gerar sua própria restrição. O controle de acesso responde à primeira. A validação da solicitação responde à segunda. A modelagem da resposta responde à terceira. Um único token de API genérico e um endpoint JSON flexível não respondem bem a nenhuma delas.

Essa distinção importa especialmente quando um agente usa uma ferramenta repetidamente. Uma consulta ampla feita uma vez pode parecer aceitável em uma demonstração. Em uma execução real, o agente pode chamá-la de novo depois de uma nova tentativa, citar a saída em uma solicitação posterior ou passá-la para outra ferramenta. O primeiro campo desnecessário se transforma em várias cópias desnecessárias.

Crie o mapa de dados em torno de uma ação, não de uma tabela do banco

Um mapa de dados útil começa com um verbo e um efeito externo. «Ler cliente» não é uma ação adequada para esse objetivo. «Confirmar se uma fatura está vencida» e «criar uma etiqueta de envio» são ações porque cada uma tem um destinatário, uma finalidade e um resultado esperado concretos.

Para cada ferramenta proposta, escreva um pequeno registro antes de criar o esquema:

A coluna da consulta confiável faz o trabalho difícil. Ela identifica as informações de que o executor pode precisar, mas o agente não. Mova essa consulta para trás do limite. O agente envia uma referência de fatura, e um serviço sob seu controle resolve o destinatário somente depois de verificar a ação.

Não transforme invoice_ref em uma cópia disfarçada de um endereço de e-mail ou em um identificador composto que contenha o nome do cliente. Referências opacas reduzem a divulgação incidental, mas não tornam automaticamente um sistema privado. Se uma referência permite que qualquer pessoa consulte um objeto de cliente, ela ainda precisa de autorização, expiração e restrição de público.

O Regulamento Geral sobre a Proteção de Dados da União Europeia apresenta o princípio relevante de forma clara no Artigo 5(1)(c): os dados pessoais devem ser adequados, pertinentes e limitados ao necessário para a finalidade. É na expressão «para a finalidade» que as equipes de engenharia costumam perder o cuidado. A finalidade não é «ajudar o agente a concluir seu trabalho». É a operação específica no limite, como enviar um lembrete ou abrir um chamado de suporte.

Um mapa também revela campos que nunca deveriam atravessar o limite em nenhuma direção. Notas em texto livre merecem sua própria linha. Elas costumam conter e-mails colados, documentos de identidade, credenciais, informações de saúde e a reclamação sem filtro de um cliente. Um campo genérico notes não tem um significado delimitado, portanto não pertence a uma solicitação de ferramenta rotineira.

Esquemas rígidos bloqueiam campos de conveniência antes da execução

Um esquema deve recusar campos que a ação não precisa. Ignorar propriedades extras silenciosamente parece uma atitude flexível, mas esconde um vazamento durante os testes e faz os desenvolvedores acreditarem que o campo foi aceito.

Suponha que um agente precise solicitar uma análise de reembolso. Este contrato de solicitação permite apenas uma referência do caso e um motivo selecionado. Ele recusa valores controlados pelo cliente, endereços e notas arbitrárias.

{
  "name": "request_refund_review",
  "description": "Create a review task for an existing support case.",
  "input_schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["case_ref", "reason_code"],
    "properties": {
      "case_ref": {
        "type": "string",
        "pattern": "^case_[A-Za-z0-9]{16}$"
      },
      "reason_code": {
        "type": "string",
        "enum": ["duplicate_charge", "service_not_received", "other"]
      }
    }
  }
}

Uma solicitação com customer_email, shipping_address, amount ou conversation_text deve falhar na validação com um resultado explícito, como:

{
  "error": "invalid_request",
  "message": "Unexpected property: customer_email"
}

Esse erro informa ao agente que ele deve usar o contrato e informa ao desenvolvedor que um campo indesejado chegou ao limite. Não repita o valor recusado no erro. Manipuladores de erro já causaram mais vazamentos que muitos caminhos de produção porque serializam a solicitação inteira que falhou para fins de depuração.

A validação do esquema, sozinha, não protege campos pertencentes ao servidor. Uma solicitação pode passar com uma case_ref aparentemente válida que pertence a outra conta, ou com um reason_code válido associado a uma referência de ação emitida para outro agente. O executor precisa vincular a referência ao emissor, à ação pretendida e ao período de validade. Pense em uma referência de ação como um comprovante de retirada, não como uma chave primária pública do banco.

Use um construtor de solicitações quando um agente começar com contexto não confiável ou amplo demais. O construtor deve extrair os campos permitidos e criar um objeto novo. Não pegue um objeto grande e apague algumas chaves conhecidas como perigosas. A remoção por lista de bloqueio falha quando surge um campo novo, quando a estrutura de um objeto aninhado muda ou quando alguém chama a ferramenta usando um alias com outro nome.

ALLOWED_REASONS = {"duplicate_charge", "service_not_received", "other"}

def build_refund_request(case_ref, reason_code):
    if not isinstance(case_ref, str) or not case_ref.startswith("case_"):
        raise ValueError("invalid case_ref")
    if reason_code not in ALLOWED_REASONS:
        raise ValueError("invalid reason_code")
    return {"case_ref": case_ref, "reason_code": reason_code}

Essa pequena função evita uma falha comum: passar um dicionário case inteiro para uma biblioteca cliente porque ela aceita argumentos nomeados arbitrários. O objeto de retorno explícito é sem graça. Em um limite de dados de clientes, sem graça é bom.

A saída da ferramenta precisa de seu próprio contrato

A saída bruta de uma ferramenta faz parte do contexto do agente, mesmo quando a ferramenta nunca recebe dados de clientes como entrada. Trate cada resposta como material que o agente pode citar, guardar, transformar ou enviar para outro sistema.

Uma resposta de provedor após a criação de um envio pode incluir o endereço completo do destinatário, número de telefone, informações da conta da transportadora, dados da etiqueta, detalhes de roteamento e campos internos de diagnóstico. O agente normalmente precisa apenas de uma referência do envio e da informação sobre se pode dizer ao cliente que o pedido está a caminho.

Defina separadamente a resposta voltada ao agente e o resultado voltado ao serviço:

{
  "status": "created",
  "shipment_ref": "ship_Q7J4K2P8",
  "customer_message_allowed": true
}

O serviço de execução pode armazenar ou encaminhar a resposta detalhada da transportadora para onde a equipe operacional precisa dela. Não deve retorná-la apenas porque isso facilita a depuração. Se uma pessoa operadora precisar de um recibo, ofereça uma interface protegida para isso. Não use a transcrição do agente como banco de dados para solução de problemas.

As respostas de erro exigem o mesmo tratamento. Uma API upstream pode retornar o endereço recusado, um número de conta ou um trecho citado da solicitação. Converta isso em um código de erro limitado para o agente, como recipient_unavailable, reference_invalid ou provider_retryable. Coloque os detalhes de diagnóstico protegidos em um sistema destinado à equipe operacional.

A especificação do Model Context Protocol define ferramentas como funções chamáveis com entradas e resultados estruturados. Essa estrutura oferece aos desenvolvedores um lugar claro para impor tipos de resposta. Uma ferramenta que retorna um bloco de texto ou JSON arbitrário perde essa vantagem. Um esquema de resposta restrito também facilita os testes do comportamento do agente, pois a próxima decisão só pode depender de campos conhecidos.

Evite retornar um campo chamado details se não puder declarar sua estrutura exata e suas regras de sensibilidade. Uma brecha vaga se torna permanente. Alguém colocará o resultado bruto ali durante um incidente e depois esquecerá de removê-lo.

Remoção de dados, pseudônimos e sigilo são controles diferentes

Substituir um nome por um token não significa que os dados se tornaram seguros para circular. Um token estável que possa ser relacionado a um banco de dados de clientes continua sendo dado pessoal na maioria dos modelos práticos de ameaça. Uma referência de ação de uso único, limitada a um chamador e a um período curto, tem um modo de falha muito mais restrito.

A remoção de dados elimina valores conhecidos de um objeto. Ela ajuda quando um sistema interno precisa mostrar um registro a uma pessoa operadora, mas é frágil como limite principal para agentes. Os nomes dos campos mudam. O conteúdo passa para estruturas aninhadas. Texto livre contém informações que nenhuma lista fixa de remoção consegue localizar com segurança.

A pseudonimização substitui um identificador por outro. Ela reduz a exposição quando o destinatário não consegue resolver o vínculo. Falha quando o mesmo agente pode chamar uma ferramenta ampla de consulta usando esse identificador, quando o token aparece em ferramentas sem relação ou quando o próprio valor carrega significado. acme-health-urgent-001 não é opaco só porque não contém um símbolo de e-mail.

O sigilo vem de manter os dados de resolução e as credenciais no lado confiável do limite. O agente envia uma instrução restrita, e um serviço resolve as informações protegidas somente para a ação permitida. Essa é a diferença que evita o erro conhecido de passar um objeto de cliente «higienizado» para um agente e presumir que o trabalho terminou.

Você também deve separar minimização de dados de autorização. Um agente devidamente autorizado ainda pode receber dados demais. Da mesma forma, um chamador não autorizado pode receber muito pouco, mas esse pouco ainda pode causar dano. Imponha os dois controles e teste-os de forma independente.

Credenciais amplas tornam os esquemas restritos menos confiáveis

Um esquema de solicitação perfeito não compensa um agente que possui uma credencial capaz de chamar diretamente a API subjacente. Se o agente puder ler o segredo ou usá-lo em seu ambiente de execução, ele poderá ignorar a ferramenta cuidadosamente projetada e pedir ao provedor uma resposta mais completa.

Coloque as credenciais onde a ação é executada, não onde o modelo raciocina. O executor injeta o cabeçalho de autorização ou a identidade SSH depois de validar a solicitação restrita. O agente vê o resultado, não o segredo, um espaço reservado ou uma cópia em uma variável de ambiente.

O OAuth 2.0, descrito na RFC 6749, usa escopos para limitar o acesso concedido a um cliente. O escopo é útil, mas muitas implementações tratam um escopo como um passe amplo para um departamento. Um escopo customers.read ainda pode permitir uma consulta do registro completo. Combine o escopo da credencial com endpoints específicos de ações e filtragem de respostas. Caso contrário, o escopo apenas limita qual coleção grande o agente pode pesquisar.

Mantenha a autoridade separada por efeito. Um agente que pode criar um rascunho não deve também ter autoridade para enviá-lo. Um agente que pode solicitar uma análise de reembolso não deve emitir o reembolso. Essa separação reduz a pressão para adicionar uma credencial administrativa genérica só para fazer um fluxo funcionar.

Para equipes do macOS que usam Sallyport, o aplicativo mantém as credenciais de API e SSH em seu cofre criptografado e executa a ação HTTP ou SSH em vez de revelar a credencial ao agente. Esse arranjo só ajuda se a chamada continuar restrita. Um token protegido ainda pode autorizar uma solicitação ampla demais.

Um fluxo de suporte mostra onde os dados se espalham

Um vazamento comum começa com uma solicitação razoável: permitir que um agente de suporte prepare uma resposta para uma entrega que falhou. A primeira implementação expõe get_order(order_id), que retorna o pedido, o perfil do cliente, o endereço de entrega, o status do pagamento, o histórico de suporte e os eventos da transportadora. O agente precisa do evento da transportadora e da permissão para enviar uma atualização aprovada.

O agente chama a consulta e recebe o registro completo. Depois passa detalhes selecionados para uma ferramenta de criação de mensagens. O prompt de criação agora contém o endereço e o histórico, embora nenhum dos dois afete a mensagem. Uma chamada de ferramenta que falha envia o prompt inteiro para um log de erro. Uma pessoa engenheira copia esse erro para uma tarefa de diagnóstico. A resposta ampla original se transformou em quatro problemas separados de retenção.

Crie o fluxo de outra forma. Dê ao agente uma ação assess_delivery_update que aceite order_ref. O serviço de execução verifica a autoridade do chamador, busca o pedido internamente, lê o status da transportadora, aplica a regra de contato e retorna apenas isto:

{
  "status": "contact_allowed",
  "event_code": "delivery_delayed",
  "approved_template": "delivery_delay_notice",
  "order_ref": "ord_9VJ3R6M1"
}

O agente pode decidir se a situação justifica a mensagem aprovada. Uma ação separada, send_approved_delivery_update, aceita order_ref e approved_template. Ela não aceita um endereço de e-mail nem um corpo em texto livre. O serviço resolve o destinatário e renderiza o modelo depois de verificar o consentimento e o estado do pedido.

Esse projeto parece mais restritivo porque é. Essa restrição é o objetivo. O agente não pode reutilizar casualmente um perfil de cliente para outra tarefa, e uma ferramenta posterior não pode receber os dados por acidente.

Não responda a isso com o argumento genérico de que «a ferramenta precisa de flexibilidade». A flexibilidade pertence ao código confiável da aplicação, onde pode ser testada, revisada e auditada quanto ao tratamento de dados. Dar flexibilidade a um agente por meio de objetos amplos de solicitação e resposta transfere o custo para cada prompt e cada sistema posterior.

Telas de aprovação não conseguem inspecionar todos os campos ocultos

A aprovação protege contra ações não autorizadas, mas não consegue fiscalizar com segurança cargas excessivas. Uma pessoa vê um resumo curto, decide sob pressão e aprova a ação. Se o serviço esconde um endereço ou histórico desnecessário dentro de uma solicitação, a aprovação não fez nada para reduzir a divulgação.

A aprovação também cria um incentivo ruim quando substitui o projeto adequado da ferramenta. As pessoas desenvolvedoras continuam adicionando campos porque «o usuário aprova todas as chamadas». Em pouco tempo, o cartão de aprovação contém detalhes demais para ser lido ou detalhes de menos para permitir uma decisão. As pessoas aprovam ações repetidas com aparência inofensiva sem perceber que uma solicitação inclui um campo novo.

Mostre a ação e seus parâmetros delimitados em uma interface de aprovação, mas imponha a lista permitida antes que essa interface apareça. A pessoa aprovadora deve escolher se autoriza send approved delivery update for ord_9VJ3R6M1, não inspecionar manualmente um registro de cliente serializado.

Use aprovação por chamada para efeitos em que cada execução merece atenção humana. Não a use como scanner de dados pessoais. A pessoa que vê a aprovação não tem tempo nem contexto para decidir se cada campo aninhado era necessário.

Um bom teste de revisão é simples: retire a pessoa aprovadora da história. O contrato da ferramenta ainda impediria que dados desnecessários saíssem do serviço confiável? Se a resposta for não, o limite está fazendo pouco.

Registros de auditoria devem comprovar ações sem virar outro armazenamento de dados

Você precisa de evidências quando um agente age em nome de um cliente. Não precisa de um arquivo permanente, legível pelo agente, com cargas completas para obter essa evidência.

Registre o nome da ação, o processo ou a sessão que a iniciou, o horário, o resultado, a decisão de autorização e uma referência de correlação. Se precisar de evidência de integridade da carga, registre um digest criptográfico de uma representação canônica e protegida, não a própria representação. Armazene os nomes dos campos aceitos, não seus valores sensíveis.

Por exemplo, um evento de auditoria pode manter este formato:

{
  "action": "send_approved_delivery_update",
  "session_ref": "sess_4KH8N2",
  "order_ref_digest": "sha256:8e4c...",
  "accepted_fields": ["order_ref", "approved_template"],
  "outcome": "sent",
  "authorized_by": "per_call"
}

Um digest não elimina magicamente o risco à privacidade. Se a entrada vier de um conjunto pequeno e conhecido, um invasor poderá tentar valores e comparar os hashes. Use uma referência interna protegida quando a equipe operacional precisar recuperar detalhes e limite o acesso ao sistema que contém o registro original. Nunca trate um hash simples de um endereço de e-mail como anônimo.

Mantenha os diagnósticos operacionais separados do resultado da ferramenta recebido pelo próprio agente. A equipe de suporte pode precisar de acesso protegido ao corpo de um erro upstream por um período curto. O agente não precisa disso. Essa separação também oferece uma política mais limpa de exclusão e retenção, pois os registros brutos não se acumulam em todos os diários.

O Sallyport projeta sessões de agentes e chamadas individuais a partir de um log de auditoria criptografado, encadeado por hashes e sem permissão de escrita; seu comando sp audit verify pode verificar a cadeia offline sem uma chave do cofre. A verificação de integridade responde se um evento registrado foi alterado. O esquema do evento ainda determina se esse registro contém dados demais do cliente desde o início.

Teste o limite com compartilhamento excessivo intencional

Uma revisão de privacidade que testa apenas chamadas válidas e bem-sucedidas não detecta o comportamento que causa a maior parte das exposições acidentais. Teste o que acontece quando um agente envia um objeto completo, quando um serviço upstream retorna um campo inesperado e quando ocorre uma exceção no meio da solicitação.

Use um fixture com valores sensíveis falsos e reconhecíveis e depois verifique se eles não atravessam o limite do agente. O fixture deve incluir campos aninhados e texto livre, pois exemplos planos dão uma aprovação fácil ao código de remoção.

{
  "case_ref": "case_Ab92Kx71LmQ4Rt8P",
  "reason_code": "duplicate_charge",
  "customer": {
    "email": "[email protected]",
    "address": "17 Example Lane",
    "payment_note": "card ending 4242"
  },
  "conversation_text": "Customer says their medical appointment depends on delivery."
}

O resultado esperado é uma falha de validação que mencione apenas a propriedade inesperada. Depois, inspecione quatro lugares: a resposta visível ao agente, os logs da aplicação, os registros de rastreamento de erros e os eventos de auditoria. As pessoas desenvolvedoras costumam validar a solicitação, mas esquecem que o middleware de exceções registrou o corpo original.

Adicione testes de contrato para a saída também. Simule uma resposta upstream que contenha um objeto completo de cliente e verifique se a ferramenta emite apenas os campos documentados. Faça isso sempre que o cliente do provedor mudar. Uma atualização do SDK pode acrescentar campos de resposta sem que ninguém altere o prompt do agente.

Por fim, execute um teste de transcrição. Dê ao agente uma tarefa normal, capture todas as entradas e resultados de ferramentas que ele recebe e procure os valores do fixture. Esse teste identifica interpolação acidental no prompt e textos de depuração que os testes de esquema podem não detectar.

A primeira ação a ser redesenhada costuma ser a ferramenta de consulta ampla. Substitua-a por uma ação que produza um efeito externo real ou retorne uma decisão delimitada. Se o novo contrato parecer restrito demais para ser conveniente, isso geralmente indica que o sistema vinha contando com o agente para transportar dados de que nunca precisou.