Цю сторінку ще не перекладено.

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:

support-agent.md
---
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:

Markdown
::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:

Markdown
::param{name=limit type=integer default=200}
instruction deliver
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:

Delivered
### 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;
  • verbatim bodies and examples.

The sample above, delivered with two values:

Shell
instruction deliver support-agent.md environment=production regions=EU,UK
Output
# 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.
Shell
instruction deliver support-agent.md environment=production "team=R&D *core*"
Output
# 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.

Shell
instruction deliver support-agent.md
stderr (exit code 1)
line 1: ${environment} is required and has no value  [parameter-missing]
Shell
instruction deliver support-agent.md environment=prod max_refund=lots
stderr (exit code 1)
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 extends gets only the values in its record's with mapping: { uri: ./base.md, as: base, with: { team: Billing } }.
  • An included document gets no values, so its parameters take their defaults. ::include has no with attribute.

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

Shell
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.

Shell
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:

tools/call
{
  "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:

tools/call
{
  "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:

HTML
<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:

tools/call
{
  "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:

tools/call
{
  "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.

Last checked against the product:

Was this page helpful? Report a problem