Parameters
This page is for developers who write instructions that take values, and for anyone who delivers them. It covers how a parameter is declared, which types it can have, where a value is inserted, what happens when a value is missing or wrong, and every way to supply values: the CLI, the MCP server, the renderer and deployments.
A parameter is a named value, written ${name} in the text. It is filled in when the instruction is delivered, as data: a value never becomes Markdown or instruction syntax.
Declare a parameter
Declare parameters in the front matter's parameters mapping, one key per parameter:
---
spec: "1"
title: Support agent
parameters:
environment:
type: enum
values: [staging, production]
required: true
source: workspace
description: Where the agent works.
team: { type: string, default: Support, example: Billing }
escalate_after: { type: duration, default: 30m }
regions: { type: list, default: [EU, US] }
max_refund: { type: integer, default: 200 }
---
# ${team} support agent
You answer customers of the ${team} team in ${environment}, for ${regions}.
MUST (if the refund is over ${max_refund} EUR): ask a person before you refund.
BECAUSE: refunds over ${max_refund} EUR need a second pair of eyes.
MUST: escalate a ticket that stays open longer than ${escalate_after}.
Write `${team}` in code as it is, and link [the guide](https://example.org/${team}) as it is. Or declare one in the body, with a visible param leaf. The leaf takes the same keys as attributes, and name is required:
::param{name=tone type=enum values="calm,brief" default=calm required title="Tone" description="How the agent writes."}
Write in a ${tone} tone. Each declaration takes these keys:
| Key | Value | Default | Effect |
|---|---|---|---|
type |
One of the types below | string |
What a value must be |
values |
A list of strings; in a leaf, a comma-separated string | The allowed values. Required, and nonempty, for enum |
|
required |
true or false |
false |
Without a value and without a default, delivery stops with parameter-missing |
default |
A value of the declared type | Used when no value is given | |
example |
Any value | Preview data only: the renderer's inputs show it. Delivery never uses it | |
description |
A string | What the value is for. The renderer's input for the parameter shows it as its label | |
source |
input, workspace, identity or static |
input |
Where the value is meant to come from. The resolver records it and doesn't enforce it: every value comes from what the caller passes |
A name matches [A-Za-z_][A-Za-z0-9_.-]*, the same in a declaration and in ${name}. Each name is declared once in a document: the front matter and the leaves share one set of names.
A leaf's values are text
Attribute values in a leaf are text, so a leaf's default only fits the text types: string, enum, url and duration. Give a number, integer, boolean or list parameter its default in the front matter:
::param{name=limit type=integer default=200} line 1: the default of "limit" is not a valid integer [parameter-invalid] A leaf stays in what the agent receives, as a description of the input. Delivered without a value, the leaf sample above reads:
### param: Tone
Attributes: {"default":"calm","description":"How the agent writes.","name":"tone","required":true,"type":"enum","values":["calm","brief"]}
Write in a calm tone. Types
| Type | A valid value | From name=value text |
|---|---|---|
string |
Any string | The text |
number |
A finite number | Number(text), when the text reads as one |
integer |
A whole number | Number(text), when the text reads as one |
boolean |
true or false |
true or false; any other text is refused |
enum |
One of values, exactly |
The text |
list |
An array of strings | Split on commas, each item trimmed; empty text is an empty list |
url |
An absolute http:// or https:// address without spaces |
The text |
duration |
A whole number and a unit: ms, s, m, h, d or w (30m, 2h) |
The text |
A default must be a valid value of its type, or the document has a parameter-invalid error. "From name=value text" is how the CLI and the renderer read a value given as text. JSON values over MCP are taken as they are, so send an integer as 150, not "150".
Where a value is inserted
A value replaces ${name} in parsed prose: paragraphs, headings, list items, quotes and table cells. It also goes into a rule's condition and reason, and into an allowance's max, budget, approve-above, times, from, until, currency and per attributes.
${name} stays as written in:
- code spans and code fences;
- math;
- link destinations and other URLs;
- every other attribute;
- HTML blocks and HTML tags, their attribute values included (text between two inline tags is prose, and gets the value);
- YAML and JSON bodies;
- comments, front matter and back matter;
verbatimbodies and examples.
The sample above, delivered with two values:
instruction deliver support-agent.md environment=production regions=EU,UK # Support support agent
You answer customers of the Support team in production, for EU, UK.
MUST (if the refund is over 200 EUR): ask a person before you refund.
BECAUSE: refunds over 200 EUR need a second pair of eyes.
MUST: escalate a ticket that stays open longer than 30m.
Write `${team}` in code as it is, and link [the guide](https://example.org/${team}) as it is. The values went into the heading, the prose, the rule's condition and its reason. team, escalate_after and max_refund took their defaults. The code span and the link stayed as written.
How a value reads
- A string is inserted as it is, with the punctuation that could open Markdown or instruction syntax escaped with a backslash:
\ ` * _ { } [ ] < > | ~ $. - A number or a boolean is written as JSON writes it:
150,2.5,true. - A list is its items, each escaped, joined with a comma and a space:
EU, UK.
instruction deliver support-agent.md environment=production "team=R&D *core*" # R&D \*core\* support agent
You answer customers of the R&D \*core\* team in production, for EU, US. Insertion happens once. The text a value inserts is never read again for parameters, references or rules.
Missing and wrong values
| Situation | Result | Diagnostic |
|---|---|---|
| A valid value is given | The value is inserted | |
| A value is given that doesn't fit the type | Delivery stops; the token stays ${name} |
parameter-invalid (error) |
| No value, and a default | The default is inserted | |
No value, no default, and required: true |
Delivery stops | parameter-missing (error) |
| No value, no default, not required, and the parameter is used | ${name} stays; the result is partial |
parameter-optional (warning) |
${name} names no declared parameter |
${name} stays; the result is partial |
parameter-optional (warning) |
| A value is given for a name the document doesn't declare | The value is ignored |
An invalid value is an error even when there is a default: a default never stands in for a wrong value. A partial result is still delivered, with status: "partial". An error stops delivery. The whole list of codes is on Diagnostics and fixes.
instruction deliver support-agent.md line 1: ${environment} is required and has no value [parameter-missing] instruction deliver support-agent.md environment=prod max_refund=lots line 1: the value given for ${environment} is not a valid enum (staging, production) [parameter-invalid]
line 1: the value given for ${max_refund} is not a valid integer [parameter-invalid] A front-matter declaration's diagnostics point at the front matter's first line. A leaf's point at the leaf.
Parameters in bases and includes
Each document has its own declarations and its own values. Values never pass from one document to another on their own:
- A base named in
extendsgets only the values in its record'swithmapping:{ uri: ./base.md, as: base, with: { team: Billing } }. - An included document gets no values, so its parameters take their defaults.
::includehas nowithattribute.
See Includes, inheritance and extensions.
Supply values
| Where | How |
|---|---|
instruction deliver <file> [name=value ...] |
Values as arguments, read as each declared type reads text |
instruction render <file> [name=value ...] |
The same, for the delivered view of the HTML |
spec_deliver (MCP) |
params, a JSON object, for a text you send |
instructions_versions_read (MCP) |
params, a JSON object, with resolve: true, for a released version |
The <instruction-md> element |
The params attribute (JSON) for the delivered view; inputs to try values |
| A deployment or a deployment rule | parameters, stored with it and handed to the runner |
The CLI
instruction deliver support-agent.md environment=production regions=EU,UK instruction deliver reads bases and includes from files beside the document. With --resolved it prints the resolved artifact (instruction-resolved/1) as JSON instead of the text. An argument that isn't name=value stops it with not a name=value: <argument>. Warnings go to stderr, and the text to stdout. See The instruction CLI.
instruction render support-agent.md --view delivered environment=production regions=EU,UK Over MCP
spec_deliver delivers a text you send. Nothing else is loaded, so a base or an include it names stays unresolved:
{
"name": "spec_deliver",
"arguments": {
"content": "<the instruction's text>",
"params": {
"environment": "production",
"regions": [
"EU",
"UK"
]
}
}
} It returns content (the agent's text), ok, status, diagnostics, resolvedDigest and dependencies.
instructions_versions_read with resolve: true delivers a released version, with its bases and includes read from instructions you may read:
{
"name": "instructions_versions_read",
"arguments": {
"instructionId": "acme/support-agent",
"versionId": "latest",
"resolve": true,
"params": {
"environment": "production",
"max_refund": 150
}
}
} When an error stops delivery, it answers validation with N error(s) stop its delivery: … and the errors in details.diagnostics. Otherwise it returns the text as content, with status, deliveredDigest, manifest, any diagnostics and deliverySignature (null when the version has no author signature). See What an agent receives.
The renderer
The params attribute gives the delivered view its values, as JSON. A string value is read as its declared type reads text, so "EU,UK" is a list. inputs draws an input for each parameter above the document. A value tried there is drawn where the parameter is used and goes into the delivered view. The text stays as written:
<script src="https://instruction.md/render@1.classic.js" defer></script>
<instruction-md src="/agents/support-agent.md" view="delivered"
params='{"environment": "production", "regions": "EU,UK"}' inputs></instruction-md> The element sends an imd-params event with each change. With save-inputs, a Save button sends imd-params-save with the values, for a host that writes them back as defaults. See Embed and preview.
Deployments
Plans On Pro, Team, and Enterprise
A deployment stores values for the agent it runs, an object of at most 16 KB. Deploying an instruction needs the Admin role on it (the manage permission). Sent again for the same instruction and platform, deployments_create replaces the stored parameters with the ones you send:
{
"name": "deployments_create",
"arguments": {
"instructionId": "acme/support-agent",
"platform": "agentd-prod",
"parameters": {
"environment": "production"
}
}
} Plans On Team and Enterprise
A deployment rule's parameters control, also at most 16 KB, holds values for every instruction it selects. An "ins_…" key holds one instruction's own values, which override the common ones for that instruction. Rules are made by the organization's owners and admins. A change of the control reaches every agent of the rule at once:
{
"name": "deployments_rules_create",
"arguments": {
"orgId": "acme",
"name": "Support on agentd",
"platform": "agentd-prod",
"selector": {
"tags": {
"all": [
"support"
]
}
},
"controls": {
"parameters": {
"environment": "production",
"ins_<id>": {
"environment": "staging"
}
}
}
}
} deployments_list returns each deployment's parameters, for the runner that starts its agent.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
${name} is required and has no value [parameter-missing] |
A required parameter got no value and has no default | Pass the value, or give it a default |
the value given for ${name} is not a valid <type> [parameter-invalid] |
The value doesn't fit the type. Over MCP, a number sent as a string doesn't fit integer |
Send a value of the type; for enum, one of values exactly |
the default of "<name>" is not a valid <type> [parameter-invalid] |
The default doesn't fit, often a leaf's text default on a typed parameter | Move the declaration to the front matter |
${name} is not a declared parameter, so it stays as written [parameter-optional] |
A typo, or a parameter declared in another document | Declare it, or fix the name |
the parameter "<name>" is declared twice [parameter-invalid] |
The front matter and a leaf, or two leaves, use one name | Keep one declaration |
${name} stays in the text though a value was given |
It is in code, a URL, an attribute or an example | Move it into prose |
Still stuck: Support.