- the launch carries an identity policy (
runtime_options.identity_creationwithenabled: true), and - the agent’s profile has mob tools (
tools.mob = true), which is its spawn grant.
The policy the host enables
The policy is one object inruntime_options.identity_creation of
meta/init (a Rust host returns the same shape from
GatewayHostComposition::identity_creation_policy). It needs a persistent
state root. Unknown keys are refused at every level, and the default outcome
of every change is deny, so each change an agent may ask is opted in by a
rule. Identity policy is the policy’s reference;
this section is what an agent’s tools need of it.
create, descriptive, capability, peers,
authority, profile, archive, remove, adopt), by who asks (kind,
and for an agent its identity, profile and authority labels) and by the
target agent (identity, profile, authority labels). Every matching rule
applies and the strictest outcome wins. An update that touches several
classes is judged per class, and the strictest outcome applies to the whole
request.
The outcomes in this release are allow, require_approval and deny. A
policy that names notify or review is refused at launch.
peers decides which agents a create or an update may wire an agent to. Its
default is deny: an agent can list a peer only when a peer rule allows that
peer, and an agent that wants to be reachable by the agent it creates lists
its own name as a peer like any other.
The grant
The right to ask is the ordinary spawn grant: the mob operator authority a member of a profile withtools.mob = true is built with. By default it
covers every profile of the mob. Core checks it when a change is asked and
again when it commits, for each profile the change names, so a grant that was
narrowed or revoked meanwhile ends the change (profile_not_allowed,
grant_revoked) with nothing written.
A member that is private to a person (a console side chat, a member such a
member created, a fork of one) gets no identity tools, whatever its profile:
it would carry a person’s conversation into a shared agent’s instructions or
first message. A call that reaches the tools anyway is refused
private_requester.
The eight tools
These are the same requests the host methods
meta/identity/* take, field
for field, without the two members only the host plane writes (proposer,
source_evidence). The arguments are closed: an argument a tool does not name
is refused invalid_request with the argument as field. Who asks is never
an argument. It is the member whose session made the call: an agent acts only
as itself, and a change attributed to another agent than the calling session’s
member is refused invalid_request.
What the tools do not take in this release: grants, schedules, a fork source,
another mob, placement, binding, backend, addressability or runtime mode.
Grants and schedules for a new agent are separate calls. An agent’s
addressability and runtime mode are set by the host (meta/identity/create,
meta/identity/update); identity_list and identity_get read them back.
A host’s change of the runtime mode seats the agent again, as a profile move
does (see Moving a profile).
There is no reset tool; a host resets an agent with its own methods.
What a model is told
Each tool’s description says what a long-term agent is, that the caller is recorded and owns nothing, what each outcome means and what to do on it. The texts are part of the product and are pinned by tests, so an edit is deliberate.first_messageruns once as the new agent’s first turn. It is a kickoff with no requester: it is not a message from the creating agent, the new agent has nothing to reply to, and it reaches the creating agent only if that agent is one of its peers. The turn has the same tools as any other turn of the new agent. A create with a first message answers once the new agent’s session exists; the first run continues after the answer. Without a first message the agent is created dormant: nothing is loaded and nothing runs until something is delivered to it. In a governed realm an agent is created without a first message: a create that gives one is refused (unsupportedatagents[i].first_message), and the agent’s first input comes through the host’s own ingress.instructionsis a list of strings, one per section; most agents need one.labels. The host reserves some label keys, and a create that gives one is refused. An update keeps a reserved label the agent carries when it does not name it; an update that would give it another value or remove it is refusedreserved_keyatset.labels(the removal of one of the product’s own label keys atset.labels_remove).- An agent never changes itself. An update, archive, unarchive or removal
that names the caller is refused
self_change_refused. - A configured agent is changed in configuration. A run-time change of an
agent your roster declares is refused
owner_read_only.
Outcomes
Every change answers one typed outcome, the same on every surface:
A person cannot approve a request they made themselves. Who may approve is
set outside the policy, in the approver map of the launch’s access file:
unless that map binds the rule’s approver id to the stdio operator or to a
person a declared ingress attests, a held change can only be withdrawn or
lapse at its deadline (see
Approval rules). In 0.9.15 and
0.9.16 the decision is taken through the host, not in the Console, which
shows it: see
Decisions held for a person.
A tool’s answer is this outcome without its
operation_id. An operation id
is the host’s handle on a change (meta/identity/operation reads by it): an
agent names its request with its own request_id, no tool takes an operation
id, and nothing an agent reads of its own change names one, neither the
tool’s answer nor the notice of a decision. A held change’s decision_id and
deadline_ms are in the answer.
A change is keyed by its operation. With a request_id, the same id and the
same arguments read the same state and never commit twice, and the same id
with other arguments is refused operation_reused. Without one, the operation
is derived from where the tool call ran (its session, run, round and call id),
so a call the runtime dispatches again after an interruption reads the state
of the first.
On a create, an agent’s seat is seated, or owed when its first message
did not start: the agent exists and its name is taken, and it is seated, and
its first message runs once, at its next delivery.
An agent the host prepares
A policy may name a preparation for a profile (preparation.<profile>.mode: "required", see
Identity policy). An agent created of such a
profile waits for its host: its create answers pending_preparation, and
until the host’s operator settles it (meta/identity/settle_preparation) it
has no member, takes no message and runs nothing. Its first message, if it
has one, runs once when it is settled. There is no tool for the settle, and
nothing an agent sends speeds it up: the agent that asked reads where the new
agent stands with identity_list and identity_get
(readiness: "preparation_pending"), or with the identical create under the
same request_id, which answers done once the agent is settled.
An update of an agent that waits changes its record only, and the agent still
waits. An update that moves an agent into a profile the host prepares is
refused unsupported at set.profile: the agent is created in that profile
instead. Only a create answers pending_preparation.
Changing labels
A label change (set.labels, set.labels_remove) is applied at once and
does not seat the agent again. The agent keeps its member and its
conversation, and it goes on listing and managing the mobs it created.
Who can change an agent’s labels: another agent of the mob that the host’s
rules let change it, through identity_update, and a host, through
meta/identity/update. An agent cannot change its own labels
(self_change_refused).
- The roster and what decides by a label use the new labels at once.
The mob’s roster reads them from the update on. An access rule’s
match_labelsdecides on them at the next call (an open event stream at its next read of the roster, within 20 seconds), and the identity policy’s rules read the agent’s record. A label that was removed stops deciding there at once. - The agent’s next build uses them. An idle agent is released by the
update, so its next delivery builds it again: your customizer is handed
the new labels, and a label that was removed is not among them. An agent
that is busy is not interrupted, and going idle builds nothing: it keeps
what it was built with until it is next released. That is a later update
of it once it is idle, a retire (
meta/retire), an idle retirement, or a restart. The update’s answer does not say that the agent was busy. Until the agent is next seated, any later update of it releases it when it is idle: one more build at its next delivery, nothing else. - Agents that a label change does not release. Three kinds of agent stay live through a label update and keep what they were built with: an agent of a host whose sessions are not durable (a release releases nothing there; it takes new labels when it is rotated onto a fresh conversation or the process restarts), a placed agent (its member host owns its build), and an agent wired to a placed agent. The roster and the access rules use their new labels at once all the same.
- What its peers read of it. A build adds the agent’s labels to the peer metadata of its conversation and takes none away, so a removed label stays in what its peers read of it until the agent starts a new conversation. Nothing is decided on it.
- A fork inherits the new labels. A fork of the agent takes the labels the roster reads for it at the fork, which are the update’s from the update on, also while the agent is busy and still runs on what it was built with: a label that was added is inherited, and a label that was removed is not.
- The seat’s own journal row trails. The record of the agent’s seat in
the mob’s journal keeps the labels the agent was seated with until the
agent is next seated (a respawn, a profile move, a runtime-mode change, a
reset). It decides nothing an update can change. It is what an earlier
release that serves the same store reads, so it matters before a
rollback: Meerkat’s upgrade guide says how to find such agents. No turn,
wake, build or restart of the agent brings it in line. Before rolling
back, either seat the agent again (
meta/respawn), which keeps its conversation and, for an agent that created mobs, its listing and management of them on this release (while an earlier release runs, the agent lists and manages none of its mobs, which go on running; the return restores that with no call), or set its labels back to the ones it was seated with and apply the change again after the return: for an agent that is idle, that update brings the record in line without seating the agent again, so it manages its mobs on the earlier release as well. An agent that held work at that update keeps its record as it was, and the answer does not say so: once it is idle, send another update of it (a new request that changes something, its display name for example; the same request sent again only reads back its first answer). Meerkat’s upgrade guide has the query that lists the agents still to settle. - A broken agent is the exception. An agent whose build was refused for
good is
brokenand serves nothing. Once its labels have changed since it was last seated, any update of it seats it again, the update that changes them included, and its next send is served. So the update that corrects the labels of an agent refused for them (its row lacked a label your customizer sets) gets it built; and an agent whose labels were changed earlier and that broke later for another reason is seated again by its next update, whatever that update changes. If it had created mobs before it broke, it goes on listing and managing them once it is seated again: the update seats its successor on the same conversation. - One label is never given.
decision.approval_branchis the label of an approval branch, a one-time member that Meerkat opens itself to run approved work, and no change of an agent gives it. A create that gives it is refusedreserved_keyatagents[i].labels, and no agent of the request is created; an update that adds it is refusedreserved_keyatset.labels, and the agent is unchanged; an adoption (meta/identity/adopt) of an agent whose configuration gives it is refusedreserved_keyatname, and the agent stays configured.meta/identity/plandoes not check this key: it answers such a request as it answers any other label, and the change itself is then refused. An agent whose record carries the label already keeps it through an update that does not add it, andset.labels_removetakes it off. While its record carries it the agent is never seated again: a respawn is refused, and a profile move or a runtime-mode change changes its record and leaves its member as it was. The names of approval branches are kept the same way: a create or an adoption of an agent whose name beginsapproval-branch-and holds only ASCII letters, digits,-and_(a name Meerkat holds as written) is refusedinvalid_nameat that name (agents[i].name,name).
Moving a profile
A profile move (set.profile) seats the agent again on the same
conversation, once it is idle: it goes on under the new profile’s model,
tools and skills. A host’s change of the runtime mode
(set.runtime_mode_override of meta/identity/update) seats the agent
again in the same way.
An agent seated again this way goes on listing and managing the mobs it
created with its own tools, as after a respawn: its successor runs on the
same conversation. Its new profile’s tools decide what it can call, so move
an agent that must go on managing its mobs to a profile that has the mob
tools. What still ends that management: a reset or a delete of the agent (a
fresh conversation), and anything that retires the agent’s member and seats
it again later. The mobs and their members then stay as they are, unlisted
for the agent, and after a reset or a delete they are removed at the
gateway’s next start (read from the source). An archive of an agent that
still owns mobs it created is refused owns_mobs; the RPC reference lists
what the refusal does not count. Have the agent destroy such a mob first.
Who can do this to an agent: another agent of the mob that the host’s rules
let change it, through identity_update (a profile move), and a host,
through meta/identity/update (a profile move or a runtime-mode change).
An agent cannot do it to itself: a change that names the caller is refused
self_change_refused, and no tool takes a runtime mode.
Changing instructions
An instructions change is in the agent’s record at once. It reaches the agent at its next run, or later when the result says so; a run that starts within moments of the change may still use the earlier instructions; earlier instructions are never rewritten. A dormant agent is not woken by it. The update’s result says what became of the change inagents[0].instructions:
Whatever the kind, the host’s instruction status read
(
meta/instruction_status) is the authority for whether the change is in
effect: the agent’s slot reads pending while the change is recorded and not
yet in effect, and effective once it is. A change that waits for a
compaction is brought into effect by the host: a reset of the agent starts
it on a new conversation with the current instructions and gives the earlier
conversation up (see
Changing an agent’s instructions).
Archive, remove, and a fresh life
Three different things end an agent’s current work, and they are not interchangeable:- Archive (
identity_archive,meta/identity/archive) stops the agent and keeps its name, record, conversation and memory. Messages to it are refused until it is unarchived, and it comes back on the same conversation with its current instructions. An archive of an agent that still owns mobs it created is refusedowns_mobs, and nothing is changed: the refusal says how many mobs there are, and names them to the host and to an administrator. Have the agent destroy its mobs (mob_destroy) and archive it then, or keep the agent. When the agent can no longer manage a mob its session owns, no Meta host method destroys that mob, and the agent’s archive and its removal are refused through Meta while its session owns it; on a gateway the way out is a reset of the agent, which costs its conversation and, by the gateway’s next start, those mobs (the RPC reference lists the cases and the refusal’s limits, undermeta/identity/archive). The refusal is Meta’s: a Rust host that calls Core’sarchive_identityorremove_identityitself is not refused, and there the mobs the agent created are removed with their stores when the host next starts, and unarchiving the agent does not bring them back. - Remove (
identity_remove,meta/identity/remove) retires the name for good. The name is never an agent again, for anyone. The removed agent’s conversation and memory are kept, and nothing can reach them. A removal of an agent that still owns mobs it created is refusedowns_mobs, as its archive is: have the agent destroy its mobs first. meta/delete_identitygives an agent a fresh life and keeps it: a new conversation under the same name. It removes nothing from the mob.
agents[0].schedules. An agent is told the effect
and how many schedules there are ({effect, count, incomplete?}); which
schedules they are is the host’s to read (meta/identity/* over the stdio
gateway, and a Console caller with runtime.admin). incomplete: true means
a schedule could not be read or changed yet, and the identical call with the
same request_id follows the rest. A launch whose host connects no schedules
to these changes changes none, and the answer has no schedules.
Listing and looking up
identity_list shows every long-term agent of the mob that is not private to
a person, of any profile and whoever asked for it. It is not a list of “my
agents”, and it is not limited to what the caller may create: an agent of a
profile the caller may create no agent of is listed too, and
identity_directory is the read that says what the caller may create and
name. Each entry carries
name, display_name, profile, spec_digest, spec_revision, archived
and readiness, and, read back only, addressability when the agent is
internal_only and runtime_mode_override when the agent’s record names
one. An agent that waits for its host’s preparation reads
readiness: "preparation_pending": it has no member and takes no message
until the host settles that. An agent is not shown who asked for another agent, when, or
under which consent, nor another requester’s open operations, nor whether the
host’s roster lists the agent’s name as well; the host’s
meta/identity/list shows those. A list is in one stable order, and after
continues it.
identity_get reads one agent’s record by name: the list entry’s members,
and its instructions, context, labels and peers (the peers its
changes listed, among the agents the caller is shown). It is the host’s
meta/identity/get without who asked for the agent, when, or under which
consent, and without another requester’s open operations.
identity_directory answers “what may I name” before a create: each profile
and each possible peer with a verdict. Its peers are the agents that are
neither archived nor private to a person.
One rule decides which agents an agent is shown, in every read and in every
change: an agent is shown no member that is private to a person. A read or a
change that names such a member answers identity_unknown at name, exactly
as for a name no agent holds, so the answer tells nothing about it.
All three are reads: they never wake an agent and load nothing.
Tool list size
The eight tools may wait behind the deferred tool catalog. In a session whose tool catalog is exact and large enough to defer, their definitions are left out of the model request, and the model finds them withtool_catalog_search
and loads them with tool_catalog_load before its first call.