Analisar arquivos

Analisar arquivos

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

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 único arquivo, defina o tipo de argumento como Arquivo e faça referência a ele no prompt do usuário. Por exemplo: "Analisar o seguinte relatório e resumir 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}}
   

   Nesse exemplo, reportFiles é um argumento Array de Arquivo e analysisInstructions é um argumento String opcional. Ambos devem ser definidos no painel do Data Manager .

   

   

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 raciocinar melhor sobre 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. Neste campo, descreva como o agente deve usar as entradas de arquivo referenciadas na solicitação do usuário (por exemplo, {{reportFiles}}). O agente mapeia automaticamente esses arquivos referenciados para essa entrada no runtime. Exemplo: "Use os arquivos fornecidos no prompt 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 é adicionada ao seu agente e configurada para processar entradas de arquivos. O rastreamento de execução no painel Trilha de execução mostra como cada anexo foi tratado 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.

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 a contextualização em vez da incorporação completa do arquivo, especialmente para arquivos grandes ou de várias páginas.
• Pré-indexe documentos e sincronize-os antes ou durante a execução do agente por meio de ferramentas personalizadas.

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.

Tipos de arquivos compatíveis

As seguintes extensões de arquivo são compatíveis: GIF, JPE, JPEG, PDF, PNG, TIFF, WEBP.

O suporte a tipos de arquivo varia por provedor de LLM. Por exemplo, o suporte a PDF pode falhar em alguns modelos Anthropic, dependendo do nome ou da codificação do arquivo.

Gerenciamento de PDFs grandes

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

Limites de arquivo

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

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.