Processamento de Documentos
Financiamento e uso de IA
IA incluída usa créditos REDA. Traga sua própria IA usa a conta de provedor da sua organização, cobrada diretamente pelo provedor. A licença define um modelo para toda a organização. Nos dois, o REDA AI governa ferramentas e ações configuradas no Salesforce. Configure a licença e as contas de IA.
Com conta própria, o modelo escolhido define os níveis de raciocínio profundo e recursos disponíveis. Confira os níveis e avisos no seletor AI Account; não presuma que todos os provedores aceitam a mesma combinação. Ferramentas administrativas e processamento de documentos usam a conexão padrão da organização. Configure o padrão e teste o fluxo.
O que é o Processamento de Documentos?
O Processamento de Documentos é a capacidade da plataforma que permite que um agente da REDA AI trate um arquivo como uma entrada de primeira classe. O agente pode ler o documento, raciocinar sobre seu conteúdo e usar os resultados para consultar ou atualizar registros do Salesforce — tudo em um único turno de conversa ou job assíncrono.
Diferente de um pipeline tradicional de “enviar e depois analisar”, a REDA AI envia o documento bruto diretamente ao modelo como conteúdo multimodal. Não há etapa separada de OCR, nenhum modelo de esquema fixo, e nenhum salto por armazenamento externo. O mesmo processador lida com documentos que chegam por qualquer canal:
- Arquivos anexados por um usuário dentro de uma conversa de chat
- Anexos de e-mail recebidos por um endereço de Email Service de entrada
- Arquivos passados por um Fluxo do Salesforce como parte de uma ação declarativa do agente
- Arquivos enviados pela API REST por um sistema externo
Formatos suportados
| Formato | Extensões | Como o agente o lê |
|---|---|---|
.pdf |
Enviado como um bloco de documento multimodal — texto, layout e imagens incorporadas são lidos juntos. | |
| Imagem | .png, .jpg, .jpeg |
Enviado como uma entrada visual — o agente lê o texto visível e descreve o conteúdo visual. |
| CSV | .csv |
Interpretado como dados tabulares; as linhas podem ser mapeadas para registros do Salesforce por meio de uma ferramenta de Mapeamento de Arquivo. |
| Texto | .txt |
Incorporado como conteúdo de texto simples para o agente resumir ou extrair informações. |
| JSON | .json |
Incorporado como dados estruturados para o agente consultar ou transformar. |
A lista de permissões ativa é controlada pela configuração de plataforma Allowed File Extensions e pode ser restringida por agente no registro de Definição de Agente.
Como o processador funciona
-
O arquivo chega
Seja qual for a forma como o arquivo entra na organização — envio no chat, anexo de e-mail, entrada de Fluxo, ou chamada de API —, ele é armazenado como um registro
ContentVersion, de modo que as regras padrão de compartilhamento e auditoria se aplicam. -
Validação
A extensão do arquivo é verificada contra a lista de permissões, o tamanho é verificado contra o Max File Size (MB), e a contagem de caracteres do CSV é verificada contra o Max CSV Characters. Arquivos que falham na validação são rejeitados com um erro claro e nunca são enviados ao modelo.
-
Montagem do bloco
O processador converte o arquivo no bloco multimodal correto para o modelo: um bloco de documento para PDFs, um bloco de imagem para entradas visuais, ou um bloco de texto incorporado para formatos de texto simples.
-
Arquivos grandes
Arquivos pequenos são incorporados diretamente. Arquivos acima do File Distribution Threshold são expostos por meio de uma URL
ContentDistributionde curta duração, para que o modelo possa buscá-los sem que o arquivo seja carregado na memória. O link de distribuição expira automaticamente e é removido por um job agendado. -
Raciocínio
O agente lê o documento dentro do turno atual e, em seguida, chama as ferramentas que tiver disponíveis — consultando registros, criando registros, ou acionando uma ferramenta Apex personalizada que recebe os dados extraídos como um JSON estruturado.
-
Resultado
O agente relata o que foi encontrado, solicita confirmação antes de qualquer ação de gravação (a menos que a execução automática esteja ativada para esse agente), e todos os registros novos ou atualizados ficam sujeitos à segurança em nível de campo e ao compartilhamento do usuário em execução.
Três formas de conectar documentos a registros
Ler um documento é só metade do trabalho. A outra metade é decidir o que o agente deve fazer com o que leu. A REDA AI oferece três padrões, todos construídos sobre o mesmo processador.
| Padrão | Ideal para | Esforço de configuração |
|---|---|---|
| Extração conversacional (apenas ferramentas integradas) |
Perguntas pontuais sobre um arquivo, resumos, copiar e colar alguns valores em um registro existente. Funciona com as ferramentas padrão get_record, create_record, update_record. |
Nenhum — funciona pronto para uso em qualquer agente com Allow File Upload ativado. |
| Ferramenta de Mapeamento de Arquivo (tipo de ferramenta File_Mapping) |
Importações em massa previsíveis — normalmente CSV. Você declara quais colunas mapeiam para quais campos em qual objeto; o agente preenche os valores a partir do arquivo. | Baixo — configuração declarativa no Tool Builder. Não requer Apex. |
| Ferramenta Apex com processamento de arquivo (tipo de ferramenta Apex_Class com Is File Processing ativado) |
Extração específica de domínio onde você quer controle total — gravações em múltiplos objetos, lógica condicional, chamadas a sistemas externos, reconciliação com registros existentes. | Maior — requer uma classe Apex que implemente a interface do executor. A classe recebe os dados extraídos como uma entrada Map<String, Object>. |
Tanto o tipo de ferramenta de Mapeamento de Arquivo quanto o tipo Apex são criados no Tool Builder. Veja Configurando ferramentas para a interface de construção por cartão de tipo, o painel de impacto em tempo real e a orientação por tipo que o AI Generator fornece enquanto você constrói.
Canais que acionam o Processamento de Documentos
Em uma conversa de chat
Em qualquer agente com Allow File Upload ativado, os usuários anexam um arquivo da mesma forma que digitariam uma mensagem. O agente lê o arquivo como parte do próximo turno. Veja Envio de arquivo para a experiência do usuário, os canais suportados e as configurações por agente.
A partir de um e-mail de entrada
A REDA AI vem com um handler de Email Service que aceita e-mails de entrada em um endereço gerenciado pelo Salesforce. Anexos acima de um tamanho mínimo pequeno são filtrados pela mesma lista de permissões, armazenados como ContentVersion, e enfileirados para processamento assíncrono pelo agente roteado. Anexos minúsculos, como logotipos e assinaturas de e-mail, são ignorados automaticamente.
O mapeamento do endereço de entrada para o agente fica nos metadados customizados de Email Routing. Veja Canal de e-mail — Entrada para a configuração completa.
A partir de um Fluxo do Salesforce
Um Fluxo disparado por registro pode passar um ContentDocumentId (ou o ContentVersion relacionado) para a ação invocável da REDA AI, junto com um agente de destino e uma instrução. O agente processa o arquivo em segundo plano e grava seus resultados de volta no Salesforce. Veja Invocando a REDA AI a partir de Fluxos.
A partir de um sistema externo
Tanto o External Widget quanto as APIs de Community aceitam entradas de arquivo junto com uma mensagem de chat, de modo que um aplicativo de terceiros pode enviar um documento para uma conversa da REDA AI de forma programática.
Confirmação de ação
O Processamento de Documentos segue o mesmo modelo de segurança do resto da plataforma. Quando o agente decide gravar no Salesforce com base no que leu, ele apresenta um cartão de ação e aguarda a confirmação do usuário — a menos que o agente esteja configurado com Auto Execute File Actions, caso em que as gravações acontecem imediatamente. Veja Confirmação de ação para o fluxo completo e a postura recomendada para cada canal.
Configuração
O Processamento de Documentos reutiliza as configurações de manuseio de arquivo da página Platform Settings. Os valores mais relevantes:
| Configuração | Padrão | Finalidade |
|---|---|---|
| Max File Size (MB) | 5 | Teto rígido para qualquer arquivo que o processador aceitará. |
| Allowed File Extensions | pdf,csv,png,jpg,jpeg,txt,json |
Lista de permissões global aplicada antes que qualquer arquivo chegue ao modelo. |
| Max CSV Characters | 50.000 | Limita o tamanho de um único arquivo CSV que o agente processará de forma incorporada. |
| File Distribution Threshold (KB) | 1300 | Arquivos acima desse tamanho são entregues ao modelo por meio de uma URL de curta duração, em vez de serem incorporados. |
| Distribution Expiry (Minutes) | 30 | Tempo de vida da URL temporária usada na entrega de arquivos grandes. |
| File Processing Credit Multiplier | Configurável | Amplia o orçamento de tokens de saída para turnos com arquivos, para que o agente possa produzir resultados de extração mais completos. |
| Email File Processing Enabled | — | Controle de segurança para definir se os anexos em mensagens de Email Service de entrada são processados. Desativado ignora os anexos; o e-mail ainda é roteado para o seu agente. |
Veja Configurações da plataforma para a referência completa de metadados do Setup.
Impacto nos créditos
O Processamento de Documentos aumenta a contagem de tokens de entrada de uma conversa, porque o conteúdo do arquivo é enviado ao modelo. O impacto nos créditos depende do formato:
- Texto e CSV — a contagem de tokens escala com a contagem de caracteres.
- PDF e imagens — enviados como blocos multimodais, que usam mais tokens por unidade de conteúdo do que texto simples.
- Saída — o File Processing Credit Multiplier aumenta o orçamento máximo de resposta para turnos com arquivos. Um valor maior significa resultados de extração mais completos, a um custo de crédito mais alto.
Veja Otimização do uso de créditos para orientações de ajuste.
Segurança e governança
- Permanece na sua organização. Os arquivos são armazenados como
ContentVersionna sua organização do Salesforce. A plataforma não copia arquivos para nenhum repositório externo. - O compartilhamento padrão se aplica. Quem executa o agente precisa ter acesso de compartilhamento ao arquivo e a qualquer registro que o agente leia ou grave.
- A segurança em nível de campo é aplicada. Gravações resultantes da extração de documentos respeitam a FLS do usuário em execução — campos que o usuário não pode editar não são alterados.
- URLs de arquivos grandes de curta duração. Quando o modelo busca um arquivo grande por meio de um link de distribuição, a URL expira após o período configurado e é removida por um job agendado.
- Trilha de auditoria. Toda conversa envolvendo arquivos é registrada nos registros padrão de Conversation e Message, incluindo as chamadas de ferramenta que o agente fez e os registros que tocou.
Veja Segurança de dados na REDA AI para a postura de segurança completa.
Boas práticas
Combine o padrão com a tarefa. Use ferramentas integradas para extrações pontuais; use uma ferramenta de Mapeamento de Arquivo quando o mesmo formato de arquivo é processado repetidamente; recorra a uma ferramenta Apex somente quando a lógica realmente exigir código.
Restrinja a lista de permissões por agente. Um agente que só processa faturas não precisa aceitar envios de imagem. Restrinja Supported File Types na Definição de Agente para reduzir entradas inesperadas.
Mantenha os CSVs enxutos. Remova colunas não utilizadas antes de processar, e divida arquivos grandes em lotes que caibam confortavelmente dentro do Max CSV Characters. O agente é mais preciso com entradas focadas.
Seja criterioso com o Auto Execute File Actions. A execução automática remove a etapa de confirmação. Reserve-a para agentes internos confiáveis e formatos de arquivo bem conhecidos.
Teste os caminhos de falha. Durante a construção, entregue ao agente PDFs malformados, CSVs em branco e imagens irrelevantes — o estilo de resposta a entradas ruins faz parte da experiência do usuário.
Automação e confiabilidade
Invocações em massa pelo Flow podem retornar IDs de solicitações adiadas em vez de respostas imediatas. Revise elementos seguintes que esperam resposta, créditos ou resultados na mesma transação. Ações automáticas preservam canal e modo configurados e registram resultados reais no contexto, sem garantir uma narração adicional. Deslocamentos horários explícitos são preservados nos caminhos compatíveis de eventos, agendamentos, gravação de campos e CSV. Sem deslocamento, permanece a interpretação do usuário executor. O modo Sistema não gera avisos apenas por ser usado; registros e notificações de nível ERROR permanecem. Extração respeita o limite de saída, cores funcionam nos temas Salesforce compatíveis e testes empacotados evitam referências estáticas que bloqueavam instalação sem tipos de registro de Conta.
Perguntas frequentes
Não. Os arquivos permanecem na sua organização do Salesforce como registros ContentVersion. O modelo lê o documento diretamente como uma entrada multimodal — não há serviço intermediário de OCR ou de extração de documentos.
Arquivos acima do File Distribution Threshold são entregues ao modelo por meio de uma URL ContentDistribution de curta duração, em vez de serem mantidos em memória. O link expira após o período configurado e é removido por um job agendado.
Sim. Com o Email File Processing ativado, os anexos no endereço de Email Service de entrada são filtrados, armazenados como arquivos no Salesforce e roteados para o agente mapeado a esse endereço por meio dos metadados de Email Routing. Veja Canal de e-mail — Entrada.
Use uma ferramenta de Mapeamento de Arquivo quando o arquivo é tabular, o mapeamento de coluna para campo é estável, e a operação é uma criação ou atualização direta. Use uma ferramenta Apex quando precisar de lógica condicional, gravações em múltiplos objetos, deduplicação em relação a registros existentes, ou chamadas a sistemas externos.
Sim. As gravações disparadas pelo Processamento de Documentos são executadas sob as permissões do usuário e respeitam a segurança em nível de campo e o compartilhamento. Campos que o usuário não pode editar não são alterados, mesmo que o documento contenha um valor para eles.
PDFs escaneados e imagens são lidos pelo modelo como conteúdo visual, então o texto legível é extraído na mesma chamada. A qualidade depende da imagem de origem — digitalizações nítidas extraem os dados de forma confiável, e fotos de baixa resolução funcionam melhor com orientação explícita do usuário na conversa.
Sim. O conteúdo do arquivo faz parte da entrada que o modelo processa, então arquivos maiores usam mais créditos. O File Processing Credit Multiplier também amplia o orçamento de saída para turnos com arquivos. Veja Otimização do uso de créditos para orientações de ajuste.
Próximos passos
Configure importações em massa com o tipo de ferramenta de Mapeamento de Arquivo, crie um extrator personalizado com o tipo de ferramenta Apex, ou aprenda a conectar documentos de entrada na página Canal de e-mail — Entrada.