> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents that create agents

> Let an agent create, change, archive and remove long-term agents under the host's identity policy: the policy, the grant, the eight identity tools and their outcomes.

*Mirrored from Meerkat Meta main at [de520227a811](https://github.com/lukacf/meerkat/commit/de520227a81178fce9ffea3abcafa4a7bddfbf27) 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](https://docs.rkat.ai/meta/reference/identity-policy.md) is the policy's reference;
this section is what an agent's tools need of it.

```json theme={null}
{
  "enabled": true,
  "peers": {
    "rules": [
      { "id": "research-team", "target": { "profile": ["researcher"] }, "outcome": "allow" }
    ],
    "default": "deny"
  },
  "approval": {
    "rules": [
      {
        "change": ["create", "descriptive", "peers", "archive"],
        "requester": { "kind": "agent", "profile": ["coordinator"] },
        "target": { "profile": ["researcher"] },
        "outcome": { "kind": "allow" }
      },
      {
        "change": ["remove", "profile"],
        "requester": { "kind": "agent", "profile": ["coordinator"] },
        "target": { "profile": ["researcher"] },
        "outcome": { "kind": "require_approval", "approver": { "id": "owner" } }
      }
    ],
    "default": { "kind": "deny" }
  }
}
```

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.

> [!WARNING]
>
> 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

| Tool | Arguments | What it does |
| - | - | - |
| `identity_create` | `agents: [{name, profile, display_name?, instructions?, context?, labels?, first_message?, peers?}]`, `request_id?` | Creates 1 to 256 agents, all together or not at all. They may name each other as peers. |
| `identity_update` | `name`, `expected_spec_digest`, `set {display_name?, instructions?, context?, labels?, labels_remove?, profile?}`, `peers_add?`, `peers_remove?`, `request_id?` | Changes one agent. A member left out of `set` stays as it is. A label change keeps the agent's member (see [Changing labels](#changing-labels)); a profile move seats the agent again (see [Moving a profile](#moving-a-profile)). |
| `identity_archive` | `name`, `expected_spec_digest`, `request_id?` | Stops an agent and keeps it: name, record, conversation and memory stay, its last conversation is harvested as for any agent that leaves, and messages to it are refused. Its schedules are paused with it. Refused `owns_mobs` while the agent still owns mobs it created: have it destroy them first (see [Archive, remove, and a fresh life](#archive-remove-and-a-fresh-life)). |
| `identity_unarchive` | `name`, `expected_spec_digest`, `request_id?` | Brings an archived agent back on the conversation it had. The schedules its archive paused are resumed. |
| `identity_remove` | `name`, `expected_spec_digest`, `request_id?` | Removes an agent for good. Its name is never available again; its last conversation is harvested as for any agent that leaves. Its schedules are ended. Refused `owns_mobs` while the agent still owns mobs it created. |
| `identity_list` | `profile?`, `include_archived?`, `after?` | Lists the mob's long-term agents that are not private to a person, of any profile. Read only. |
| `identity_get` | `name` | Reads one agent's record: what the list says of it, and its instructions, context, labels and peers. Read only. |
| `identity_directory` | `query?`, `after?` | Lists the profiles the caller may create agents of and the agents it may name as peers, each `allowed`, `needs_decision` or `not_allowed`. Read only. |

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](#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:

| `outcome` | Meaning | What the caller does |
| - | - | - |
| `done` | The change committed. `agents` names each agent with its `state`, `spec_digest` and `spec_revision`. | Keep the `spec_digest`: the next change of that agent sends it as `expected_spec_digest`. |
| `pending_decision` | A person must decide (`decision_id`, `deadline_ms`). Nothing is written but the decision. | Wait. Repeating the call with other arguments is a new request. The identical call with the same `request_id` returns the current state. An agent that is itself a long-term agent gets a notice when the decision is made. |
| `pending_preparation` | The create committed, and at least one agent (its `state` is `pending_preparation`) waits for the host to prepare it: it has no member, takes no message and runs nothing until the host settles it, and its first message runs once then. | Nothing: no tool settles it. `identity_list` and `identity_get` read it as `readiness: "preparation_pending"`, and the identical call with the same `request_id` returns where it stands. |
| `refused` | Nothing was written. `kind` is one of a closed vocabulary, `field` names the argument, `detail` says what to send instead, `retryable` says whether the same call may succeed later. | Fix what `detail` names, or retry later when `retryable` is true. |

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](https://docs.rkat.ai/meta/reference/identity-policy.md#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](https://docs.rkat.ai/meta/guides/console.md#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](https://docs.rkat.ai/meta/reference/identity-policy.md)). 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`:

| `kind` | Meaning |
| - | - |
| `applies_at_next_run` | The change reaches the agent at its next run. |
| `applies_after_compaction` | The agent's model takes new instructions only at the head of what it reads: the change reaches it after its next compaction at the start of a run, which a short conversation may never reach. |
| `applies_at_next_session` | The change does not reach the agent as it runs now, for `reason`, and applies when the agent next starts a new conversation. Reasons: `prepared_authorization_required` (a governed runtime), `slot_limit_exceeded`, `active_set_budget_exceeded`, `lowering_unavailable`, `body_too_large`, `record_unavailable`. |
| `unchanged` | The agent holds the same instructions already. |

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](https://docs.rkat.ai/meta/concepts/roster.md#changing-an-agent%E2%80%99s-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](https://docs.rkat.ai/meta/guides/deployment.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.