MutagenT Python SDK

The Python client for the MutagenT platform API.

Status: mutagent-sdk is 0.4.1 on PyPI, generated from openapi.json via mutagent-xgen. Mutagent (sync) and AsyncMutagent (async) expose the same 13 groups. Streaming (sandbox.stream_sandbox, helix_sessions.stream_helix_session) is known-limited — see Reference § Known limitations.

Context

mutagent-sdk is the official Python client for the MutagenT platform API, generated from the platform's OpenAPI document by mutagent-xgen, MutagenT's in-house SDK generator. A Pydantic v2 model covers every request/response body in the API spec. See the root README for where this SDK sits relative to the platform API and the other clients (TypeScript SDK, CLI).

Concepts

• Groups — one namespace per API tag (client.agents, client.sandbox, …), each with a sync method on Mutagent and an async form on AsyncMutagent. See the table in Components.
• Models — a Pydantic v2 model for every request/response body; a ...TypedDict counterpart accepts the same fields as a plain dict.
• Two-credential model — a platform api_key for most groups, versus a short-lived sandbox bearer token for sandbox, environments and helix_sessions; see Cloud Sandboxes, Environments and Helix Sessions.
• HTTPS by default — a plain-HTTP server_url is refused for a non-local host unless allow_insecure_http=True.
• Request bodies — a method that sends a body accepts either a model instance or a plain dict with the API's camelCase wire names.
• SDKError — the uniform exception for any non-2xx response, carrying status_code, body and the raw httpx.Response.

Components

mutagent-sdk-python/
├── openapi.json          # fetched from a running server via scripts/dump-spec.sh
├── .mutagen/               # mutagent-xgen config (gen.yaml, gen.lock)
├── src/mutagent/
│   ├── client.py           # Mutagent (sync)
│   ├── async_client.py     # AsyncMutagent
│   ├── <group>.py           # one file per group (agents.py, sandbox.py, …)
│   ├── models/               # [generated] Pydantic models
│   ├── lib/                   # [generated] security, HTTP helpers
│   └── _funcs/                 # [generated] per-operation implementations
├── docs/sdks/                # [generated] one page per group
├── tests/                     # pytest suite
└── README.md, CHANGELOG.md, CLAUDE.md   # hand-maintained (safe to edit; see CLAUDE.md)

Quick start

from mutagent import Mutagent

client = Mutagent(api_key="YOUR_API_KEY")

agents = client.agents.list_agents(limit=10)
print(f"Found {len(agents['data'])} agents")

server_url defaults to MUTAGENT_SERVER_URL, and to https://api.mutagent.io when that is unset (see Configuration); pass server_url="http://localhost:3003" for a local server. Set MUTAGENT_API_KEY in your environment to omit api_key entirely:

from mutagent import Mutagent

client = Mutagent()  # reads MUTAGENT_API_KEY

Async client:

import asyncio
from mutagent import AsyncMutagent

async def main():
    async with AsyncMutagent(api_key="YOUR_API_KEY") as client:
        profile = await client.user_profile.get_profile()
        print(profile)
        print(await client.workspaces.list_workspaces())

asyncio.run(main())

A dict request body is sent as written (camelCase keys); a model instance accepts either the snake_case field name or the camelCase alias:

agent = client.agents.create_agent({
    "name": "Support Agent",
    "slug": "support-agent",
    "systemPrompt": "You answer customer support questions.",
})

A non-2xx response raises SDKError:

from mutagent import Mutagent, SDKError

client = Mutagent()
try:
    client.agents.get_agent(404)
except SDKError as e:
    print(f"HTTP {e.status_code}: {e.body}")

Groups

Per-method reference lives in docs/sdks/, one page per group:

# Organizations, members and invitations
members = client.organization_members.list_organization_members("<org-id>")
invitation = client.invitations.create_invitation("<org-id>", {"email": "dev@example.com", "role": "editor"})

# LLM providers
provider = client.llm_providers.create_provider_config({"name": "Anthropic", "provider": "anthropic", "apiKey": "<provider-key>"})
print(client.llm_providers.test_provider_config(provider["id"]))

Cloud Sandboxes, Environments and Helix Sessions

sandbox, environments and helix_sessions call routes that accept only a short-lived sandbox token, sent as Authorization: Bearer. Exchange your API key for one via sandbox.create_sandbox_token, then pass the result to a second client as bearer_token. An explicit bearer_token wins over MUTAGENT_API_KEY; passing both api_key and bearer_token raises ValueError.

from mutagent import Mutagent
from mutagent.models import HelixSignal, Mode

platform = Mutagent(api_key="YOUR_API_KEY")
token = platform.sandbox.create_sandbox_token({"workspaceId": "<workspace-id>"})

client = Mutagent(bearer_token=token["token"])
session = client.helix_sessions.launch_helix_session(body={"mode": Mode.INTERACTIVE})
client.helix_sessions.send_helix_session_input(
    session["reference"],
    {"line": '{"type": "prompt", "id": "p1", "message": "List the files"}'},
)
client.helix_sessions.signal_helix_session(session["reference"], {"signal": HelixSignal.SIGINT})

Full route list per group: the Groups reference pages above.

Configuration

Both are user-set (this package owns no platform infrastructure). See .env.example for placeholder values.

Reference

0.4.0 breaking changes

0.4.0 is the first published release to carry these changes. Code written against 0.1.1 needs the following (two versions sit between them on PyPI — 0.2.0 and 0.3.0 — both later builds of the same pre-rename client, so every rename here applies when upgrading from either; #2028 reset the repository's version to 0.2.0, a number PyPI already held, so no Python release could publish until 0.4.0).

Client groups

• sandbox holds sandbox providers, presets, the sandbox lifecycle, commands, the token exchange (create_sandbox_token) and the session routes addressed by sandbox id.
• New group helix_sessions: launch_helix_session, list_helix_sessions, send_helix_session_input, close_helix_session_input, signal_helix_session, checkpoint_helix_session, list_helix_session_checkpoints, restore_helix_session, stream_helix_session, get_helix_models, set_helix_default_models. These existed as sandbox methods in 0.1.1.
• New group environments. In 0.1.1 its operations were methods of sandbox.
• helix_agent_deployments is renamed managed_agents; method names are unchanged.
• provider_configs is renamed llm_providers; its methods are renamed too (table below).
• user_profile keeps its name; two of its methods are renamed (table below).

• Model and enum names in mutagent.models come from the schema names in the API document (Mode, HelixArm, HelixSignal, HelixLaunchRequest, LlmProviderType, ErrorResponse). Generator-invented names from 0.1.1 (Schemadefaul7, ModeArmModel, NameSlugDescription5) no longer exist. String enums (Mode, HelixArm, HelixSignal, QueryFlag, WorkspaceDriftPolicy) subclass str, so a member compares equal to its value (Mode.HEADLESS == "headless").
• Session mode values: "headless" or "interactive" (Mode.HEADLESS, Mode.INTERACTIVE). The 0.1.1 values "oneshot" and "rpc" are gone.
• Default server: https://api.mutagent.io when server_url and MUTAGENT_SERVER_URL are both unset; was http://localhost:3003 in 0.1.1.
• Stream methods: sandbox.stream_sandbox and helix_sessions.stream_helix_session changed — see Known limitations below.

Known limitations

• A field whose wire name is a Python keyword or builtin is escaped on the model (Workspace.id is read as workspace.id_); the alias keeps the wire name, so both directions still send and receive id.
• Streaming in 0.4.1: the sync stream_sandbox and stream_helix_session send Accept: application/json, read the whole response, and return None — the event data is discarded. The async versions raise TypeError before a request is sent.

Generated by mutagent-xgen

This package is generated by mutagent-xgen. To regenerate after API changes:

bash scripts/dump-spec.sh   # fetch latest spec from a running server
mutagent-xgen run            # regenerate the SDK

README.md is emitted once and never rewritten by a regeneration, so hand-written content here is safe.

License

This SDK is released under the Apache License 2.0.

Copyright 2026 MutagenT. All rights reserved.

_{Built with care by the MutagenT Team • mutagent.io}