meerkat-sdk) brings Meerkat agents into Python applications
and automation. Create and resume sessions, stream results, use tools, schedule
work or coordinate teams through async Python APIs. The SDK connects through
rkat-rpc to the same runtime used by the CLI and other service surfaces.
- Contract version:
0.9.16 - Python:
>=3.10 - Runtime dependencies:
websockets>=12,<16, plustyping_extensions>=4.1on Python 3.10
Install
The rkat-rpc binary
MeerkatClient starts the first rkat-rpc it finds: MEERKAT_BIN_PATH when
set, then an explicit MeerkatClient(rkat_path=...), then rkat-rpc on
PATH. The SDK runs those as they are: trusting a binary you chose is your
decision. Otherwise it downloads the release binary of its own version and
caches it under ~/.cache/meerkat/bin/rkat-rpc/v<version>/<target>/.
Only that download is verified. A published meerkat-sdk package pins the
sha256 of every release archive it may download and of the rkat-rpc inside
it: pinned when the package is built, from the release’s manifest, with each
archive’s build attestation verified, and never fetched at download time. The download uses HTTPS only, redirects
included, and refuses an archive over 256 MiB (BINARY_DOWNLOAD_TOO_LARGE). The archive is checked before anything is
extracted, the binary before it is installed, and the cached binary again each
time it is reused. A mismatch raises BinaryIntegrityError (code
BINARY_INTEGRITY_MISMATCH, with asset, path, expected_sha256 and
actual_sha256): the SDK deletes what failed, runs nothing and does not fall
back to another binary.
A source or git install of the SDK (
pip install -e "sdks/python[dev]") pins
no digests and refuses to download, raising MeerkatError with code
BINARY_DIGEST_UNAVAILABLE. Build or install rkat-rpc yourself and put it on
PATH, or set MEERKAT_BIN_PATH or rkat_path to a binary you trust.Quick start
The selected model needs a compatible credential route: an already provisioned auth binding or the provider’s environment key. This example selects Claude. For a clean API-key setup, export your Anthropic key in the shell that starts Python; therkat-rpc child inherits it:
auth_binding when it is not the configured default. A different provider’s
key is not a substitute for the selected model’s credentials.
Method overview
Session lifecycle
await client.create_session(...) -> Sessionclient.create_session_streaming(...) -> EventStreamawait client.create_deferred_session(...) -> DeferredSessionawait client.list_sessions(...) -> list[SessionSummary]await client.read_session(session_id) -> SessionDetailsawait client.read_session_history(session_id, offset=0, limit=None) -> SessionHistory
Session runtime inputs
await client.inject_context(session_id, text, source=None, idempotency_key=None)await session.inject_context(...)await client.send_external_event(session_id, event_type, payload, blocks=None, idempotency_key=None)await session.send_external_event(event_type, payload, blocks=None, idempotency_key=None)
Turn APIs
Session.turn(...), Session.stream(...), and DeferredSession.start_turn(...) support:
injected_context,transient_turn_contextskill_refs,turn_tool_overlayadditional_instructionskeep_alive,model,provider,self_hosted_server_id,system_promptprovider_paramsreasoning_effort(from 0.9.15): a level ("high") sets the session’s provider-neutral reasoning effort from this turn on,{"action": "clear"}removes it, and omitting it keeps it (the server’s contract must be 0.9.15 or later; see the reference)auth_binding: a binding ref (or{"action": "set", "value": ref}) switches the session’s credential binding from this turn on,{"action": "clear"}drops it, and omitting it keeps the current one
max_tokens, output_schema and structured_output_retries,
but the server refuses these on a turn with INVALID_PARAMS: they are build
settings. Pass them to create_session(...) or create_deferred_session(...).
Immediate session creation also accepts injected_context,
transient_turn_context, auth_binding, the schedule/WorkGraph/web-search
feature toggles, and a typed system-prompt override. Deferred creation accepts
the same durable setup except transient_turn_context; supply request-only
host facts to DeferredSession.start_turn(...) instead. Injected context
becomes ordered user-channel context immediately before the prompt. Transient
turn context is not durable transcript history.
Config APIs
await client.get_config() -> ConfigEnvelopeawait client.set_config(config, expected_generation=None) -> ConfigWriteResultawait client.patch_config(patch, expected_generation=None) -> ConfigWriteResult
config, generation, realm metadata), not a bare config object; writes additionally carry live_propagation.
Additional runtime surfaces
await client.get_models_catalog()await client.create_schedule(...)await client.get_schedule(...)await client.list_schedules(labels=None, limit=None, offset=None)await client.update_schedule(...)await client.pause_schedule(...)await client.resume_schedule(...)await client.delete_schedule(...)await client.list_schedule_occurrences(...)await client.list_schedule_tools()await client.call_schedule_tool(...)
WorkGraph observability
WorkGraph mutation remains agent-owned through tools. Host SDK callers can inspect the graph and its goal/attention projections:await client.get_workgraph_item(...)await client.list_workgraph_items(...)await client.list_ready_workgraph_items(...)await client.get_workgraph_snapshot(...)await client.list_workgraph_events(...)await client.get_workgraph_goal_status(...)await client.list_workgraph_attention(...)
Jobs, approvals, artifacts, and projected event replay
- detached jobs:
jobs_get,jobs_list,jobs_cancel,jobs_progress,jobs_result,jobs_artifacts,jobs_retry,jobs_health,jobs_subscribe,jobs_unsubscribe - monitors:
monitors_start - Meta workers:
meta_job_heartbeat,meta_job_progress,meta_job_checkpoint,meta_job_complete,meta_job_fail,meta_job_cancel_ack - approvals:
request_approval,list_approvals,get_approval,decide_approval - artifacts:
list_artifacts,get_artifact,download_artifact - projected events:
latest_event_cursor,list_events_since,event_snapshotwhen host event projection is enabled
meerkat.generated.types rather than re-exported at the package root.
Transcript history, revisions, and recovery
input_state(...)reconciles an admitted input by input id or idempotency keyexport_session_atif(...)exports a session trajectoryread_session_transcript_revision(...)andlist_session_transcript_revisions(...)inspect durable revisionsfork_session_at(...)andfork_session_replace(...)create a new branchrewrite_session_transcript(...),update_system_prompt(...), andrestore_session_transcript_revision(...)perform guarded edits
Live channel APIs
The oldRealtimeChannel helper has been removed. Use LiveChannel.session(...)
for a session-bound wrapper, or call the direct live/* RPC helpers on
MeerkatClient.
live_ws=True and request
transport="websocket"; only that bootstrap has a URL.
The server exposes one offer-to-answer exchange and no candidate-trickle RPC.
Install the returned answer_sdp as the browser peer’s remote description.
await client.live_open(session_id, turning_mode=None, transport=None, seed_max_chars=None)await client.live_webrtc_answer(channel_id, token, offer_sdp)await client.live_status(channel_id)await client.live_close(channel_id)await client.live_send_input_text(channel_id, text)await client.live_send_input_audio(channel_id, data_base64, sample_rate_hz, channels)await client.live_send_input_image(channel_id, idempotency_key, mime, data_base64)await client.live_send_input_video_frame(channel_id, codec, data_base64, timestamp_ms)await client.live_commit_input(channel_id, response_modality=None)await client.live_interrupt(channel_id)await client.live_truncate(channel_id, item_id, content_index, audio_played_ms)await client.live_refresh(channel_id)
user_content_committed with the matching key
before treating the image as durable context. See Live Channels
for replay, conflict, and reconnect limits.
seed_max_chars is an optional positive serialized-character budget for a
core-selected whole-turn seed suffix. Omit it for the full canonical seed.
Every ordered System message must fit. Runtime context and complete image identity, tombstone,
and accounting sidecars remain outside the window; any truncation reports
degraded continuity. Zero is rejected by the server.
Mob APIs
await client.create_mob(...) -> Mobawait client.list_mobs()await client.list_quarantined_mobs()/await client.mob_restore_retry(mob_id)await mob.spawn(...)await mob.spawn_many(...)await mob.read_events(after_cursor=0, limit=100)await mob.wait_for_kickoff_complete(...)await mob.spawn_helper(..., result_label=..., max_text_bytes=..., role_name=...)await mob.fork_helper(..., result_label=..., max_text_bytes=..., role_name=...)- host/grant control:
mob.hosts(),mob.route_installs(),mob.bind_host(...),mob.revoke_host(...),mob.grant_scopes(...),mob.revoke_scopes(...),mob.grants() - remote member control:
mob.hard_cancel(...),mob.stop_member_run(agent_identity, run_id, reason=...),mob.compact_member(agent_identity), member history, member live open/status/control/close, and member/mob event subscriptions
resume_from_role durable role-migration authority.
Realm profile CRUD
await client.create_mob_profile(name, profile)await client.get_mob_profile(name) -> StoredMobProfile | Noneawait client.list_mob_profiles()await client.update_mob_profile(name, profile, expected_revision=...)await client.delete_mob_profile(name, expected_revision=...)
Additional wrappers
The Python client also exposes:- realm helpers:
list_realms(),get_realm(...) - auth helpers:
list_auth_profiles(...),get_auth_profile(...),create_auth_profile(...),delete_auth_profile(...),auth_login_*,auth_provision_api_key(...),auth_status(...),auth_logout(...) - blob/skill/MCP helpers:
get_blob(...),list_skills(),mcp_add(...),mcp_remove(...),mcp_reload(...) - comms helpers:
session.send(...),session.peers() - typed ingress helpers:
send_peer_response_terminal(...) - runtime host inspection:
get_runtime_host_info(),get_runtime_host_capabilities(),get_runtime_host_health()
Generated assistant images
When a session model calls the built-ingenerate_image tool, generated images appear in committed history as SessionAssistantBlock entries with block_type == "image". The SDK preserves image_id, blob_id, media_type, width, height, revised_prompt, and provider metadata.
WireGenerateImageRequest, WireGenerateImageExecutionPlan, WireImageGenerationToolResult, WireImageOperationPhase, and WireAssistantImageRef.
Typed session metadata
SessionSummary(fromsession/list) includestotal_tokensSessionDetails(fromsession/read) includesmodel,provider,last_assistant_text- both use integer unix timestamps for
created_at/updated_at
Streaming model
EventStream is an async context manager returned by session.stream() and client.create_session_streaming(). Iterate it to receive typed event dataclasses, then read events.result.
TurnCompleted.usage is optional. Absence means the provider supplied no
normalized accounting for that call; skip the row instead of treating it as
zero.
Known event types without a handwritten parser class arrive as
UnknownEvent
with their wire payload preserved in event.data. This includes server-tool
content, model-fallback, rewrite-receipt, and boundary-append events; they are
in the generated inventory. RunStarted.input preserves the typed content or
pending-tool-results input. HookFailed.reason retains a known native cause
or an UnknownHookFailureReason wrapper with reason_code="unknown",
raw_reason_code and the exact original dictionary in raw. Check raw fields
before use. Unknown causes display "unknown hook failure" in error.
A present reason takes priority over a
legacy error, and malformed known causes keep their raw payload in a
malformed event. hook_launch_refused uses the same recognized raw-event
path. See the event compatibility
reference for exact behavior.