Minimização de respostas de API para um contexto de agentes de IA mais seguro

Agentes de IA não precisam de uma cópia de cada objeto com que interagem. Eles precisam de informação suficiente para tomar a próxima decisão, executar a ação e relatar o que aconteceu. Quando uma API retorna um cadastro completo de cliente, uma fatura, um ticket, uma configuração de repositório ou um incidente para um agente que só precisa de um ID e de um status, a API já ampliou o problema de exposição de dados.

Isso é fácil de não perceber porque a solicitação pode ser somente de leitura, autenticada e enviada por TLS. Nada disso muda o que acontece depois. A resposta pode entrar em uma transcrição do agente, um registro de ferramenta, uma solicitação ao modelo, um cache local, um relatório de bug ou uma fila de revisão humana. Se o agente consegue ler algo, presuma que isso agora está no contexto dele.

A correção prática é a minimização de respostas de API: defina a menor resposta útil para cada tarefa do agente, facilite a solicitação desse formato e torne os dados amplos um caminho excepcional, sujeito à análise humana. O objetivo não é deixar o JSON mais bonito. É reduzir o número de lugares onde dados pessoais, financeiros e operacionais podem aparecer depois de uma chamada automatizada comum.

Uma leitura autenticada ainda pode revelar dados demais

O acesso de leitura limita gravações. Ele não limita cópias, resumos, citações nem o envio acidental de dados para outra ferramenta. As equipes costumam chamar um agente de «somente leitura», como se isso encerrasse o risco. Na verdade, isso resolve apenas uma classe de risco.

Considere um agente encarregado de identificar faturas vencidas e abrir uma tarefa de acompanhamento. Ele precisa do ID da fatura, do ID da conta, da data de vencimento, do valor, da moeda e do estado da cobrança. Um endpoint convencional de faturas também pode retornar endereços de cobrança e entrega, identificadores fiscais, referências do processador de pagamentos, descrições dos itens, um memorando interno de um usuário financeiro e o histórico completo de pagamentos. Cada campo extra cria outro fato que o agente pode repetir sem necessidade.

Os dados operacionais têm o mesmo problema. Uma tarefa que verifica se uma implantação terminou pode precisar do nome do serviço, do identificador da compilação, do estado e da categoria da falha. Raramente precisa de uma exportação completa do ambiente com nomes de host, endereços internos, saída de comandos, comentários de incidentes ou configurações não relacionadas.

A distinção que costuma ser confundida é importante: autorização responde se um chamador pode acessar um recurso; minimização responde quanto desse recurso o chamador recebe para este trabalho específico. Um token com permissão para ler invoice:123 pode estar corretamente autorizado e ainda assim receber uma representação insegura dessa fatura.

A RFC 9110 da IETF descreve representações como informações destinadas a refletir o estado atual ou desejado de um recurso. Ela não exige uma única representação máxima por recurso. Isso cria um espaço útil para o design. Um recurso pode ter uma representação resumida, uma operacional e uma financeira, desde que a API deixe cada contrato claro.

Não dependa de uma instrução no prompt como «ignore os dados pessoais». Prompts influenciam o comportamento; o formato da resposta controla a exposição. Se um endpoint envia um endereço residencial, o agente já o recebeu antes de decidir ignorá-lo.

Comece pelo trabalho que o agente precisa concluir

Um contrato de resposta seguro começa pela decisão que o agente precisa tomar, não por um modelo de banco de dados existente. Escreva a tarefa em uma frase e liste os fatos que mudam a ação. Todo o restante precisa justificar sua presença.

Por exemplo, um agente que tenta novamente jobs de compilação com falha pode precisar desta resposta:

{
  "job_id": "job_4821",
  "state": "failed",
  "retryable": true,
  "failure_class": "transient_dependency",
  "attempts_remaining": 1
}

Ele não precisa do log completo da compilação para decidir que a nova tentativa é permitida. Se uma pessoa precisar de diagnósticos depois, ofereça um endpoint separado, com público mais restrito e um motivo explícito para a consulta. Um endpoint de logs também deve aceitar intervalos limitados, porque logs completos contêm tokens, entradas de clientes, caminhos e trechos de configuração com mais frequência do que se admite.

Monte uma pequena matriz de tarefas antes de alterar os endpoints. Ela força conversas que, de outra forma, permanecem vagas:

Um campo só pertence à resposta se mudar o caminho que o agente seguirá, aparecer na solicitação da ação ou precisar aparecer no relatório destinado ao usuário. «Pode ser útil depois» não é uma boa justificativa. É assim que endpoints de lista chegam a ter cinquenta campos e ninguém sabe quem depende deles.

O exercício também revela campos que deveriam ser calculados, não divulgados. Um agente não precisa de um registro da folha de pagamento para saber se a aprovação de uma despesa exige um gerente. Retorne approval_required: true. Ele não precisa de todas as permissões para saber se uma implantação pode prosseguir. Retorne deployment_permitted: false e um código de motivo estável.

Isso não é segurança por obscuridade. É um contrato de API deliberado, que entrega aos chamadores o resultado necessário sem fornecer o registro subjacente.

Objetos padrão devem ser resumos, não linhas do banco

O design mais confiável fornece por padrão um resumo seguro em chamadas comuns de lista e consulta. Torne as representações detalhadas explícitas, autorizadas separadamente e pouco frequentes. Exigir que cada chamador se lembre de incluir uma opção restritiva falhará em algum momento, especialmente quando uma biblioteca adicionar um método conveniente que a omita.

Um resumo de cliente pode ter esta aparência:

{
  "id": "cus_7f31",
  "display_name": "Northwind Parts",
  "account_state": "active",
  "open_invoice_count": 2,
  "support_tier": "standard"
}

Não retorne email, phone, endereço, identificador fiscal, metadados do instrumento de pagamento nem notas em texto livre só porque uma linha de cliente contém esses dados. Alguns podem ser necessários para um aplicativo de cobrança. Eles não pertencem a um contrato de resumo usado por um agente de operações.

Há dois padrões viáveis. Um endpoint de resumo separado, como GET /customers/{id}/summary, é direto e fácil de auditar. Um parâmetro de projeção, como GET /customers/{id}?view=summary, pode funcionar quando usa um conjunto fixo e documentado de visões. Ambos são melhores que um endpoint que retorna tudo e pede a cada cliente que ignore o que não precisava.

Evite uma opção genérica expand=* ou include=all para credenciais voltadas a agentes. Ela vira o caminho de menor resistência durante a depuração e permanece em produção porque removê-la parece arriscado. Se uma representação detalhada for necessária, dê a ela o nome da tarefa: view=collections, view=deployment_status ou view=case_triage. Nomes de tarefas obrigam uma revisão de design. «Tudo» evita uma.

Uma objeção comum é que visões separadas duplicam código. Elas duplicam parte do código de mapeamento. Esse custo é pequeno diante da investigação necessária quando uma transcrição de ferramenta contém um número fiscal ou uma nota interna de incidente. A camada de mapeamento também é o lugar para documentar responsabilidades e testar a promessa de que uma visão do agente exclui colunas sensíveis.

A seleção de campos deve usar uma lista de permissões, não um truque de parser

Um parâmetro fields pode reduzir bem as respostas, mas somente quando o servidor o trata como uma lista de permissões estrita. Um parser permissivo transforma um recurso conveniente em uma interface de extração de dados.

Esta solicitação é razoável:

GET /v1/invoices?state=overdue\u0026fields=id,account_id,due_date,amount,currency,collection_state\u0026limit=25

O servidor deve retornar apenas os campos permitidos para esse endpoint e essa credencial. Se um chamador pedir billing_address ou payment_reference, rejeite a solicitação com um erro claro. Não adicione campos sensíveis silenciosamente e não aceite caminhos aninhados arbitrários, como customer.*.

Um contrato de resposta pode especificar o comportamento com precisão:

{
  "error": {
    "code": "unsupported_field",
    "message": "Field 'payment_reference' is not available in the agent invoice view",
    "allowed_fields": [
      "id",
      "account_id",
      "due_date",
      "amount",
      "currency",
      "collection_state"
    ]
  }
}

O próprio erro precisa de disciplina. Nunca inclua o valor do campo rejeitado, dados do registro próximo, um stack trace, texto bruto de consulta de outro serviço nem um erro de banco de dados. Corpos de erro costumam virar uma segunda API acidental, sobretudo quando engenheiros os tornam detalhados para acelerar um incidente.

O GraphQL merece o mesmo cuidado. As pessoas presumem que os clientes só podem solicitar o que nomeiam, o que ajuda, mas um esquema ainda pode expor campos sensíveis, relações aninhadas podem multiplicar registros e aliases podem tornar uma única consulta difícil de analisar. Defina limites de profundidade e complexidade, desative ou restrinja a introspecção quando isso for adequado ao ambiente e autorize campos, não apenas objetos de nível superior. Mais importante, crie um esquema para agentes ou consultas persistentes para as poucas tarefas aprovadas. Um esquema amplo acompanhado de uma instrução educada não é uma interface restrita.

O OWASP API Security Top 10 destaca a autorização quebrada no nível das propriedades dos objetos. A preocupação costuma ser descrita como um chamador obtendo uma propriedade que nunca deveria acessar. O uso por agentes acrescenta outro modo de falha: o chamador pode tecnicamente ter acesso, mas a tarefa não exige a propriedade e não deveria distribuí-la para o contexto do modelo. Mantenha os dois testes. Pergunte «esta credencial pode ler isso?» e depois «por que esta tarefa precisa disso agora?»

A paginação controla o volume, mas os filtros controlam a relevância

Uma resposta com dez registros não é automaticamente pequena. Se cada registro contém um objeto aninhado grande ou um campo de texto longo, a paginação apenas divide o vazamento em páginas organizadas.

Use filtros que expressem o trabalho do agente. Um agente de cobrança deve consultar faturas vencidas em um estado e intervalo de datas definidos. Não deve listar todas as faturas e decidir localmente quais importam. Um agente de implantação deve pedir um serviço e uma versão atuais, não consultar todos os ambientes e procurar o resultado depois.

A paginação por cursor também exige um formato cuidadoso. O cursor deve ser opaco e não deve conter um endereço de e-mail, nome de conta, valores de filtro sem criptografia nem uma chave interna de banco que revele a ordenação. Os clientes colocarão cursores em logs e tickets. Trate-os como dados que circulam.

Mantenha limites de página conservadores para credenciais de agentes. Um limite pequeno faz mais do que reduzir o uso de tokens. Ele cria uma pausa na qual o agente pode examinar um resumo, escolher um registro relevante e fazer uma chamada de acompanhamento direcionada. Essa sequência é mais segura que carregar todo o histórico da conta porque uma tarefa começou com as palavras «investigue este cliente».

Não confunda um endpoint de busca com permissão para retornar todos os detalhes correspondentes. A busca normalmente deve retornar um cartão de resultado: ID estável, rótulo, estado e talvez o motivo da correspondência. O chamador pode buscar uma visão detalhada permitida depois de selecionar um registro. Esse padrão de duas chamadas parece menos conveniente que um objeto de resultado enorme, mas torna a transferência de informações sensíveis visível e passível de revisão.

Texto livre e registros aninhados precisam de seu próprio limite

Campos estruturados são mais fáceis de classificar que textos escritos por pessoas. Campos de texto livre absorvem nomes, números de telefone, credenciais coladas por engano, acusações, dados de saúde, aconselhamento jurídico e opiniões internas. A description de um ticket parece inofensiva em uma revisão de esquema até que alguém leia os tickets de uma semana real.

Trate comentários, notas, descrições, anexos, logs e corpos de mensagens como sensíveis por padrão em fluxos autônomos. Quando isso bastar para escolher uma ação, retorne uma categoria, uma classificação curta gerada pelo servidor ou uma contagem. Por exemplo, um agente pode precisar de has_customer_reply: true e latest_message_at, não da própria mensagem.

Não peça ao modelo para ocultar texto arbitrário depois da recuperação. Essa abordagem é popular porque parece preservar um único endpoint amplo. Ela falha de duas formas. Primeiro, o conteúdo bruto já entrou no contexto do agente antes da ocultação. Segundo, a ocultação gerada pelo modelo é probabilística, portanto um nome parcial, número de conta ou citação pode permanecer.

Se uma tarefa realmente exigir texto, imponha limites rígidos à solicitação. Busque uma mensagem por ID, não uma conversa inteira. Peça um limite conhecido de caracteres imposto pelo servidor. Remova o conteúdo dos anexos, a menos que uma pessoa tenha aprovado essa consulta específica. Informe o que o cliente receberá quando houver truncamento, como content_truncated: true, para que o agente não invente detalhes ausentes.

Dados aninhados criam uma versão mais discreta do mesmo problema. Uma resposta que inclui customer, contacts, invoices, payments e events pode parecer um único objeto no código do aplicativo. Para fins de exposição, ela é um conjunto de bases independentes. Exija endpoints separados ou expansões explícitas e permitidas para cada relação. Depois, teste a pior consulta comum, não apenas o caminho feliz que retorna um registro esparso.

O tratamento de erros e a observabilidade podem recriar o vazamento

As equipes costumam restringir a resposta de sucesso e depois copiar a carga original para logs de depuração, atributos de rastreamento, filas de nova tentativa e relatórios de exceção. Os dados mudaram de lugar, mas a exposição não diminuiu.

Inspecione todo o caminho da chamada. No mínimo, examine o wrapper da ferramenta do agente, o modo de depuração do cliente HTTP, o gravador de solicitações, a configuração do rastreamento distribuído, o serviço de relatórios de erros, a fila de jobs, o armazenamento local de transcrições e o fluxo de suporte. Os lugares que afirmam registrar «somente metadados» merecem um teste direto, não confiança.

Execute um registro canário em um ambiente que não seja de produção. Dê a ele valores fictícios distintivos nos campos que nunca devem chegar ao contexto do agente, como CANARY_BILLING_ADDRESS_927 e CANARY_INTERNAL_NOTE_927. Execute a tarefa real do agente e procure essas strings em todos os armazenamentos autorizados de logs e rastreamentos. Repita para uma solicitação com falha, um timeout e uma resposta malformada. Testes do caminho de sucesso não encontram a maior parte da captura acidental de cargas.

Um diário de chamadas útil registra a ação sem duplicar conteúdo:

{
  "time": "2025-03-08T14:03:12Z",
  "caller": "release-agent",
  "operation": "GET /v1/jobs/{id}/retry-status",
  "resource_id": "job_4821",
  "response_view": "retry_status",
  "field_set": ["job_id", "state", "retryable", "failure_class"],
  "result_count": 1,
  "outcome": "200"
}

Registre identificadores somente quando suas próprias regras de retenção e acesso permitirem. Em sistemas de maior risco, armazene uma referência com chave ou um ID de correlação de curta duração. Um hash também pode vazar se o valor original vier de um domínio pequeno e previsível, portanto não chame o hashing de ocultação sem considerar o que um invasor consegue enumerar.

Higienize as mensagens de erro de saída no limite do servidor. Um driver de banco pode expor um trecho de SQL que falhou. Um serviço upstream pode enviar um registro inteiro dentro de um envelope de erro. Sua API deve mapear essas falhas para códigos públicos estáveis, manter diagnósticos detalhados em um armazenamento restrito e não incluir o corpo da resposta em erros direcionados a agentes por padrão.

Separe capacidade de divulgação no gateway do agente

Um gateway de ações deve manter a credencial e executar a solicitação, mas não deve tratar toda resposta disponível para essa credencial como adequada ao contexto do agente. O isolamento do segredo e a minimização da resposta resolvem partes diferentes da mesma chamada.

O Sallyport mantém segredos de API e SSH em seu cofre criptografado e retorna os resultados das ações ao agente, sem expor o próprio segredo. Isso protege a credencial, enquanto o responsável pela API ainda precisa decidir se o resultado contém um cadastro de conta desnecessário, saída de comando ou detalhe operacional.

Dê a cada tarefa do agente um modelo de solicitação com nome sempre que possível. O modelo fixa o método, o host, o formato do caminho, os campos de consulta permitidos, o limite de página e a visão de resposta aceita. Um modelo de status de versão pode permitir um único ID de serviço e retornar um objeto de status curto. Ele não deve aceitar uma URL arbitrária e uma expressão fields arbitrária só porque ambas são fáceis de encaminhar.

É aqui que a ideia de um proxy amplo causa problemas. Um encaminhador HTTP genérico pode ser útil no desenvolvimento, mas não consegue expressar a diferença entre «verificar esta implantação» e «baixar todos os logs de artefatos». Coloque a intenção na ação que pode ser chamada. Quando uma nova tarefa precisar de mais dados, exija uma alteração na API ou um novo modelo. Essa fricção existe por um motivo: alguém precisa explicar por que os dados extras devem entrar no contexto.

A aprovação humana ainda tem um papel nas exceções. Se um agente precisar do conteúdo de uma mensagem de suporte para resolver um caso, uma pessoa pode aprovar essa chamada específica depois de ver o destino e o escopo. A aprovação não deve virar o substituto normal de respostas restritas. As pessoas aprovam cartões familiares rapidamente, sobretudo durante um incidente, e aprovações recorrentes as treinam a parar de ler.

Teste a ausência de campos como parte do contrato

A maioria dos testes de API verifica se os campos esperados existem. APIs voltadas a agentes também precisam testar se os campos proibidos não existem, inclusive quando o código segue um caminho alternativo.

Mantenha um teste de lista de bloqueio junto de cada visão de resposta. Use nomes de campos realistas, incluindo relações aninhadas e texto livre. O teste deve falhar se a serialização adicionar um campo depois por meio de um padrão do ORM, de um DTO compartilhado ou de uma relação carregada antecipadamente.

forbidden = {
    "email",
    "phone",
    "billing_address",
    "tax_id",
    "payment_reference",
    "internal_note",
    "attachments",
}

body = get_invoice_agent_view("inv_1042")
assert forbidden.isdisjoint(body.keys())
assert "customer" not in body
assert "events" not in body

Esse teste simples detecta apenas campos de nível superior. Adicione testes de serialização que percorram toda a árvore JSON e teste separadamente endpoints de lista, busca, erro e exportação. O maior vazamento costuma vir de uma resposta de coleção que reutiliza um serializador completo de detalhes porque isso economizou algumas linhas de código.

Os testes de contrato também devem impor limites de tamanho da resposta. Um limite rígido em bytes não servirá para todos os objetos, mas um teto razoável alerta quando alguém adiciona um campo de texto sem limite ou uma relação. Combine-o com um fixture que contenha notas longas e muitos registros filhos, caso contrário o teste dará uma falsa sensação de segurança.

Revise as alterações fazendo três perguntas diretas: qual tarefa do agente precisa deste campo? Qual visão de resposta o inclui? Qual teste prova que ele permanece ausente em todos os outros lugares? Se o autor não puder responder, não integre o campo a um endpoint amplamente acessível.

Torne a recuperação excepcional de detalhes visível e temporária

Alguns trabalhos realmente exigem detalhes sensíveis. Análise de fraude, recuperação de conta, investigação de segurança e casos difíceis de suporte não podem funcionar inteiramente com resumos. A resposta não é fingir o contrário. É tornar essa recuperação explícita, breve e limitada ao registro exato.

Use um endpoint ou ação separado que receba um ID de registro estável e uma finalidade declarada. Retorne apenas o menor trecho necessário, como um campo de pagamento contestado ou uma mensagem selecionada de cliente. Não conceda acesso à exportação completa de uma conta porque o mesmo caso contém uma cobrança contestada.

Para recuperações de maior risco, exija que uma pessoa aprove a chamada individual e registre o chamador, a finalidade, a visão, a referência do registro e o resultado. Mantenha o registro de auditoria separado do corpo da resposta sensível. Você precisa saber que uma recuperação ocorreu sem criar outra cópia casual da informação.

Uma API madura torna o caminho seguro o mais fácil. As visões resumidas devem ter nomes claros, boa documentação e campos estáveis. Endpoints detalhados e amplos devem parecer deliberados porque carregam mais responsabilidade. Se o agente precisa repetidamente de um campo sensível, não normalize a exceção. Reavalie o design da tarefa e pergunte se uma decisão no servidor ou um valor derivado e ocultado resolveria o problema.

A primeira auditoria útil normalmente é um endpoint de lista, não o endpoint que todos já temem. Capture uma tarefa real do agente, marque cada campo usado e compare essa lista com a resposta recebida. A parte não utilizada é sua próxima alteração na API.