Workflow Agents: How They Work
Every time you click "Execute" in TeXRA, an agent takes your files and instructions, asks an AI model to do the work, and delivers the result. This page explains what happens under the hood—enough to understand the system, customize it, and troubleshoot when things go sideways.
Agent Definition Files (.yaml)
Each agent is defined in a simple .yaml file that tells TeXRA what to say to the AI model and how to handle the response. You can browse these files in the Agent Explorer, or create your own (see Custom Agents).
Understanding the YAML Structure
These .yaml files have two main parts (and thankfully, YAML is usually less prickly than XML or JSON):
settings: Define general operational parameters. For example:agentCategory: Is it aworkflowagent (structured Chain-of-Thought reasoning with XML-wrapped output) or atoolUseagent (interactive conversation that can call tools like file editing, web search, etc.)?prefills: Text the agent should automatically start its response with (e.g.,<scratchpad>).- (Other settings control output format, inheritance, etc. See Configuration and Custom Agents for full details).
prompts: Contain text templates that TeXRA fills with your specific context (input files, instructions) to guide the LLM at different stages:systemPrompt: Sets the overall role and high-level instructions for the LLM.userPrefix: Provides the main context, including your input file(s) (available via e.g.,) and the specific instruction you typed in the UI (available via).userRequest: Asks the LLM to perform the initial task (Round 0). Often instructs the LLM to think within<scratchpad>tags and then output the main content wrapped within the XML tags defined bysettings.documentTag(e.g.,<document>...</document>). You can also provide an array here: the first entry becomes the round 0 request, and any additional entries drive automatic reflection rounds (Round 1+). When a run consumes more rounds than entries you specify, the first reflection template is reused.
_(Prompts use Jinja2 templating. For a detailed list of available variables like and how to use them, see the Custom Agents guide.)*
Transparency & Customization
The prompts described above (systemPrompt, userPrefix, etc.) represent TeXRA's structured approach to guiding the LLM. This structured, template-based system means the agent's behavior is transparent and highly customizable through the .yaml file, not a hidden black box.
Basic Execution Flow
When you click "Execute" in the TeXRA UI, TeXRA uses the selected agent's definition (.yaml) and your UI inputs to interact with the chosen LLM:
Key Stages:
- Initialization: TeXRA loads the agent definition and reads the files you selected.
- Prompt Construction: It combines the agent's
systemPrompt,userPrefix(filled with your files and instruction), anduserRequesttemplates into a full prompt for the LLM. - LLM Interaction (Round 0): TeXRA sends the prompt to the selected LLM API. The LLM generates a response, typically including reasoning (
<scratchpad>) and the final answer wrapped in XML tags (e.g.,<document>...</document>). - Processing: TeXRA saves the raw LLM response (often as an
.xmlfile internally). It then parses this file, extracts the content from the primary XML tag (defined bysettings.documentTag), and saves that extracted content to the final output file (e.g.,filename_agent_r0_model.tex). You can monitor this in the ProgressBoard. For LaTeX files, TeXRA can also automatically generate alatexdifffile comparing the output to the input, enhancing observability. See the LaTeX Diff guide for details.
Continuation Handling: If the LLM response gets cut off due to output token limits before generating the required endTag, TeXRA automatically sends a continuation prompt. This prompt asks the model to resume generating exactly where it left off, ensuring complete outputs even for very long tasks. This happens seamlessly within a processing round.
What Goes Into the Prompt
TeXRA assembles a conversation from your agent's prompts and the content you selected in the UI. If you enabled Attach TeX Count or Attach Diagnostics, that information is included too. Figures and audio files are sent alongside the text for models that support them. The AI then reasons through the task and produces its output.
Reflection Rounds (Round 1+):
When an agent definition includes multiple userRequest entries (or increases settings.rounds), TeXRA automatically performs additional passes after Round 0 completes:
- Reflection Prompt: It renders the appropriate reflection template from subsequent
userRequestentries to ask the LLM to critique and improve its own Round 0 output (which is included in the conversation history). - LLM Interaction (Round 1): The LLM generates a revised response.
- Processing: TeXRA saves this refined output to a separate file (e.g.,
filename_agent_r1_model.ext).
You can control how many rounds execute by editing the agent YAML—either adjust settings.rounds for the maximum number of passes or add more entries to userRequest. The run stops early whenever the model signals it is finished or when no reflection prompt content is supplied.
This basic flow, potentially with the reflection rounds, allows TeXRA agents to perform targeted tasks based on their specific definitions and your instructions. For concrete examples of built-in agents, see the Built-in Agent Reference.
Potential XML Issues
Occasionally, LLMs might generate slightly malformed XML (e.g., missing closing tags), especially with very long or complex outputs. If TeXRA fails to extract content from an agent's output (_r0_*.xml or _r1_*.xml file), you might need to manually inspect the .xml file and correct any structural errors (like adding a missing </document> tag) before TeXRA can process it correctly. See the Troubleshooting guide for more details.
Reflection
After generating an initial output (Round 0), TeXRA agents that define reflection prompts evaluate and refine their work (Round 1):