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 Document tasks: 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, chat with the built-in creator agent and describe the behavior you want. It studies the existing agents, writes the YAML into your custom agents folder (you approve the write like any other edit), and can test the new agent before handing it over.

Step 2: create a new YAML file

1. In the Agents tab, select New chat agent or New document task () to create a new agent YAML file from a template 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 parts, one mapping

• inherits: my_polishstarts from another agent in the same folder
• prompt · temperaturethe persona: how it behaves
• task:the document task
  • rewrite: true
  • prefix:
  • requests:list → revisions

• requests[0]
  Revision 1first draft
• requests[1]
  Revision 2critique & improve

Each extra entry adds one more revision.

An agent file is inherits + a persona (prompt, temperature) + a task block; the task.requests list maps position-by-position onto revisions (requests[0] is Revision 1, requests[1] Revision 2).

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

name: notation_checker # Lowercase letters, underscores, or dashes.
description: Standardizes notation across the selected documents.

# --- Agent Inheritance (Optional) ---
# Inherit fields from another agent in the same directory (a custom agent
# inherits from another custom agent, such as a customized copy of a built-in).
# The child's fields override the parent's; a `task` block merges field by
# field, and a list such as `requests` replaces the parent's list.
# inherits: my_polish

# --- Persona ---
temperature: 0.1 # Optional, 0 to 1 (default 1.0). Lower is more deterministic.

prompt: |
  # The system prompt: 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]

# --- Document task ---
# A `task` block lets this agent also run as a document task. Without it,
# the agent only chats (see below). A file with `task` cannot also list `tools`.
task:
  rewrite: true # Edit the input documents (true, the default) or write new documents (false).

  # File Handling (Optional - Advanced)
  # files:
  #   STYLE_GUIDE: styles/internal_style.sty # Map variable names to files the agent bundles, relative to its YAML file location. Workspace files are attached per run as context files instead.
  # outputs: # Used when the agent writes new files with fixed names.
  #   - 'introduction.tex'
  #   - 'methods.tex'

  prefix: |
    # 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 }}`]

  requests:
    - |
      # The prompt for the AI's first revision.
      # 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 a reflection revision.
      # Each entry is one revision: add or remove entries to control how many run.
      [Define how the model should critique or iterate on its previous output]

The file is flat and strict: a key TeXRA does not know is refused, and the older nested settings: / prompts: layout is not read. There is no model field; you choose the model when you run the agent.

Reflection tips: TeXRA takes the first requests entry as the initial request and each remaining entry as one reflection prompt, in order. The number of entries is the number of revisions.

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 task.outputs or receive an explicit generated output list.

Custom variables (from task.files):

• Each file bound in task.files is available as {{ VARNAME_FILE }} (its path) and {{ VARNAME_CONTENT }} (its text); a binding TEMPLATE: template.tex gives {{ 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 task.prefix:

task:
  prefix: |
    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 Document tasks: how they work guide.
• Inheritance: Inheriting from a related agent in the same directory (for example a customized copy of correct or polish) saves effort. Define only the fields 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 document task finishes, its result lists the output files, so follow-up steps can reuse them without another trip through the file picker. This is how multi-stage pipelines work: for example, an orchestrator agent can run polish with the document_task tool, then hand the result to a correct task, 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.

Agents with tools

An agent without a task block works in a chat: 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 agent with tools, leave out the task block and list the tools you want to grant. Such an agent has no request template: what you type is sent as the user message. TeXRA groups tools by the plugin that adds them (listed on Settings → Plugins ()). Each chip below is a token you can put straight into your tools: array:

Dashboard → Toolstools you can grant an 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_entriesdiagnostics
• Academic ResearchSearch arXiv, download paper sources, manage Zotero
  arxiv_searchdownload_arxiv_sourcezotero_*
• WebFetch pages and search the internet
  web_searchweb_fetch
• DelegationDelegate to Codex, consult another chat model
  codexinquiry
• Lean 4Check Lean proofs and search Mathlib
  lean_diagnosticslean_inspectlean_looglelean_filelean_project
• Memory & WorkflowPersistent memory, plans, sub-agent delegation
  memoryplanagentscriptexecutionsaccept_run_files

The grantable tool categories; 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 agents with tools (like research, review, lean, or numerics) in the Agents tab. Their tools: array shows which tools are wired up.

Example skeleton:

name: bib_helper
description: Finds references and edits the bibliography.
tools:
  - read_file
  - write_file
  - edit_file
  - glob
  - grep
  - web_search

prompt: |
  [Define the agent's role and how it should use its tools]

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 document task that writes two generated output files:

name: intro_and_conclusion
inherits: my_polish
task:
  rewrite: false
  outputs:
    - introduction.tex
    - conclusion.tex
  requests:
    - |
      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 task.outputs:

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.

Customized built-in agents and updates

Built-in agents ship with TeXRA and update when TeXRA does. A custom agent with the same name as a built-in overrides it. Customize in the Agents tab (or texra agents customize <name>) copies the built-in into your custom agents folder and records which version it copied in a basedOn: line at the end of the file.

When an update changes that built-in, the Agents tab marks your copy and offers View built-in, Reset to built-in (deletes your copy so the new version is used), and Keep mine (keeps your copy and dismisses the notice). In the terminal, texra agents list and texra agents show print the same notice, and texra agents reset <name> or texra agents keep <name> settle it. An agent you wrote yourself under a built-in's name has no basedOn: line and is never flagged.

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.