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. A long-term agent is a durable, named member of the mob. It keeps its own conversation and memory across restarts, and it is addressed by name. Your host code can read and change the mob’s agents while the gateway runs, with 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 as runtime_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.
A rule names the changes it governs in 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 refused owner_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.
Three things make this safe to automate:
  • request_id names 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 with operation. A different request under the same id is refused operation_reused.
  • expected_spec_digest is the spec you read. There is one spec digest on every surface, the digest of the agent’s record: the same value in list, get, a change’s outcome and the current_digest of a stale_spec refusal. An adoption does not change it.
  • A refusal says what to do. not_adoptable carries a reason in its details; an agent that is changed at run time already answers nothing_to_adopt. declared_apply_open is retryable: the gateway is applying your configuration, so send the same request again.
Once the adoption committed, stop declaring the agent in your configuration. While your roster still lists it, the agent is served from its record and the roster’s entry for that name is not applied: the identity’s status (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 including claude-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.
This block archives and removes the agent moments after changing its instructions, so the gateway log may show one or two 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: owed means 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 (unsupported at agents[i].first_message): create the agent without one. The peers an agent lists are checked against the policy’s peers rules, whose default is deny (peer_not_allowed): allow them there, for example with "peers": {"default": "allow"}. An agent may name who reaches it, addressability (addressable, the default, or internal_only), and how it runs, runtime_mode_override (autonomous_host or turn_driven; left out, as its profile says): the members and values of a roster row, with the same meaning. get and list read both back, each only when it is not the default.
  • Update. set names what changes; a member left out is unchanged. instructions and context are replaced whole. labels sets the keys it names, and labels_remove removes 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 refused reserved_key at set.labels, the removal of one of Meta’s own labels at set.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). A profile change 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 of runtime_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). addressability and runtime_mode_override take the values they take on a create and are the change class capability of 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 a reason): 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, in status["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 is delivery_owed for 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)) reads archived true; the member is left out otherwise. 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. 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 refused owns_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: schedules with its effect (paused, resumed, ended), count, the schedules (schedule_id and name) and incomplete, 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. The effect and the count are told to every caller of the change; the list is your host’s. These calls are given it, and so is a Console caller with runtime.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 later operation read state no schedules, so do not compare a retry’s answer whole with the first one. plan of 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 answers pending_preparation: the agent reads readiness preparation_pending, takes no delivery (a retryable refusal), runs nothing and wakes nothing. Its status reads preparation_pending true (preparationPending), and its open_operations name its create until the settle. Prepare what it needs, then call identities.settle_preparation(name, request_id=...) (settlePreparation(name, { requestId })): the agent is seated dormant and its first message, if it has one, runs once. The same request_id and name answer the same result. An agent that awaits no preparation refuses preparation_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.
The vocabulary is closed: a new kind is a breaking change of the SDKs. A gateway newer than your SDK may still send a kind the SDK does not list. It is the same error, with the kind’s token in 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