Padrões de Agentes
A capacidade de um agente é decidida inteiramente pelas permissões da credencial que ele carrega. Projetar um agente é, portanto, quase sempre decidir o que conceder — e isso é mais fácil a partir de formas conhecidas do que de uma folha em branco.
Conceda as permissões de um padrão e o agente faz aquele trabalho e nada além.
Um agente "somente leitura" provisionado apenas com entity.read não consegue
contar registros nem detectar duplicatas, porque nenhuma das duas operações lê
uma entidade:
- Contar é uma operação de estatísticas e exige
statistics.read. - Detectar duplicatas roda o motor de comparação e exige
entity.match.
As duas falham fechado, então o sintoma é uma recusa, não uma resposta errada — mas é uma recusa confusa se você acreditava ter concedido apenas leitura.
Escolhendo um padrão
| Padrão | Responde | Altera dados |
|---|---|---|
| Analista somente leitura | "O que existe aqui, e com que qualidade?" | Não |
| Triagem de duplicatas | "Estes dois são o mesmo, e devem ser unidos?" | Sim |
| Carga em massa | "Suba este lote e me diga o que falhou." | Sim |
| Atendimento de privacidade | "Alguém exerceu um direito sobre seus dados — execute." | Sim |
Os padrões se combinam. Um agente pode ter qualquer combinação; as permissões simplesmente somam.
Analista somente leitura
Lê e relata. Não altera nada, porque nenhuma dessas permissões concede escrita.
| Operação | Responde | Permissão |
|---|---|---|
countEntities | Quantos registros de um tipo existem | statistics.read |
searchEntities | Quais registros correspondem a este texto ou atributo | search.read |
getEntity | Um registro | entity.read |
getEntity360 | Um registro com suas origens, histórico e relacionamentos | entity.read |
listRelationships | Como os registros se conectam | entity.relationship.read |
getDqScore | A pontuação de qualidade por trás de um registro | dq.score.read |
listAuditEntries | O que mudou, e quem mudou | audit.read |
O mascaramento importa mais aqui: um valor que o operador não pode ver é mascarado antes de chegar ao agente, então o agente não consegue relatá-lo nem se perguntado diretamente.
Triagem de duplicatas
Trabalha a fila de revisão manual — os pares que o motor pontuou como prováveis, mas não certos. Veja revisar correspondências potenciais para entender o que um revisor de fato decide.
| Operação | Faz | Permissão | Classe |
|---|---|---|---|
findDuplicates | Encontra prováveis duplicatas de um registro | entity.match | Leitura |
listPotentialMatches | Lê a fila de revisão | potential-match.read | Leitura |
getPotentialMatch | Lê um par e sua pontuação | potential-match.read | Leitura |
confirmMatch | Confirma um par da fila e une os registros | entity.merge + potential-match.resolve | Edição |
rejectMatch | Registra que um par não é correspondência | potential-match.resolve | Edição |
snoozeMatch | Adia um par sem decidi-lo | potential-match.resolve | Edição |
markNotAMatch | Exclui um par de pontuações futuras | entity.read + potential-match.resolve | Edição |
mergeEntities | Une registros diretamente, fora da fila | entity.merge + entity.read | Destrutiva |
unmergeEntities | Desfaz uma consolidação, restaurando o que foi absorvido | entity.unmerge + merge-history.read | Destrutiva |
Resolver um par da fila e consolidar diretamente são permissões diferentes. Um agente pode ter autorização para trabalhar a fila — onde o motor já propôs o par e uma pessoa pode auditar a decisão — sem poder unir dois registros quaisquer que ele mesmo escolheu.
Carga em massa
Sobe lotes e relata o resultado. A carga em si roda de forma assíncrona, então o agente submete e depois consulta o andamento.
| Operação | Faz | Permissão | Classe |
|---|---|---|---|
createBulkJob | Submete um lote | bulk-job.create | Destrutiva |
getBulkJob | Relata o progresso | bulk-job.read | Leitura |
getBulkJobResults | Relata o que teve sucesso e o que falhou | bulk-job.read | Leitura |
cancelBulkJob | Interrompe um trabalho em andamento | bulk-job.cancel + bulk-job.read | Edição |
Submeter conta como destrutivo porque o tamanho da mudança não é visível na chamada — uma submissão pode tocar um único registro ou um milhão.
Atendimento de privacidade
Trata solicitações do titular e consentimento. Conceda-o de forma restrita.
| Operação | Faz | Permissão | Classe |
|---|---|---|---|
listDsrs | Lê as solicitações em aberto | dsr.read | Leitura |
createDsr | Registra uma nova solicitação | dsr.create + entity.read | Edição |
updateDsrStatus | Move a solicitação entre estados | dsr.update | Edição |
fulfillDsr | Executa a solicitação, inclusive a eliminação | dsr.update | Destrutiva |
listConsentRecords | Lê a que o titular consentiu | consent-record.read | Leitura |
withdrawConsentRecord | Revoga um registro de consentimento | consent-record.update | Edição |
Uma solicitação de eliminação revoga todo registro cuja base legal é o consentimento, retendo os que se apoiam em outra base — o resultado correto, e não algo para se descobrir depois do fato.
O que todo padrão tem em comum
| Comportamento | Vale para |
|---|---|
| Duas chamadas para alterar qualquer coisa. Toda escrita é uma prévia e, em seguida, uma confirmação separada com um token de uso único. O modelo não consegue produzir esse token sozinho. | Toda operação de escrita, sempre |
| A permissão também é verificada na segunda chamada. Confirmar não contorna nada. | Toda operação de escrita |
getMe exige apenas me.read. Um agente sempre consegue relatar as próprias permissões efetivas — inclusive o que lhe falta. | Todo padrão |
| O mascaramento é aplicado antes de o agente ver o valor. Não há superfície sem máscara a que recorrer. | Todo padrão |
A coluna Classe é um sinal para o cliente. Operações de leitura não mudam nada. Edições são reversíveis. Operações destrutivas são sinalizadas para que um cliente bem-comportado pergunte a uma pessoa antes de prosseguir — mas essa pergunta é uma cortesia do cliente, e um cliente configurado de forma permissiva pode pulá-la.
Mantenha as duas coisas separadas ao avaliar risco. A pergunta pode ser desligada; o contrato de duas chamadas e a verificação de permissão são impostos pelo endpoint e não podem. Um agente configurado para aprovar tudo continua sendo um agente que só faz o que suas permissões permitem.
Provisionando um agente
| Passo | O que você faz |
|---|---|
| 1 | Escolha o padrão e leia as permissões que suas tabelas listam |
| 2 | Crie um papel com exatamente essas, e nada mais |
| 3 | Atribua-o à credencial que o agente vai carregar — uma pessoa, ou um token de sistema se o agente rodar sem supervisão |
| 4 | Pergunte ao agente o que ele pode fazer. getMe relata as permissões efetivas, então você verifica a concessão em vez de presumi-la |
O passo 4 pega as duas surpresas acima numa única chamada.
Descobrindo o conjunto completo
Estas são operações representativas, não o catálogo inteiro. O endpoint publica a própria lista de ferramentas, cada entrada nomeando o que faz e a permissão que exige. Consulte-a em vez de copiar as operações para a sua própria configuração.
A seguir
- Identidade de Agentes — se um agente toma uma identidade emprestada ou tem a sua própria
- Modelo de Segurança da IA — o que um agente não pode fazer, e por quê
- Conecte um Agente — colocando um para rodar
- Controle de Acesso — como permissões se compõem em papéis