Analisar arquivos

Adicione a ferramenta Analisar arquivos a um projeto do Agents para processar e raciocinar em relação ao conteúdo dos arquivos usando LLMs.

A ferramenta Analisar arquivos permite que os agentes processem e raciocinem sobre o conteúdo do arquivo usando LLMs.

Adicione a ferramenta Analisar arquivos

Para adicionar a ferramenta Analisar arquivos ao seu agente, siga as seguintes etapas:

1. Defina entradas de arquivo. No painel Gerenciador de dados, adicione um argumento para cada entrada de arquivo em seu esquema de agente.

   Figura 1. Criação de argumentos de entrada de arquivo

   

   O argumento de entrada deve ser referenciado explicitamente na solicitação do usuário usando a sintaxe {{exampleInput}}. Os argumentos de entrada que não são referenciados são ignorados e podem afetar a pontuação do agente.

   • Para um arquivo único, defina o tipo de argumento como Arquivo e faça referência a ele na solicitação do usuário. Por exemplo: "Analise o seguinte relatório e resuma as principais descobertas: {{reportFile}}".
   • Para transmitir vários arquivos, defina o tipo de argumento como Array e o tipo de item como Arquivo e, em seguida, faça referência ao argumento por nome na solicitação do usuário.Você também pode adicionar argumentos de strings opcionais para instruções de runtime.Por exemplo:

   Analyze the following report files and summarize the key findings.
   
   ## Inputs
   - Report files: {{reportFiles}}
   - Additional instructions (optional): {{analysisInstructions}}
   

   Neste exemplo, reportFiles é um argumento Array de Arquivo e analysisInstructions é um argumento String opcional. Ambos devem ser definidos no painel Gerenciador de dados.

   

2. Adicione a ferramenta Analisar arquivos à definição do seu agente:

   1. Selecione Adicionar ferramenta no painel Ferramentas.
   2. Na categoria Ferramentas integradas, escolha Analisar arquivos.
   3. Atualize o nome e a descrição da ferramenta para ajudar o agente a entender melhor quando usá-la. O nome e a descrição orientam a fase de planejamento do agente — eles determinam quando o agente decide chamar a ferramenta, não o que a ferramenta faz com os arquivos no runtime.

   

3. Defina as entradas da ferramenta. A ferramenta vem pré-configurada com duas entradas principais:

   • attachments (array): uma entrada definida por solicitação que informa ao agente quais arquivos passar para a ferramenta. Nesse campo, descreva como o agente deve usar as entradas de arquivos mencionadas na solicitação do usuário (por exemplo, {{reportFiles}}). O agente mapeia automaticamente esses arquivos de referência para essa entrada no runtime. Exemplo: "Usar os arquivos fornecidos na solicitação do usuário (por exemplo, {{reportFiles}}) como entradas para análise."
   • analysisTask(string): uma instrução do runtime que informa ao LLM o que fazer com os arquivos depois que a ferramenta é invocada — por exemplo, "Analisar esses relatórios. Extrair o título do relatório, um resumo executivo, as principais descobertas ordenadas por importância, recomendações acionáveis e o sentimento geral." Isso é diferente do nome e da descrição da ferramenta, que controlam quando o agente chama a ferramenta. Se seu caso de uso envolver apenas um arquivo, você pode descrever os anexos adequadamente (por exemplo, "Usar o arquivo fornecido em {{reportFile}}…").

4. Execute o agente com arquivos de entrada.

   1. Abra a janela Configuração de depuração :
      1. Navegue até a guia Argumentos do projeto.
      2. Carregue seus arquivos de entrada vinculados ao seu argumento reportFiles.
   2. Selecione Salvar e execute a sessão de depuração.

   

5. Após executar o agente, inspecione o trace de execução por meio do painel inferior.

A ferramenta Analisar arquivos agora está adicionada ao seu agente e configurada para processar entradas de arquivos. O Trace de execução no painel Trilha de execução mostra como o sistema tratou cada anexo durante a execução.

Traces de anexos de arquivos

Ao usar a ferramenta Analisar arquivos, todas as entradas e saídas de arquivos são capturadas no painel Trilha de execução, na guia Histórico. O trace fornece visibilidade detalhada sobre como os anexos foram tratados durante a execução do agente.

Para cada arquivo, o trace mostra:

• ID: um identificador exclusivo para o anexo.

• Nome: nome do arquivo original (por exemplo, 1.jpg).

• Tipo MIME: tipo de arquivo detectado (por exemplo, image/jpeg).

  Figura 2. A análise do arquivo na trilha de execução

  

Selecione a chamada de ferramenta no rastreamento de execução e navegue até a guia Arquivos para baixar o arquivo.

Figura 3. Como baixar um arquivo a partir de rastreamentos

Melhores práticas e perguntas frequentes

Observação:

Consulte Trabalhando com arquivos para obter mais detalhes sobre o uso de arquivos de Processes do Maestro, fluxos de trabalho de RPA ou execuções de agentes independentes.

A ferramenta Analisar Arquivos permite que os agentes processem documentos e imagens usando LLMs.Embora sejam potentes, há algumas limitações e comportamentos importantes a serem considerados ao projetar agentes orientados por arquivos.

Limites de arquivos

Cada arquivo não deve exceder 30 MB. Não há limite imposto no número de arquivos por solicitação.

Tipos de arquivos compatíveis

A ferramenta Analisar arquivos é compatível com os seguintes tipos de arquivo: .pdf, .gif, .jpg, .jpeg, .png, .tiff, .webp.

O suporte para diferentes formatos pode variar dependendo do provedor e do modelo de LLM selecionados. Os resultados também podem variar entre provedores e modelos, especialmente para arquivos que contêm gráficos, imagens incorporadas ou layouts complexos.

Suporte a arquivos para configurações de LLM personalizadas

Os tipos de arquivo compatíveis são os mesmos quando você usa o recurso Traga seu próprio LLM por meio da AI Trust Layer. A configuração de um provedor, família de modelos ou tipo de API cujo modelo subjacente aceita outros formatos não estende os tipos de arquivo que a ferramenta Analisar arquivos aceita. Para obter detalhes sobre como configurar um LLM personalizado, consulte Configuração de LLMs.

Como funciona o processamento de arquivos

Quando você passa um arquivo para um LLM, o modelo não recebe o arquivo original como está.A maioria dos provedores aplica uma etapa de pré-processamento antes de adicionar o conteúdo ao contexto do modelo. O comportamento do pré-processamento depende do tipo de arquivo.

Os arquivos PDF podem ser processados como texto extraído e imagens de página em modelos compatíveis com visão. Os arquivos de imagem são passados para o modelo como imagens, sujeitos ao comportamento de redimensionamento descrito em LLMs redimensionar imagens.

Provedores como OpenAI, AWS Bedrock e Vertex AI podem usar diferentes abordagens de pré-processamento, e os detalhes de implementação exatos são específicos do provedor e podem não estar totalmente documentados.

Arquivos grandes podem exceder os limites de token

Agents processam arquivos incorporando seu conteúdo a solicitações de LLM, que são restringidas pelo limite de tokens do modelo. PDFs grandes ou documentos de imagem digitalizados podem falhar silenciosamente ou retornar erros vagos como "Ocorreu um erro", especialmente quando eles excedem o orçamento de token do modelo.

Para mitigar:

• Use modelos com capacidade de token mais alta.
• Use recursos orientados à recuperação, como Pesquisar arquivo ou contextualização, especialmente para arquivos grandes ou com várias páginas.
• Pré-indexe documentos e sincronize-os antes ou durante a execução do agente por meio de ferramentas personalizadas.

Tratamento de PDFs grandes

PDFs grandes podem exceder o orçamento de Token do LLM quando processados integralmente.Divida o PDF em partes menores ou páginas individuais antes de passá-las para o agente.

LLMs redimensionam imagens

Quando os arquivos de imagem (por exemplo, .jpg, .png) são enviados como parte da solicitação do LLM, a maioria dos modelos os redimensiona automaticamente. Isso pode distorcer as relações de aspecto ou perder dados precisos em pixels.

Evite solicitações que dependam de coordenadas exatas, caixas de delimitação ou comparações alinhadas por pixels (por exemplo, diferenças de imagem que exigem posicionamento x/y específico). Para obter mais informações, consulte o guia de visão de imagem do OpenAI para comportamento de redimensionamento específico do modelo.

Dicas para melhores resultados

• Os nomes dos arquivos devem estar limpos: os modelos antrópicos, em particular, rejeitam nomes de arquivos com caracteres especiais ou espaços em branco repetidos.
• Mantenha a contagem de imagens baixa: alguns modelos, como o GPT-4o, são compatíveis com um máximo de 10 a 50 imagens por solicitação.
• Use o formato PDF quando o layout, gráficos ou diagramas forem importantes.