Skip to main content
The Python SDK (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, plus typing_extensions>=4.1 on Python 3.10

Install

For local development:

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; the rkat-rpc child inherits it:
Skip this export if you already use a compatible auth binding; pass it with 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(...) -> Session
  • client.create_session_streaming(...) -> EventStream
  • await client.create_deferred_session(...) -> DeferredSession
  • await client.list_sessions(...) -> list[SessionSummary]
  • await client.read_session(session_id) -> SessionDetails
  • await 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_context
  • skill_refs, turn_tool_overlay
  • additional_instructions
  • keep_alive, model, provider, self_hosted_server_id, system_prompt
  • provider_params
  • reasoning_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
They also accept 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() -> ConfigEnvelope
  • await client.set_config(config, expected_generation=None) -> ConfigWriteResult
  • await client.patch_config(patch, expected_generation=None) -> ConfigWriteResult
All config APIs return an envelope (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_snapshot when host event projection is enabled
Approval methods maintain audit records only. Requesting or deciding a record does not automatically gate, authorize, or execute an action. Records persist when the RPC bundle exposes a store path. See JSON-RPC approvals. Every public Python RPC wrapper binds its request and result transport boundary to generated RPC-schema contracts. For the families above, the generated parameter and result class names in 0.8.24 are imported from 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 key
  • export_session_atif(...) exports a session trajectory
  • read_session_transcript_revision(...) and list_session_transcript_revisions(...) inspect durable revisions
  • fork_session_at(...) and fork_session_replace(...) create a new branch
  • rewrite_session_transcript(...), update_system_prompt(...), and restore_session_transcript_revision(...) perform guarded edits

Live channel APIs

The old RealtimeChannel helper has been removed. Use LiveChannel.session(...) for a session-bound wrapper, or call the direct live/* RPC helpers on MeerkatClient.
For WebSocket instead, connect with 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.
live_webrtc=True passes the --live-webrtc process flag, which exists only when rkat-rpc was compiled with its non-default live-webrtc Cargo feature. The 0.8.24 auto-downloaded release binary and a normal default-feature build do not include that flag. From the Meerkat repository, build an explicit binary with ./scripts/repo-cargo build -p meerkat-rpc --features live-webrtc, then put it on PATH or pass its path as MeerkatClient(rkat_path).
  • 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)
Image keys are required, caller-stable, and session-scoped. The helper returns after queue acceptance; wait for 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(...) -> Mob
  • await 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
Multi-host placement and host/grant mutations are trusted operator APIs on the JSON-RPC SDK surface. They are intentionally not exposed as agent-callable mob tools. The agent-callable spawn wire also cannot declare the Rust-only resume_from_role durable role-migration authority.

Realm profile CRUD

  • await client.create_mob_profile(name, profile)
  • await client.get_mob_profile(name) -> StoredMobProfile | None
  • await 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()
Auth profiles and credentials are realm-scoped. Login/provisioning yields an auth binding that sessions and mob member specs can reference without carrying the provider secret itself; a remote member host resolves the binding within its authorized realm.

Generated assistant images

When a session model calls the built-in generate_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.
Image-generation wire contracts are also exported for integrations that inspect tool results directly: WireGenerateImageRequest, WireGenerateImageExecutionPlan, WireImageGenerationToolResult, WireImageOperationPhase, and WireAssistantImageRef.

Typed session metadata

  • SessionSummary (from session/list) includes total_tokens
  • SessionDetails (from session/read) includes model, 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.