Ferramentas de Classe Apex

O que é uma Ferramenta de Classe Apex?

Uma ferramenta de Classe Apex é o terceiro tipo de ferramenta que você pode construir no Criador de Ferramentas da REDA AI, ao lado de SOQL Template e File Mapping. Use-a quando:

• O trabalho exige lógica condicional, várias etapas ou gravações em mais de um objeto
• Você precisa chamar um sistema externo como parte da ferramenta
• Você quer reconciliar com registros existentes, deduplicar ou aplicar regras de negócio antes de gravar
• Você está construindo uma extração orientada por arquivo em que a estrutura dos dados é rica demais para o mapeamento declarativo

A plataforma cuida do contrato com o agente: o JSON Schema, a validação de entrada, o encapsulamento de erros, a confirmação de ação, o registro de auditoria e a formatação do resultado. Sua classe Apex só precisa cuidar do trabalho em si.

A Interface do Executor

Toda ferramenta de Classe Apex implementa uma única interface global:

global interface REDAAI_Executable {
    Object execute(String toolName, Map<String, Object> input);
}

Dois parâmetros, um valor de retorno:

• toolName — o nome de desenvolvedor da Definição da ferramenta que disparou essa chamada. Use-o se uma única classe implementa várias ferramentas e precisa direcionar o comportamento conforme o chamador.
• input — os parâmetros fornecidos pelo agente, validados em relação ao JSON do seu Esquema de entrada, mais a chave _channel descrita abaixo.
• Valor de retorno — depende da categoria da ferramenta (veja Contrato de retorno abaixo).

Saber em qual canal você está sendo executado

A mesma ferramenta pode ser chamada por um agente com quem um colega conversa dentro do Salesforce, por um widget público de um site ou por um agente de API não assistido que roda de madrugada — e muitas vezes o certo é se comportar de forma diferente em cada caso. Por isso a REDA AI acrescenta um conjunto de chaves fornecidas pela plataforma ao mapa input antes de chamar você, começando pelo canal:

global class OrderLookupTool implements REDAAI_Executable {
    global Object execute(String toolName, Map<String, Object> input) {
        String channel = (String) input.get('_channel');   // 'Internal' | 'External_Widget' | 'Community' | 'API'

        if (REDAAIConstants.CHANNEL_EXTERNAL_WIDGET.equals(channel)) {
            return summaryForPublicVisitor(input);
        }
        return fullInternalDetail(input);
    }
}

O valor é Internal, External_Widget, Community ou API — os mesmos valores usados pelo campo Canal, então compare com as constantes REDAAIConstants.CHANNEL_* em vez de digitar o literal. Ele é definido pela plataforma — não pelo agente. Se o modelo tentar fornecer _channel por conta própria, a REDA AI o sobrescreve; e quando o canal realmente não pode ser resolvido, a chave é removida por completo em vez de ficar com um valor inventado pelo modelo. Assim, um _channel presente é sempre confiável, e a ausência dele significa “desconhecido”, nunca “Internal”.

Mais duas chaves chegam da mesma forma, com a mesma garantia de sobrescrita e remoção — a plataforma sempre as fornece, e qualquer valor que o modelo tente definir é descartado:

Ambas são removidas em vez de ficarem desatualizadas quando não há conversa ou agente em escopo — então, assim como com _channel, um valor presente é confiável e a ausência significa “desconhecido”.

As ferramentas existentes não precisam de nenhuma mudança. Uma ferramenta que nunca lê _channel simplesmente ignora uma entrada a mais no mapa e se comporta exatamente como antes.

Campos da Definição da Ferramenta

Construindo a Classe Apex

Um executor mínimo no estilo Action que cria um único registro:

global with sharing class MyToolExecutor implements redaai.REDAAI_Executable {
    global Object execute(String toolName, Map<String, Object> input) {
        try {
            String name = (String) input.get('account_name');
            Account a = new Account(Name = name);
            insert as user a;

            return new Map<String, Object>{
                'success' => true,
                'message' => 'Account created.',
                'recordId' => a.Id
            };
        } catch (Exception e) {
            return new Map<String, Object>{
                'success' => false,
                'message' => e.getMessage()
            };
        }
    }
}

Alguns pontos a observar:

• A classe é global. Public não serve — a plataforma instancia a classe por meio da interface global para que consumidores de pacotes gerenciados possam registrar implementações a partir de seus próprios namespaces.
• A classe declara with sharing. A plataforma não aplica o sharing por você; o executor é responsável pela postura de acesso a dados que deseja adotar.
• A cláusula insert as user executa o DML em modo de usuário, de forma que a segurança em nível de campo seja aplicada. Esse é o padrão recomendado, a menos que você tenha um motivo específico para elevar o acesso.
• Os erros são capturados e retornados como uma resposta estruturada. Exceções não tratadas ainda são capturadas no registro de incidentes, mas uma resposta limpa dá ao agente algo útil para dizer de volta ao usuário.

Contrato de Retorno

A estrutura de retorno depende da Categoria da ferramenta:

Ferramentas Apex Orientadas por Arquivo

Definir Processamento de Arquivos como true muda o que o agente passa para você. Em vez de parâmetros de forma livre, a plataforma primeiro pede ao modelo que extraia dados estruturados do arquivo enviado usando o esquema que você definiu, e então entrega esses dados extraídos ao seu executor como o Map de input.

É isso que torna as ferramentas de Classe Apex o padrão certo para trabalho com arquivos não tabulares — PDFs, imagens, documentos mistos — onde o modelo plano de coluna-para-campo do File Mapping não é suficiente.

Projetando o esquema de entrada para extração

O esquema de entrada descreve a estrutura extraída, não o arquivo bruto. Para um documento com várias linhas, o agente pode produzir algo como:

{
  "rows": [
    { "external_id": "INV-1001", "amount": 250.00, "due_date": "2026-05-01" },
    { "external_id": "INV-1002", "amount": 980.50, "due_date": "2026-05-15" }
  ]
}

Seu executor então itera esse array rows, busca registros correspondentes, aplica as regras de negócio necessárias e grava de volta no Salesforce.

Quando você constrói a ferramenta no Criador de Ferramentas com Processamento de Arquivos ativado, o Gerador de IA pode produzir uma amostra da estrutura de dados extraída a partir de um arquivo representativo que você enviar. Use-a como o contrato contra o qual você escreve seu Apex.

Nomenclatura, Empacotamento e Resolução

• Visibilidade da classe — a classe e seu método execute devem ambos ser declarados como global (não public).
• Implementação — deve implementar redaai.REDAAI_Executable.
• Tamanho do nome da classe — até 255 caracteres no campo Classe Executora.
• Uma classe, várias ferramentas — um único executor pode dar suporte a várias Definições de Ferramenta e alternar o comportamento conforme toolName.

Segurança e Governança

• Você é responsável pela postura de segurança. A plataforma não aplica FLS nem sharing dentro da sua classe. Use os padrões with sharing e USER_MODE / as user, a menos que tenha um motivo explícito para elevar o acesso.
• Reconhecimento de segurança ao salvar. Na primeira vez que você salvar uma ferramenta personalizada (Apex, SOQL Template ou File Mapping) no Criador de Ferramentas, você aceita um termo de responsabilidade compartilhada confirmando que é responsável pela sua segurança, permissões (CRUD/FLS), delimitação de dados, validação de entrada e conformidade legal — porque a REDA AI pode invocá-la de forma autônoma, inclusive nos canais Comunidade e Externo, sem uma etapa de confirmação humana. Sua aceitação (nome + carimbo de data/hora) é registrada na ferramenta e complementa o Contrato de Prestação de Serviços (MSA) da REDA AI. Ferramentas nativas (ISV) são isentas; você aceita uma vez por ferramenta e isso é preservado entre edições.
• A entrada é validada. A plataforma valida o input em relação ao seu esquema antes de invocar sua classe — você pode confiar nos nomes e tipos de campo que declarou, mas sempre faça o cast dos valores de forma defensiva.
• A confirmação de ação ainda se aplica. Definir a Categoria como Action significa que o agente mostra um cartão de confirmação antes de chamar sua classe, a menos que o agente esteja configurado para execução automática.
• Erros vão para incidentes. Exceções não tratadas são capturadas como registros de incidente da REDA AI com o contexto da conversa, o nome da ferramenta e o stack. Retornar uma resposta de erro limpa é mais amigável; o registro de incidentes é a rede de segurança.
• Execução síncrona. As ferramentas de Classe Apex rodam de forma inline como parte do turno do agente. Trabalhos de longa duração devem ser enfileirados pelo seu executor (Queueable, Schedulable, batch) e a resposta imediata deve informar ao usuário que o trabalho foi iniciado.

Quando Recorrer a uma Ferramenta Apex

Boas Práticas

Torne a descrição implacavelmente precisa. A decisão do agente de chamar sua ferramenta depende quase inteiramente da descrição da ferramenta. Explicite o que a ferramenta faz, o que ela não faz, e quaisquer pré-condições.

Mantenha os esquemas enxutos. Use required, enum, maxLength e tipos explícitos. Quanto mais enxuto o esquema, menos surpresas chegam ao seu Apex.

Sempre retorne uma mensagem útil. Mesmo em caso de falha, retorne success: false e uma message legível por humanos. O agente lê a mensagem de volta para o usuário; erros opacos levam a conversas confusas.

Mantenha-se síncrono, ou enfileire e reporte. Não bloqueie o turno do agente com um callout lento. Ou conclua rapidamente, ou enfileire o trabalho assíncrono e retorne uma resposta informando ao usuário que está em andamento.

Teste com o painel de pré-visualização do Criador de Ferramentas. O painel de impacto ao vivo mostra o esquema de entrada, o cartão de ação e o contrato de runtime que o agente verá — identifique incompatibilidades ali antes da primeira conversa real.

Perguntas frequentes

Próximos Passos

Leia Ferramentas de Template SOQL para o padrão mais leve quando tudo que você precisa é uma consulta parametrizada, ou Processamento de Documentos para o panorama mais amplo de como os arquivos fluem pela REDA AI.