Custom agents

Every research discipline develops distinct methodological conventions. Whether you need an agent to verify every algebraic step in a derivation against domain invariants, standardize notation across an entire project, or enforce strict formatting for journal submissions, custom agents allow you to formalize these workflows in declarative YAML files.

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

Agent fundamentals

Before creating a custom agent, it helps to understand the underlying concepts:

• Agent architecture and execution flow: the .yaml structure, settings, prompts, and how agents run. Read the Workflow agents: how they work guide.
• Built-in agents: the standard agents TeXRA provides, useful as examples and as inheritance parents. Read the Built-in agent reference.
• **Agents tab**: browse and manage agent files from the **Agents** tab () in the TeXRA Settings.

Reference agents

TeXRA includes ready-made reference agents you can use as starting points. Treat them as recipes: copy one into your custom agents directory, adjust 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 the fixed <documents> container and emits one <document name="..."> per input.

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 seeds a custom_agents directory inside its global storage. Open the Agents tab () in the TeXRA Settings to see its location.
2. Override (optional): to manage agents elsewhere, open the Agents tab and select Change () in the directory info bar to pick a new folder. TeXRA creates that directory if needed and uses it instead of the default.

Automatic creation

To have TeXRA draft an agent for you, select New Agent () in the Agents tab. The wizard asks for the agent name and a short description (tool-use agents additionally let you pick the tools to grant). TeXRA sends that information to your configured helper model, which returns the YAML enclosed in <yaml>...</yaml> tags. The extension extracts the content between those tags and saves it as a template in your custom agents folder (falling back to a built-in template if generation fails).

Step 2: create a new YAML file

1. In the Agents tab, select From template () to create a new agent YAML file in your custom agents directory.
2. Alternatively, select the folder icon (, Open custom agents folder) in the directory info bar to open the directory and create a .yaml file manually.
3. Choose a descriptive name using underscores and ending with .yaml (for example literature_review_generator.yaml).

Step 3: define the agent

Open the new .yaml file. A starter template is already inserted. An agent is three labelled sections plus one mapping 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
• 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. These 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: polish # Or correct, merge, 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 # Number of passes (Round 0 plus reflection rounds). The actual count is max(rounds, number of userRequest entries); a run ends earlier only on failure or cancellation.

  # File Handling (Optional - Advanced)
  # requiredFilesInternal:
  #   STYLE_GUIDE: styles/internal_style.css # Map variable names to files the agent bundles, relative to its YAML file location. Workspace files are attached per run as context files instead.
  # 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 }}`, `{{ ALL_CONTEXTS }}` 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 the fixed <documents> output structure.
      [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 (Nunjucks templating)

Prompts are processed with the Nunjucks templating engine (Jinja2-style syntax), so you can insert dynamic information with {{ variable_name }} syntax. TeXRA provides several built-in variables based on the files and instructions you select in the UI.

This mechanism is sometimes called 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 }} and the full list of selected files is available 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 (read Working with figures).

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. Read 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 requiredFilesInternal are available as {{ VARNAME_CONTENT }} (for example {{ TEMPLATE_CONTENT }}).
• When agents finish, TeXRA 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 the execution flow and how prompts and settings interact, read the Workflow agents: how they work guide.
• Inheritance: Inheriting from a relevant built-in agent (like correct or polish) saves effort. Define only the settings and prompts you need to change.
• Multiple outputs: If your agent needs to generate multiple distinct files, make sure your prompts generate the required XML structure. Read the Handling multiple files guide.
• Start simple: Begin with basic settings and prompts and add complexity incrementally.
• **Test iteratively:** Test often 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 hand the result to a correct step, all in one session.

You do not need to configure this yourself; it happens when an agent definition includes orchestration prompts. The reference agents contain 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, such as reading and editing files, searching the web, and looking up papers.

Typical user story: You are 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 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 Settings → Tools ). Each chip below is a token you can put straight into your tools: array:

Dashboard → Toolstools you can grant a tool-use agent

• File & ShellRead, write, edit, search, and run commands in your project
  read_filewrite_fileedit_fileglobgrepbash
• 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_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 grantable tool categories on Settings → 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 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
  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.

Read Handling multiple files for more details.

Step 4: save and run

1. Save your .yaml file.
2. TeXRA watches the custom agents directory, so your new agent appears in the Agent dropdown () of the TeXRA UI. No window reload needed.

From a terminal the iteration loop is faster, with no window reload needed. Verify the agent registered, then smoke-test it in one go:

texra agents show

$texra agents show literature_review_generator

name:

literature_review_generator

category:

workflow

source:

custom

path:

…/custom_agents/literature_review_generator.yaml

$texra run literature_review_generator --input notes.tex --instruction "Draft the related-work section."

executions/e2c70a94b18f/r0/notes.tex

agents show confirms the registration (source: custom plus the file it loaded), and a one-shot texra run proves the prompts work before you polish the YAML further.

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 does not 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 Settings.