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

What an agent receives

This page is for developers who build a host or an agent that reads instructions, or who need to know exactly what a model is given. It describes the agent's text (instruction-text/1) line by line, the resolved artifact (instruction-resolved/1) and its digest, every way to get them, and how they relate to the signed source.

An author writes a source: front matter, Markdown, rules and blocks, comments, backmatter. An agent never receives the source. A resolver reads it, composes what it extends and includes, puts in the parameters' values, and writes the agent's text. Every reader of the specification writes the same text for the same source.

From the source an author writes to the text an agent receives.

The two forms

  • The agent's text, instruction-text/1: plain Markdown, the only thing a model is meant to read.
  • The resolved artifact, instruction-resolved/1: JSON. The composed tree with every node's origin, the sources it read, the diagnostics, a status and a digest. A host keeps it to show what was delivered and why.

The resolver makes both at once. A version's requires and its signatures are covered under Served text and signed bytes.

The agent's text, line by line

This source has a front matter, a comment, a parameter, a typed reference, a declared person, a named rule with a condition and a reason, an example, and a backmatter:

calendar-helper.md
---
spec: "1"
title: Calendar helper
parameters:
  timezone: { type: string, default: Europe/Berlin }
---

<!-- Reviewers: keep this under one page. -->

# Calendar helper

Plan the day in ${timezone}. Ask :person[Alex]{ref=#owner} before you change an invitation.

::person{id=owner title="Alex" role=owner}

MUST[status] (if an event is tentative): keep it tentative.
BECAUSE: the organizer hasn't decided yet.

:::example{title="A good brief"}
Three meetings, one focus block at 10:00.
:::

---
authors: [Alex]
review: { by: Sam }

The agent receives:

instruction-text/1
# Calendar helper

Plan the day in Europe/Berlin. Ask Alex (person; #owner) before you change an invitation.

### person: Alex

Attributes: {"role":"owner"}

MUST (if an event is tentative): keep it tentative.
BECAUSE: the organizer hasn't decided yet.

### Example: A good brief

```markdown
Three meetings, one focus block at 10:00.
```

What happened to each part:

In the source In the agent's text
Front matter (--- … --- at the top) Left out.
Backmatter (from the last --- line to the end) Left out.
Comments (<!-- … -->) Left out.
Markdown prose Copied as written.
A parameter, ${name} Its value: the one supplied, else its declared default. Markdown punctuation in a value is escaped, so a value inserts data, never syntax. A list reads as its items joined with , . Without a value, it stays as written.
A typed inline reference, :person[Alex]{ref=#owner} label (kind; target): Alex (person; #owner). A #id the document doesn't have adds [unresolved]. :ref[…] and :cite[…] read the same way.
Any other inline form, such as :kbd[Enter] Its label.
A rule LABEL: body. The label is MUST (for MUST and ALWAYS), NEVER (for NEVER and MUST NOT), SHOULD, SHOULD NOT (for SHOULD NOT and AVOID), MAY or GUARDRAIL. A condition follows the label: MUST (if …):.
A rule's reason BECAUSE: … on the next line.
A rule's id, MUST[status] Left out. Any other attribute of a rule follows as an attribute line.
A block A generated heading, ### Label: Title, then its attribute line, then its body.
An example ### Example: Title (Counterexample with avoid), its body in a fenced markdown block.
An allowance Its heading, one fixed sentence, then its body. See The delivered sentence.

A block's heading label is Policy, Instruction or Context for those kinds, Example or Counterexample for an example, and the kind's own name otherwise (### mcp: Calendar). Its title is its title, else its id, else the kind's name.

The attribute line is Attributes: and the attributes as canonical JSON (RFC 8785: sorted keys, no spaces). id, title, class and style are left out, and so are the presentation attributes of a layout block (tabs, steps, columns and the like). With nothing left, there is no line.

A body in YAML, JSON or another structured format is written as a fenced block in its format. The body of a verbatim block, of an example and of a kind the specification doesn't define is copied as written. Everything else in a body is written by the same rules, nested.

Every generated part (a rule with its reason, a heading with its attribute line and body, a run of Markdown) is separated from the next by exactly one blank line, and the text ends with exactly one line feed.

With the parameter timezone set to America/Toronto, only the value changes:

instruction-text/1, timezone=America/Toronto
# Calendar helper

Plan the day in America/Toronto. Ask Alex (person; #owner) before you change an invitation.

### person: Alex

Attributes: {"role":"owner"}

MUST (if an event is tentative): keep it tentative.
BECAUSE: the organizer hasn't decided yet.

### Example: A good brief

```markdown
Three meetings, one focus block at 10:00.
```

After the body, a resolved text can have two more sections. ### Resolved references holds the records a resolver enriched references with, each a fenced JSON block, sorted by key. ### Composition changes lists each replace, extend and remove that changed an inherited document, with its origin and reason. The reference resolver binds no resolver adapter, so instruction.md writes no resolved references.

A conformance vector

The specification's conformance vectors (packages/spec/specification/conformance/text/) pin the text exactly. Each is an authored tree and the text every reader must write for it. This one is a rule with a condition and a reason:

reason.json
{
  "format": "instruction/1",
  "body": [
    {
      "type": "directive",
      "kind": "must",
      "form": "container",
      "attrs": {
        "if": "an event is tentative",
        "because": "Status matters."
      },
      "children": [
        {
          "type": "markdown",
          "source": "retain its status."
        }
      ]
    }
  ]
}
reason.txt
MUST (if an event is tentative): retain its status.
BECAUSE: Status matters.

Written by an author, the same rule is:

instruction.md
MUST (if an event is tentative): retain its status.
BECAUSE: Status matters.

This page is built with the reference resolver, and the build fails if it no longer writes reason.txt for either. instruction test <dir> runs the vectors against the CLI's reader.

Complete and partial

A delivery's status is complete or partial:

  • partial: something optional could not be read or bound. An optional include or base (no required), a parameter left as written because it has no value or isn't declared (parameter-optional), or an optional extension. Each is a warning, and the rest is delivered.
  • An error stops the delivery: a required include that can't be read (reference-missing), a required parameter without a value (parameter-missing), a composition cycle, a document deeper than 8 levels or reading more than 64 sources (limit-exceeded), or any other error.

An include that can't be read:

instruction.md
---
spec: "1"
title: Calendar helper
---

Plan the day.

::include{src="instruction://acme/house-style" as=style}

stays in the text as its own block, and the delivery is partial:

instruction-text/1, partial
Plan the day.

### include: include

Attributes: {"as":"style","src":"instruction://acme/house-style"}
Diagnostics
warning: reference-optional: the include "style": instruction://acme/house-style could not be read

With required on the include, the same is an error, and nothing is delivered:

Diagnostics
error: reference-missing: the include "style": instruction://acme/house-style could not be read

When the include can be read, its text takes the block's place:

instruction-text/1, complete
Plan the day.

SHOULD: write in short sentences.

instruction.md reads what a delivery composes only from instruction:// addresses of instructions the reader may read, at the ref or version named (@stable, @v3), else the latest. It fetches nothing else, a web address or a file: those stay unresolved. One the reader may not read is unresolved too, and the answer says no more than that. Each source read is recorded, as any read is. See Composition.

The resolved artifact

instruction deliver <file> --resolved prints it. For the source above (its body cut short here):

instruction-resolved/1
{
  "format": "instruction-resolved/1",
  "status": "complete",
  "document": {
    "uri": "instruction://acme/calendar-helper",
    "sha256": "sha256:171da38f6f7c2dcb32e31166bd0eb70b9c5a3383d9ee770e6ba84fe5947058fc"
  },
  "body": [
    {
      "type": "markdown",
      "source": "\n\n# Calendar helper\n\nPlan the day in Europe/Berlin. Ask :person[Alex]{ref=#owner} before you change an invitation.\n\n",
      "range": {
        "start": 7,
        "end": 13
      },
      "instance": "root"
    },
    "… 3 more nodes"
  ],
  "extensions": [],
  "objects": [],
  "resources": [],
  "dependencies": [],
  "provenance": [],
  "diagnostics": [],
  "resolved_digest": "sha256:690a134cf6b591e8116af2316faf1a24efbff7ebb200202228c188488c76d79a"
}
Field What it holds
format instruction-resolved/1.
status complete or partial.
document The document's uri, the sha256 of its source bytes, and its version when the host knows it.
body The composed tree. Every node carries instance: root for the document's own, root/<alias> for an included or inherited document, nested the same way. Parameters already have their values.
extensions The extensions bound. Empty in instruction.md: no extension manifest is retrieved.
objects, resources The records a resolver enriched references with. Empty in instruction.md.
dependencies Each source it read: uri, resolved_uri, sha256, mode (live or pinned), version, selector and instance.
provenance Where each composed part came from: its instance, uri, operation (include, inherit, replace, extend or remove), target and reason.
diagnostics Everything the resolver reported, sorted by source, line and code.
resolved_digest sha256: and the hex SHA-256 of all the fields above in canonical JSON (RFC 8785).

The included document of the previous section is one dependency:

dependencies
[
  {
    "uri": "instruction://acme/house-style",
    "resolved_uri": "instruction://acme/house-style",
    "sha256": "sha256:c8e064578acde4b2a5dfe66d299b674a4fbf06c71640d4b57c49586874f28338",
    "mode": "live",
    "version": "ver_01JX0000000000000000000000",
    "instance": "root/style"
  }
]

Two resolutions of the same sources with the same parameters have the same resolved_digest, so a host can tell whether anything an agent was given changed.

The three digests

Digest Of what Where you see it
The authored digest The source's bytes, exactly as released. A version's digest; md.instruction/digest in a resource's _meta; instruction digest <file>.
The delivered digest The agent's text. deliveredDigest in instructions_versions_read with resolve; the digest the follow prompt names; deliveredDigest in what instruction watch reports.
resolved_digest The resolved artifact, without its own digest. The artifact; the manifest that instructions_versions_read returns; resolvedDigest in spec_deliver.

All three are sha256: and 64 lowercase hex digits.

Where to get it

Where What you get
The resource instruction://owner/name (or @stable, @v3, by id) The source as served, with its _meta. Not the agent's text.
instructions_versions_read The source as served; with resolve: true and params, the agent's text.
The prompt follow The agent's text, as the conversation's instructions, at the instruction's default ref or the one its address names.
spec_deliver The agent's text for any text you send, with no other source read.
instruction deliver <file> The agent's text for a file, its bases and includes read from files beside it.
instruction pull <uri> --delivered A released version's agent text, what it composes read from the server.
instruction watch --out FILE Each new version's agent text, written into a file an agent reads.
instruction mcp --follow <uri> The followed instruction's agent text as the resource instruction://current and the prompt follow, on a stdio server.
<instruction-md view="delivered"> The renderer's delivered view, in a web page.
The editor The status bar counts the words to the agent, from the same text; the assistant's preview reads it too.

From the MCP server

instructions_versions_read takes versionId (a version id, v3, or a ref; default latest), resolve and params:

instructions_versions_read arguments
{
  "instructionId": "acme/calendar-helper",
  "versionId": "stable",
  "resolve": true,
  "params": { "timezone": "America/Toronto" }
}
The answer
{
  "instructionId": "ins_01JX0000000000000000000000",
  "versionId": "ver_01JX0000000000000000000000",
  "number": 3,
  "digest": "sha256:…",
  "delivered": true,
  "content": "# Calendar helper\n\nPlan the day in America/Toronto. …",
  "deliveredDigest": "sha256:…",
  "status": "complete",
  "manifest": {
    "format": "instruction-resolved/1",
    "status": "complete",
    "document": { "uri": "instruction://acme/calendar-helper", "sha256": "sha256:…", "version": "ver_01JX0000000000000000000000" },
    "dependencies": [],
    "resolved_digest": "sha256:…"
  },
  "deliverySignature": "eyJ…"
}

content is the agent's text. digest is the released source's, deliveredDigest the text's, and manifest is the resolved artifact's identity: its format, status, document, dependencies and resolved_digest, without its body, provenance or diagnostics. deliverySignature is a JWS over the delivered digest and the manifest, issued for you (its audience), when the version has an author signature. A delivery with errors is refused with validation, the first three messages in the error and up to 50 diagnostics in details.diagnostics. Warnings come back in diagnostics. A sealed instruction is never resolved here: without resolve you get its envelope (sealed: true, mediaType application/vnd.instruction-md.sealed+json), and with resolve the call is refused with forbidden, because the server can't read it. Resolve it where it is unlocked: the editor, instruction-mcp or the CLI. See Tools and Sealed instructions for developers.

spec_deliver takes content and params, reads no other source, and stores nothing. What the text composes stays unresolved, so a text with includes is partial:

spec_deliver arguments
{
  "content": "---\nspec: \"1\"\ntitle: Calendar helper\n---\n\nPlan the day.\n\n::include{src=\"instruction://acme/house-style\" as=style}\n",
  "params": {}
}
The answer
{
  "content": "Plan the day.\n\n### include: include\n\nAttributes: {\"as\":\"style\",\"src\":\"instruction://acme/house-style\"}\n",
  "ok": true,
  "status": "partial",
  "diagnostics": [
    {
      "code": "reference-optional",
      "severity": "warning",
      "message": "the include \"style\": instruction://acme/house-style could not be read",
      "line": 8
    }
  ],
  "resolvedDigest": "sha256:4c66c01de15467d6f4973225f0800fbbba7b68abd7b62a0c94792b3fe4bbfbce",
  "dependencies": []
}

ok is false when an error stops the delivery. instruction mcp serves spec_deliver too, on your machine, with the same answers.

From the CLI

Shell
# a file, its bases and includes read from files beside it
instruction deliver calendar-helper.md timezone=America/Toronto

# the resolved artifact instead
instruction deliver calendar-helper.md --resolved

# a released version, what it composes read from the registry
instruction pull instruction://acme/calendar-helper@stable --delivered

# the renderer's delivered view, as HTML
instruction render calendar-helper.md --view delivered

instruction deliver reads what a file composes only from files under its own folder, prints warnings to standard error, and exits 1 on an error. pull --delivered and watch read what the text composes from the server. If resolving it fails, they write the source instead. See CLI commands.

In a web page

HTML
<instruction-md ref="instruction://acme/calendar-helper@stable" view="delivered" views="delivered,source" params='{"timezone":"America/Toronto"}'></instruction-md>

view is the view it opens in (rendered, delivered or source), and params gives parameter values as JSON. The delivered view resolves in the browser and reads no include or base, so a text that composes others shows as partial there. See Embed.

Served text and signed bytes

Three texts are in play for one version:

  • The released bytes. The source exactly as published, never changed afterwards. The authored digest and the author signature cover them.
  • The served text. The released bytes with the organization's integrations policy added at the top of the front matter, as host-integrations lines. This is what a resource, instructions_versions_read without resolve, a read link and the page's Markdown return. A sealed instruction is served as its envelope, with nothing added. The lines are outside the signed bytes; a verifier takes them out again before it checks the author signature. See The integrations policy.
  • The agent's text. Resolved from the released bytes, not from the served text, so it carries no front matter and no policy. A delivery signature covers it.

A host that requires signatures checks the author signature over the source, and the delivery signature over the text it hands the model. See Signing and verification.

Capability families

A document requires the capability families of the kinds it uses. spec_validate and instructions_validate return them as requires. A released version keeps them: md.instruction/requires in a resource's _meta, and the capabilities claim of its author signature, which a delivery signature repeats and never widens. A host can refuse a document that requires what it doesn't support, or grant only those. The source above requires ["advisory","connected","guidance"].

The families, from the specification's registry:

FamilyKinds
advisorycaution, example, important, info, note, tip, warning
authorityallowance
compositionembed, extend, include, remove, replace
connectedagent, mcp, person, role, service, skill, source, tool, wallet
contractform, glossary, output, param
guidancealways, avoid, context, guardrail, instruction, may, must, never, policy, should
layoutaside, card, column, columns, details, grid, section, step, steps, tab, tabs
presentationcomponent
resourceaudio, diagram, drawing, figure, image, pdf, resource, video
technicalconfig, data, eval, properties, sandbox, schedule, script, test, workflow

Two more are added by name:

  • agents: an agent with no protocol, src or endpoint, one the host runs itself. See Agents the host runs.
  • spending: an allowance. A host applies it only where its operator grants spending. See Allowances and wallets.

If it doesn't work

What you see Why What to do
validation: "1 error(s) stop its delivery: …" The version has an error once composed, such as a required include you may not read. Read details.diagnostics. Give the reader access to the include, or make it optional.
status: "partial" An optional include, base or extension couldn't be read, or a parameter has no value. Read the warnings in diagnostics. Declare the parameter, or check the include's address.
${name} in the agent's text The parameter has no value and no default. Pass it in params, or give it a default in the front matter.
… [unresolved] after a reference The #id it names isn't in the document. Declare the object, or fix the ref.
A rule's id isn't in the text Ids are left out of the agent's text. Nothing to fix: refer to a rule by its words, or read the id from the resolved artifact.
A blocked tool still appears in the text The agent's text is resolved from the released bytes and carries no policy. Enforce the policy from the served text or md.instruction/policy.

Still stuck: ask us.

Questions

Which parts of my instruction does the agent not receive?

The front matter, the backmatter and comments are never delivered. A rule's id and a block's id, title, class and style are not in its attribute line, although the title is in its heading. Everything else is, layout blocks included. See The agent's text, line by line.

Is the agent's text the same in every reader?

Yes. The text profile fixes every line, and the specification's conformance vectors pin it exactly. instruction.md's server, its CLI and the Go, Python and Rust libraries write the same text for the same source and parameters.

Why doesn't the resource give me the agent's text?

A resource gives the source as served, so a reader can verify the author signature and read the policy. Ask instructions_versions_read with resolve: true, or use the prompt follow, for the agent's text.

Does the agent's text include the organization's integrations policy?

No. It is resolved from the released bytes and carries no front matter. The policy is in the served text and in md.instruction/policy.

Last checked against the product:

Was this page helpful? Report a problem