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.
• **Agents Tab**: Browse and manage agent files from the **Agents** tab () in the TeXRA Dashboard.

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 agent handles one input or several through a unified protocol: set documentTag: documents and your prompt emits one <document name="..."> per input.

Migrating an older custom YAML? See agent-yaml-migration.md for the full before/after walk-through covering the W2/W3/W4 changes (auxiliary→context picker merge, _multiple retirement, single-slot collapse).

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 live in a dedicated directory that TeXRA prepares for you.

1. Find the Default Folder: TeXRA automatically seeds a custom_agents directory inside its global storage. Open the Agents tab () in the TeXRA Dashboard to see its location.
2. Override (Optional): If you prefer to manage agents elsewhere, open the Agents tab and click Change () in the directory info bar to pick 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, click New Agent () in the Agents tab. The wizard only asks for a short description and the default output filenames. TeXRA sends that info to a Claude model, which returns 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

1. In the Agents tab, click From Template () to create a new agent YAML file in your custom agents directory.
2. Alternatively, click Open Folder () to open the directory and create a .yaml file manually.
3. 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. An agent is just three labelled sections plus one mapping you need to keep in mind:

custom_agent.yamlthree sections, one mapping

• inherits: polishstarts from a built-in parent
• settings:how it behaves
  • agentCategory: workflow
  • rounds: 2
  • documentTag: documents
• prompts:what it says
  • systemPrompt:
  • userPrefix:
  • userRequest:array → rounds

• userRequest[0]
  Round 0initial draft
• userRequest[1]
  Round 1reflection

Extra entries add more reflection rounds.

An agent file is inherits + settings + prompts; the userRequest array maps position-by-position onto rounds (item [0] is Round 0, item [1] the first reflection).

Customize it to define your agent's structure. Here are the key fields:

# --- 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)?
  rounds: 2 # Maximum number of passes (Round 0 plus reflection rounds). The actual count is max(rounds, number of userRequest entries); a run can still stop early once the model signals it is finished.

  # Output Handling
  documentTag: documents # The main XML tag wrapping the agent's final output (defaults to `documents`).
  endTag: '</documents>' # The closing tag that signals the agent has finished its main output.
  prefills:
    - "<documents>\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: ['inputFiles', 'contextFiles'] # Search within these UI file categories (e.g. inputFiles, contextFiles, mediaFiles).
  # 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 {{ variable_name }} 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 {{ INPUT_CONTENT }} while the full list of selected files can be accessed through {{ ALL_INPUTS }}. When you run the agent these placeholders are replaced with real data.

Built-in prompt variables

One selected file

{{ INSTRUCTION }}textWhat you typed in the Instruction box

{{ INPUT_FILE }}pathPrimary input file

{{ INPUT_CONTENT }}textText of the primary input file

{{ CONTEXT_FILE }}pathPrimary context file

{{ CONTEXT_CONTENT }}textText of the primary context file

{{ EDITED_FILE }}pathEdited file (used in merge)

{{ EDITED_CONTENT }}textText of the edited file

{{ MEDIA_FILE }}pathPrimary media file — content sent separately

Every selected file

{{ ALL_INPUTS }}xmlAll inputs wrapped in <document> tags

{{ ALL_CONTEXTS }}xmlAll context files as the same XML

{{ LIST_OF_ALL_INPUTS }}csvComma-separated input paths

{{ LIST_OF_ALL_CONTEXTS }}csvComma-separated context paths

The naming follows one rule: *_FILE gives you a path, *_CONTENT gives you that file's text, ALL_* bundles every selected file into one <document name="...">…</document> XML string, and LIST_OF_* gives the same set as a comma-separated path list. Media is the exception — MEDIA_FILE is a path, but the media itself is sent to multimodal models separately rather than inlined as text (see Working with Figures). Legacy custom agents can still read the REFERENCE_* and AUXILIARY_* aliases, but new agents should use CONTEXT_*.

Multiple Document Output:

• {{ INPUT_FILES }}: Array of input filenames. Editing agents should iterate over this list and emit one <document name="..."> block per input filename, preserving the input order and names. Use {{ INPUT_FILES | join(", ") }} for a human-readable list. See Handling Multiple Files.
• {{ OUTPUT_FILES }}: Array of declared generated output filenames. This is only populated for agents that set defaultOutputFiles or receive an explicit generated output list.

Custom Variables (from settings):

• Files specified in requiredFiles or requiredFilesInternal are available as {{ VARNAME_CONTENT }} (e.g., {{ TEMPLATE_CONTENT }}).
• Files matched by filePatternsContain are available as {{ VARNAME_CONTENT }} (e.g., {{ BIBLIOGRAPHY_CONTENT }}).
• 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:

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

  Refer to these context files:
  {{ ALL_CONTEXTS }}

  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 realise you need three new BibTeX entries, a TikZ architecture diagram, and a consistency pass across four .tex files. Rather than juggling browser tabs and terminal windows, you open a research 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 groups tools by category (matching Dashboard → Tools ) — each chip below is a token you can drop straight into your tools: array:

Dashboard → Toolstools you can grant a tool-use agent

• File & ShellRead, write, edit, search, list, and run commands in your project
  read_filewrite_fileedit_fileglobgreplsbash
• LaTeXExtract figures, TikZ, and bibliography; report compile diagnostics
  extract_figuresextract_tikz_figuresextract_bib_entriesdiagnosticstexcount
• Academic ResearchSearch arXiv and Crossref, resolve DOIs, manage Zotero
  arxiv_searcharxiv_metadatadownload_arxiv_sourcecrossref_doicrossref_searchzotero_*
• WebFetch pages and search the internet
  web_searchweb_fetch
• ComputationRun Wolfram Language, delegate to Codex, consult another chat model
  wolframcodexinquiry
• Lean 4Check Lean proofs and search Mathlib
  lean_diagnosticslean_inspectlean_looglelean_filelean_project
• Memory & WorkflowPersistent memory, to-do lists, sub-agent delegation
  memorytodo_writeplandelegate_workflowdelegate_agentexecutionsaccept_run_files

The seven tool categories on Dashboard → Tools; every chip is a name you can list verbatim in your agent's tools: array.

For the exact tool names to list in your YAML, browse any of the built-in tool-use agents (like research, review, lean, or numerics) in the Agents tab — their tools: array shows exactly which tools are wired up.

Example skeleton:

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 appropriate filename list. Below is a simplified template for a workflow agent that writes two generated output files:

inherits: polish
settings:
  agentCategory: workflow
  documentTag: documents
  endTag: </documents>
  defaultOutputFiles:
    - introduction.tex
    - conclusion.tex

prompts:
  userRequest: |
    The output files should be in this order: {{ OUTPUT_FILES | join(", ") }}.

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

    <documents>
    {% for output in OUTPUT_FILES %}
    <document name="{{ output }}">
    % UPDATED_CONTENT_FOR_{{ output }}
    </document>
    {% endfor %}
    </documents>

This structure lets TeXRA save each <document> block to the corresponding filename from the selected input list or from settings.defaultOutputFiles:

Multiple output<document name> → saved file

Model output

• <document name="introduction.tex">… content …</document>
• <document name="conclusion.tex">… content …</document>
• <document name="summary.tex">… content …</document>

• →
• →
• ⤫

TeXRA saves

• introduction.texsaved
• conclusion.texsaved
• summary.texname not in list → skipped

Each <document name="…"> block is saved to the file whose name matches; a name that isn't in the declared list is skipped and nothing is written.

See Handling Multiple Files for more details.

Step 4 — Save and Reload

1. Save your .yaml file.
2. Reload the VS Code window (Command Palette → Developer: Reload Window).
3. Your new custom agent should now appear in the Agent dropdown () of 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 Agents tab () in the TeXRA Dashboard.