Skip to content
docs

Agent files

An agent: a model with standing instructions, a one-line summary and the tools it may use. An agent does nothing on its own; an interaction puts it to work.

What agents are for, and how to use them: Agents.

Where the file goes

Section titled “Where the file goes”

agents/, or any sub-folder of it. The file name without .mtr is the agent’s name. Other files refer to it as @ref("<name>").

A resource’s name is its file name without .mtr (an app’s is its folder’s name). Use letters, digits, _, - and . (but not ..), at most 128 characters. Two files of the same kind may not have the same name, even in different sub-folders or with different capitals.

Properties

Section titled “Properties”

A file must set model, prompt and summary. Everything else is optional.

model

Section titled “model”

Required. Reference to an AI model.

The AI model the agent runs on, by its catalogue name: @ref("provider.model").

The model catalogue: @ref("provider.model"), such as @ref("deepseek.deepseek-v4-flash"). List the names with mt aimodel-list or the API.

model = @ref("deepseek.deepseek-v4-flash")

prompt

Section titled “prompt”

Required. Text.

The agent’s standing instructions (its system prompt): who it is and how it behaves. Use @prompt("name") for anything longer than a sentence. Run inputs (%%name%%) are not filled in here; they belong in the interaction’s task.

prompt = @prompt("poet")

summary

Section titled “summary”

Required. Text.

One line that describes the agent to other agents: a router choosing who answers, or a manager choosing who to hand work to, reads it.

summary = "A friendly assistant"

functions

Section titled “functions”

Optional. List of blocks.

The tools the agent may call in every interaction it takes part in.

routedSubAgents

Section titled “routedSubAgents”

Optional. List of references to agents.

Makes the agent a router. On every turn it is given, its model picks one of these agents (by their summary, guided by this agent’s prompt) and that agent takes the turn instead. The first one is the fallback.

routedSubAgents = [ @ref("maths-tutor") ]

allowSwarm

Section titled “allowSwarm”

Optional. true or false. Default: false.

Lets the agent start other interactions as sub-runs, where the interaction it takes part in allows them (its swarm block).

allowSwarm = true

allowWebSearch

Section titled “allowWebSearch”

Optional. true or false. Default: false.

Gives the agent the built-in web search tool.

allowWebSearch = true

allowWebFetch

Section titled “allowWebFetch”

Optional. true or false. Default: false.

Gives the agent the built-in web fetch tools, which read any URL as text.

allowWebFetch = true

Each item of functions

Section titled “Each item of functions”

A tool the agent may call, wherever it takes part: { ref = @ref("current-weather") }.

functions › ref

Section titled “functions › ref”

Required. Reference to a tool.

The tool.

ref = @ref("current-weather")

functions › guidance

Section titled “functions › guidance”

Optional. Text.

A note kept with the agent about how it should use the tool. The model reads the tool’s own guidance; to change that for one interaction, set guidance where the interaction binds the tool.

guidance = "Use it when the customer asks about an order."

A complete example

Section titled “A complete example”

From the 14-web-research example project:

agents/researcher.mtr
model = @ref("deepseek.deepseek-v4-flash")
prompt = "You are a careful researcher. Search the web, read the most relevant pages, and only state what the pages support."
summary = "Researches questions on the web"
// Give the agent Maitento's built-in web tools. Every search and page fetch is metered.
allowWebSearch = true
allowWebFetch = true
maitento