Building a Custom Agent
Build an agent of your own by describing it in one sentence, then check the review screen, try it on the last 30 days of your records and turn it on. The seven-step wizard is still there under Advanced.
When nothing in the agent library does the job your organization needs, you can build an agent of your own and keep it alongside the rest.
When you’d use this
- Your review process is specific to your organization and no library agent matches it.
- You want an agent that reads one of your own document types.
- You want the same agent set up differently for two departments, with each copy tuned by its own settings.
- A library agent is close but you want to start from it and change the detail.
Finding it
Sidebar → Agents → My agents, then Create Custom Agent in the page header. You can also start from a library card in Agent library: Customize a copy opens the builder with that agent’s settings and tools filled in. The library agent’s own instructions stay hidden; your copy adds your instructions on top of them.
Owners, admins and anyone with the Agent Operator role can build agents. An agent runs with its builder’s own access, and the tool picker offers only the tools that person can use.
Describe it in one sentence
The builder opens on one question: What should this agent do? One or two sentences is enough, for example “Receipts over $500 need an approval”. Click Draft it.
Muin drafts the whole agent from your sentence: a name, its instructions, the tools it needs, a schedule and what each finding includes. Nothing is saved yet. Everything you type is kept in your browser, so a reload or a refusal does not lose it.
The review screen
The review screen shows the draft, one section per part:
| Section | What you check |
|---|---|
| Name | What the agent is called in your list |
| Instructions | What the agent is told to do. A copy of a library agent shows only Your instructions |
| Tools | What it can look at, and what it can do |
| Schedule | Only when something happens, Every day, Every week, Every month or Custom (a cron expression) |
| Output | What each finding includes |
| Model | Fast, Balanced or Smart. Fast is cheapest, Smart is most careful |
Click Ask to change and say what you want different, for example “only check receipts from this month”. Muin shows the change before and after, and changes the draft only when you accept it. Undo last change puts it back. Nothing is saved until you turn the agent on or save the draft.
Problems are checked when the review screen opens and shown beside the field they belong to. While any remain, Turn on stays disabled and the page says “Fix the problems marked below to turn it on.”
Tools
Tools come from the same catalog Ask Muin uses, filtered to the ones you are allowed to use. The picker has two groups:
| Group | What it means |
|---|---|
| What it can look at | Read tools. For each one choose Agent decides when or Don’t use |
| What it can do (asks you first) | Changes to your records. Each one is marked Always asks you first |
A tool you cannot use yourself is listed under Not available to you and cannot be added. The agent can only see what the person who turned it on can see. Every change it proposes waits for approval, see Approving Agent Changes.
Try it on the last 30 days
Try it runs the draft on your real records from the last 30 days and shows what it would have found. A change it would have made shows as “Would ask you first” with a preview. Nothing is saved and nothing changes: every record the replay touched is rolled back. An agent that reacts to events is replayed on up to 20 of the most recent matching events.
A replay is charged as building and testing credits. See AI Credits.
Practice checks
Practice checks are ten made-up cases the agent should get right before it runs for real: four everyday ones, three unusual ones and three it should refuse, such as deleting a record. Click Write practice checks. Each check says what happens and what a correct answer says. Edit a check, Leave out one, or Add a check of your own. Write new checks replaces them with ten new ones.
Run practice checks runs every included check on the agent you are building. Nothing is saved or changed: each run is rolled back. Each check shows Passed or Failed with the reason, and a tool problem when the agent used a tool you did not give it. Up to 20 checks run at once. Practice checks are charged as building and testing credits.
When two or more checks failed, Turn on asks “Turn on anyway?” first. Keep working on it takes you back to the review screen. Turn on anyway saves the agent, and your answer is recorded with it. The checks move with the agent: they become a set of checks on its Evaluate tab. See Evaluate an Agent.
Try the cheaper model
After a run on Balanced or Smart, Try the cheaper model runs the same checks on Fast. When Fast passes every check your model passed, it says “Fast passes every check.” and offers Switch to Fast, with how much less AI it used on those checks. Otherwise it says how many checks Fast missed, and you keep the model you have. The agent’s price per run does not change with the model.
What it costs
What it costs shows the credits per run and about how many credits a month the agent will use on its schedule, as a share of what you have left this month. After a test run the estimate says “Based on your test runs”. From here you can Set a monthly limit or Add credits.
Turn it on
Turn on saves the agent and opens its setup: “Saved. Choose its settings, then turn it on.” Save draft keeps it under Agents → My agents → Drafts without turning it on. A draft is not an agent yet: it never runs and is not counted as one of your agents.
Drafts
If you leave the builder or the seven-step wizard with something typed, Muin asks Keep this agent as a draft? Keep draft saves everything you typed. Discard throws it away, and Keep editing stays where you are.
Your drafts are listed under Agents → My agents, in Drafts. Continue opens a draft in the builder you left it in, on the same step, with every field as you left it. Delete asks first and then removes the draft. Only you see your drafts; an owner or admin can open one if you share its link.
When you turn the agent on, its draft is removed.
Building costs credits
Drafting, Ask to change, the problem check, test runs and replays are AI calls. They are labelled Building and testing on Settings → Billing → Usage.
Each month your plan includes building and testing credits, shown as “(included)”: 100 on the Free trial and Starter, 500 on Growth, Scale and Enterprise. After those, building and testing uses your monthly AI credits like any other AI work.
When both are used up, the builder shows a card to add credits. Your draft is kept under My agents → Drafts, and the step you were on runs again once the credits are added.
Advanced: the seven-step wizard
Advanced on the builder opens the full wizard, and Edit on an agent you built opens it too. The wizard keeps everything in the browser until you save, so you can move back and forth freely.
| Step | What you do |
|---|---|
| Choose Goal | Pick Review & Analyze, Score & Rate, Classify & Categorize or Extract & Summarize |
| Pick Module | Pick the Module and Document Type, and give the agent its Agent Name and Short Description |
| Describe | Say in plain English what the agent should do |
| Settings | Define the values each copy of this agent can be tuned with |
| Edit Prompt | Generate the prompt, then read it and adjust |
| Test | Run it against a sample document |
| Set up and turn on | Choose this copy’s settings, alerts and schedule, then turn it on |
Settings: what each copy can be tuned with
Settings are the difference between one agent and a reusable one. Each setting you define becomes a field somebody fills in when they set this agent up, so Finance and HR can run the same agent at different thresholds.
For each setting you give a Label, Help text, a Setting key, and where it applies a Lowest allowed, Highest allowed, Unit, Default value and Group. Marking one required means the agent will not run until somebody chooses a value for it.
The kinds available are Number, Yes or no, Choose one, Choose several, Short text, Date, Month and day and US state.
A setting key is lowercase letters, numbers and underscores, starting with a letter. For example
invoice_threshold.
Prompt
Click Generate Prompt and the assistant drafts a system prompt and a user prompt template from your description. Regenerate asks again; Replace this prompt? confirms before overwriting something you have edited.
Insert setting drops a {{settings.<key>}} reference into the prompt, which is how a setting
reaches the agent at run time. Referencing a key you have not defined is refused with a message
naming the key, so the two cannot drift apart.
If the assistant is unavailable you still get a plain starting point, and the page says plainly that it is a starting point and not the assistant’s work.
Templates can also use document_text, document_type, document_filename and
extracted_data.
Guardrails
Saving is refused, with the reason, when:
- The prompt contains a prompt-injection pattern. The error names the pattern it found.
- The prompt references a variable or tool that does not exist.
- A prompt is longer than 10,000 characters.
- A
{{settings.<key>}}reference has no matching setting.
Every custom agent runs at temperature 0, so the same input gives the same answer instead of a differently worded one each time.
Test, then turn on
Test Against Sample Document runs the real agent against a document you pick. Save the agent first. The page tells you so if you have not.
The last step is the agent’s own setup: it stays off while you work through it (“This agent is turned off while you set it up. Choose its settings, then turn it on.”), and Turn on stays disabled until every required setting has a value.
Editing one you already built
Open Sidebar → Agents → My agents → Custom, then the agent. Its page has six tabs:
| Tab | What it holds |
|---|---|
| Overview | Goal, system prompt, user prompt template, and how each running copy is doing |
| Configuration | Module, document types, tools, output format |
| Settings | The settings schema this agent exposes |
| Runs | What this agent has done |
| Evaluate | Checks built from its past runs, and comparisons of a change against how it works today |
| Versions | Every published prompt version, with Roll back |
Edit reopens the wizard. Saving publishes a new prompt version and keeps the old one, so Versions lets you Roll back if a change made the answers worse. To find out before you save, click Compare before publishing in the header: it tries a new prompt on the agent’s past runs. See Evaluate an agent before you change it.
The header also lets you duplicate the agent, turn it on or off, and delete it. Deleting confirms first.
What it affects
- A custom agent appears in your agent library beside the built-in ones, and anyone with permission can set up their own copy of it.
- Each copy keeps its own settings, alerts and schedule. Changing the definition changes what every copy does; changing a copy’s settings changes only that copy.
- Findings an agent raises become inbox tasks, visible in Tasks.
- A test run or a replay uses the same AI as a real run, and nothing it does is saved.
- Building and testing uses credits. See AI Credits.
When it goes wrong
| What you see | Why | What to do |
|---|---|---|
| “Fix the problems marked below to turn it on.” | The problem check found something in the draft | Fix each field it marks, or use Ask to change |
| “We could not find what this agent was meant to start from.” | The library agent or chat message it started from is gone | Click Start over and describe it in a sentence |
| “Saved, but not everything was set” | The agent saved, but some parts need you | Set the items it names on the agent’s page |
| A card to add credits in the builder | This month’s AI credits and included building credits are used up | Add credits. The draft is kept and the step runs again |
| “Nothing to check in the last 30 days.” | There were no matching records to replay on | Turn it on anyway, or try again once records exist |
| “This prompt uses {{settings.X}}, but there is no setting with that key.” | The prompt and the settings disagree | Add the setting on the Settings step, or remove the reference |
| “Please generate or write a system prompt” | The prompt step is empty | Click Generate Prompt, or write one |
| “Failed to create agent” / “Failed to update agent” | The save was refused | Read the message. It names the guardrail that stopped it, usually an unknown tool or variable, or a prompt-injection pattern |
| “Save the agent first to test it” | Testing needs a saved agent | Finish the earlier steps and save, then test |
| “Choose every required setting above before turning this agent on.” | A required setting has no value | Fill it in; Turn on then enables |
| “Agent not found” | The agent was deleted, or belongs to another organization | Click Back to Agents |
| No Agents section in your sidebar | Your role has no agent access | Ask an owner to build it, or to change your role |
Next step
- Turning On an Agent and Reading Its Runs: the Overview tab, limits, rules and feedback.
- AI Credits: what building and running agents costs.
- AI Agents Overview: the library you are adding to.
- Building Workflows: when the job is a fixed sequence of steps rather than a judgement.