# 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](https://docs.maitento.com/concepts/agents.md).

## 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

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

### `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.

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

### `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`.

```hcl
prompt = @prompt("poet")
```

### `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.

```hcl
summary = "A friendly assistant"
```

### `functions`

Optional. [List of blocks](#each-item-of-functions).

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

### `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.

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

### `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).

```hcl
allowSwarm = true
```

### `allowWebSearch`

Optional. `true` or `false`. Default: `false`.

Gives the agent the built-in web search tool.

```hcl
allowWebSearch = true
```

### `allowWebFetch`

Optional. `true` or `false`. Default: `false`.

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

```hcl
allowWebFetch = true
```

## Each item of `functions`

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

### `functions` › `ref`

**Required.** Reference to a tool.

The tool.

```hcl
ref = @ref("current-weather")
```

### `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.

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

## A complete example

From the [14-web-research](https://github.com/maitento/maitento/tree/main/examples/14-web-research) example project:

```hcl title="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
```