Atualizado em Sep 7, 2026

Ler Arquivo como Texto

Use esta ação quando um workflow ou um agente precisa do texto que está dentro de um arquivo armazenado — um contrato que um contato enviou por e-mail, uma planilha que alguém subiu, um log que uma etapa anterior baixou — para que uma etapa seguinte possa resumir, pesquisar ou decidir o que fazer com base no que ele diz.

Ideal para

• Responder às perguntas de um contato sobre o PDF ou documento do Word que ele acabou de anexar
• Extrair o texto de um arquivo para que uma etapa de LLM possa resumir, classificar ou extrair informações dele
• Ler um arquivo de texto simples — um .txt, um CSV — que uma etapa anterior baixou para o storage. Uma exportação em JSON ou um log só voltam legíveis se tiverem sido armazenados como texto: veja O tipo vem do content type armazenado
• Descobrir o que um anexo realmente é antes de gastar qualquer coisa com ele: o tipo de mídia volta mesmo quando o arquivo não pode ser lido como texto

Por que isso importa

Nenhuma outra ação entrega o conteúdo de um arquivo. Inspecionar Mídia informa que um arquivo tem 4 MB e dois minutos de duração; Criar URL Assinada de Armazenamento dá um link para ele. Nenhuma das duas permite que uma etapa aja sobre o que o arquivo diz.

Esta ação é a única que devolve texto utilizável por uma etapa seguinte, e o devolve na mesma execução — diferente de Transcrever Áudio, que inicia um job em segundo plano, aqui o texto está no resultado desta etapa e a etapa imediatamente seguinte já pode usá-lo.

Campos principais

Campo	O que faz
Arquivo	O arquivo a ler, como uma expressão que resolve para uma referência de arquivo. Em uma execução de agente, o anexo recebido é contactMessage.body.file; depois de uma etapa de upload ou download, é step(0).file. Um caminho em texto simples também funciona
Bucket e Caminho completo	Uma alternativa ao campo Arquivo, quando você quer apontar diretamente para o arquivo. O Bucket assume por padrão o storage da sua empresa, então normalmente basta o Caminho completo
Máximo de caracteres	Limite opcional de quanto texto volta. De qualquer forma o limite máximo é 2.000.000. Deixe vazio para o máximo
Finalidade	Rótulo opcional que descreve a etapa nos logs. Não altera qual arquivo é lido

Deixando o agente escolher o arquivo

Um parâmetro de ferramenta de agente é um valor de nível superior nas expressões: um parâmetro chamado caminho é escrito caminho, e não parameters.caminho — que não resolve para nada e lê silenciosamente a coisa errada. Assim, o campo Arquivo pode ser {"fullPath": caminho} e o modelo escolhe qual arquivo ler.

Isso importa quando uma mesma mensagem recebida trouxe vários anexos. contactMessage.body.file nomeia no máximo um deles, enquanto as linhas [attachment] … · ref: <caminho> que o agente vê listam todos — o modelo devolve o caminho ref: daquele que quer.

O arquivo ainda precisa pertencer à sua empresa. Um caminho fora dela falha exatamente como um arquivo que não existe — deliberadamente o mesmo erro, para que esta etapa não possa ser usada para descobrir se o arquivo de outra empresa existe.

O que as etapas seguintes podem usar

Estes valores ficam na raiz da etapa, então leia-os como step(N).text, e não step(N).data.text. Veja Ações que publicam na raiz da etapa.

Valor	O que é
step(N).text	O texto extraído. Vazio quando supported é falso
step(N).supported	Se o arquivo pôde ser lido como texto — veja abaixo
step(N).truncated	true quando o texto foi cortado em um limite. Não trate como o documento inteiro
step(N).reason	Por que o arquivo não pôde ser lido, e qual ação trata esse caso. Vazio quando supported é verdadeiro
step(N).mediaKind	text, document, pdf, image, audio ou video
step(N).mimeType	O tipo de conteúdo armazenado
step(N).fileName	O nome original do arquivo usado por quem enviou, não o caminho no storage
step(N).size	Tamanho em bytes

Quais arquivos são lidos como texto

Tipo	Arquivos	O que você recebe
text	Qualquer coisa cujo content type armazenado comece com text/ — text/plain, text/csv, text/markdown	Devolvido diretamente
document	Word, Excel, PowerPoint e seus equivalentes OpenDocument — .doc, .docx, .odt, .rtf, .xls, .xlsx, .ods, .ppt, .pptx, .odp	Convertido em texto no servidor
pdf	.pdf	Convertido em texto no servidor. Um PDF digitalizado sem camada de texto volta como suportado e com texto vazio — não há OCR
image	Fotos e imagens	Não é lido. Modelos com visão recebem imagens diretamente; use Inspecionar Mídia para as dimensões
audio	Gravações e áudios	Não é lido. Use Transcrever Áudio para obter uma transcrição
video	Clipes e gravações de tela	Não é lido. Use Inspecionar Mídia para os dados do contêiner, ou Transformar Mídia para extrair o áudio e então Transcrever Áudio

Qualquer coisa que o conversor não consiga abrir — um .zip, um .bin, um documento corrompido — também volta sem ser lida, com "This file type cannot be converted to text."

O tipo vem do content type armazenado, e não do nome do arquivo

O tipo acima é decidido apenas pelo content type armazenado do objeto. text/… é text, application/pdf é pdf, image/…, audio/… e video/… são o que dizem, e todo o resto é document — que só é lido se for um dos tipos Office ou PDF da tabela.

O nome do arquivo tem exatamente uma segunda chance, e só dentro do caminho document: uma extensão Office ou PDF resgata um documento armazenado como application/octet-stream. .json, .log, .md e .yaml não estão em nenhuma das duas listas, então para eles o content type armazenado é tudo o que conta:

Armazenado como	O que você recebe
text/plain, text/csv, text/markdown	Devolvido diretamente
application/json — o que um .json recebe do próprio cabeçalho Content-Type de uma API, e da detecção automática de Download para Armazenamento e Upload para Storage	document, e não um extraível: supported é false com "This file type cannot be converted to text."
application/octet-stream — onde um .log, um .md ou um .yaml param quando nada define um tipo	O mesmo

Renomear o arquivo não muda nada disso. Defina o tipo ao armazenar: tanto Download para Armazenamento quanto Upload para Storage aceitam um Tipo de conteúdo opcional, e text/plain ali é o que torna o arquivo legível depois.

Um arquivo que não pode ser lido não é uma etapa que falhou

Quando o arquivo é real mas não é texto — uma imagem, uma gravação, um vídeo — a etapa é bem-sucedida. step(N).supported é false, step(N).reason explica o que usar no lugar, e step_ok(N) continua true, então o resto do workflow segue rodando. Ramifique com base na resposta, em vez de contar com um erro:

step(0).supported                    // realmente veio texto?
step(0).mediaKind == "audio"         // mande para Transcrever Áudio
step(0).truncated                    // só parte do documento voltou

Falhas de verdade interrompem a etapa: nenhum arquivo naquele caminho, um arquivo de outra empresa, um documento acima do limite de tamanho, ou uma conversão que o serviço aceitou e não conseguiu terminar.

Um caso parece falha e não é. Onde o conversor de documentos não está configurado — uma instalação self-hosted ou local rodando sem o serviço de transcodificação — todo documento do Office e todo PDF volta exatamente como um .zip: supported false, o mesmo motivo "This file type cannot be converted to text." e step_ok(N) ainda true. Se um .docx comum é lido em um ambiente e volta como tipo não suportado em outro, desconfie do conversor antes do arquivo.

Limites

• Documentos do Office e PDFs acima de 20 MiB são recusados. Isso é uma falha real da etapa, e não um arquivo não lido.
• Arquivos de texto são lidos até 2 MiB e então cortados, com truncated marcado. Nunca são recusados pelo tamanho.
• O texto volta limitado a 2.000.000 de caracteres, ou ao Máximo de caracteres quando você define algo menor. Verifique step(N).truncated antes de tratar o texto como o documento completo.

Quanto custa

Ler um arquivo de texto simples apenas o lê, e não custa nada além da própria execução.

Arquivos do Word, Excel, PowerPoint e PDF são convertidos pelo mesmo serviço que faz a conversão de mídia, então essas leituras são cobradas da sua cota de transcodificação pelo tempo que a conversão levar. Aqui não há cache, diferente de Inspecionar Mídia — ler o mesmo documento em duas etapas o converte duas vezes. Leia uma vez e guarde o texto no estado da sessão se mais de uma etapa seguinte precisar dele.

Segurança

O texto que esta etapa devolve é conteúdo não confiável, escrito por quem fez o arquivo. Células ocultas de planilha, parágrafos em branco sobre branco e notas do apresentador sobrevivem à extração, e nada disso era visível para quem encaminhou o documento.

Trate-o como material a resumir ou citar, nunca como instruções a seguir. Quando ele alimentar uma etapa de LLM, mantenha-o na mensagem enviada ao modelo, e não na mensagem de sistema do agente.

Dicas

• Encadeie diretamente: o anexo recebido em uma etapa, esta ação na seguinte, e a etapa de LLM que usa o texto na etapa depois dela.
• Verifique step(N).supported antes de entregar step(N).text a um modelo. Em um arquivo não lido o texto é vazio, e um documento vazio é justamente o tipo de coisa sobre a qual um modelo inventa uma resposta com muito gosto.
• Defina Máximo de caracteres quando precisar apenas do começo — a primeira página de um contrato, o início de um log — em vez de pagar para colocar um documento inteiro no contexto de um modelo.
• Use step(N).fileName ao responder ao contato. O caminho no storage é um identificador opaco e não significa nada para ele.