Relacionamentos Polimórficos
Task.WhoId, Task.WhatId, Event.WhoId e Event.WhatId. A REDA AI trata esses casos com segurança no contexto de registro e expõe uma única configuração de agente que controla o quão estrito o runtime é quando algo não pode ser resolvido.
Por Que Isso Importa
A maioria dos campos de busca aponta para um único objeto — Account.OwnerId sempre aponta para um Usuário. Mas o Salesforce inclui vários campos de busca polimórficos cujo destino depende da linha:
| Campo | Possíveis destinos |
|---|---|
Task.WhoId |
Contact, Lead |
Task.WhatId |
Account, Oportunidade, Caso, Campanha, Contract e vários outros |
Event.WhoId |
Contact, Lead |
Event.WhatId |
Account, Oportunidade, Caso e outros objetos relacionados |
FeedItem.ParentId |
Qualquer objeto habilitado para feed |
Também podem ser definidos campos polimórficos personalizados na sua organização. A restrição é a mesma onde quer que apareçam: o SOQL não consegue percorrer cegamente um Name de relacionamento nesses campos, porque a plataforma não sabe de antemão o Name de qual objeto deve ler.
Como a REDA AI as Trata
Quando a plataforma constrói o contexto de registro para um agente, ela carrega os Nomes de API de Campo configurados mais — se a opção Incluir Nomes Relacionados estiver ativada — um Relationship.Name automático para cada busca. A expansão automática de Name é controlada por uma única regra:
A plataforma expande automaticamente o Relationship.Name somente para buscas cujo destino é um único objeto. Buscas polimórficas (com vários destinos) são ignoradas silenciosamente — o Id da busca é incluído, mas o Name não.
Essa é uma proteção deliberada. Sem ela, uma consulta que inclui WhoId.Name geraria erro nas linhas em que o WhoId aponta para um Lead em vez de um Contact (ou vice-versa), porque o SOQL é construído uma única vez para todo o lote.
O que o agente vê
- Para buscas não polimórficas — o agente vê tanto o Id quanto o Name (por exemplo, OwnerId: 005…, Owner Name: Jane Smith).
- Para buscas polimórficas — o agente vê o Id, mas não o Name. Se o agente precisar do Name, ele pode consultá-lo sob demanda usando uma ferramenta integrada como
get_record.
Para modelos de domínio construídos em torno de Tasks ou Events, isso significa que o agente recebe o registro de atividade de forma limpa, mas precisa dar um passo extra para identificar o Contact, Lead ou registro relacionado pelo nome. Esse passo custa uma chamada de ferramenta, mas mantém o runtime previsível.
Modo Estrito vs. Degradado
Além da proteção para campos polimórficos, a plataforma expõe uma configuração no nível do agente que controla o quão estrita é a construção do contexto de registro quando campos individuais não podem ser carregados:
| Configuração | Onde | Padrão |
|---|---|---|
| Permitir contexto de registro degradado | No registro de Definição de Agente | Desativado (estrito) |
Modo estrito (padrão)
Com a configuração desativada, a plataforma exige que todo campo de contexto configurado possa ser carregado. Se um campo configurado tiver sido excluído, renomeado ou bloqueado pela segurança em nível de campo (FLS) para o usuário em execução, a plataforma cancela a execução do agente com um erro. Esse é o padrão mais seguro para agentes internos que precisam de contexto consistente para tomar decisões — a conversa falha rapidamente em vez de gerar respostas a partir de um quadro parcial.
A configuração tem um segundo gatilho, mais comum: nenhuma configuração existir. Se um agente aponta para um objeto que não tem nenhum registro de Context Field ativo, o modo estrito não degrada nada — ele interrompe a execução com:
“No active Context Field configuration found for <Objeto>. Configure a
REDAAI_Context_Field__c record or enable Allow Degraded Record Context on the agent.”
Essa é a causa habitual de um agente novo falhar em um objeto que ninguém configurou ainda e, como o modo
estrito é o padrão, isso acontece já de saída. Com a configuração ativada, a REDA AI recorre a uma lista
de campos embutida — StageName, Status, Type,
Priority, Subject, CloseDate, Amount,
Phone, Email, Industry, OwnerId,
CreatedDate — limitada a 10 campos, mantendo agentes antigos funcionando. Ele recebe
apenas os campos dessa lista que o objeto realmente tiver, e é por isso que uma configuração de verdade
continua sendo a resposta certa.
Modo degradado
Com a configuração ativada, a plataforma registra um incidente de aviso e prossegue com os campos que conseguiu carregar. O agente continua em execução com contexto degradado. Essa é a escolha certa para agentes voltados ao cliente ou orientados por API, nos quais um contexto parcial é aceitável e alguns campos são intencionalmente ocultados de determinados perfis de usuário.
Dois limites sempre se aplicam, mesmo no modo degradado:
- O registro em si precisa ser legível. Se o usuário em execução não tiver nenhum acesso de leitura ao registro, a execução é cancelada.
- O objeto precisa estar acessível. A negação de CRUD no nível do objeto não é algo que a plataforma consiga contornar de forma degradada.
Como Escolher a Configuração
| Use estrito (desativado) quando… | Use degradado (ativado) quando… |
|---|---|
| O agente toma decisões relevantes e precisa ver o contexto completo. | Alguns usuários têm restrições de FLS que o agente deve contornar de forma flexível. |
| Você quer que as falhas sejam evidentes e imediatas durante os testes. | O agente é executado em canais voltados ao cliente ou de API, onde uma falha suave é preferível a um erro grave. |
| Os campos configurados são estáveis e você controla o schema. | O mesmo agente é executado em vários perfis de usuário com padrões de acesso diferentes. |
A configuração pode ser alternada a qualquer momento na Definição de Agente; o efeito é imediato na próxima conversa.
Campos Polimórficos Personalizados
Se a sua organização define buscas polimórficas personalizadas (vários destinos de Reference To em um campo personalizado), a mesma regra do destino único se aplica — a expansão automática de Name é ignorada nesses campos. Trate-os como os campos polimórficos padrão:
- Inclua o Id da busca na lista de campos quando o agente precisar saber qual registro está sendo referenciado
- Não espere que um Relationship.Name venha automaticamente
- Se o agente precisar regularmente do Name relacionado, forneça a ele uma ferramenta que resolva o Id em um Name sob demanda
Configurando Agentes Centrados em Atividades
Agentes que trabalham principalmente com Tasks ou Events ainda podem usar esses registros como contexto — a limitação polimórfica afeta apenas a expansão automática de Name de WhoId e WhatId, não o restante do registro. Alguns padrões funcionam bem:
Inclua o tipo junto com o Id. Quando o campo WhoId estiver no contexto, inclua também Who.Type se disponível — o agente pode então decidir se consulta o objeto correspondente para obter um nome.
Restrinja a um único destino quando possível. Se o agente só se importa com Tasks relacionadas a Contact, filtre na origem (por exemplo, via campos de contexto no objeto pai em vez da Task).
Use uma ferramenta de Apex específica para a resolução. Uma ferramenta de Classe Apex que recebe um Id polimórfico e retorna o Name mais o tipo é uma forma limpa de dar ao agente resolução sob demanda sem sobrecarregar o contexto de registro.
Boas Práticas
Não lute contra a proteção. A regra do destino único existe para evitar erros intermitentes em tempo de execução. Tentar forçar a expansão de Name em campos polimórficos adicionando-os manualmente à lista de campos não muda o comportamento — a plataforma continua limitando a expansão.
Use o modo estrito por padrão. A maioria dos agentes é mais fácil de depurar quando falha de forma evidente diante de campos ausentes. Mude para o modo degradado de forma deliberada, para os canais e perfis de usuário em que você entende por que os campos podem estar ausentes.
Use o Depurador de Conversas para inspecionar. O Depurador mostra o contexto exato que o agente recebeu. Se o agente disser que não sabe para quem é uma Task, verifique primeiro o Depurador — o Id provavelmente está lá, mas o Name está ausente intencionalmente.
Inclua informações explícitas de tipo quando disponíveis. Who.Type e What.Type informam ao agente a qual objeto o Id polimórfico se refere sem uma consulta extra. Isso costuma ser suficiente para o agente decidir o próximo passo.
Perguntas frequentes
Não com segurança. A plataforma pula a expansão automática de Name em buscas polimórficas justamente porque o SOQL não consegue resolver genericamente um Name em vários objetos de destino. Se o agente precisar do Name, ele deve chamar uma ferramenta para resolvê-lo sob demanda.
Sim, quando são relevantes para o propósito do agente. A recomendação inclui o Id da busca, mas não altera o comportamento de expansão em tempo de execução — a expansão automática de Name continua sujeita à regra do destino único.
No modo estrito, a execução é cancelada com um erro. No modo degradado, a plataforma registra um aviso, descarta o campo inacessível do contexto e continua. A transcrição da conversa mostra o que o agente realmente viu.
Ela também cobre campos que foram excluídos ou renomeados desde que o registro de Campo de Contexto foi configurado. O tratamento de campos polimórficos é uma proteção separada que se aplica em ambos os modos — a configuração não a altera.
Sim — este é o padrão recomendado. A ferramenta integrada get_record pode resolver um Id conhecido para o registro completo, incluindo o Name. Ou você pode disponibilizar uma ferramenta de Classe Apex específica que recebe um Id polimórfico e um tipo de destino e retorna o Name.
Sim. No modo estrito, o cancelamento gera uma entrada no Registro de Incidentes. No modo degradado, cada evento de campo ausente gera um incidente de aviso. O registro da conversa sempre reflete o contexto que o agente realmente recebeu.
Próximos passos
Leia Adicionando Campos de Contexto para conhecer o ciclo de vida completo do registro de Campo de Contexto, ou revisite Otimizador de Campos de Contexto para recomendações assistidas por IA.