Skip to main content

​
MutagenT SDK

The MutagenT SDK (@mutagent/sdk v0.2.65) provides type-safe, async-first access to the MutagenT Platform. It is generated from the OpenAPI specification and ships as a dual ESM + CJS package.
Most developers should start with Integration packages, which provide automatic tracing for popular frameworks like LangChain, Mastra, Vercel AI, and OpenAI. The SDK is for programmatic access and advanced use cases like CI/CD pipelines, custom tooling, and automated workflows.

​
When to Use the SDK

The SDK is the right choice when you need:
  • Direct API access — Programmatic CRUD operations on prompts, agents, datasets, evaluations, and traces
  • CI/CD pipelines — Automated prompt optimization, evaluation runs, or deployment scripts
  • Custom tooling — Building internal tools, dashboards, or workflows on top of the MutagenT API
  • Building your own integration — Creating a custom adapter for a framework not yet supported by the official integration packages
  • Advanced tracing — Fine-grained manual instrumentation with @trace(), withTrace(), or the low-level span API
For framework-specific tracing with minimal setup, see the Integrations section instead.
CLI First: For most use cases, start with the CLI. Use mutagent integrate to generate SDK integration code for your framework.

​
Available SDKs

LanguageStatusPackageVersion
TypeScriptAvailable@mutagent/sdk0.2.65
PythonComing Soonmutagent—

​
Design Principles

Type-Safe

Full TypeScript support with Zod validation on all request/response types

Async-First

All operations return Promises for modern async/await patterns

REST-Aligned

Method names mirror REST API resources for predictability

Minimal

Small bundle size, tree-shakeable, zero unnecessary dependencies

​
Quick Example

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

// API key is auto-read from MUTAGENT_API_KEY env var
const client = new Mutagent();

// List prompts
const prompts = await client.prompt.listPrompts({ limit: 10 });

// Get a specific prompt
const prompt = await client.prompt.getPrompt({ id: 'prompt-id' });

// Create a new prompt
const newPrompt = await client.prompt.createPrompt({
  name: 'My Prompt',
  rawPrompt: 'You are a helpful assistant.',
});

// Update an existing prompt
const updated = await client.prompt.updatePrompt({
  id: 'prompt-id',
  descriptionIsLatestSystemPrompt: {
    description: 'Updated description',
  },
});

​
SDK Architecture

The SDK organizes operations by resource namespace:
NamespaceDescription
client.promptPrompt CRUD and versioning
client.promptDatasetsPrompt dataset management
client.promptDatasetItemsDataset item operations
client.promptEvaluationsEvaluation runs and results
client.optimizationPrompt optimization jobs
client.agentsAgent CRUD operations
client.agentDatasetsAgent dataset management
client.agentDatasetItemsAgent dataset item operations
client.agentConversationsAgent conversation management
client.agentChatStreamingStreaming agent chat
client.conversationsConversation operations
client.tracesTrace ingestion and querying
client.workspacesWorkspace management
client.organizationsOrganization management
client.providerConfigsLLM provider configurations
client.invitationsTeam invitation management
client.userProfileCurrent user profile

​
Error Handling

All API errors extend MutagentError, which exposes HTTP status code, body, headers, and the raw Response object. 
import { Mutagent } from '@mutagent/sdk';
import { MutagentError } from '@mutagent/sdk/models/errors';

const client = new Mutagent();

try {
  const prompt = await client.prompt.getPrompt({ id: 'nonexistent' });
} catch (error) {
  if (error instanceof MutagentError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.statusCode);
    console.error('Body:', error.body);
    console.error('Headers:', error.headers);
  }
}

​
Next Steps

TypeScript Setup

Install and configure the TypeScript SDK

Tracing Module

Custom instrumentation with the tracing API

Integrations

Framework adapters with automatic tracing

Python SDK

Python SDK status and preview