Anexos de conversa: ler, guardar, analisar e transformar

O cliente manda uma planilha, um contrato em PDF, um extrato bancário de 30 páginas — e o agente não fica só olhando. Ele lê o conteúdo, e a partir daí você escolhe o que fazer: guardar para consultar depois, analisar com precisão de planilha, só ler aquele trecho agora, ou pedir um arquivo novo a partir dele — comprimido, com só algumas páginas, ou convertido. Esta página cobre as quatro coisas e fecha com a receita para montar um especialista que sabe fazer tudo isso sozinho.

Para o básico de mandar um arquivo na conversa — tipos aceitos, limite de 10 arquivos por mensagem — veja Anexos: arquivos na conversa.

O que o agente enxerga de um anexo

Cada anexo pode ser um documento (PDF, Word, Excel, PowerPoint, CSV, texto, Markdown, JSON, HTML ou código) ou uma imagem (PNG, JPEG, GIF, WebP). Numa mesma mensagem: até 10 arquivos, 10 MB por arquivo e 20 MB no total.

Para documentos, o agente recebe o texto extraído direto na conversa, até um teto de 200 mil caracteres — o equivalente a 35–40 páginas bem densas. Acima disso, ele não trava nem inventa o resto: recebe um aviso explícito com os números exatos (quantos caracteres apareceram, de quantos no total) e é instruído a avisar você de que está vendo um recorte do documento — nunca que o arquivo está corrompido ou ilegível.

Cada anexo tem um identificador (o attachment_id), visível para o agente nos metadados do anexo. É o endereço do arquivo original completo — é ele que as ferramentas de guardar, analisar e ler usam para trabalhar com o documento inteiro, não só com o recorte que apareceu na conversa. Esse identificador vale dentro da mesma conversa: o anexo é efêmero, não é armazenamento permanente — se você quer que ele sobreviva à conversa, precisa guardá-lo (veja abaixo).

Guardar vs. analisar

Esta é a decisão central: o mesmo anexo pode virar memória de consulta ou dado exato para conta, e são caminhos diferentes.

Você quer...	Peça isto	O agente usa
Consultar este documento em conversas futuras	"guarda este manual na base"	upload_file
Somar, contar ou cruzar números de uma tabela	"some as tarifas deste extrato"	register_source + query_source
Ler um trecho específico, sem guardar nem fazer conta	"o que diz a cláusula 4?"	read_attachment
Um arquivo novo — comprimido, com só algumas páginas, ou convertido	"reduz esse PDF" / "manda só as 3 primeiras páginas"	transform_file

Guardar: base de conhecimento

upload_file manda o anexo (pelo attachment_id) para a base de conhecimento da organização. Aceita PDF, DOCX, TXT e MD, até 100 MiB.

CSV e XLSX também podem ser guardados — e, quando são, fazem duplo papel: viram material de busca na base e viram fonte de dados para a análise de dados automaticamente, sem passo extra.

Um PDF escaneado (sem camada de texto, só imagem) passa por reconhecimento de texto automático, processado em lotes — o padrão cobre até 200 páginas.

Analisar: números exatos

register_source registra o anexo (pelo attachment_id) como fonte de dados; query_source consulta essa fonte com SQL, para respostas exatas em vez de estimativas. É o caminho certo sempre que a pergunta é "quanto", "quantos" ou "qual o total de".

Aceita:

• CSV.
• XLSX — use o parâmetro sheet para escolher a aba; se você não especificar, a resposta lista as abas disponíveis para você escolher.
• PDF com tabelas — a extração das tabelas é automática. É assim que um extrato bancário de 22 páginas vira uma soma exata, em vez de uma conta aproximada de cabeça.

export_to_artifact exporta o resultado de uma consulta como CSV, XLSX ou HTML, pronto para compartilhar.

Ler sob demanda

read_attachment lê o texto completo de um anexo em fatias (com offset e next_offset para continuar de onde parou). Use para um documento longo que não é tabela e não merece virar entrada permanente na base — uma leitura pontual, de passagem.

Se o PDF for um escaneado — sem camada de texto, só a imagem da página — não é preciso pedir nada especial: essa leitura reconhece o texto automaticamente, por OCR, até um teto de 10 páginas por documento. Acima disso, a ferramenta aponta o caminho certo: guardar o arquivo na base de conhecimento (upload_file), que faz o mesmo reconhecimento em segundo plano, sem essa pressa — o mesmo OCR em lote de até 200 páginas descrito acima.

Transformar: um arquivo novo

transform_file recebe um anexo — ou um artefato já gerado por uma operação anterior, para encadear — e devolve um arquivo novo. O original nunca é alterado. Três operações:

• compress (PDF) — recomprime as imagens do documento. Você escolhe um nível de qualidade (tela, leitura ou alta), nunca um tamanho de destino: compressão com perda não tem alvo garantido. A plataforma relata a redução que de fato conseguiu — bytes de entrada, de saída e o percentual — depois de rodar, não antes. Pedir "reduz pela metade" não é uma promessa que a ferramenta possa cumprir. Se a recompressão não encolher o arquivo, o original volta sem alteração.
• extract_pages (PDF) — gera um PDF só com as páginas escolhidas (ex.: "1-3,7").
• convert — PDF para imagem (PNG ou JPEG, só a primeira página de um PDF com várias — use extract_pages antes para escolher outra) ou imagem para PDF. Outras combinações, como PDF para PDF ou imagem para outro formato de imagem, não são suportadas.

Cada transformação tem um teto de 200 páginas no arquivo de entrada — acima disso, a ferramenta recusa antes de processar. Vindo de um anexo, o arquivo de entrada já respeita o limite de 10 MB por arquivo do início desta página; encadeando a partir de um artefato anterior, o teto sobe para 50 MB.

O resultado é um artefato: fica salvo na organização como qualquer outro artefato (veja Artefatos), pronto para baixar ou para servir de entrada a uma nova transformação. No app, ele aparece como um card de arquivo na própria conversa; o link de download é válido por 7 dias.

O que a plataforma não faz com arquivos

• Não junta vários arquivos em um só. transform_file trabalha com um arquivo de entrada por vez; combinar páginas de documentos diferentes num único PDF não é uma operação suportada.
• Não redimensiona imagem por essa via. convert troca o formato (imagem ↔ PDF), não o tamanho da imagem.
• Não lê nem produz formatos de escritório (DOCX, PPTX e afins) — só PDF e imagem entram e saem de transform_file.

Para criar um especialista que domina anexos

Um roteiro completo, do zero:

1. Habilite as ferramentas certas — na configuração do especialista, adicione ao campo tools as ferramentas das três fontes de ferramentas de anexos que a plataforma já traz:

   • anexos — read_attachment e transform_file;
   • base de conhecimento — upload_file;
   • análise de dados — register_source, query_source e export_to_artifact.

   No campo tools cada item se escreve no formato fonte.ferramenta, com o nome da fonte exatamente como ele aparece na tela de fontes de ferramentas do painel.

   Sem um bloco knowledge_base, o especialista não lê nenhum arquivo da base — o acesso é concedido, não presumido. Para dar acesso, declare o bloco com os arquivos (files) ou as etiquetas (tags) que ele pode ler, ou all_files: true para a base inteira:

   knowledge_base:
     files:
       - politicas/troca.pdf
     tags:
       - manuais

   Com o bloco, ele enxerga apenas o que estiver listado ali.

2. Escreva no prompt como usar as ferramentas — copie e adapte este trecho:

   prompt: |
     Quando o usuário pedir para guardar, analisar ou transformar um anexo,
     use o `attachment_id` da ferramenta certa — nunca recodifique o texto
     extraído que apareceu na conversa como se fosse o arquivo original: isso
     usaria só o recorte, não o documento completo.
   
     Se a mensagem trouxer o aviso de que o texto foi cortado, avise o
     usuário de que você está vendo um recorte do documento — nunca diga que
     o arquivo está corrompido ou ilegível.
   
     Para somar, contar ou cruzar dados de uma tabela (planilha, extrato,
     relatório), use `register_source` e `query_source` em vez de somar de
     cabeça: o resultado precisa ser exato, não estimado.
   
     Para gerar um arquivo novo — comprimido, com só algumas páginas, ou
     convertido — use `transform_file` com o `attachment_id` do anexo (ou o
     `artifact_id` de um artefato já existente, para encadear).

3. Suba a versão do especialista. Qualquer edição — inclusive habilitar estas ferramentas — só vale depois que o campo version muda. Esqueceu de subir a versão? A mudança pode demorar para valer.

4. Verifique. Anexe um PDF de 20 ou mais páginas numa conversa de teste, peça "guarda isso na base", depois "some a coluna X" e depois "manda só as 3 primeiras páginas desse PDF" — confira que o especialista aciona upload_file, register_source/query_source e transform_file com o attachment_id do anexo, em vez de responder de memória com o recorte que viu na conversa.

dica

Pedir tudo isso pronto para a Aura também funciona — "cria um especialista de análise de contratos que guarda tudo na base, sabe somar tabela de um extrato e consegue comprimir um PDF grande" já sai com os grants e o prompt certos.

Caminho alternativo fora do chat

Nem todo envio precisa vir de uma conversa. A tela Arquivos do painel (aba de base de conhecimento) aceita upload manual, com etiquetas, por organização — útil para carregar de uma vez os documentos de referência antes mesmo do primeiro atendimento.

Perguntas frequentes

O anexo continua disponível depois que a conversa termina? Só se você pedir para guardar (upload_file). Sem isso, o anexo é efêmero: vale para aquela conversa, não é armazenamento permanente.

Um documento de 300 páginas quebra o agente? Não. Para leitura inline, ele recebe até 200 mil caracteres do texto e um aviso claro de que é um recorte. Para tabelas grandes, o caminho é register_source + query_source, que não passa pelo teto de texto — a consulta roda sobre os dados, não sobre o recorte extraído.

Minha planilha tem várias abas — o agente sabe qual usar? Ele pergunta, ou você já indica com o parâmetro sheet. Sem especificar, a resposta lista as abas disponíveis para você escolher.

Isso funciona com PDF de tabela, tipo extrato bancário? Sim — register_source extrai as tabelas do PDF automaticamente, e a soma sai exata via SQL, mesmo num extrato de dezenas de páginas.

Meu PDF é uma foto escaneada, sem texto selecionável — dá para ler assim mesmo? Sim, até um teto de 10 páginas: a leitura reconhece o texto por OCR automaticamente, sem passo extra. Acima do teto, guarde o arquivo na base de conhecimento (upload_file) — o mesmo reconhecimento roda em segundo plano, para documentos de até 200 páginas.

Posso pedir para comprimir um PDF para caber num tamanho específico? Você pode pedir para comprimir, escolhendo um nível de qualidade — não um tamanho final. A ferramenta relata a redução que conseguiu depois de rodar; não é uma meta que ela promete bater de antemão.