TeXRA

Appearance

Handling Multiple Files (Inputs & Outputs) ​

TeXRA excels at managing complex academic projects often split across multiple files, like a paper with several chapters or appendices. This guide explains how to work with multiple input files and how agents can generate multiple, distinct output files in a single run.

Why Use Multiple Files? ​

Working with multiple files is often necessary when:

  • Your source document is split (e.g., chapter1.tex, chapter2.tex, appendixA.tex).
  • You need to apply consistent changes (like polishing or correcting) across related documents.
  • You only want an agent to modify specific parts (e.g., only update chapter2.tex and appendixA.tex based on the full context).
  • An agent needs to generate distinct outputs based on a single input (less common, but possible).

UI for Multiple Files ​

The TeXRA UI provides dedicated sections for managing multiple input files.

  • Input Files: Each Input row is an ordered list — use Add files (), Add opened files (), or drag-and-drop to append sources. They are concatenated and provided as context to the selected agent. For editing agents, the expected output filenames are the selected input filenames in the same order.
  • Fixed Outputs: Agents that create files with names not determined by the inputs declare those filenames in settings.defaultOutputFiles.
Input
1chapter1.tex
2chapter2.tex
3appendixA.tex
Row order is the output order — editing agents reuse each input filename as its output filename.

The Input group is an ordered list — drag to reorder. For editing agents the row order is the output order, and each input filename is reused as its output filename.

(See File Management for general UI controls.)

How It Works: Agent Input ​

When you provide multiple input files, TeXRA typically combines their content (often wrapping each in <document name=\"...\"> tags within a parent <documents> tag) and includes it in the prompt sent to the selected agent. The agent receives the combined context to inform its processing.

How It Works: Agent Output & Extraction ​

This is the crucial part for generating multiple distinct files:

  1. TeXRA Determines Outputs: Editing agents use the selected input filenames as the output filenames. Generator agents can declare fixed filenames through settings.defaultOutputFiles.

  2. Agent Generates Structured XML: The selected agent must be designed (through its prompts) to produce a single XML response containing separate blocks for each intended output file, using a structure like this:

    xml
    <documents>  <!-- the agent's configured documentTag; "documents" by default -->
  <document name="chapter2.tex">
    % ... content for the first output file ...
  </document>
  <document name="appendixA.tex">
    % ... content for the second output file ...
  </document>
  ...
</documents>

  3. TeXRA Extracts: The TeXRA backend parses this XML response. It looks for <document> tags with a name attribute that exactly matches one of the expected output filenames.

  4. Files Saved: For each matching tag found, TeXRA extracts the content within that tag and saves it to the corresponding filename. If the agent's response doesn't include a <document> tag with a name matching one you specified, that file will not be created or updated.

agent responseone XML message
<documents>
<documentname="chapter2.tex">
% … content for chapter2.tex …
</document>
<documentname="appendixA.tex">
% … content for appendixA.tex …
</document>
<documentname="notes.tex">
% … content for notes.tex …
</document>
</documents>
expected outputsselected input filenames
chapter2.texmatched → saved
appendixA.texmatched → saved
notes.texno match → skipped

Each <document name="…"> block is matched by name against the expected output filenames — matches are saved, a block with no matching name is skipped.

Key Point: The agent must be explicitly instructed via its prompts to generate the <document name=\"...\"> structure matching the output filenames provided through INPUT_FILES for editing agents, or OUTPUT_FILES for agents that declare generated output filenames.

Tracking Multi-Output Runs ​

TeXRA uses the selected input filenames as the output filenames for ordinary editing agents. Agents that generate files with fixed names can declare defaultOutputFiles; those names are exposed as OUTPUT_FILES. Prompt rendering and output extraction depend on these filename lists, not on a separate YAML flag or a _multiple filename convention.

editing agentinputs become outputs
INPUT_FILES
input files
chapter2.tex
appendixA.tex
output files
chapter2.tex
appendixA.tex
generator agentdeclares fixed outputs
defaultOutputFiles → OUTPUT_FILES
input files
notes.md
output files
paper_section.tex
appendix.tex

Two ways output filenames are determined: editing agents reuse the selected INPUT_FILES, while generator agents emit the fixed names declared in defaultOutputFiles (exposed as OUTPUT_FILES).

Declaring multi-output agents in YAML ​

Custom workflow agents can advertise that they expect multiple outputs by setting settings.defaultOutputFiles to the expected filenames. This gives prompts a fixed OUTPUT_FILES list when the filenames are not the input filenames.

yaml
name: my_agent
settings:
  agentCategory: workflow
  defaultOutputFiles:
    - paper_section.tex
    - appendix.tex

The legacy useMultipleOutputs and isMultipleOutput YAML fields are no longer part of the current agent settings schema. Update existing YAML files to declare defaultOutputFiles instead.

Example: Multiple-Output Agent Prompts ​

Workflow edit prompts can use INPUT_FILES to request and format multiple outputs within the <documents> tag. INPUT_FILES is an array of selected input filenames, so templates should iterate over it. Use {{ INPUT_FILES | join(", ") }} when the prompt needs a readable list.

yaml
# Inside a workflow agent's userRequest prompt:
# ... instructions ...
Output one updated document for each input file, using the matching input
filename as the document name.

# Use the following format:
<documents>
{% for output in INPUT_FILES %}
<document name="{{ output }}">
% UPDATED_CONTENT_FOR_{{ output }}
</document>
{% endfor %}
</documents>

For agents with settings.defaultOutputFiles, iterate over OUTPUT_FILES instead.

This instructs the model to generate the necessary XML structure that TeXRA can parse.

When to Use ​

  • Applying consistent edits (e.g., polish, correct) across multiple related .tex files.
  • Tasks where an agent naturally produces distinct outputs (though less common than editing existing files).
  • Targeting agent modifications to specific files within a larger project.

Next Steps ​

Output Naming ​

By default, TeXRA uses the selected input filenames as the output filenames. Agents that write fixed new files should declare settings.defaultOutputFiles. Editing prompts should reference INPUT_FILES; generated-output prompts should reference OUTPUT_FILES so the model emits matching <document name="..."> tags.