Analizar archivos

Analizar archivos

La herramienta Analizar archivos permite a los agentes procesar y razonar sobre el contenido del archivo utilizando LLM.

Para añadir la herramienta Analizar archivos a tu agente, realiza los siguientes pasos:

1. Define file inputs. In the Data Manager panel, add an argument for each file input in your agent schema.

   Figura 1. Crear argumentos de entrada de archivo

   

   Input argument must be explicitly referenced in the user prompt using the {{exampleInput}} syntax. Input arguments that are not referenced are ignored and may affect the agent's score.

   • 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. Añade la herramienta Analizar archivos a tu definición de agente:

   1. Selecciona Añadir herramienta en el panel Herramientas.
   2. En la categoría Herramientas integradas, elige Analizar archivos.
   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. Ejecuta el agente con archivos de entrada.

   1. Abre la ventana Configuración de depuración:
      1. Navega a la pestaña Argumentos del proyecto.
      2. Carga tus archivos de entrada vinculados a tu argumento reportFiles.
   2. Selecciona Guardar y ejecuta la sesión de depuración.

   

5. Después de ejecutar el agente, inspecciona el seguimiento de ejecución a través del panel 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.

Seguimientos de archivo adjunto

Al utilizar la herramienta Analizar archivos, todas las entradas y salidas de los archivos se capturan en el panel Seguimiento de ejecución, en la pestaña Historial. El seguimiento proporciona una visibilidad detallada de cómo se gestionaron los archivos adjuntos durante la ejecución del agente.

Para cada archivo, el seguimiento muestra:

• ID: un identificador exclusivo para el archivo adjunto.

• Nombre: nombre del archivo original (por ejemplo, 1.jpg).

• Tipo MIME: tipo de archivo detectado (por ejemplo, image/jpeg).

  Figura 2. El análisis de archivo en el seguimiento de ejecución

  

Selecciona la llamada de herramienta del seguimiento de ejecución y ve a la pestaña Archivos para descargar el archivo.

Figura 3. Cómo descargar un archivo de los seguimientos

Mejores prácticas y preguntas frecuentes

Nota:

Para obtener más Detalles sobre el uso de Archivos de Processes de Maestro, Flujos de trabajo de RPA o ejecuciones de agente independientes, consulta Trabajar con Archivos.

La herramienta Analizar Archivos permite a los agentes procesar documentos e imágenes utilizando LLM. Aunque es potente, hay algunas limitaciones y comportamientos importantes a tener en cuenta al diseñar agentes impulsados por archivos.

Los archivos grandes pueden superar los límites de token.

Agents process files by embedding their contents into LLM prompts, which are constrained by the model's token limit. Large PDFs or scanned image documents may silently fail or return vague errors like "An error occurred", especially when they exceed the model's token budget.

Para mitigar:

• Usa modelos con mayor capacidad de tokens.
• Usa Contextualización en lugar de la incrustación de archivo completo, especialmente para archivos grandes o de varias páginas.
• Preindexa documentos y sincronízalos antes o durante la ejecución del agente a través de herramientas personalizadas.

Los LLM cambian el tamaño de las imágenes

Cuando se envían archivos de imagen (por ejemplo, .jpg, .png) como parte de la solicitud de LLM, la mayoría de los modelos cambian automáticamente su tamaño. Esto puede distorsionar las relaciones de aspecto o perder datos precisos de píxeles.

Evita solicitudes que se basen en coordenadas exactas, cuadros de límite o comparaciones alineadas de píxeles (por ejemplo, diferencias de imagen que requieren un posicionamiento x/y específico). Para obtener más información, consulta la guía de visión de imagen de OpenAI para el comportamiento de cambio de tamaño específico del modelo.

Tipos de archivo compatibles

Se admiten las siguientes extensiones de archivo: GIF, JPE, JPEG, PDF, PNG, WEBP.

La compatibilidad con tipos de archivo varía según el proveedor de LLM. Por ejemplo, la compatibilidad con PDF puede fallar en algunos modelos de Anthropic dependiendo del nombre del archivo o la codificación.

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.

Consejos para mejores resultados

• Los nombres de archivo deben estar limpios: los modelos antrópicos, en particular, rechazan nombres de archivo con caracteres especiales o espacios en blanco repetidos.
• Mantén bajo el recuento de imágenes: algunos modelos como GPT-4o admiten un máximo de 10-50 imágenes por solicitud.