Skip to main content
Mirrored from Meerkat Meta main at de520227a811 on 2026-11-17; Meta version 0.9.16 at that commit. Available from Meerkat Meta 0.9.15. An agent can create a long-term agent at run time. A long-term agent is an identity of the mob: a durable, named member that keeps its own conversation and memory across restarts and is addressed by its name. An agent created at run time is the same kind of agent as one your configuration declares: it gets its model, tools and skills from its profile, it is reached through the same doors, and it survives a restart with no roster entry. The agent that asked for it is recorded as who asked. It does not own the new agent, the new agent does not report to it, and the new agent is not limited to the asking agent’s tools. Nothing of this is on by default. An agent gets the identity tools only when both of these hold:
  1. the launch carries an identity policy (runtime_options.identity_creation with enabled: true), and
  2. the agent’s profile has mob tools (tools.mob = true), which is its spawn grant.
Without either, the tools are absent from the agent’s tool list. They are not listed and then refused.

The policy the host enables

The policy is one object in runtime_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.
A rule selects by the change (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.
Always give an agent rule a target. The spawn grant covers every profile of the mob, so the rule is the only control over what an agent may create. A rule {"change": ["create"], "requester": {"kind": "agent"}, "outcome": {"kind": "allow"}} with no target lets every agent that has mob tools create agents of every profile, as often as it likes, each with the instructions and first message the creating agent wrote. A new agent of a profile with mob tools can then create agents itself. There is no count per creator and no ceiling tied to the creator: an agent created at run time is an ordinary agent of its profile.
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 with tools.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_message runs 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 (unsupported at agents[i].first_message), and the agent’s first input comes through the host’s own ingress.
  • instructions is 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 refused reserved_key at set.labels (the removal of one of the product’s own label keys at set.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_labels decides 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 broken and 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_branch is 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 refused reserved_key at agents[i].labels, and no agent of the request is created; an update that adds it is refused reserved_key at set.labels, and the agent is unchanged; an adoption (meta/identity/adopt) of an agent whose configuration gives it is refused reserved_key at name, and the agent stays configured. meta/identity/plan does 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, and set.labels_remove takes 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 begins approval-branch- and holds only ASCII letters, digits, - and _ (a name Meerkat holds as written) is refused invalid_name at 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 in agents[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 refused owns_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, under meta/identity/archive). The refusal is Meta’s: a Rust host that calls Core’s archive_identity or remove_identity itself 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 refused owns_mobs, as its archive is: have the agent destroy its mobs first.
  • meta/delete_identity gives an agent a fresh life and keeps it: a new conversation under the same name. It removes nothing from the mob.
An archive and a removal owe the agent what leaving the roster owes any agent: its last conversation is harvested and distilled, an exit interview is queued and the host’s retirement hook is told (see Lifecycle side effects across a restart). They run right after the agent’s member has stopped; no order is promised between them and the change’s answer. A removal of an archived agent owes nothing more. The schedules that target an agent follow these changes: an archive pauses the active ones, an unarchive resumes exactly those (a schedule somebody paused by name stays paused), and a removal ends every one. The first answer of the change says so in 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 with tool_catalog_search and loads them with tool_catalog_load before its first call.