Como transformar telemetria de inteligência artificial em dados relacionais consultáveis, implementar guardrails orçamentários em tempo de execução e projetar arquiteturas de decisão resilientes.
À medida que as empresas aceleram a transição de protótipos experimentais para frotas de agentes autônomos em produção, a gestão operacional de IA atinge um novo patamar de complexidade. Com milhares de ações sendo disparadas diariamente pelo Agentforce no atendimento, nas vendas e nos processos de back-office, perguntas antes secundárias tornam-se críticas: quanto cada departamento está consumindo em tokens e Agentic Work Units (AWU)? Quais tópicos de agente apresentam picos anômalos de latência? Como evitar estouros orçamentários antes do fechamento da fatura?
Com a publicação oficial das Release Notes do Salesforce Winter ’27, a plataforma responde a esses desafios introduzindo o AI Usage Data Model. Trata-se de um conjunto de entidades de dados padrão que expõe métricas granulares de execução de IA diretamente no núcleo relacional do Salesforce.
Para arquitetos e desenvolvedores, essa mudança é transformadora: a telemetria de agentes deixa de ser uma caixa preta acessível apenas por dashboards estáticos e passa a ser uma camada totalmente programável via SOQL, Apex e Data Cloud. Neste artigo técnico, vamos dissecar a estrutura do AI Usage Data Model, analisar padrões de consulta e implementar um mecanismo programático de contenção orçamentária em Apex.
1. A Anatomia do AI Usage Data Model no Winter ’27
Historicamente, auditar o consumo de IA em plataformas corporativas dependia de logs externos ou relatórios consolidados com atraso de processamento. O AI Usage Data Model unifica essa camada através de objetos padronizados que registram cada interação, divididos em três dimensões fundamentais:
- Dimensão de Sessão e Conversação (
AIAgentSession): Representa a jornada completa do usuário ou processo com o agente, armazenando o objetivo inicial, canal de entrada, duração total e status de resolução. - Dimensão de Execução de Ação (
AIAgentActionExecution): Registra cada ferramenta ou método (Apex, Flow ou servidor MCP) invocado pelo agente durante o raciocínio, incluindo tempo de resposta e código de retorno. - Dimensão de Consumo de Recursos (
AIModelUsageSummary): Contabiliza o volume exato de tokens de entrada (prompt tokens), tokens de saída (completion tokens), modelo de linguagem utilizado (como Claude Opus ou Gemini Flash) e o equivalente em Agentic Work Units (AWU).
+-------------------------------------------------------------+
| AIAgentSession |
| - SessionId, Channel, Status, ResolutionScore, Duration |
+-------------------------------------------------------------+
|
+--------------+--------------+
| 1:N | 1:N
v v
+-------------------------------+ +-------------------------------+
| AIAgentActionExecution | | AIModelUsageSummary |
| - ActionName, TargetType, | | - ModelProvider, ModelName, |
| ExecutionTimeMs, Status | | PromptTokens, OutputTokens |
+-------------------------------+ +-------------------------------+
Essa estrutura relacional permite cruzar o comportamento dos agentes com qualquer objeto de negócio do CRM, como Contas, Casos ou Oportunidades.
2. Consultando Métricas de Telemetria com SOQL
Como o AI Usage Data Model é totalmente integrado ao banco de dados relacional da plataforma, podemos executar consultas analíticas utilizando SOQL padrão. Isso viabiliza a criação de relatórios em tempo real e rotinas automatizadas de inspeção.
Identificando as 5 Ações Mais Lentas do Agentforce nas Últimas 24 Horas
Uma das principais causas de degradação da experiência do usuário em agentes autônomos são chamadas a APIs ou métodos Apex com alta latência. A consulta abaixo identifica os gargalos de desempenho:
SQL
SELECT
ActionName,
TargetType,
AVG(ExecutionTimeMs) AverageLatency,
COUNT(Id) TotalInvocations
FROM AIAgentActionExecution
WHERE CreatedDate = LAST_N_DAYS:1
GROUP BY ActionName, TargetType
ORDER BY AVG(ExecutionTimeMs) DESC
LIMIT 5
Calculando o Consumo de Tokens Agrupado por Modelo e Departamento
Para equipes de FinOps e governança de TI, saber exatamente qual modelo está gerando maior volume de tokens por centro de custo é indispensável:
SQL
SELECT
ModelName,
Session.Department__c,
SUM(PromptTokens) TotalInputTokens,
SUM(OutputTokens) TotalOutputTokens,
COUNT(Id) TotalTransactions
FROM AIModelUsageSummary
WHERE CreatedDate = THIS_MONTH
GROUP BY ModelName, Session.Department__c
ORDER BY SUM(PromptTokens) DESC
3. Implementando Guardrails Orçamentários com Apex e Triggers
A grande vantagem de dispor desses dados dentro da plataforma é a capacidade de agir proativamente. Se uma sessão de agente entrar em loop infinito de raciocínio ou uma integração com servidor MCP gerar consumo excessivo de tokens, um trigger em Apex pode interceptar o evento e suspender a execução antes que os limites financeiros da organização sejam rompidos.
Abaixo temos uma classe de serviço e um trigger em Apex projetados para monitorar e conter o consumo por conta empresarial em tempo de execução:
Classe de Governança: AIAgentBudgetGovernorService.cls
Apex
/**
* @description Serviço de governança para monitoramento de custos e limites de IA.
* Avalia o consumo registrado no AI Usage Data Model e aplica travas orçamentárias.
*/
public with sharing class AIAgentBudgetGovernorService {
// Limite diário padrão de tokens por sessão corporativa (Hard Limit de Segurança)
private static final Integer MAX_DAILY_TOKENS_PER_ACCOUNT = 250000;
/**
* @description Avalia novos registros de consumo e dispara alertas ou bloqueios.
* @param usageRecords Lista de registros recém-inseridos em AIModelUsageSummary.
*/
public static void evaluateUsageThresholds(List<AIModelUsageSummary> usageRecords) {
Set<Id> sessionIds = new Set<Id>();
for (AIModelUsageSummary usage : usageRecords) {
if (usage.SessionId != null) {
sessionIds.add(usage.SessionId);
}
}
if (sessionIds.isEmpty()) {
return;
}
// Mapeia as sessões e as contas corporativas associadas
Map<Id, AIAgentSession> sessionsMap = new Map<Id, AIAgentSession>([
SELECT Id, AccountId__c, AccountId__r.Name, AccountId__r.AI_Budget_Status__c
FROM AIAgentSession
WHERE Id IN :sessionIds
WITH USER_MODE
]);
Set<Id> accountIdsToCheck = new Set<Id>();
for (AIAgentSession session : sessionsMap.values()) {
if (session.AccountId__c != null) {
accountIdsToCheck.add(session.AccountId__c);
}
}
if (accountIdsToCheck.isEmpty()) {
return;
}
// Agrega o consumo total do dia por conta
List<AggregateResult> dailyUsage = [
SELECT Session.AccountId__c accId, SUM(PromptTokens) totalIn, SUM(OutputTokens) totalOut
FROM AIModelUsageSummary
WHERE Session.AccountId__c IN :accountIdsToCheck
AND CreatedDate = TODAY
WITH USER_MODE
GROUP BY Session.AccountId__c
];
List<Account> accountsToLock = new List<Account>();
for (AggregateResult ar : dailyUsage) {
Id accId = (Id) ar.get('accId');
Decimal totalTokens = ((Decimal) ar.get('totalIn')) + ((Decimal) ar.get('totalOut'));
if (totalTokens > MAX_DAILY_TOKENS_PER_ACCOUNT) {
Account acc = new Account(
Id = accId,
AI_Budget_Status__c = 'Throttled',
AI_Budget_Alert_Notes__c = 'Limite diário de tokens excedido (' + totalTokens + ' tokens em ' + Date.today().format() + '). Ações de alto custo temporariamente suspensas pelo Governor.'
);
accountsToLock.add(acc);
}
}
if (!accountsToLock.isEmpty()) {
update as user accountsToLock;
System.debug(LoggingLevel.WARN, 'AIAgentBudgetGovernor: ' + accountsToLock.size() + ' contas tiveram o acesso ao Agentforce limitado preventivamente.');
}
}
}
Trigger de Governança: AIModelUsageSummaryTrigger.trigger
Apex
/**
* @description Trigger disparado após a gravação de telemetria no AI Usage Data Model.
*/
trigger AIModelUsageSummaryTrigger on AIModelUsageSummary (after insert) {
if (Trigger.isAfter && Trigger.isInsert) {
AIAgentBudgetGovernorService.evaluateUsageThresholds(Trigger.new);
}
}
4. A Transição para a ‘Decision Architecture’ no Salesforce
A chegada do AI Usage Data Model no Winter ’27 coincide com uma evolução metodológica mais ampla no desenvolvimento corporativo: a transição de simples sistemas de registro (Systems of Record) para Sistemas de Decisão e Ação (Decision Architecture).
Nesse novo modelo, as aplicações corporativas deixam de ser ilhas isoladas de formulários e telas. A arquitetura de software é decomposta em quatro camadas coordenadas:
- Contexto (Data Cloud & SOQL): Unifica os dados cadastrais, telemetria em tempo real e histórico de interações.
- Lógica de Decisão (Atlas Reasoning Engine & Model Selection): Avalia os fatos, determina a próxima melhor ação e seleciona o modelo de linguagem adequado (balanceando custo e precisão).
- Autoridade (Enterprise Harness & Guardrails): Define explicitamente o que o agente pode ou não fazer, avaliando permissões, travas de orçamento e pontuações de risco de segurança.
- Execução e Orquestração (Apex, Flow e Headless 360): Dispara a transação nos sistemas de destino (CRM, ERP ou aplicativos móveis de campo), registrando a telemetria no AI Usage Data Model para fechamento do ciclo.
+-------------------------------------------------------------------+
| CONTEXT LAYER |
| (Salesforce Data Cloud + AI Usage Data Model) |
+-------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------+
| DECISION LAYER |
| (Atlas Engine + Subagent LLM Selection Optimizer) |
+-------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------+
| AUTHORITY LAYER |
| (Enterprise Harness + Security Risk Scoring + Apex Traps) |
+-------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------+
| EXECUTION LAYER |
| (Apex Invocables, Headless 360, Flow, MCP External Tools) |
+-------------------------------------------------------------------+
5. Recomendações Práticas para Arquitetos no Winter ’27
Para preparar sua organização e seus projetos para essa nova fase de maturidade, adote as seguintes práticas de engenharia:
- Configure o Rastreamento de Centros de Custo: Utilize campos customizados no objeto de sessão (
AIAgentSession) para associar cada interação ao centro de custo ou unidade de negócio responsável. - Estabeleça Alertas Baseados em Percentis: Em vez de monitorar apenas a média de tempo de resposta, crie relatórios para o percentil p95 e p99 das ações em
AIAgentActionExecution, identificando instabilidades esporádicas de rede ou servidor. - Combine Subagentes Especializados com Modelos Menores: Aproveite a flexibilidade do Agentforce Builder para delegar tarefas de extração simples a modelos ultra-rápidos (como Gemini Flash), reservando modelos de raciocínio profundo (como Claude Opus) apenas para exceções que justifiquem o custo por token.
- Valide a Cobertura em Sandboxes de Preview: Ative o AI Usage Data Model na sua scratch org ou sandbox do Winter ’27 e valide o impacto dos seus triggers de governança antes da virada definitiva para produção.
Conclusão
O lançamento do AI Usage Data Model no Winter ’27 marca a consolidação da maturidade da engenharia de IA na Salesforce. Ao transformar o consumo de agentes, a latência de ferramentas e o uso de tokens em dados relacionais de primeira classe, a plataforma entrega aos arquitetos o controle necessário para escalar a inteligência autônoma com total previsibilidade orçamentária e conformidade técnica.
Como a sua equipe está monitorando o consumo de tokens e a performance dos seus agentes em produção? Deixe suas impressões nos comentários e participe da discussão técnica sobre a evolução do ecossistema Salesforce no LinkedIn.