Custom Agents

Every lab has its own writing style, formatting quirks, and recurring tasks. Maybe your group always needs a "rewrite the abstract for a Nature-style letter" pass, or you want an agent that converts your internal notes into arXiv-ready LaTeX. Custom agents let you encode these workflows once and reuse them with a single click.

This guide walks you through creating your own agent definition files (.yaml) so TeXRA does exactly what your research needs—no coding required.

Agent Fundamentals

Before creating a custom agent, it's highly recommended to understand the underlying concepts:

Agent Architecture & Execution Flow: Learn about the .yaml structure, settings, prompts, and how agents run. See the Agent Architecture & Execution Flow guide.
Built-in Agents: Review the standard agents provided by TeXRA for examples and potential inheritance parents. See the Built-in Agent Reference.
Agent Explorer: Learn how to browse and manage agent files using the Agent Explorer view in the TeXRA sidebar.

Reference Agents

TeXRA includes ready-made reference agents you can use as starting points. Think of them as recipes: copy one into your custom agents directory, tweak it, and you have a new agent in minutes. Examples range from content-enhancement workflows to notation standardizers and multi-agent orchestrators. Each also has a _multiple variant for multi-file output.

Creating a Custom Agent File

Follow these steps to create a new custom agent:

Step 1: Locate or Configure the Custom Agents Directory

Custom agents reside in a dedicated directory that TeXRA prepares for you.

Find the Default Folder: TeXRA automatically seeds a custom_agents directory inside its global storage. Look for the "Custom Agents" section in the Agent Explorer; it points to this location by default.
Override (Optional): If you prefer to manage agents elsewhere, open the Agents tab in the TeXRA Dashboard and click Change in the directory info bar to select a new folder. TeXRA will ensure that directory exists and use it instead of the default.

Automatic Creation

If you'd like TeXRA to draft an agent for you, use the Create AI Agent button in the Agent Explorer title bar. The wizard only asks for a short description and the default output filenames. TeXRA sends this information to a Claude model, which replies with the YAML enclosed in <yaml>...</yaml> tags. The extension extracts the content between those tags and saves it as a basic CoT template (single or multiple files) in your Custom Agents folder.

Step 2: Create a New YAML File

Using the Agent Explorer, right-click within your "Custom Agents" directory (or a subfolder).
Select "New File".
You'll be prompted for a name. Choose a descriptive name using underscores and ending with .yaml (e.g., literature_review_generator.yaml).

Step 3: Define the Agent

Open the newly created .yaml file and you'll find a starter template already inserted. Customize it to define your agent's structure. Here are the key fields:

yaml

# --- Agent Inheritance (Optional) ---
# Specify a built-in or other custom agent to inherit settings and prompts from.
# See guide/built-in-agents.md for potential parents.
inherits: base # Or polish, correct, etc.

# --- Agent Settings ---
# Define the agent's core behavior and operational parameters.
# Override parent settings here if inheriting.
settings:
  # Core Behavior
  agentCategory: workflow # 'workflow' for structured reasoning with XML-wrapped output, or 'toolUse' for interactive agents that call tools (file editing, web search, etc.)
  temperature: 0.1 # LLM creativity (0.0 = deterministic, >0 = more random). Can be overridden by user settings.
  isRewrite: true # Does the agent primarily rewrite existing content (true) or generate new content (false)?

  # Output Handling
  documentTag: document # The main XML tag wrapping the agent's final output (required for CoT).
  endTag: '</document>' # The closing tag that signals the agent has finished its main output.
  outputExt: tex # Default file extension for the output file (e.g., tex, md, txt).
  prefills:
    - "<document>\n" # List of strings the AI should start its response(s) with.
      # Item [0] is for Round 0, Item [1] is for Round 1 (reflection).
      # Crucial for models needing specific start formats (e.g., XML tags).

  # File Handling (Optional - Advanced)
  # requiredFiles:
  #   TEMPLATE: path/to/template.tex # Map variable names to required file paths relative to workspace.
  # requiredFilesInternal:
  #   STYLE_GUIDE: styles/internal_style.css # Map variable names to files relative to the agent's YAML file location.
  # filePatternsContain:
  #   - pattern: 'bibliography' # Find files whose names contain this pattern.
  #     varName: BIBLIOGRAPHY # Make content available via {{ BIBLIOGRAPHY_CONTENT }} in prompts.
  #     categories: ['auxiliaryFile', 'auxiliaryFiles'] # Search within these UI file categories.
  # defaultOutputFiles: # Used when the agent is designed to produce multiple outputs.
  #   - 'introduction.tex'
  #   - 'methods.tex'

# --- Agent Prompts ---
# Define the text templates used to instruct the LLM.
# Override parent prompts here if inheriting.
prompts:
  systemPrompt: |
    # Defines the AI's role, core instructions, constraints, overall persona.
    # Sent once at the beginning (for supported models).
    [Define the AI's role and core instructions]

  userPrefix: |
    # Provides introductory text, main context (input files, user instruction).
    # Variables like `{{ INPUT_CONTENT }}`, `{{ INSTRUCTION }}`, `{{ BIBLIOGRAPHY_CONTENT }}` (from filePatternsContain) are substituted here.
    [Define context, instructions, and input variables like `{{ INPUT_CONTENT }}`]

  userRequest:
    - |
      # The prompt for the AI's first round of work (Round 0).
      # Often includes guidance for thinking (<scratchpad>) and output structure (<documentTag>).
      [Define the initial task prompt, potentially including scratchpad guidance]
    - |
      # Optional follow-up prompt for reflection rounds (Round 1+).
      # Duplicate or remove items to control how many reflections TeXRA schedules automatically.
      [Define how the model should critique or iterate on its previous output]

Reflection Tips: When userRequest is an array, TeXRA takes the first entry as the initial request and treats the remaining entries as reflection prompts. If a run requests more reflections than the list provides, the first reflection template is reused.

Using Variables in Prompts (Jinja2 Templating)

Prompts are processed using the Jinja2 templating engine, allowing you to insert dynamic information using syntax. TeXRA provides several built-in variables based on the files and instructions you select in the UI:

This mechanism is sometimes referred to as Variable Retrieval (VR)—the extension loads your chosen inputs, references, figures, and any additional context, then exposes them as template variables. For example, the text content of your main file becomes while the full list of selected files can be accessed through . When you run the agent these placeholders are replaced with real data.

Common Variables:

{{ INSTRUCTION }}: The text entered into the "Instruction" box in the UI.
{{ INPUT_FILE }}: The path of the primary input file.
{{ INPUT_CONTENT }}: The full text content of the primary input file.
{{ REFERENCE_FILE }}: Path of the primary reference file.
{{ REFERENCE_CONTENT }}: Content of the primary reference file.
{{ AUXILIARY_FILE }}: Path of the primary auxiliary file.
{{ AUXILIARY_CONTENT }}: Content of the primary auxiliary file.
{{ EDITED_FILE }}: Path of the edited file (used in merge).
{{ EDITED_CONTENT }}: Content of the edited file.
{{ MEDIAFILE }}: Path of the primary media file. _Note: Media content itself isn't directly inserted as text; it's handled separately for multimodal models. See Working with Figures.

Multiple File Variables:

{{ ALL_INPUTS }}: XML string containing all selected input files (primary + multiple) wrapped in <document name="...">...</document> tags.
{{ ALL_REFERENCES }}: Similar XML string for all reference files.
{{ ALL_AUXILIARYS }}: Similar XML string for all auxiliary files.
{{ LIST_OF_ALL_INPUTS }}: Simple comma-separated string listing all input file paths.
{{ LIST_OF_ALL_REFERENCES }}: Similar comma-separated list for reference files.
{{ LIST_OF_ALL_AUXILIARYS }}: Similar comma-separated list for auxiliary files.

Multiple Output Variable:

{{ OUTPUT_FILES_ORDER }}: Comma-separated string listing the output filenames specified in the UI. Crucial for agents generating multiple files. See Handling Multiple Files.

Custom Variables (from settings):

Files specified in requiredFiles or requiredFilesInternal are available as (e.g., ).
Files matched by filePatternsContain are available as (e.g., ).
When agents finish, TeXRA automatically captures detected XML segments so orchestrated workflows can reuse them without going through the file picker again (details below).

Example Usage in userPrefix:

yaml

userPrefix: |
  Please process the main document: {{ INPUT_FILE }}
  <document name="{{ INPUT_FILE }}">
  {{ INPUT_CONTENT }}
  </document>

  Refer to these auxiliary files:
  {{ ALL_AUXILIARYS }}

  Apply the following instruction:
  <instruction>{{ INSTRUCTION }}</instruction>

Key Considerations:

Architecture Overview: For a high-level understanding of the execution flow and how prompts/settings interact, see the Agent Architecture & Execution Flow guide.
Inheritance: Inheriting from a relevant built-in agent (like correct or polish) can save significant effort. Only define the settings and prompts you need to change.
Multiple Outputs: If your agent needs to generate multiple distinct files, ensure your prompts generate the required XML structure. See the Handling Multiple Files guide.
Start Simple: Begin with basic settings/prompts and add complexity incrementally.
Test Iteratively: Test frequently and review logs in the ProgressBoard.

Chaining Agents Together

After a workflow agent finishes, TeXRA captures the output so follow-up steps can reuse it without another trip through the file picker. This is how multi-stage pipelines work—for example, an orchestrator agent can run a polish step, then automatically hand the result to a correct step, all in a single session.

You don't need to configure this yourself; it happens automatically when an agent definition includes orchestration prompts. See the reference agents for working examples.

Tool-Use Agents

Tool-use agents are interactive: instead of producing a single polished file, they hold a conversation and take actions on your behalf—reading and editing files, searching the web, looking up papers, and more.

Typical user story: You're writing up results for a conference submission and realize you need three new BibTeX entries, a TikZ architecture diagram, and a consistency pass across four .tex files. Rather than switching between browser tabs and terminal windows, you open a chat agent and describe what you need. The agent reads your project, searches arXiv for the missing references, drafts the TikZ code, and edits the files—all in one session.

To create your own tool-use agent, set agentCategory: toolUse and list the tools you want to grant. TeXRA provides tools in several categories:

Category	What it lets the agent do
File workspace	Read, write, edit, search, and list files in your project
Shell	Run commands (compilation, scripts, etc.)
Web & search	Fetch web pages and search the internet
Literature	Search arXiv, Crossref, and manage your Zotero library
Math	Run Wolfram Language computations
Figures	Extract and compile figures and TikZ diagrams
Memory & tasks	Remember context across sessions; track multi-step progress

For the exact tool names to list in your YAML, browse any of the built-in tool-use agents (like chat, search, or ask) in the Agent Explorer—their tools: array shows exactly which tools are available.

Example skeleton:

yaml

settings:
  agentCategory: toolUse
  tools:
    - read_file
    - write_file
    - edit_file
    - glob
    - grep
    - web_search

The ProgressBoard logs every tool call and its result, so you can always see what the agent is doing.

Example: Multiple Output Agent

If your workflow requires several output files, your agent must structure its response using the OUTPUT_FILES_ORDER variable. Below is a simplified template similar to the built-in polish_multiple.yaml:

yaml

inherits: polish
settings:
  agentType: CoT
  documentTag: latex_documents
  endTag: </latex_documents>
  defaultOutputFiles:
    - introduction.tex
    - conclusion.tex

prompts:
  userRequest: |
    {% if OUTPUT_FILES_ORDER %}
    The output files should be in this order: {{ OUTPUT_FILES_ORDER }}.
    {% endif %}

    <scratchpad>
    - Plan revisions for each file
    </scratchpad>

    <latex_documents>
    <document name="{{ OUTPUT_FILES_ORDER[0] }}">
    % UPDATED_FILE_1
    </document>
    <document name="{{ OUTPUT_FILES_ORDER[1] }}">
    % UPDATED_FILE_2
    </document>
    </latex_documents>

This structure lets TeXRA save each <document> block to the corresponding filename from the UI list. See Handling Multiple Files for more details.

Step 4: Save and Reload

Save your .yaml file.
Reload the VS Code window (Command Palette > Developer: Reload Window).
Your new custom agent should now appear in the "Agent" dropdown menu in the TeXRA UI.

Strict XML Extraction

TeXRA expects the model's output to use properly closed XML tags. For agents producing multiple files, each <document> block must include a name attribute matching one of the filenames from the UI. If tags are mismatched or a filename doesn't match, extraction fails and no files are saved—check the ProgressBoard logs for details.

For more examples and advanced options, browse the built-in agent definitions through the Agent Explorer.

Custom Agents ​

Reference Agents ​

Creating a Custom Agent File ​

Step 1: Locate or Configure the Custom Agents Directory ​

Automatic Creation ​

Step 2: Create a New YAML File ​

Step 3: Define the Agent ​

Using Variables in Prompts (Jinja2 Templating) ​

Chaining Agents Together ​

Tool-Use Agents ​

Example: Multiple Output Agent ​

Step 4: Save and Reload ​

Strict XML Extraction ​

Custom Agents

Reference Agents

Creating a Custom Agent File

Step 1: Locate or Configure the Custom Agents Directory

Automatic Creation

Step 2: Create a New YAML File

Step 3: Define the Agent

Using Variables in Prompts (Jinja2 Templating)

Chaining Agents Together

Tool-Use Agents

Example: Multiple Output Agent

Step 4: Save and Reload

Strict XML Extraction