How to create an agent with mm init

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# How to create an agent with `mm init`

This guide shows how to write a new agent.yaml for a model and a job, with mm's wizard: it asks a few questions, reads what the model server says about the model, and writes a commented file — every value with the reason it has that value. No model runs while it does. It assumes a model server is running (llmman, Ollama, Docker Model Runner, llama-server, or any OpenAI-compatible one).

## Steps

1. In the directory where the agent will work, run:

   ```bash
   mm init
   ```

   (`mm --init` is the same.)

2. In a terminal, a window opens, in the style of `mm -tui`: the steps on the left, the current question in the middle — with what the highlighted choice means —, and on the right the agent.yaml as it would be written, updated as you move the selection. A real capture (130 × 34, llmman, usage step, `docs` highlighted):

   ```text
    mm init — new agent · llmman · Qwen3.5-4B:Q4_K_M
   ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
    ✓ Server    llmman   │ What is the agent for?                   │ # docs — answers from a documentation folder (docs/), with lin…
    ✓ Model     Qwen3.5-…│                                          │ #
    ✓ Family    qwen     │   developer  (default)                   │ # Written by `mm init`. Every value says why it has that value…
    ▸ Usage              │   reviewer                               │ # them as you watch the agent work (guides/agent-settings-for-…
    · Machine            │   translator                             │ #
    · Ask first          │   writer                                 │ #   model family: qwen
    · Name               │   assistant                              │ #   usage:        docs
    · File               │   researcher                             │ #   machine:      small — a laptop, models up to about 8B
                         │ ▸ docs                                   │ #
                         │   json                                   │ #   mm -config <this file>          or   mm -tui <this file>
                         │   coordinator                            │
                         │                                          │ provider: llmman
                         │ answers from a documentation folder      │ model: "hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M"
                         │ (docs/), with links to the passages      │
                         │                                          │ # 0 = mm asks the server for the window it serves (the model's…
                         │                                          │ # is 262144 tokens; the server may serve less)
                         │                                          │ contextWindow: 0
                         │                                          │ # usage docs's default: tools run without asking
                         │                                          │ yolo: true
                         │                                          │ # usage docs
                         │                                          │ bashTool: false
                         │                                          │ editTools: true
                         │                                          │ planTool: false
                         │                                          │ askUserTool: false
                         │                                          │ # no skills: add a skills/ folder and set skillsDir to use som…
                         │                                          │ # docs/en/how-to/add-a-skill.md)
                         │                                          │ skillsDir: no-skills
                         │                                          │ # usage docs
                         │                                          │ maxTurns: 8
                         │                                          │ # settings guide, row "Small model (≤ 8B), short tasks"
   ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
    ↑↓ choose · Enter next · Esc back · PgUp/PgDn preview · Ctrl-C quit
   ```

   `↑` `↓` choose, `Enter` answers and goes to the next question, `Esc` goes back one question, `PgUp` `PgDn` scroll the preview, `Ctrl-C` quits without writing. A text question (the name, the file) is typed; `Ctrl-U` clears it. On a screen narrower than 100 columns, `Tab` shows the preview in place of the question. When every question is answered, `Enter` writes the file.

   The questions: the model server, the model (from the server's list), its family (detected from the name), what the agent is for (developer, reviewer, translator, writer, assistant, researcher, docs, json, coordinator), which machine runs the model (small, medium, large), whether to ask before each command or file change, the agent's name and the file.

3. mm writes the file and checks that it loads:

   ```text
   ✅ wrote agent.yaml
   ✅ mm loads it
   Next: mm -config agent.yaml   (or mm -tui agent.yaml)
   ```

4. Read the file: each value is preceded by its reason — the GGUF's own sampling, a model card, a measured demo of this repository, the settings guide's row for your machine. Change what does not fit as you watch the agent work.

## Variants

- **Prove the model answers.** Add `--check`: after writing, mm asks the model "Say hello in one line." with the new file and says whether it answered. The first answer loads the model, which can take a while.
- **Line by line.** `--line`, or a run whose input or output is not a terminal (`mm init < answers.txt`), asks the same questions one per line: numbered choices, Enter takes the default.
- **No questions, for a script.** Give every answer as a flag, and `--yes` for the rest:

  ```bash
  mm init --provider llmman --model hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M \
          --usage docs --machine small --name rata -o agent.yaml --yes --check
  ```

- **See the file without writing it.** `-o -` prints it on stdout.
- **A server elsewhere.** `--base-url http://192.168.1.20:17434/v1`; it is written into the file as `baseUrl`.
- **A server that does not answer.** mm says so and asks for the model's name: the settings then come from the family table only.
- **An existing file.** mm never overwrites it, and says so before asking anything: choose another name with `-o`.
- **A JSON agent.** `--usage json` writes a `structuredOutput` example (Go types) to replace with yours, and turns every tool off, since a structured answer forbids tools.
- **A model mm does not know.** The family `other` gives a generic starting point and a note in the file: check the model card.

## See also

- [Command line reference — `mm init`](../reference/cli.md#mm-init--the-agentyaml-wizard): every flag, the sources, the exit codes
- [Configuration reference](../reference/configuration.md): every key the file holds
- [Agent settings for small models](../../../guides/agent-settings-for-small-models.md): what each setting does, the machine rows
- `agent.creator.yaml`: an agent that creates agents with a model, for the unusual cases