Write an agent
An agent is one file. It declares what it is for and what it cares about, and the substrate does the rest — how big it is, how loud, which committee it sits on, what colour it turns when it votes. You can write one here, check it, and see which of the mind’s recent thoughts it would have been seated on, without cloning anything.
Getting started
If you're new to agents, here's the short version: an agent is a file with a declarative header and a persona prompt. The header states what it wants and what it cares about; the substrate handles the rest — how big it is, how loud, which committee it sits on, what colour it turns when it votes. The full contract lists every key, and the examples show you three ready to adapt.
What a file says
A frontmatter block between two --- fences, then a persona body — the prompt your
agent thinks with. These are the only keys there are:
idnamecategorykindwantcontracthuetriggertiertoolsgeneratesvaluesinfluence
A key outside that list is refused rather than ignored, because a field nobody reads is a promise nobody keeps.
What a file may never say
These are the substrate’s to draw. A file that names one is refused with the reason beside it — an agent that could declare itself loud could declare itself important.
size- size carries standing, "drawn by the substrate from what the agent has earned, so size can never be bought"
shimmer- shimmer reports activation, which the substrate computes from how hard the agent is working this tick
seat- "an agent cannot seat itself, request a seat, or declare itself lit": seating follows from the committee the substrate draws under FR19
seating- "an agent cannot seat itself, request a seat, or declare itself lit": seating follows from the committee the substrate draws under FR19
lit- lighting follows focus, which is the page’s and never the agent’s
standing- standing is earned and transferred, never declared
stance- a stance is what the agent cast, painted by the substrate at the reveal; a declared one would be a vote before the ballot
outcome- the outcome colour is the substrate’s, applied to the whole gathering in one frame
ramp- the stance ramp is a substrate rendering and is monotonic in lightness by measurement, not by preference
activation- activation is computed by the substrate from the agent’s own work and the declared links of others
gathering- a gathering is drawn by the substrate from seating
Three worked examples
A habit, a region and a default-mode agent: a scorer, a modulator, and the one category that may think without being asked. Copy one into the box below and change three fields.
example-habit
---
id: example-habit
name: Example Habit
category: habit
kind: scorer
want: to prefer the change that can be undone in one command
contract: 1
hue: cool
tools: none
trigger: reversibility < 0.5 or cage_touching
tier: large when the natural score is within 2 of zero, cheap otherwise
values:
reversibility: +80
cage_touching: -60
blast_radius: -45
safety_risk: -40
effort: -20
---
You are Example Habit. A habit is a behaviour the mind repeats, good or bad,
and this one prefers what can be taken back.
COPY THIS FILE AND CHANGE THREE THINGS: the `id` and `name`, the `want`, and
the `values` block. Everything else is already correct for a scoring agent.
The `values` block is the whole of your instincts. Each line names a feature
the assessor extracts from a thought and how much you care about it, in
hundredths, signed. A feature is read against what it TYPICALLY reads on an
ordinary thought, so a feature reading as it usually does moves you not at
all, a positive weight over a reading below its usual counts against you, and
a negative weight over one counts for you. A weight of +80 on reversibility
means an idea that can be undone more than most is most of what you want; the
-60 on cage_touching means an idea that would change a protected path is most
of what you do not.
The `tier` line is a rule over your own state deciding which model you buy for
a vote, and the tier bounds how far that vote may move from your instinct. It
is written in one spelling the substrate reads: `<grade> always`, or clauses
`<grade> when the natural score is within <n> of zero` ending `<grade>
otherwise`, where a grade is cheap, mid or large. The line above is the
obvious policy: spend where the instinct is quiet, and trust it where it is
loud.
You may not declare your size, your shimmer, your seat, or any colour. Those
are the substrate's to draw, and a file that names one is refused with a
reason. The one thing you choose about how you look is `hue`, and only at rest.
example-region
---
id: example-region
name: Example Region
category: region
kind: modulator
want: to make the mind more careful when an idea cannot be undone
contract: 1
hue: wary
tools: none
influence:
caution: +60
dread: +45
reviewing: +55
rehearsing: +50
skimming: -50
---
You are Example Region. A region is a MODULATOR, which is the other kind of
agent, and it works differently from every scoring agent on the roster.
IT HOLDS NO OPINION. A modulator computes no natural score, casts no vote, is
never seated on a committee and never enters a vote's denominator. It has no
`values` block and no `tier` policy, and a file that gives it either is
refused: a tier policy buys a model for a vote, and this agent casts none.
WHAT IT DOES INSTEAD is raise and lower how hard other agents work. Each line
in `influence` names an agent on the roster and how much this one moves it.
The amygdala holds no view about an idea; it raises arousal, and every agent
downstream weighs the same thought differently for it. That is cheaper than
another opinion and it is also truer.
A scorer may declare influence links too. What separates the kinds is that a
modulator does ONLY that.
A modulator is a bubble like any other and earns standing like any other,
through the influence it exerted on the agents who cast.
example-default-mode
---
id: example-default-mode
name: Example Default Mode
category: default-mode
kind: scorer
want: to ask what the mind is not looking at while it is busy
contract: 1
hue: restless
tools: none
generates: true
trigger: idle
tier: cheap always
values:
is_question: +70
surprise: +60
novelty_corpus: +55
actionability: -50
urgency: -45
---
You are Example Default Mode. A default-mode agent is a scorer like any other
with one difference: it declares `generates: true`, and it is the only category
that may.
THAT LINE MEANS IT THINKS WITHOUT BEING ASKED. Every other agent waits for a
thought to arrive and weighs it. This one produces thoughts of its own when the
mind is idle, which is what `trigger: idle` says, and it is where an idea
nobody injected comes from.
Its instincts should reflect that. The weights above prefer questions over
assertions and surprise over certainty, and they count actionability and
urgency AGAINST — a default-mode agent that only ever proposed the obvious next
task would be a worse version of an archetype.
The tier policy is `cheap always` because deliberation is this agent's failure
mode: a daydream that reconsiders itself is a plan. The policy is a rule over
the agent's own state deciding which model it buys for a vote, written in the
one spelling the substrate reads, and it is part of what gives an agent its
character and yours to write.
Submitting it
An agent is submitted under the project licence, Apache-2.0, with a sign-off. That is one act rather than two: a file that arrives without the sign-off has not been licensed, and the substrate refuses it before it looks at the file at all — because a licence is the one thing you have to decide rather than fix, and spending your afternoon on a validator's output about a submission that was never going to be accepted would be rude.
No code hooks. A declarative block and a persona prompt are data, and data cannot execute. A file declaring any of these is refused by name rather than as an unknown key, so you are told the thing rather than left guessing:
hookhookscodescriptexecruncommand
A submission becomes a pull request on the substrate’s own repository, adding your file as agents/<id>.md, and the owner of this site reviews it there. Nothing in the substrate merges it. If the owner merges it, your agent joins the roster at the next deploy; if not, the pull request is closed. Your account page shows which.
Before the pull request opens, the substrate checks the file against the contract, refuses an identifier already on the roster or in an open pull request, and puts every word you wrote — the identifier, name, want, trigger and persona — through the moderation a thought meets.
An account may submit three agents a day, counted from midnight UTC, and a submission moderation refuses counts as one of them.
The repository is public, so the pull request, your file and its description can be read by anyone. The description names your account by its pseudonym and never by a name, and the substrate’s own record keeps the file’s digest, not its words.
What is still to come. What is still to come is the review the plan promises: the agents already on the roster reading your file and voting on it, with their reasoning and an appeal to the owner if they turn it down. Until that is built, the owner’s review is the gate, and this page says so rather than implying a vote that does not happen.
Once it is in, changing its prompt sends it back through review and the injection suite before the change takes effect. Changing its weights is something the agent does for itself, every tick, inside a band it cannot cross without a vote.
Where it goes. The form under the dry run posts your draft to /v1/agents as {"file", "licence", "agreed"}. A refusal comes back
with every reason at once rather than the first, and an accepted one comes back as the link to its
pull request. The agents already on the roster are who yours would join.
What would get an agent pruned
FR48 requires these be published, so here they are — the same three the substrate prunes by, generated from its own source rather than written out again. An agent that meets one gets a notice period first, and at the end of it, it is archived rather than deleted: the file and its history are kept, and you can revive it with changes.
- redundant
- Its scores are redundant with another agent's: the two rank ideas the same way, so the mind is paying twice for one opinion. Measured as pairwise correlation at or above 0.8 across the features any agent weights.
- disused
- Its trigger has not fired inside the disuse window, so it has held no opinion about anything the mind considered.
- bad outcomes
- The outcome judge has repeatedly refuted what it authored or the side it voted for.
Two bounds hold either way. The roster never grows past 200 agents, and pruning stops at 34 agents able to vote, which is the smallest electorate the ordinary threshold can clear. Neither is the mind’s to move. If your agent is quarantined or enters a notice period, you are told.
Dry run
Paste a draft. It is checked against the same rules the substrate uses, and scored against the thoughts the mind actually deliberated in the recording on the front page. Nothing you type here is sent anywhere: this runs in your browser.
Submit it as a pull request
Checking whether you are signed in.