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. Define file inputs. In the Data Manager panel, add an argument for each file input in your agent schema.

   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.

   • For a single file, set the argument type to File and reference it in the user prompt. For example: "Analyze the following report and summarize the key findings: {{reportFile}}".
   • To pass multiple files, set the argument type to Array and the item type to File, then reference the argument by name in the user prompt. You can also add optional string arguments for runtime instructions. For example:

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

   In this example, reportFiles is an Array of File argument and analysisInstructions is an optional String argument. Both must be defined in the Data Manager panel.

   

   

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. Update the tool name and description to help the agent reason better about when to use it. The name and description guide the agent's planning phase — they determine when the agent decides to call the tool, not what the tool does with the files at runtime.

   

3. Set the tool’s inputs. The tool comes preconfigured with two main inputs:

   • attachments (array): A prompt-defined input that tells the agent which files to pass to the tool. In this field, describe how the agent should use the file inputs referenced in the user prompt (for example, {{reportFiles}}). The agent automatically maps those referenced files to this input at runtime. Example: "Use the files provided in the user prompt (for example, {{reportFiles}}) as inputs for analysis."
   • analysisTask (string): A runtime instruction telling the LLM what to do with the files once the tool is invoked — for example, "Analyze these reports. Extract the report title, an executive summary, key findings ordered by importance, actionable recommendations, and the overall sentiment." This is distinct from the tool name and description, which control when the agent calls the tool. If your use case involves only one file, you can describe attachments accordingly (for example, "Use the file provided in {{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.

The Analyze Files tool is now added to your agent and configured to process file inputs. The execution trace in the Execution Trail panel shows how each attachment was handled during the run.

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, 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.

Handling large PDFs

Large PDFs can exceed the LLM's token budget when processed in full. Split the PDF into smaller chunks or individual pages before passing them to the agent.

File limits

Each file must not exceed 30 MB. There is no enforced limit on the number of files per request.

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.