runtime.identities in the Python SDK (meerkat-meta) and the TypeScript
SDK (@rkat/meta-sdk). Each call is one meta/identity/* host method.
There is one kind of agent. An agent made at run time is the same as one
your configuration declares: the same profile, tools, memory, peers, console
entry and restart recovery. Who asked for an agent is recorded, and nothing
reads it for a decision. No read tells the two apart.
This page starts with the case of an application that already has agents:
moving one from configuration to run-time changes.
1. Launch with a policy
The gateway changes agents only under your policy. Give the policy on the builder. It is sent asruntime_options.identity_creation, and it needs a
persistent launch.
A call of this family never answers “method not found” on a gateway of this
release: that answer means the gateway is older.
change, selects by the requester and
the target, and gives an outcome. The rule above lets your SDK calls, which
are the host on the rpc surface, adopt agents. A rule must name at least one
change: create, descriptive (display name, instructions, context, labels),
capability, peers, profile, archive (an archive and an unarchive),
remove, adopt or authority. A change no rule matches gets the default
outcome, which is deny, so the sections below need their changes added to
the rule. An authority change always needs a person’s decision: a rule that
allows it is refused at init.
The outcomes of this release are allow, require_approval (a person
decides; the rule names an approver) and deny. A policy that names
notify or review is refused at init.
The SDK sends the policy unchanged and models none of it: the gateway owns
its shape and refuses the init for a policy it cannot read. The
policy reference has the whole shape.
2. Adopt an agent your configuration declares
An agent your configuration declares is changed in configuration. A run-time change of it is refusedowner_read_only. To change it at run time, adopt it
first: adopt releases the agent from configuration. From then on it is
changed at run time, and configuration no longer declares it.
The agent keeps its name, its conversation, its memory and the peers it has.
request_idnames the change. The same id and the same request return the same state and commit at most once. After a lost answer or a restart, send the same call again, or read it withoperation. A different request under the same id is refusedoperation_reused.expected_spec_digestis the spec you read. There is one spec digest on every surface, the digest of the agent’s record: the same value inlist,get, a change’s outcome and thecurrent_digestof astale_specrefusal. An adoption does not change it.- A refusal says what to do.
not_adoptablecarries areasonin its details; an agent that is changed at run time already answersnothing_to_adopt.declared_apply_openis retryable: the gateway is applying your configuration, so send the same request again.
runtime.status(name)) reads roster_listing_superseded true
(rosterListingSuperseded in TypeScript), and false for every other agent;
get, list, the directory and the plan of a change of it read the same
member.
To adopt every agent, page through list and adopt each one:
3. Read an operation later
A change answers one of three outcomes, or is refused:
An agent’s
open_operations (get and list) are the ids of the operations
open for it: its create while it waits for your host’s preparation, and each
change of it that is held for a person’s decision or approved and not yet
carried out. The gateway leaves the member out when nothing is open; the SDKs
then read an empty list.
pending_decision carries the operation_id, the decision_id and the
decision’s deadline_ms. Do not repeat the change under a new request_id.
The SDK does not poll: read the operation when you want its state, by your
own request_id or by the outcome’s operation_id.
withdraw ends a held decision without writing anything. After a withdrawal
the operation reads refused with kind decision_closed
(state: withdrawn), a second withdraw answers decision_closed too, and
the same request_id cannot be asked again: ask the change under a new one.
A person decides a
held change through the durable decision methods;
the person who asked cannot decide their own request. In this release the
host’s own consequence lines come from a Rust host composition only: a
decision of an SDK host renders without them.
4. Create, update, archive and remove
One limit to know before you change an agent’s instructions. On a model that takes a system instruction only ahead of the conversation, a changed instruction reaches an agent that already has a conversation only when that conversation is compacted at the start of a run. Those models are every Gemini model, the Anthropic models up to and includingclaude-opus-4-7,
claude-sonnet-5 and claude-haiku-4-5, and the OpenAI models gpt-live-1
and gpt-live-1-codex. Newer Anthropic models and the other OpenAI models
take a changed instruction in mid-conversation, except an OpenAI model
served through the ChatGPT backend (chatgpt_backend), whose requests carry
no system instruction besides the prompt: there a change applies only from a
new conversation. A model the catalog does not know is treated as taking it
only ahead of the conversation. The instruction status tells for a given
agent. That compaction may never happen by itself: a conversation is
compacted only when it reaches its compaction threshold (by default about
four fifths of the model’s context window), never after a time or a number
of turns. Until then the agent goes
on following its earlier instructions. To bring the change into effect,
reset the agent, which discards its conversation; Instructions below has
it.
One thing to know before you archive or remove an agent: an archive and a
removal of an agent that still owns mobs it created are refused
owns_mobs, until the agent has destroyed them (Archive and unarchive
below). The agent in this block has created none.
operator_instruction_delivery warnings (failure=AGENT_ERROR,
failure=SESSION_NOT_FOUND): the change was on its way into the agent’s
conversation when the conversation was archived. Nothing is lost: the change
is already in the agent’s record.
- Create. One call creates 1 to 256 agents, all or nothing; they may name
each other as peers. A new agent is dormant: nothing is loaded and nothing
wakes until its first delivery or its first message. Each agent’s outcome
carries its
seat:owedmeans the agent is committed and durable and its first message did not start; it is seated at its next delivery, without a restart. On a governed runtime a create that gives a first message is refused before anything is written (unsupportedatagents[i].first_message): create the agent without one. The peers an agent lists are checked against the policy’speersrules, whose default isdeny(peer_not_allowed): allow them there, for example with"peers": {"default": "allow"}. An agent may name who reaches it,addressability(addressable, the default, orinternal_only), and how it runs,runtime_mode_override(autonomous_hostorturn_driven; left out, as its profile says): the members and values of a roster row, with the same meaning.getandlistread both back, each only when it is not the default. - Update.
setnames what changes; a member left out is unchanged.instructionsandcontextare replaced whole.labelssets the keys it names, andlabels_removeremoves keys. A reserved label the agent carries (one of Meta’s own, or one your policy reserves, that its configuration gave it before its adoption) stays through an update that does not name it; an update that would change or remove it is refusedreserved_keyatset.labels, the removal of one of Meta’s own labels atset.labels_remove. A label change is applied at once and does not seat the agent again: the mob’s roster and the access rules use the new labels at once, an idle agent is released and takes them at its next build, on the same conversation, and a busy one keeps what it was built with until it is next released; a broken agent whose labels have changed since it was last seated is seated again by its next update (see Changing labels). Aprofilechange moves the agent to that profile’s model and tools on the same conversation. The move seats the agent again, and so does a change ofruntime_mode_override: an agent that created mobs with its own tools goes on listing and managing them (see Moving a profile for what still ends that).addressabilityandruntime_mode_overridetake the values they take on a create and are the change classcapabilityof your policy; an update sets a runtime mode and cannot return the agent to its profile’s. - Instructions. A change of instructions is in the agent’s record at
once; earlier instructions are never rewritten. The update’s outcome says
when the agent follows it.
applies_at_next_run: at its next run (a run that starts within moments of the change may still use the earlier instructions); an agent that has no conversation yet takes the current instructions in its first run, unless that run was already being started when the update arrived.applies_after_compaction: the limit above; the sample above answers it on such a model, because the agent’s first message has given it a conversation.applies_at_next_session(with areason): from the agent’s next new conversation.unchanged: the update left the instructions as they were. The instruction status (runtime.instruction_status(namespace="meerkat.identity.instructions", key="editor", identity="editor")) shows where a change stands, instatus["members"][0]["slots"][0]["state"]:{"state": "pending", "reason": "leading_prefix_only_lowering"}is recorded and not yet followed;{"state": "effective"}is followed. Right after the update the reason isdelivery_owedfor a moment: the change is not in the agent’s conversation yet (the other values are on the roster page). A reset (runtime.reset("editor"); in the Console, the roster’s reset action where the console configuration shows it,show_reset, and the viewer may reset the agent) starts a new conversation led by the current instructions, and the earlier conversation is lost. The call is available for every agent that is not archived. The change also takes effect at the agent’s next compaction at the start of a run. A respawn does not bring the change into effect, and neither does an archive followed by an unarchive. The SDKs can also compact the agent’s conversation, which brings a waiting instruction into effect on the same conversation:runtime.compact_member("editor")in Python,runtime.compactMember("editor")in TypeScript; before you use it on an agent that created mobs, read the SDK reference (Python, TypeScript): against a gateway before 0.9.15 the call costs the agent those mobs. - Archive and unarchive. An archived agent keeps its name, record,
conversation and memory, and messages to it are refused. Like any agent
that leaves, it is owed the harvest and distillation of its last
conversation, an exit interview and the retirement hook (cause
unlisted); they start right after its member retired, and no order is promised between them and the archive’s answer. Unarchive brings it back on the same conversation. While it is archived the identity’s status (runtime.status(name)) readsarchivedtrue; the member is left out otherwise. 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. Removal is permanent: the name is never available again
(
name_taken; in 0.9.15 a create under it that a rule holds for approval is refused only when the approved change is carried out, see Known limitations in the Meta changelog). The agent’s conversation and memory are kept, and no other agent can reach them. A removal owes what an archive owes (the harvest, the exit interview, the retirement hook); a removal of an archived agent owes nothing more. A removal of an agent that still owns mobs it created is refusedowns_mobs, as its archive is. Archive an agent that may be needed later, once it has destroyed the mobs it created (Archive and unarchive above). - Schedules. The schedules that target an agent follow these three
changes, so that none keeps firing at an agent that takes no delivery: an
archive pauses its Active schedules, an unarchive resumes exactly the
schedules paused that way (one somebody paused by name stays paused), and
a removal ends every one. A schedule is the agent’s when it names the
agent or its session, or is a Console schedule for it. The agent’s entry
of the first answer says how its schedules stand after the change:
scheduleswith itseffect(paused,resumed,ended),count, theschedules(schedule_idandname) andincomplete, true when a schedule could not be read or changed (send the same request again: it follows the rest). After an archive the list is the schedules paused for the agent; after an unarchive, the agent’s schedules that are active after the call, one somebody resumed by name while it was archived included; after a removal, the ended ones. A schedule somebody paused by name is on neither of the first two lists. Theeffectand thecountare told to every caller of the change; the list is your host’s. These calls are given it, and so is a Console caller withruntime.admin. An agent that asks for the change through its tools, and any other Console caller, is answered without the list, since a schedule that targets an agent may be anybody’s. A replay of the request and a lateroperationread state noschedules, so do not compare a retry’s answer whole with the first one.planof those changes carries the list the change would answer. While an agent is archived no schedule is pointed at it through Meta: the agents’ schedule tools and the Console refuse a create or an update that would (identity_archived); a pause, a resume and a delete by name stay. Two limits hold for a schedule that names only a session: a removal of the session’s agent does not end it, and one created, or resumed by name, while that agent is archived is active. Each of its fires ends as a missing target and no turn runs; after a removal, end it by hand (Agent changes). - Host preparation. When your policy names a profile’s preparation
required, a create of an agent of that profile answerspending_preparation: the agent readsreadinesspreparation_pending, takes no delivery (a retryable refusal), runs nothing and wakes nothing. Its status readspreparation_pendingtrue (preparationPending), and itsopen_operationsname its create until the settle. Prepare what it needs, then callidentities.settle_preparation(name, request_id=...)(settlePreparation(name, { requestId })): the agent is seated dormant and its first message, if it has one, runs once. The samerequest_idand name answer the same result. An agent that awaits no preparation refusespreparation_not_pending. If you cannot prepare an agent, leave it pending (waiting costs nothing) or remove it.
directory lists the profiles you may name and the agents you may list as
peers, each with the verdict your rules give it (allowed, needs_decision
with the lines the decision shows, or not_allowed). plan answers the outcome
and the rendering a change would get, and holds and writes nothing.
changes_hold holds every change for a while, for example during a deploy:
each change is refused the retryable changes_held. The hold does not
survive a restart of the host: set it again as soon as the start has
answered, before you serve callers. The start itself is not held: what a
launch carries out before your call (a held change that was approved, a
change asked by an agent a schedule wakes) is carried out.
5. Handle a refusal
Every refusal of every call raises one error,IdentityRefusedError. Nothing
of a refused change was written.
kind and known_kind
(knownKind) false, so handle an unknown kind by retryable and detail.
Params the gateway cannot read are this error too, with kind
invalid_request: problem malformed for an unknown member or a wrong type,
empty for a change without its request_id. One case is not this error: a
candidate launch refuses every change before the family is reached, with the
gateway-wide -32047 and kind candidate_launch (AnnouncementRefusedError
in both SDKs). It still answers the reads.
Advisory values are open. An agent’s readiness, a change’s state, a
provenance’s entered, a directory verdict, the addressability and
runtime_mode_override an agent reads back and the effect on its
schedules may take values your SDK does not know: they are kept as the
gateway sent them.
get and list answer each agent’s provenance: how it came to exist, who
asked, when, and the consent the change committed under. It is recorded and
shown; nothing reads it for a decision.
See also
- Python SDK
- TypeScript SDK
- Identity policy
- Agent changes: the host methods behind the calls
- Durable decisions
