> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> MutagenT SDK architecture and patterns

# MutagenT SDK

The MutagenT SDK (`@mutagent/sdk` v0.2.137) 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.

<Note>
  **Most developers should start with [Integration packages](/integrations/overview)**, 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.
</Note>

## 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](/integrations/overview) section instead.

<Tip>
  **CLI First**: For most use cases, start with the [CLI](/cli/overview). Use `mutagent integrate` to generate SDK integration code for your framework.
</Tip>

## Available SDKs

| Language   | Status    | Package         | Version   |
| ---------- | --------- | --------------- | --------- |
| TypeScript | Available | `@mutagent/sdk` | `0.2.137` |
| Python     | Available | `mutagent-sdk`  | `0.1.1`   |

## Design Principles

<CardGroup cols={2}>
  <Card title="Type-Safe" icon="shield-check">
    Full TypeScript support with Zod validation on all request/response types
  </Card>

  <Card title="Async-First" icon="bolt">
    All operations return Promises for modern async/await patterns
  </Card>

  <Card title="REST-Aligned" icon="server">
    Method names mirror REST API resources for predictability
  </Card>

  <Card title="Minimal" icon="feather">
    Small bundle size, tree-shakeable, zero unnecessary dependencies
  </Card>
</CardGroup>

## Quick Example

```typescript theme={null}
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

<Mermaid>
  flowchart LR
  Client\["Mutagent"] --> Resources

  subgraph Resources\["Resource Namespaces"]
  direction TB
  P\["prompt"]
  D\["promptDatasets"]
  DI\["promptDatasetItems"]
  E\["promptEvaluations"]
  O\["optimization"]
  A\["agents"]
  AD\["agentDatasets"]
  T\["traces"]
  W\["workspaces"]
  PC\["providerConfigs"]
  end

  P --> Methods\["list / get / create / update / delete"]

  style Client fill:#7C3AED,color:#fff
  style P fill:#06B6D4,color:#000
  style D fill:#06B6D4,color:#000
  style DI fill:#06B6D4,color:#000
  style E fill:#06B6D4,color:#000
  style O fill:#06B6D4,color:#000
  style A fill:#06B6D4,color:#000
  style AD fill:#06B6D4,color:#000
  style T fill:#06B6D4,color:#000
  style W fill:#06B6D4,color:#000
  style PC fill:#06B6D4,color:#000
</Mermaid>

The SDK organizes operations by resource namespace:

| Namespace                   | Description                   |
| --------------------------- | ----------------------------- |
| `client.prompt`             | Prompt CRUD and versioning    |
| `client.promptDatasets`     | Prompt dataset management     |
| `client.promptDatasetItems` | Dataset item operations       |
| `client.promptEvaluations`  | Evaluation runs and results   |
| `client.optimization`       | Prompt optimization jobs      |
| `client.agents`             | Agent CRUD operations         |
| `client.agentDatasets`      | Agent dataset management      |
| `client.agentDatasetItems`  | Agent dataset item operations |
| `client.traces`             | Trace ingestion and querying  |
| `client.experiments`        | Manage experiments            |
| `client.promptReadiness`    | Prompt readiness checks       |
| `client.promptExecutions`   | Prompt execution management   |
| `client.playground`         | Playground interactions       |
| `client.workspaces`         | Workspace management          |
| `client.organizations`      | Organization management       |
| `client.providerConfigs`    | LLM provider configurations   |
| `client.invitations`        | Team invitation management    |
| `client.userProfile`        | Current user profile          |

## Error Handling

All API errors extend `MutagentError`, which exposes HTTP status code, body, headers, and the raw `Response` object.

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="TypeScript Setup" icon="js" href="/sdk/typescript/installation">
    Install and configure the TypeScript SDK
  </Card>

  <Card title="Tracing Module" icon="radar" href="/sdk/typescript/tracing">
    Custom instrumentation with the tracing API
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/integrations/overview">
    Framework adapters with automatic tracing
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python/installation">
    Install and use the Python SDK
  </Card>
</CardGroup>