Custom agents
Every agent in TeXRA is a YAML file: a chat persona with a prompt and a list of tools. You can copy and edit any built-in agent or write a new one from scratch—for example, to check derivations against your group's conventions or to manage a bibliography.
This guide shows how to create and test your own .yaml agent definitions.
Agent fundamentals
Before creating a custom agent, it helps to understand the underlying concepts:
- Agent architecture and execution flow: how chats and programs run. Read the Agent architecture guide.
- Built-in agents: the standard agents TeXRA provides, useful as examples. Read the Built-in agent reference.
- **Agents tab**: browse and manage agent files from the **Agents** tab () in the TeXRA Settings.
Creating a custom agent file
Step 1: locate or configure the custom agents directory
Custom agents live in a dedicated directory that TeXRA prepares for you.
- Find the default folder: TeXRA seeds a
custom_agentsdirectory inside its global storage. Open the Agents tab () in the TeXRA Settings and expand Custom agent folder at the bottom of the Library section to see its location. - Override (optional): to manage agents elsewhere, select Change folder in that Custom agent folder row to pick a new folder (Use default folder switches back). 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
- In the Agents tab, select New agent to create a new agent YAML file from a template in your custom agents directory.
- Alternatively, select the folder icon (, Open custom agents folder) in the Custom agent folder row to open the directory and create a
.yamlfile manually. - Choose a descriptive file name ending with
.yaml(for exampleliterature_review_generator.yaml).
Step 3: define the agent
Open the new .yaml file. A starter template is already inserted. An agent file has five fields:
name: notation_checker # Letters, digits, underscores, or dashes; starts with a letter or digit.
description: Checks notation across the project's documents.
temperature: 0.1 # Optional, 0 to 1 (default 1.0). Lower is more deterministic.
tools: # The tools the agent may call.
- read_file
- edit_file
- glob
- grep
prompt: |
# The system prompt: the AI's role, core instructions and constraints.
[Define the AI's role and core instructions]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.
No task block
Earlier versions let an agent file define a document task in a task: block (prefix, requests, files, outputs and template variables). That block no longer exists, and a file that has it is refused as an unrecognized key. Documents are revised by the built-in programs instead.
Custom document workflows
User-defined programs are not available yet. To get a custom document workflow:
- Write the request in the instruction. The programs take their scope and point of view from the instruction, so "read as a referee for a physics journal and mark every unsupported claim" needs no new agent, only
annotatewith that sentence. - Ask an agent to chain programs. A program's result lists the files it wrote, so an agent can pass them to the next program in the same session, for example
annotate, thenapply. Read Multi-agent workflows. - Put project conventions in
AGENTS.md. Notation rules, journal style and anything else every run should follow belong in the project'sAGENTS.md, not in an agent file.
Agents with tools
An agent works in a chat: it holds a conversation and calls tools to read and edit files, run commands, search the web, and look up papers.
List the tools to grant under tools:. What you type in the composer is sent directly as the user message. TeXRA groups tools by plugin (listed on Settings → Plugins ()); each chip below is a tool name you can place in tools::
File & ShellRead, write, edit, search, and run commands in your project read_filewrite_fileedit_fileglobgrepbashLaTeXExtract figures, TikZ, and bibliography; report compile diagnostics extract_figuresextract_tikz_figuresextract_bib_entriesdiagnosticsAcademic ResearchSearch arXiv, download paper sources, manage Zotero arxiv_searchdownload_arxiv_sourcezotero_searchzotero_addzotero_exportzotero_collectionsWebFetch pages and search the internet web_searchweb_fetchDelegationDelegate to Codex or Claude Code codexclaude_codeLean 4Check Lean proofs and search Mathlib lean_diagnosticslean_inspectlean_looglelean_filelean_projectMemory & WorkflowPersistent memory, plans, sub-agent and task delegation memoryplanagentprogramscriptexecutionsaccept_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 Tasks view () logs every tool call and its result, so you can always see what the agent is doing.
Step 4: save and run
- Save your
.yamlfile. - 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, verify the agent registered, then smoke-test it in one go:
texra agents show bib_helper
texra run bib_helper --instruction "List the entries in refs.bib that main.tex never cites."agents show prints the agent's name, its source (custom) and the file it loaded.
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> resolve it. An agent you wrote yourself under a built-in's name has no basedOn: line and is never flagged.
For more examples, browse the built-in agent definitions through the Agents tab () in the TeXRA Settings.