Python SDK - Meerkat

This page documents MobKit v0.8.34 (mirrored from v0.8.34). The MobKit Python SDK provides a typed host API for launching and operating Meerkat mobs through the SDK-facing gateway. Apps own policy. Meerkat and meerkat-mob remain authoritative for agent execution, identity, membership, lifecycle, and wiring; MobKit packages gateway startup, provider adapters, operational modules, persistence projections, and operator surfaces.

Installation

pip install meerkat-mobkit

The wheel is client-only and does not contain rpc_gateway. Download mobkit-rpc-gateway-<version>-<target>.tar.gz for Unix or macOS, or mobkit-rpc-gateway-<version>-<target>.zip for Windows, and extract its rpc_gateway binary (rpc_gateway.exe on Windows). Alternatively, follow the source-build instructions. Pass that binary’s path to .gateway(...).

Quick start

import asyncio
from meerkat_mobkit import MobKit

async def main():
    async with await MobKit.builder().mob("config/mob.toml").gateway("/path/to/rpc_gateway").build() as rt:
        handle = rt.mob_handle()

        # Send a message (comms)
        await handle.send("agent-1", "Hello")

        # Watch what happens (observation)
        async for event in handle.subscribe_agent("agent-1"):
            print(event.event_type, event.data)

asyncio.run(main())

Durable detached tools

Declare long-running host work explicitly instead of holding callback/call_tool open:

from meerkat_mobkit import DetachedJobExecution, DetachedJobResult

async def run_scan(ctx):
    await ctx.progress(1, "scan started")
    # ctx.arguments is the persisted non-secret specification.
    # ctx.credentials is resolved for this committed attempt only.
    result_ref = await perform_scan(ctx.arguments, ctx.credentials)
    return DetachedJobResult(result_ref)

class AppAgentBuilder:
    async def build_agent(self, options):
        options.register_tool(
            "security_scan",
            lambda args: {"error": "detached owner required"},
            description="Run a durable security scan",
            execution=DetachedJobExecution(
                runner="homecore.security_scan",
                version="v1",
                restart_class="checkpoint_resumable",
                idempotency_scope="interaction_and_arguments",
                submission_timeout_ms=30_000,
                credential_scopes=("unifi.read",),
                handler=run_scan,
            ),
        )

runtime = await (
    MobKit.builder()
    .persistent_state("state/mobkit")
    .job_credentials(resolve_profile_credentials)
    .session_service(AppAgentBuilder())
    .gateway("/path/to/rpc_gateway")
    .build()
)

job = await runtime.jobs.get(job_id)
await runtime.jobs.cancel(job_id)

The gateway durably accepts the job and returns a receipt; host work then runs outside the agent turn. Start, reconcile, and cancel are short control-plane callbacks subject to the 120-second public contract (the Python host and wire margins are 125 and 130 seconds). On reconnect, MobKit offers the exact committed attempt, fence, lease, checkpoint, and runner handle. Reopening does not mint a new fence; only a machine-authorized claim or retry can do that. Resolved credentials are attempt-local and never enter durable job state.

Identity-First API

For household-style apps (HomeCore), the identity-first API provides durable lifecycle management. Agents are addressed by stable identities (identity:luka, triage:main), not member IDs.

from meerkat_mobkit import MobKit
from meerkat_mobkit.identity_first_models import DispatchInput, DurableAgentSpec, ManagedPeerEdge

# Boot with roster provider
rt = await (
    MobKit.builder()
    .mob_inline(MOB_TOML)                 # or .mob("mob.toml")
    .persistent_state(state_dir)
    .agent_memory()                       # optional: durable per-agent memory
    .roster(my_roster)                    # provides DurableAgentSpec list
    .topology_provider(my_topology)       # optional: managed edges
    .agent_customizer(my_customizer)      # optional: per-identity prompts
    .gateway("./rpc_gateway")
    .build()
)

# Identity-scoped agent handles
triage = rt.agent("triage:main")
luka = rt.agent("identity:luka")

# Delivery
await luka.send("Hello")                                          # Addressable only
await triage.dispatch_text("School closed", origin="connector")   # Any identity

# Delivery + wait for THAT turn's answer. These wait on the completion
# cursor the gateway captured before delivery, so they stay correct when an
# agent answers two turns identically.
answer = await luka.send_and_wait("Hello", timeout=90)

# Observation (no mob_handle, no member IDs needed)
inspection = await triage.inspect()   # output_preview, completion_cursor, peers
output = await triage.wait_for_output(timeout=90)   # any output, including an earlier turn's
await rt.wait_until_ready(["triage:main", "identity:luka"])

# Status
status = await luka.status()          # state, session_id, generation, labels

# Lifecycle
await luka.reset()                    # Destructive: new generation, new session
await rt.agent("domain:calendar").respawn()  # Non-destructive recovery
await rt.reconcile()                  # In-process roster reconciliation

DurableAgentSpec fields

The roster provider returns one DurableAgentSpec per identity. The Rust side deserializes the same shape, so every field below reaches the gateway verbatim; fields left at their default are omitted from the wire.

Field	Type	Description
`identity`	`str`	Stable identity (`triage:main`); no whitespace or `/`
`profile`	`str`	Profile name from mob.toml `[profiles.*]`
`addressability`	`str`	`addressable` (default) or `internal_only`
`display_name`	`str`, optional	Human-facing name
`labels`	`dict[str, str]`	Member labels
`context`	`Any`, optional	Opaque host context handed to the customizer
`additional_instructions`	`list[str]`	Appended to the profile’s system prompt
`placement`	`str`, optional	Exact Meerkat host ref; never degrades to local
`runtime_mode_override`	`str`, optional	`autonomous_host` or `turn_driven`. `None` defers to the profile’s `runtime_mode`, whose meerkat default is `autonomous_host`. Ambient per-turn memory requires `turn_driven` (see the configuration reference)
`initial_message`	`str` or `list[ContentBlock]`, optional	First turn a fresh `autonomous_host` member runs on (Rust `ContentInput`: text or content blocks). `None` leaves meerkat’s fallback spawn prompt in place

DurableAgentSpec(
    identity="archivist:main",
    profile="archivist",
    runtime_mode_override="turn_driven",      # pin this identity regardless of the profile default
    initial_message="Index yesterday's mail.", # or [TextBlock(...), ImageBlock(...)]
)

Roster provider context

The gateway calls roster(context) with a typed RosterContext (meerkat_mobkit.identity_first_models.RosterContext), a one-to-one mirror of the Rust struct:

Field	Type	Meaning
`mob_definition`	`dict \| None`	The booted mob’s compiled definition as JSON (`id`, `profiles`, …). Always present behind the bundled `rpc_gateway`; `None` only for in-process Rust embedders and test harnesses that resolve a roster without a mob definition.
`previous_identities`	`list[str]`	Identities the identity runtime has registered at the time of the call. Empty on the bootstrap resolves (nothing is registered yet), populated on later re-derivations such as `mobkit/topology/query` or an edge reconcile.

class MyRoster:
    async def roster(self, context):
        household = (context.mob_definition or {}).get("id")
        known = set(context.previous_identities)
        ...

DispatchInput convenience constructors

DispatchInput.system("text")
DispatchInput.connector("event from slack", correlation_id="msg-1")
DispatchInput.scheduler("nightly sync")

Mob-Level API

For direct mob-member operations (discovery-based), the mob handle API is still available. The app-facing surface has three categories. Each is a distinct concern — no method crosses categories.

Comms — deliver work to agents

result = await handle.send("agent-1", "Review PR #42")
print(result.accepted, result.member_id, result.session_id)

Returns a SendMessageResult with accepted, member_id, and session_id fields. The message enters the agent’s inbox and is processed by the host loop.

Observation — watch what’s happening

# Stream one agent's events
async for event in handle.subscribe_agent("agent-1"):
    print(event.event_type, event.data)

# Stream mob-wide events (all agents)
async for event in handle.subscribe_mob():
    print(event.source, event.data)

Observation is independent of delivery. Subscribe before or after sending — the stream is continuous.

Structural mob events — durable observability

MobHandle.query_mob_events() and subscribe_mob_events() project every meerkat MobEventKind (25 variants) into a typed envelope preserving mob_id, run_id, step_id, agent_identity, and the full payload.

from meerkat_mobkit import EventQuery, MobEventsStaleError

# Latest 256 matching events
events = await handle.query_mob_events(EventQuery(
    event_types=["flow_started", "flow_completed"],
    mob_id="home",
))
for e in events:
    print(e.cursor, e.kind, e.run_id, e.data)

# Resume from a checkpointed cursor
try:
    new_events = await handle.query_mob_events(EventQuery(
        after_seq=last_seen_cursor,
    ))
except MobEventsStaleError as exc:
    # Cursor is past the current frontier — rewind.
    new_events = await handle.query_mob_events(EventQuery(
        after_seq=exc.latest_cursor,
    ))

MobStructuralEvent.cursor is the meerkat ledger cursor — durable across mobkit gateway restarts when the runtime is built with .persistent_state(path). Checkpoint a cursor and resume by passing it as after_seq on the next call.

Flow runs

# All runs across all flows
runs = await handle.list_runs()

# Filter to one flow
runs = await handle.list_runs(flow_id="onboarding")

for run in runs:
    print(run.run_id, run.status, len(run.step_ledger))

Returns MobRun carrying the full meerkat ledger projection (step_ledger, failure_ledger, frames keyed by frame id, loops keyed by loop id, loop_iteration_ledger, flow_state, activation_params, schema_version, etc.).

Control plane — manage the runtime

# Inspect runtime state
status = await handle.status()
print(status.running, status.loaded_modules)

# Ensure an EPHEMERAL worker exists (spawn if missing). Durable members
# (per-user agents, coordinators) belong on the identity plane instead —
# see "new user first contact" below.
snapshot = await handle.ensure_member("scratch-worker-7", role="worker")
print(snapshot.agent_identity, snapshot.state)

# Find members by label
members = await handle.find_members("owner", "user-123")

# Reconcile the named modules (routing, delivery). This does not touch the
# roster; identity roster reconciliation is rt.reconcile().
result = await handle.reconcile(["routing", "delivery"])

# Call an MCP tool on a loaded module
result = await handle.call_tool("gmail", "gmail_search", {"query": "is:unread"})

# Or bind a module for repeated calls
gmail = handle.tool_caller("google-workspace")
messages = await gmail("gmail_search", query="is:unread")

ensure_member() and find_members() both return typed MemberSnapshot objects (single and list[MemberSnapshot] respectively).

Roster — inspect and manage members

# List the full roster
members = await handle.list_members()
for m in members:
    print(f"{m.agent_identity}: {m.state} ({m.role})")

# Inspect a specific member
snapshot = await handle.get_member("agent-1")

# Member lifecycle
await handle.retire_member("agent-1")
await handle.respawn_member("agent-1")

# Non-destructive cold reload (same session, same generation) and the
# in-process health read that works while the actor loop is stalled
health = await handle.member_health("agent-1")
if health.last_delivery_error and health.last_delivery_error["class"] == "reload_required":
    outcome = await handle.reload_member("agent-1")
    assert outcome.disposition in ("discarded", "not_degraded")

Method	Return type	Description
`list_members()`	`list[MemberSnapshot]`	List all members in the roster
`get_member(member_id)`	`MemberSnapshot`	Get a single member by ID
`retire_member(member_id)`	`None`	Retire a member (graceful shutdown)
`respawn_member(member_id)`	`None`	Respawn a previously retired member (identity-first: a destructive continuity reset)
`reload_member(member_id)`	`MemberReloadResult`	Non-destructive cold reload: same identity, same durable session, same generation (identity-first only)
`member_health(member_id)`	`MemberHealth`	Lifecycle and delivery health from in-process reads; carries `actor_loop`, `open_stall_id`, and `last_delivery_error`
`reconcile_edges()`	`ReconcileEdgesReport`	Converge mob.toml `[wiring]` (`auto_wire_orchestrator`, `role_wiring`) on the live roster. Needed after `runtime.reconcile()` or an identity-first boot only when the definition declares such wiring; `ensure_member` already runs it, and with no declared wiring the report is empty

MemberSnapshot exposes agent_identity, role, state, wired_to, and labels. Known state strings are exported from the top-level package as MEMBER_STATE_ACTIVE, MEMBER_STATE_RETIRING, MEMBER_STATE_BROKEN, MEMBER_STATE_COMPLETED, and MEMBER_STATE_UNKNOWN. The underlying Rust status enum is non-exhaustive, so consumers should tolerate future state strings.

Common pattern: new user first contact

Per-user agents are durable members, so stand them up on the identity plane — declare them through your roster provider and reconcile — rather than ensure_member-ing them into the mob roster. Identity-plane members get continuity records and resume across restarts; mob-plane members do not.

# Slack DM from a new user — add the identity to your roster source,
# reconcile, then deliver by identity.
my_roster.add_identity(f"personal:{user_id}", profile="personal",
                       labels={"owner": user_id})
await runtime.reconcile()
result = await runtime.send(f"personal:{user_id}", slack_message)
async for event in runtime.mob_handle().subscribe_agent(f"personal:{user_id}"):
    forward_to_slack(event)

Reserve ensure_member for ephemeral workers (helpers a parent spawns and an idle-retire label reaps) — the worker plane. See the identity-first doctrine.

Builder pattern

from meerkat_mobkit import MobKit

rt = await (
    MobKit.builder()
    .mob("config/mob.toml")
    .session_service(my_builder, my_store)
    .roster(my_roster)
    .gateway("./rpc_gateway")
    .build()
)

Builder methods

Method	Description
`.mob(path)`	Path to mob TOML config
`.mob_inline(toml_str)`	Inline mob TOML string (no temp file)
`.meerkat_config(path)`	Meerkat host `config.toml` forwarded as `runtime_options.meerkat_config_path`, the only door for the `[self_hosted]` and `[realm]` tables Meerkat keeps out of `mob.toml` (a host-config `[models]` table reaches the factory too, but a profile’s `model` must be catalogued, provider-annotated or defined under `mob.toml`’s own `[models.<id>]` to pass the init model check); a missing, malformed or non-validating file refuses init rather than building agents from the default config, and a top-level `[self_hosted]` or `[realm]` table inside `mob.toml` is refused at init with a message naming this option. TypeScript twin `meerkatConfig(path)`. See Self-hosted models and the Meerkat host config
`.persistent_state(path)`	Enable persistent state at path
`.continuity_store(provider)`	External identity continuity store
`.lease_provider(provider)`	External identity lease provider
`.scratch_dir(path)`	Required scratch path for external identity providers
`.roster(provider)`	Identity-first roster provider
`.topology_provider(provider)`	Identity-first topology provider
`.agent_customizer(customizer)`	Identity-first agent customizer (`customize_build(context, spec, draft)`; see Per-profile tools)
`.on_error(callback)`	Error hook. Receives every runtime `ErrorEvent` (`category`, `message`, `context`) the gateway forwards as the `mobkit/on_error` notification; sync or async, fire-and-forget. Without it the events reach only the gateway’s stderr ERROR line (see Error hook and logging)
`.identity_bootstrap_mode(mode)`	Eager, lazy, or bounded background-warm identity materialization; requires `.roster(...)`
`.role_migrations(declarations)`	Authorize durable member role migrations for THIS boot. Takes an iterable of `RoleMigrationDeclaration` dataclasses or equivalent `identity` / `from_role` dicts, validating either form; a conflicting pair for one identity raises `ValueError`, an identical repeat is accepted, and leaving the setter unused emits no `role_migrations` init-params key at all
`.session_service(builder, store)`	Session agent builder and optional store
`.gating(path)`	Gating config path
`.routing(path)`	Routing config path
`.event_log(config)`	Operational event log declaration (`event_log.memory()` / `event_log.null()`)
`.runtime_store(config)`	Explicit ephemeral runtime-store declaration (`runtime_store.memory()`)
`.memory(config)`	Memory configuration
`.agent_memory(config=True, **options)`	Durable identity-scoped agent memory
`.auth(config)`	Auth configuration
`.console_auth_required(required)`	Set `runtime_options.console_require_app_auth`; `False` is the explicit opt-out from the fail-closed console default (see Console access)
`.console_read_only(read_only=True)`	View-only console: mutating console RPCs are denied and omitted from capabilities
`.console_fetch_timeout_ms(ms)`	Bundled-console JSON fetch timeout override (positive integer)
`.console_config(path)`	Console UI TOML (`ConsoleUiConfig`) forwarded as `runtime_options.console_config_path`
`.gateway(bin_path)`	Path to rpc_gateway binary
`.modules(specs)`	Module specifications
`.build()`	Build and connect the runtime

Boot-time membership is declared, never derived: a member exists only once a .roster(provider) names it (identity plane) or ensure_member creates it (worker plane); [profiles.*] in mob.toml are role templates and spawn nothing on their own. The former .discovery(callback) and .pre_spawn(callback) builder methods were removed: they stored the callback and never transmitted it, so no boot spawn ever came from them. External identity providers follow the Rust gateway’s authoritative path: set .continuity_store(provider), .lease_provider(provider), and .scratch_dir(path) together. The Python callback dispatcher speaks the Rust wire contract for leases (result tags and ttl) and continuity deletes. LeaseProviderProtocol.renew_leases(...) is atomic from the caller’s perspective: raising means no input grant was changed, while every returned renewed or lost result is already committed for that identity. Providers must not commit a replacement grant and then raise. For continuity stores, checkpoint_version is monotonic per identity and continuity generation. A live session rebind changes session_id without resetting the version; only destructive reset advances generation and starts the version stream over. A durable member whose role changed refuses to resume with MobError::MemberRoleMigrationRequired until the host declares the migration. .role_migrations([...]) is that declaration: it emits a top-level role_migrations init param, not a runtime_options field, and the authority lasts exactly one boot because nothing persists it. Meerkat re-verifies the declared from_role against durable state and refuses with MobError::MemberRoleMigrationRejected on mismatch, and ignores the declaration entirely once the roles already agree, so a declaration left in place after the migration landed is inert. It arms only where an identity plane exists; on rpc_gateway that means alongside .roster(...). See roster and member lifecycle. Every explicit .identity_bootstrap_mode(...) call declares identity-first intent and requires .roster(...), including explicit eager mode. Omitting the setter keeps a gateway without a roster on the classic path; a configured roster with no explicit mode retains eager materialization. Gateway memory config accepts {backend: "local_json"} with an optional health_check_endpoint (memory.local_json(...)); the legacy Elephant {backend, endpoint} shape still works but emits a DeprecationWarning. memory(stores=...) is intentionally rejected because the Rust gateway does not accept store lists in mobkit/init. JWT auth is the gateway-supported auth mode; Google/OIDC helpers are not accepted by gateway init today. Agent memory is configured with .agent_memory() and requires .persistent_state(path) plus an identity roster when using the bundled gateway store. Options include realm, selection, max_entries, recall_timeout_ms, recall_failure_policy, and instruction_header; the SDK serializes them to the gateway wire contract. Automatic injection defaults to a 500 ms timeout and skips the memory block if recall fails. Storage durability declarations. The gateway is fail-closed about durable storage: a store that cannot open is a startup error, never a silent in-memory fallback. The config.runtime_store and config.event_log modules produce the explicit declarations:

from meerkat_mobkit.config import event_log, runtime_store

runtime = await (
    MobKit.builder()
    .mob("config/mob.toml")
    .persistent_state("state/mobkit")
    # Declare an in-memory runtime store (sessions do not survive restart).
    .runtime_store(runtime_store.memory())
    # Declare a bounded queryable in-process event log — or event_log.null().
    .event_log(event_log.memory(batch_size=64))
    .build()
)

The resolved picture is the typed storage census: StatusResult.storage / CapabilitiesResult.storage parse the gateway’s storage object into StorageSummary (blob durability, the H2 incremental probe, and the per-slot StorageSlotSummary census with domain, durability_class, resolution, backend, degraded, detail). A fail-closed startup refusal — file-name twins, a store that failed to open — surfaces as the typed StorageResolutionError (code -32014, STORAGE_RESOLUTION_CODE), not a TransportError; its message names the remediation (mobkit/storage/doctor, or the explicit ephemeral declaration). Blob-store durability has no wire declaration today — it is declared by Rust embedders via ephemeral_blobs(true) / binary_blob_store(...) and reported read-only in the census.

Console access

The bundled console is fail-closed. Without .auth(...) the gateway’s decision state trusts no signing key, and because require_app_auth defaults to true every console request is refused with 401; the gateway logs a startup warning naming this. Opening the console is an explicit builder call:

runtime = await (
    MobKit.builder()
    .mob("config/mob.toml")
    .gateway("./rpc_gateway")
    .console_auth_required(False)  # explicit opt-out: local console, no identity provider
    .console_config("config/console.toml")
    .build()
)

Use .console_auth_required(False) only behind a loopback bind or a reverse proxy that authenticates; for anything shared, configure .auth(...) instead. Earlier SDKs had no setter and hosts overrode MobKitRuntime._build_init_params to inject console_require_app_auth or console_config_path; both now have builder methods and the override is no longer needed. The gateway binds 127.0.0.1 on an ephemeral port by default. To publish it from another container, .http_listen("0.0.0.0:8080") together with either .auth(...) or the explicit .allow_remote() acknowledgement, and .http_public_base_url(...) to advertise the proxy’s address (read back as runtime.rust_http_public_base_url; runtime.rust_http_base_url stays the same-host form the SDK itself dials). A non-loopback bind without either is refused at init. See Deployment.

Runtime lifecycle

# Context manager (recommended)
async with await MobKit.builder().mob("mob.toml").gateway("./rpc_gateway").build() as rt:
    handle = rt.mob_handle()
    # ...

# Explicit lifecycle
rt = await MobKit.builder().mob("mob.toml").gateway("./rpc_gateway").build()
try:
    handle = rt.mob_handle()
    # ...
finally:
    await rt.shutdown()

Gateway logging (stderr)

The persistent gateway reports tracing lines, panic hooks, and storage migration progress on its stderr. By default the SDK inherits the host process’s stderr, so those lines are visible where your application logs. Two environment variables adjust this:

Variable	Effect
`MOBKIT_GATEWAY_STDERR_FILE=<path>`	Append gateway stderr to a file
`MOBKIT_GATEWAY_STDERR=devnull`	Discard gateway stderr entirely

Discarding is the legacy pre-0.8.9 default and is not recommended: it hides panic output and makes a slow-but-working storage migration indistinguishable from a hang.

Session agent builder and per-profile tools

build_agent runs once per member build on the worker plane (fresh spawn or resume). The gateway pre-fills SessionBuildOptions before it calls you:

Field	Pre-filled with
`profile_name`	The spawn’s role, taken from the member’s `profile_name` (else `role`) label that meerkat stamps from the mob-member binding
`labels`	The member’s peer labels merged with the request labels
`app_context`	The host context attached to the spawn, if any
`session_id`	The spawn’s `session_id` label when it carries one, else the resumed session’s id
`resume_session_id`	The resumed session’s id on a resume; `None` on a mint

Read profile_name, do not assign it. There is no way to select a profile from build_agent: the gateway applies only additional_instructions (mint builds only; on a resume they are ignored with a warning, because a resume inherits the persisted prompt state), labels, resume_session_id, and the registered tools from what you return, and ignores a host-set profile_name. Per-profile tools are therefore one builder that branches on the pre-filled value:

from meerkat_mobkit import SessionAgentBuilder, SessionBuildOptions

class MyBuilder(SessionAgentBuilder):
    async def build_agent(self, options: SessionBuildOptions) -> None:
        # options.profile_name arrives pre-filled from the spawn role.
        options.register_tool("calendar_lookup", my_calendar_handler)
        if options.profile_name == "security":
            options.register_tool(
                "unifi_scan",
                my_scan_handler,
                description="Scan the UniFi controller",
                input_schema={"type": "object", "properties": {"site": {"type": "string"}}},
            )

runtime = await (
    MobKit.builder()
    .mob("config/mob.toml")
    .session_service(MyBuilder())
    .gateway("./rpc_gateway")
    .build()
)

.session_service(builder) is the public setter; build() connects and registers the builder on the callback dispatcher for you. MobKitBuilder._config and MobKitRuntime._dispatcher are internal and change without notice. The builder must be set before build(): mobkit/init tells the gateway whether a session builder exists, so there is no post-connect registration.

Identity-first equivalent: `customize_build`

On the identity plane the same hook is AgentCustomizer.customize_build, registered with the public .agent_customizer(customizer). It runs on fresh create and on every restore/reconcile, receives the durable spec (so spec.profile is the profile name), and registers tools on the draft:

from meerkat_mobkit import (
    AgentBuildContext,
    AgentBuildDraft,
    AgentCustomizerProtocol,
    DurableAgentSpec,
)

class MyCustomizer(AgentCustomizerProtocol):
    async def customize_build(
        self,
        context: AgentBuildContext,
        spec: DurableAgentSpec,
        draft: AgentBuildDraft,
    ) -> None:
        # context.identity, context.active_peers, context.managed_edges are read-only.
        if spec.profile == "security":
            draft.register_tool("unifi_scan", my_scan_handler, description="Scan the UniFi controller")
        draft.additional_instructions.append(f"Your wired peers: {', '.join(context.active_peers)}")

draft also carries model, system_prompt, additional_instructions, labels, app_context, and provider_params. A tool registered here rides the same callback/call_tool dispatch as build_agent tools, so resumed identities keep it.

Provider parameters (`provider_params`)

AgentBuildDraft.provider_params mirrors meerkat’s ProviderParamsOverride: the shared sampling knobs at the top level and the provider-specific knobs nested under provider_tag, which is tagged by provider. Anthropic prompt caching is such a knob; meerkat 0.8.32 (the pinned release) defaults it to disabled on every backend, so a long-lived identity opts in here:

draft.provider_params = {
    "provider_tag": {
        "provider": "anthropic",
        "cache_control": "automatic",   # disabled | automatic | system_prefix | system_and_conversation
        "cache_ttl": "1h",              # 5m | 1h; effective only with a cache_control policy
    },
}

The flat form {"cache_control": "automatic"} is refused: both ProviderParamsOverride and the provider tags deny unknown fields, so the gateway rejects the returned draft instead of dropping the knob. Knobs the draft leaves unset are filled from the profile’s own provider_params, and a provider_tag from a different provider family than the profile’s own tag is a typed merge error, not a silent union. A declared provider_params also reaches resumed sessions (the bridge masks it into resume_overrides); it requires an inline definition profile to carry it, so an identity bound to a realm-reference profile fails the build with a message naming the realm profile as the place to declare it.

Error hierarchy

All SDK errors inherit from MobKitError:

from meerkat_mobkit.errors import (
    MobKitError,           # Base exception
    TransportError,        # Transport layer failures
    RpcError,              # JSON-RPC error responses
    NotConnectedError,     # No active runtime connection
    CapabilityUnavailableError,  # Requested capability unavailable
    ContractMismatchError,       # SDK/runtime version mismatch
    StorageResolutionError,      # Fail-closed storage refusal at init (-32014)
)

Advanced API

These methods are available for power users and module-system internals. Most apps should use send, subscribe_agent/subscribe_mob, and status/reconcile instead.

Method	Return type	Description
`spawn(spec: DiscoverySpec)`	`SpawnResult`	Spawn a member from a discovery spec
`spawn_member(module_id)`	`SpawnResult`	Spawn a member by module ID
`capabilities()`	`CapabilitiesResult`	List available RPC methods
`subscribe_events(scope, ...)`	`SubscribeResult`	Low-level event subscription
`resolve_routing(recipient)`	`RoutingResolution`	Resolve delivery routing
`send_delivery(...)`	`DeliveryResult`	Send via delivery module
`list_routes()`	`list[RuntimeRouteResult]`	List all registered routes
`add_route(...)`	`RuntimeRouteResult`	Register a new route
`delete_route(route_key)`	`RuntimeRouteResult`	Remove a route by key
`delivery_history(...)`	`DeliveryHistoryResult`	Query past delivery records
`gating_evaluate(...)`	`GatingEvaluateResult`	Evaluate a gating rule
`gating_pending()`	`list[GatingPendingEntry]`	List pending gating decisions
`gating_decide(...)`	`GatingDecisionResult`	Submit a gating decision
`gating_audit(limit)`	`list[GatingAuditEntry]`	Retrieve gating audit log
`memory_query(filters)`	`MemoryQueryResult`	Query the assertion ledger by `entity`, `topic`, and `store` filters
`remember_agent_memory(identity, ...)`	`AgentMemoryRecord`	Persist durable memory for an identity
`recall_agent_memory(identity, ...)`	`list[AgentMemoryRecord]`	Recall identity-scoped durable memory
`forget_agent_memory(identity, memory_id)`	`AgentMemoryForgetResult`	Delete identity-scoped durable memory
`memory_stores()`	`list[MemoryStoreInfo]`	List available memory stores
`memory_index(...)`	`MemoryIndexResult`	Index an operational memory assertion

Mobpack authoring

MobHandle wraps the full Flow Editor authoring surface (mobkit/mobpacks/*) with snake_case typed methods — mobpack_templates, mobpack_catalogs, mobpack_validate, mobpack_source, mobpack_export, mobpack_import, mobpack_list, mobpack_get, mobpack_create, mobpack_save, mobpack_delete, mobpack_undo, mobpack_redo, mobpack_apply_operation, mobpack_deploy_command, and mobpack_deploy. The same wrappers exist on the SDK’s typed JSON-RPC clients.

import base64

# Create a draft from the blank template, validate, export
draft = await handle.mobpack_create(template="blank", name="support-bot")
document = draft.row.document

validation = await handle.mobpack_validate(document)
print(validation.ok, len(validation.display_rows))

pack = await handle.mobpack_export(document)
archive = base64.b64decode(pack.content_base64)  # pack.filename, pack.media_type

mobpack_deploy(document, execute=True) writes the archive and runs rkat mob run on the host — gated by the surface’s advertised authoring_capabilities and, on ABAC-enforced runtimes, the caller’s mobpack.deploy grant. See the Flow Editor guide.

Public surface exports

Everything below is importable directly from meerkat_mobkit:

from meerkat_mobkit import (
    # Builder + Runtime
    MobKit, MobKitBuilder, MobKitRuntime,
    # Data models
    DiscoverySpec, PreSpawnData, SessionBuildOptions, SessionQuery,
    # Agent builder
    SessionAgentBuilder,
    # Errors
    MobKitError, TransportError, RpcError,
    MobEventsStaleError, MOB_EVENTS_STALE_CURSOR_CODE,
    StorageResolutionError, STORAGE_RESOLUTION_CODE,
    NotConnectedError, CapabilityUnavailableError, ContractMismatchError,
    # Typed results
    StatusResult, CapabilitiesResult, ReconcileResult,
    StorageSummary, StorageSlotSummary,
    SpawnResult, SpawnMemberResult,
    SendMessageResult, SubscribeResult,
    KeepAliveConfig, EventEnvelope,
    RoutingResolution, DeliveryResult,
    # Roster
    MemberSnapshot,
    MEMBER_STATE_ACTIVE, MEMBER_STATE_RETIRING, MEMBER_STATE_BROKEN,
    MEMBER_STATE_COMPLETED, MEMBER_STATE_UNKNOWN,
    # Routing & delivery
    RuntimeRouteResult, DeliveryHistoryResult,
    # Gating
    GatingEvaluateResult, GatingDecisionResult,
    GatingAuditEntry, GatingPendingEntry,
    # Memory
    MemoryQueryResult, MemoryStoreInfo, MemoryIndexResult,
    AgentMemoryRecord, AgentMemoryRecallResult, AgentMemoryForgetResult,
    # Events
    MobEvent, AgentEvent, EventStream,
    # Structural mob events + flow runs
    MobStructuralEvent, MobRun, MobRunStatus,
    StepRecord, FailureRecord, FrameRecord, LoopRecord, LoopIterationRecord,
    # Config modules
    auth, event_log, memory, runtime_store, session_store,
)

Module authoring helpers (ModuleSpec, define_module, etc.) live in meerkat_mobkit.helpers — not top-level.

​Installation

​Quick start

​Durable detached tools

​Identity-First API

​DurableAgentSpec fields

​Roster provider context

​DispatchInput convenience constructors

​Mob-Level API

​Comms — deliver work to agents

​Observation — watch what’s happening

​Structural mob events — durable observability

​Flow runs

​Control plane — manage the runtime

​Roster — inspect and manage members

​Common pattern: new user first contact

​Builder pattern

​Builder methods

​Console access

​Runtime lifecycle

​Gateway logging (stderr)

​Session agent builder and per-profile tools

​Identity-first equivalent: customize_build

​Provider parameters (provider_params)

​Error hierarchy

​Advanced API

​Mobpack authoring

​Public surface exports

​See also

Installation

Quick start

Durable detached tools

Identity-First API

DurableAgentSpec fields

Roster provider context

DispatchInput convenience constructors

Mob-Level API

Comms — deliver work to agents

Observation — watch what’s happening

Structural mob events — durable observability

Flow runs

Control plane — manage the runtime

Roster — inspect and manage members

Common pattern: new user first contact

Builder pattern

Builder methods

Console access

Runtime lifecycle

Gateway logging (stderr)

Session agent builder and per-profile tools

Identity-first equivalent: `customize_build`

Provider parameters (`provider_params`)

Error hierarchy

Advanced API

Mobpack authoring

Public surface exports

See also