SDK - MUTAGENT

The Mutagent SDK does from code what the mutagent CLI does from a terminal. Use it when your own application, backend or test suite needs to manage your account or start Helix in the cloud.

Package	Install	Version these pages describe
TypeScript: `@mutagent/sdk`	`npm install @mutagent/sdk`	0.8 (0.8.1, the version this command installs today)
Python: `mutagent-sdk`	`pip install mutagent-sdk`	0.4.1 (Python 3.10 or newer)

Your first call

This lists your workspaces and the LLM providers in the workspace your key belongs to. Set MUTAGENT_API_KEY to an API key first. See API keys.

import { Mutagent } from '@mutagent/sdk';

const client = new Mutagent({
  security: { apiKey: process.env.MUTAGENT_API_KEY! },
});

const { workspaces } = await client.workspaces.listWorkspaces();
for (const workspace of workspaces) {
  console.log(`workspace  ${workspace.name}  ${workspace.id}`);
}

const { configs } = await client.llmProviders.listProviderConfigs();
for (const config of configs) {
  console.log(`provider   ${config.name}  ${config.provider}  active=${config.isActive}`);
}

from mutagent import Mutagent

client = Mutagent()  # reads MUTAGENT_API_KEY

for workspace in client.workspaces.list_workspaces().workspaces:
    print(f"workspace  {workspace.name}  {workspace.id_}")

for config in client.llm_providers.list_provider_configs().configs:
    print(f"provider   {config.name}  {config.provider}  active={config.is_active}")

bun list.ts        # or: npx tsx list.ts
python list.py

workspace  Default workspace  <workspace-id>
provider   Gemini  google  active=true

An empty provider list means the workspace has no LLM providers yet. Add one with mutagent providers add or from the SDK (TypeScript, Python).

What the SDK covers

Area	TypeScript	Python	Pages
Workspaces and organizations	`client.workspaces`, `client.organizations`	`client.workspaces`, `client.organizations`	TypeScript, Python
LLM providers: the model keys your cloud runs use	`client.llmProviders`	`client.llm_providers`	TypeScript, Python
Environments: variables and secrets for tools	`client.environments`	`client.environments`	TypeScript, Python
Helix Cloud: run Helix on a task or as a session	`client.helixSessions`	`client.helix_sessions`	TypeScript, Python
Managed agents: deploy and run your own `agent.md` agents	`client.managedAgents`	`client.managed_agents`	TypeScript, Python
Sandbox providers and presets	`client.sandbox`	`client.sandbox`	TypeScript, Python

For cloud sessions and managed agents, see Helix Cloud.

Keys and workspaces

Every call acts in one workspace:

With a workspace API key, calls act in that key’s workspace. Nothing else to set.
With an organization API key, send the workspace as the x-workspace-id header in the call’s request options. For example, in TypeScript: client.llmProviders.listProviderConfigs({}, { headers: { 'x-workspace-id': '<workspace-id>' } }).

Helix Cloud and Environment calls also take a short-lived sandbox token that you get from your API key. The Helix Cloud page shows how.

Added in TypeScript SDK 0.7

These groups need @mutagent/sdk 0.7 or later; the install command above gets a newer version. The Python SDK does not have them yet.

Version 0.7 adds these groups to the TypeScript client:

Group	What it does
`client.reports`	Store and list Helix’s evaluation and diagnosis reports, mark them reviewed, read the individual problems each report found (findings), and the problems you filed for follow-up (triage items). The same as `mutagent reports`.
`client.inbox`	List your notifications and mark them read.
`client.integrations`	Connect trace sources and pull traces from them.
`client.helixCloud`	Start and follow Helix Cloud sessions from an application: check a workspace is ready to run, answer the approvals a session asks for, attach files. A message sent to a session that stopped because it was idle wakes the session and is delivered.
`client.gateway`	Connect GitHub and Slack, and manage triggers, routines and runs.

client.helixSessions and client.helixCloud both start cloud sessions; use the one that fits the job. client.helixSessions launches a session in a sandbox (headless or interactive, managed agents included) and drives it by its reference: send, signal, checkpoint, restore, stream. It is what the CLI uses, and what the Helix Cloud page documents. client.helixCloud starts the sessions the web app shows: a session with a goal and, optionally, a repository branch, which you can list, rename, archive, answer approvals for and attach files to. For scripted runs and managed agents, use client.helixSessions. Version 0.7 also adds calls to groups you already use:

Group	What is new
`client.environments`	Environment calls that take your API key, so you do not need a sandbox token. Change several Environments in one call. Read a variable’s value (secrets are never returned).
`client.managedAgents`	Read a managed agent’s files, spec, activity and past operations.
`client.sandbox`	List sandbox providers with your API key, with each provider’s details.

​Your first call

​What the SDK covers

​Keys and workspaces

​Added in TypeScript SDK 0.7

Your first call

What the SDK covers

Keys and workspaces

Added in TypeScript SDK 0.7