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

agentd

For developers who run agentd as a daemon and want its policy to be an instruction released on instruction.md: agentd reads the instruction over MCP, verifies its signature when you pin a publisher, and applies each new version as it is released, without a restart.

agentd following an instruction: read, subscribe, verify, apply, report.

What agentd does with an instruction

agentd 1.18 or later speaks MCP 2026-07-28, the only protocol version instruction.md's MCP server accepts, and MCP Events. With the configuration on this page, it:

  • reads instruction://ins_<id>@<ref> from the MCP server at startup, and logs instruction.loaded;
  • subscribes to that resource, and listens for the md.instruction.activity event, so a release or a ref move makes it read again;
  • applies the new version at its apply boundary, logged as instruction.applied with the old and new version ids. The servers, skills and workflows the instruction declares apply as the version arrives, unless agent.instruction.machinery is reload;
  • verifies the author signature when a trust pin names a publisher, and refuses an unsigned or wrongly signed version;
  • creates one binding and reports each version it applies, so it shows on the instruction's Agents card with the version it applied (agentd 1.23.0 or later).

agentd reads the first edition of the language (instruction/1) with the official Rust SDK from 1.21.0. Its own configuration keys are in agentd's configuration reference.

Before you start

Plans On Pro, Team, and Enterprise

  • agentd 1.18 or later, a build with the oauth, mcp-events and sign features. agentd's release binaries carry them. 1.27.0 or later asks for the instruction's own events by its id.
  • A released instruction, and the ref you follow. stable is never made for you: instruction refs <id> set stable v1 creates it. See refs.
  • An agent credential (API key) for the organization: a client id and a secret that agentd exchanges for tokens on its own. Creating one needs an admin. Each plan's number of agent credentials:

Plans Pro 10 · Team 100 · Enterprise unlimited

Create the agent credential

Shell
instruction login --admin
instruction agents create support-desk --org acme --scopes read

--scopes read lets it read and follow, nothing more. instruction agents create is an administrator's command, and instruction login --admin gives the permission it asks for. It prints the secret once:

Output
agent agt_<id> (support-desk) in acme
client_id:     <client id>
client_secret: <secret>   <- shown once; store it now (INSTRUCTION_MD_CLIENT_SECRET)
token_url:     https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
scopes:        instructions:read

next: instruction connect --host agentd --agent <client id> --org acme <uri>

Store the secret in your secret store now. Agents sign in on their own realm, instruction-md-agents, whose token address is the token_url above. The MCP server's metadata names the people's realm, not this one, so agentd needs token_url written in its configuration. Agent credentials covers rotation, revocation and workspace roles.

Find the instruction's id

agentd follows the instruction by its id, not by its name (see Pin by id):

Shell
instruction get acme/support-agent
Output
acme/support-agent  instruction://ins_<id>
title: Support agent
…

instruction connect --host agentd prints the part of agentd's configuration that reaches instruction.md, filled in with the credential's coordinates (never its secret):

Shell
instruction connect --host agentd --agent <client id> --org acme instruction://ins_<id>@stable
Output
# agentd 1.18 or later: merge into its configuration (its intelligence, a2a, store)
agent:
  instruction:
    mcp:
      server: instruction-md
      resource: "instruction://ins_<id>@stable"
      events: [md.instruction.activity]
    unavailable: keep
mcp:
  servers:
    - name: instruction-md
      endpoint: https://instruction.md/mcp
      auth:
        kind: oauth2
        grant: client_credentials
        token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
        client_id: <client id>
        client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"   # the value shown once at creation
        scopes: [instructions:read]
  • agent.instruction.mcp: the resource to read and subscribe to, on the server named instruction-md, and the event that makes agentd read it again.
  • unavailable: keep: when the server stops answering after startup, agentd keeps serving with the version it holds.
  • mcp.servers[].auth: the client-credentials grant. agentd fetches a token with the secret, and a new one before it expires. {{secret:NAME}} reads the environment variable NAME; agentd refuses a secret written in the file.

A whole daemon

The printed block merges into agentd's own configuration: its model, its store and its A2A listener. A complete file, with a signature pin:

support-desk.yaml
# agentd 1.18 or later, as a daemon: the instruction is the policy every conversation follows
agent:
  name: support-desk
  instruction:
    mcp:
      server: instruction-md
      # the instruction's id at a ref: publishing moves the ref, and the server pushes the re-read
      resource: "instruction://ins_01M…@stable"
      events: [md.instruction.activity]
    unavailable: keep
    trust:
      - uri: "instruction://ins_01M…@stable"
        publisher: "https://instruction.md/pub/acme"
intelligence:
  endpoints: https://api.anthropic.com
  dialect: anthropic
  model: claude-sonnet-5
  token: "{{secret:ANTHROPIC_API_KEY}}"
mcp:
  servers:
    - name: instruction-md
      endpoint: https://instruction.md/mcp
      auth:
        kind: oauth2
        grant: client_credentials
        client_id: "<your agent's client id>"
        client_secret: "{{secret:INSTRUCTION_MD_CLIENT_SECRET}}"
        # agents sign in on their own realm
        token_url: https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token
store:
  kind: file
  file: { path: ./support-desk-state }
a2a:
  listen: http://127.0.0.1:8420
lifecycle:
  run_until: drained

Run it with both secrets in the environment:

Shell
export ANTHROPIC_API_KEY=<your model key>
export INSTRUCTION_MD_CLIENT_SECRET=<the agent's secret>
agentd --config support-desk.yaml

A daemon needs something that can give it work, here a2a.listen. With lifecycle.run_until: drained it exits only on a signal.

Pin by id or ref

The resource's address decides what agentd follows:

agent.instruction.mcp.resource
resource: "instruction://ins_<id>@stable"   # follows the stable ref: a ref move is a new version
resource: "instruction://ins_<id>@latest"   # follows every release
resource: "instruction://ins_<id>@v3"       # one version, never another

Use the id form, instruction://ins_<id>@<ref>, for two reasons:

  • Its subscription is notified. The name form instruction://acme/support-agent@stable can be read, and a subscription to it is accepted, but it is never notified: the server's notices name the id form only (Subscriptions). agentd would then hear of a release only through the event, or at its next re-read.
  • It is what a signature names. An author signature names the instruction by its id address, and agentd compares a trust pin's uri with it as written. A pin on the name form refuses every read.

The trust entry names the same id address as the resource, and the publisher whose signature a version must carry, https://instruction.md/pub/<organization>:

support-desk.yaml (part)
agent:
  instruction:
    mcp:
      server: instruction-md
      resource: "instruction://ins_<id>@stable"
      events: [md.instruction.activity]
    unavailable: keep
    trust:
      - uri: "instruction://ins_<id>@stable"      # the same address as resource, in the id form
        publisher: "https://instruction.md/pub/acme"

With a publisher pinned, an unsigned version is refused, and so is one signed by another publisher. Every version released on instruction.md is signed with the organization's platform key. Signing and verification explains the keys.

Check it worked

  • agentd's log shows instruction.loaded at startup, then instruction.applied after each release that moves the ref you follow.
  • With agentd 1.23.0 or later, instruction.binding.reported follows each instruction.applied, and the instruction's Agents card lists the agent with the version it applied.
  • Release a version and move the ref (instruction refs <id> set stable v2). agentd applies it within seconds.

What it doesn't do yet

  • Follow by name. A subscription to the name form is never notified, and the name form doesn't match a signature pin: pin by id.
  • Report from older releases. agentd before 1.23.0 makes no binding, so the Agents card shows it as a reader without an applied version.
  • The agentd profile. The first edition of the specification has an agentd export profile, agentd/1 (profiles/agentd.md, published with the first edition). It describes how one instruction compiles into agentd's native files: agentd.json, guidance.md, workflow JSON and skills. It is a working draft. instruction.md doesn't compile exports with it, and agentd doesn't read it; agentd reads the instruction itself, as above.

If it doesn't work

What you see Why What to do
agentd exits 2 at load, naming {{secret:…}} The environment variable isn't set. Export it, or start agentd with --prompt-missing.
The token request fails The token_url is the people's realm, or the secret was rotated. Use the token_url printed with the credential (instruction-md-agents). Rotate with instruction agents rotate <id> and update the secret.
agentd can't connect to the server agentd is older than 1.18, so it speaks an older MCP. Upgrade agentd.
agentd exits 6, naming the publisher The pinned publisher isn't the one that signed the version. Pin https://instruction.md/pub/<organization> of the organization that releases it.
Every read is refused with a pin The pin's uri uses the name form. Use the id form in both resource and trust[].uri.
Releases arrive late The resource uses the name form, so nothing is pushed. Use the id form.
Still stuck Ask us.

Last checked against the product:

Was this page helpful? Report a problem