Anexos de conversa: ler, guardar e analisar

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, ou só ler aquele trecho agora. Esta página cobre as três 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

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 da analytics 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.

Para criar um especialista que domina anexos

Um roteiro completo, do zero:

1. Habilite as ferramentas certas — na configuração do especialista, adicione as três fontes de ferramentas de anexos ao campo tools: agent-base-tools (leitura), agent-base-tools-kb (guardar) e agent-base-tools-analytics (analisar):

   tools:
     - agent-base-tools-kb.upload_file
     - agent-base-tools.read_attachment
     - agent-base-tools-analytics.register_source
     - agent-base-tools-analytics.query_source
     - agent-base-tools-analytics.export_to_artifact

   Se o acesso à base de conhecimento deve ser restrito — por exemplo, um especialista que não deve enxergar contratos financeiros — declare também knowledge_base, com os arquivos ou padrões (globs) permitidos:

   knowledge_base:
     globs:
       - manuais/*
     files:
       - politicas/troca.pdf

   Sem esse bloco, o especialista enxerga toda a base de conhecimento da organização; com o bloco presente, ele enxerga apenas o que estiver listado em files e globs.

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

   prompt: |
     Quando o usuário pedir para guardar um anexo na base de conhecimento ou
     para analisar os dados de 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.

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" e depois "some a coluna X" — confira que o especialista aciona upload_file e register_source/query_source 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 e sabe somar tabela de um extrato" 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.