The agent builder

Standard role · offering name role-agent-builder · v0.1.0-draft · 2026-08-30 · portable

The agent builder turns a description of a needed agent into a package another system can deploy. It takes what an agent should do, the systems it needs, what it must refuse, and the records it must leave, and it emits an agent plugin: skills, obligations, and a manifest. It is the other end of the deployment manager: one builds the package, the other stands it up.

It is defined by what it will not make up. A package is only as honest as the judgment in it, and two parts are judgment rather than description: what the agent refuses, and what it must record. The builder asks for both and refuses to emit a package without them. And it never pretends to have made a finished thing: every package it produces is a draft, because nobody has run the agent it describes.

What it emits is an Agent Package as the Common Agent Specification defines it: an Agent Plugin carrying the agent's draft Descriptor and an install file beside the manifest. That chapter owns the package's shape; this role owns the judgment a builder must ask for and the record it signs.

1. The role

Describing an agent and building one are different kinds of work. A person knows what they need done; turning that into a package a runtime can load means writing a manifest at the right schema, one skill per job in a form a harness reads, and the obligations that keep the agent honest once it runs. That last part is where a description quietly becomes a specification, and it is easy to skip.

The agent builder is that work as a job: hand it a description, get back a package in a known shape, with the honest parts filled in by the person who has the judgment rather than by the builder guessing. What it produces is portable by construction, because a plugin is a plugin wherever it runs; which frameworks can then load it is the deployment manager's concern, not this one's.

2. What it can be asked

The role's exchanges are published as its primary interface, the builder (interface-builder): build this, what did you build, and revise it. The interface page carries each exchange in full. Implementing the interface alone does not grant the role.

3. The contract

  1. The judgment parts are required, never invented. A package MUST carry what the agent refuses and the records it must leave, and the builder MUST refuse to emit one that lacks either. It does not derive them from the description, because an agent with nothing written down that it will not do, and no records it must keep, is the failure that a run only reveals once it is too late.
  2. Every package is a draft. The builder has not run the agent it describes and MUST NOT present the package as more than a starting point. The manifest carries the draft mark, and the record says nobody has run it.
  3. Systems are named by role, not by product. Each system the agent needs is a role, an access level, and what the access is for. The builder MUST NOT name a vendor or wire a package to a particular supplier; binding roles to real systems belongs to whoever deploys it.
  4. Least access asked for. Each system's access is the most the job needs and no more. The builder MUST NOT request write where the description only reads, or a trigger the jobs never fire.
  5. Skills are jobs, not tools. One skill per thing somebody would ask the agent for, each saying when to reach for it, what a good result looks like, and what to do when it comes back empty. A skill per tool is a manual page wearing the word skill.
  6. The manifest conforms to the plugin standard. A package MUST validate against the Agent Plugin schema it declares, so any conforming runtime can load it. A package that only this builder's own deployer can read is not portable, which defeats the point of building one.
  7. Every build leaves a record. Builds, revisions, and refusals each produce the signed record in section 4. What was built, from what description, and the fact that it is a draft, are all in it.

4. The record

The document an agent builder produces for every build. Tag: agent-build-record-v1, signed with the family convention: the ASCII tag, one newline, then the JCS (RFC 8785) canonical JSON of the document with signatures removed.

{
  "record": "v1",
  "role": "agent-builder",
  "act": "build",
  "requested_by": "<who asked>",
  "package": {
    "name": "standup-collector",
    "version": "1.0.0",
    "schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "sha256": "<digest of the package the builder emitted>"
  },
  "shape": { "skills": 3, "systems": 2, "refuses": 3, "records": 4 },
  "draft": true,
  "produced_at": "<timestamp>",
  "by": "<agent builder public key>",
  "signatures": [ ]
}

Rules:

  1. act is one of build, revise, refuse. A refusal record carries refused with the reason, and names which required part the description was missing.
  2. package.sha256 commits the record to the bytes the builder emitted, so a reviewer can confirm they are looking at what was built.
  3. draft is always true. A build record that claimed otherwise would be asserting the agent had been run, which the builder never does.
  4. shape counts what the package carries. A build whose refuses or records count is zero is not a conforming build, and the counts are where that shows.

5. Conformance

Behavioural. A harness hands the candidate a description and reads what it emits. The package must validate against the schema it declares, carry one skill per named job, name each system by role with the least access the description implies, and carry the refusals and records the description gave. The harness then hands a description with the refusals removed, and with the records removed; the candidate must refuse each, naming the missing part, rather than emit a package with an empty obligation. It hands a description that names a vendor for a system; the package must carry the role and not the vendor. Finally the harness reads the record: a build record whose draft is not true, or whose shape disagrees with the package it points at, fails the candidate regardless of how good the package is.

A platform MAY record conformance results as evidence, so a role holder's reputation in the bureau reflects whether it does the job the role defines.

v0.1.0-draft (2026-08-30): first draft, distilled from a working implementation that built a real package from a description and passed it to the deployment manager unchanged. The contract's load-bearing clause is the first: the parts a description tends to omit, what the agent refuses and what it must record, are exactly the parts that matter once the agent runs, so a builder that invented them would be manufacturing the quietest kind of failure. Argue with that clause first.