@mutagent/sdk 0.5.12 → 0.5.13

package/README.npm.md

@@ -24,61 +24,147 @@
 </p>
 
 <p align="center">
-  <strong>Type-safe. Framework-agnostic. Production-ready.</strong><br>
-  <em>The official TypeScript SDK for the MutagenT AI Engineering Platform.</em>
+  <em>The TypeScript client for the MutagenT platform API.</em>
 </p>
 
 ---
 
 ## Table of Contents
 
-- [What is MutagenT SDK?](#what-is-mutagent-sdk)
-- [Features](#features)
+- [What the SDK covers](#what-the-sdk-covers)
+- [0.6.0 breaking changes](#060-breaking-changes)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Authentication](#authentication)
-- [Prompts](#prompts)
-- [Datasets](#datasets)
-- [Evaluations](#evaluations)
-- [Optimization](#optimization)
-- [Tracing & Observability](#tracing--observability)
-- [Agents](#agents)
-- [Playground](#playground)
+- [Client groups](#client-groups)
+- [Streaming](#streaming)
 - [Pagination](#pagination)
 - [Retries](#retries)
 - [Error Handling](#error-handling)
+- [Server Selection](#server-selection)
 - [Custom HTTP Client](#custom-http-client)
-- [Tree-shakeable Imports](#tree-shakeable-imports)
-- [TypeScript Support](#typescript-support)
-- [Framework Integrations](#framework-integrations)
+- [Standalone functions](#standalone-functions)
+- [Debugging](#debugging)
 - [API Reference](#api-reference)
 - [See Also](#see-also)
+- [License](#license)
 
 ---
 
-## What is MutagenT SDK?
-
-The **MutagenT SDK** is a developer-friendly, type-safe TypeScript client for the [MutagenT AI platform](https://mutagent.io). It gives you programmatic access to everything MutagenT offers: create and version prompts, upload evaluation datasets, run automated evaluations, trigger auto-optimization jobs, collect LLM traces, and manage AI agents — all from your own code.
+## What the SDK covers
+
+`@mutagent/sdk` is generated from the MutagenT platform OpenAPI document. One `Mutagent` client
+exposes 13 groups of methods:
+
+| Group | What it calls |
+|-------|---------------|
+| `userProfile` | The signed-in user's profile, password and login sessions |
+| `organizations` | Organizations, slug lookups and member counts |
+| `organizationMembers` | Organization membership and roles |
+| `workspaces` | Workspaces and the default workspace |
+| `workspaceMembers` | Workspace membership and roles |
+| `invitations` | Organization invitations |
+| `agents` | Agent records: create, read, update, delete, look up by slug |
+| `llmProviders` | LLM provider configurations, model catalog, connection tests |
+| `managedAgents` | Managed agent deployments: slots, revisions, operations |
+| `traces` | Trace ingestion and reads of traces, spans and logs |
+| `sandbox` | Sandbox providers, presets, sandbox lifecycle, commands, the sandbox token exchange, and Helix sessions addressed by sandbox id |
+| `environments` | Workspace Environments (named sets of variables and secrets) |
+| `helixSessions` | Helix sessions addressed by session reference: launch, list, input, signal, checkpoint, restore, stream |
+
+Every method is also available as a standalone function (see [Standalone functions](#standalone-functions)).
 
 ---
 
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| **Prompt Management** | Create, version, update, and delete prompts programmatically |
-| **Dataset Operations** | Upload, export, clone, and manage evaluation datasets |
-| **Evaluation Engine** | Define criteria, run automated evaluations, and retrieve scored results |
-| **Auto-Optimization** | Start optimization jobs that iteratively improve your prompts against metrics |
-| **Tracing & Observability** | OpenTelemetry-compatible tracing for LLM calls, chains, agents, and custom spans |
-| **Agents** | Create and manage AI agents with conversation history and streaming chat |
-| **Playground** | Execute and evaluate prompts interactively without running a full pipeline |
-| **Multi-tenant** | Organizations, workspaces, provider configs, and team membership |
-| **Full Type Safety** | End-to-end TypeScript with Zod-validated responses |
-| **Multiple Runtimes** | Works with Bun, Node.js, Deno, and Edge runtimes |
-| **Tree-shakeable** | Import only what you need for smaller bundles |
-| **Configurable Retries** | Per-call and global retry strategies with exponential backoff |
-| **Pagination** | Async iterable responses for all paginated list endpoints |
+## 0.6.0 breaking changes
+
+0.6.0 is one breaking release after 0.5.x. Code written against 0.5.x needs the following changes.
+
+**Client groups**
+
+- `sandbox` holds sandbox providers, presets, the sandbox lifecycle, commands, the token exchange
+  (`createSandboxToken`) and the session routes addressed by sandbox id.
+- New group `helixSessions`: `launchHelixSession`, `listHelixSessions`, `sendHelixSessionInput`,
+  `closeHelixSessionInput`, `signalHelixSession`, `checkpointHelixSession`,
+  `listHelixSessionCheckpoints`, `restoreHelixSession`, `streamHelixSession`, `getHelixModels`,
+  `setHelixDefaultModels`. The ones that existed in 0.5.x were methods of `sandbox`.
+- New group `environments`. In 0.5.x its operations were methods of `sandbox`.
+- `helixAgentDeployments` is renamed `managedAgents`. Its method names are unchanged.
+- `providerConfigs` is renamed `llmProviders`. Its methods are renamed too; see the table below.
+- `userProfile` keeps its name. Two of its methods are renamed; see the table below.
+
+**Operation names**
+
+39 operations are renamed. In the first 27 rows the 0.5.x name was derived from the route. The last
+12 rows rename operations that already had their own names.
+
+| 0.5.x | 0.6.0 |
+|-------|-------|
+| `sandbox.getApiSandboxProviders` | `sandbox.listSandboxProviders` |
+| `sandbox.postApiSandboxPreflight` | `sandbox.preflightSandbox` |
+| `sandbox.getApiSandboxPresets` | `sandbox.listSandboxPresets` |
+| `sandbox.postApiSandboxRun` | `sandbox.runSandboxCommand` |
+| `sandbox.postApiSandbox` | `sandbox.createSandbox` |
+| `sandbox.getApiSandbox` | `sandbox.listSandboxes` |
+| `sandbox.getApiSandboxById` | `sandbox.getSandbox` |
+| `sandbox.deleteApiSandboxById` | `sandbox.deleteSandbox` |
+| `sandbox.getApiSandboxByIdStream` | `sandbox.streamSandbox` |
+| `sandbox.postApiSandboxByIdExec` | `sandbox.execSandboxCommand` |
+| `sandbox.postApiSandboxTelemetryV1Traces` | `sandbox.ingestSandboxTraces` |
+| `sandbox.getApiSandboxByIdTraces` | `sandbox.listSandboxSpans` |
+| `sandbox.postApiSandboxByIdSession` | `sandbox.startSandboxHelixSession` |
+| `sandbox.getApiSandboxHelixDefaults` | `helixSessions.getHelixModels` |
+| `sandbox.putApiSandboxHelixDefaults` | `helixSessions.setHelixDefaultModels` |
+| `sandbox.getApiSandboxByIdSessions` | `sandbox.listSandboxHelixSessions` |
+| `sandbox.postApiSandboxByIdInput` | `sandbox.sendSandboxHelixSessionInput` |
+| `sandbox.postApiSandboxByIdSignal` | `sandbox.signalSandboxHelixSession` |
+| `sandbox.postApiSandboxByIdCheckpoint` | `sandbox.checkpointSandboxHelixSession` |
+| `sandbox.getApiSandboxByIdCheckpoints` | `sandbox.listSandboxCheckpoints` |
+| `sandbox.postApiSandboxByIdRestore` | `sandbox.restoreSandbox` |
+| `sandbox.postApiSandboxToken` | `sandbox.createSandboxToken` |
+| `sandbox.getApiSandboxEnvironments` | `environments.listEnvironments` |
+| `sandbox.getApiSandboxEnvironmentsByName` | `environments.getEnvironment` |
+| `sandbox.putApiSandboxEnvironmentsByName` | `environments.replaceEnvironment` |
+| `sandbox.patchApiSandboxEnvironmentsByName` | `environments.updateEnvironment` |
+| `sandbox.deleteApiSandboxEnvironmentsByName` | `environments.deleteEnvironment` |
+| `userProfile.listSessions` | `userProfile.listUserSessions` |
+| `userProfile.deleteSession` | `userProfile.revokeUserSession` |
+| `sandbox.listHelixWorkspaceSessions` | `helixSessions.listHelixSessions` |
+| `sandbox.inputHelixSession` | `helixSessions.sendHelixSessionInput` |
+| `providerConfigs.listProviders` | `llmProviders.listProviderConfigs` |
+| `providerConfigs.createProvider` | `llmProviders.createProviderConfig` |
+| `providerConfigs.getProvider` | `llmProviders.getProviderConfig` |
+| `providerConfigs.updateProvider` | `llmProviders.updateProviderConfig` |
+| `providerConfigs.deleteProvider` | `llmProviders.deleteProviderConfig` |
+| `providerConfigs.getModelsCatalog` | `llmProviders.getModelCatalog` |
+| `providerConfigs.listProviderModels` | `llmProviders.listProviderConfigModels` |
+| `providerConfigs.testProvider` | `llmProviders.testProviderConfig` |
+
+The standalone function names follow the same change, including the group prefix. For example
+`sandboxGetApiSandboxById` is now `sandboxGetSandbox`, and `providerConfigsTestProvider` is now
+`llmProvidersTestProviderConfig`.
+
+**Model, enum and error names**
+
+Model, enum and error class names come from the schema names in the API document, for example
+`Mode`, `HelixArm`, `HelixSignal`, `HelixLaunchRequest`, `LlmProviderType` and
+`ErrorResponse`. Names the generator invented in 0.5.x, such as `Schemadefaul7`, `ModeArmModel` and
+`NameSlugDescription5`, no longer exist.
+
+**Session mode values**
+
+A Helix session mode is `headless` or `interactive` (`Mode.Headless`, `Mode.Interactive`). The
+0.5.x values `oneshot` and `rpc` are gone.
+
+**Default server**
+
+The default server is `https://api.mutagent.io`. In 0.5.x it was `http://localhost:3003`. To call a
+local server, pass `serverURL: "http://localhost:3003"` or `serverIdx: 1`.
+
+**Streams**
+
+`streamHelixSession` and `streamSandbox` send `Accept: text/event-stream`. They resolve to the event
+text as one string when the server closes the stream. They do not yield events as they arrive.
 
 ---
 
@@ -108,630 +194,390 @@ yarn add @mutagent/sdk
 bun add @mutagent/sdk
 ```
 
-> This package ships both CommonJS (`require`) and ES Modules (`import`) builds.
+This package ships CommonJS (`require`) and ES module (`import`) builds. Supported runtimes are listed
+in [RUNTIMES.md](./RUNTIMES.md).
 
 ---
 
 ## Quick Start
 
 ```typescript
-import { Mutagent } from '@mutagent/sdk';
+import { Mutagent } from "@mutagent/sdk";
 
 const mutagent = new Mutagent({
   security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
+    apiKey: process.env["MUTAGENT_API_KEY"] ?? "",
   },
 });
 
-// Create a prompt
-const prompt = await mutagent.prompt.createPrompt({
-  name: 'Customer Support Template',
-  content: 'You are a helpful support agent. User query: {{query}}',
-  variables: ['query'],
-});
-
-// Add a dataset
-const dataset = await mutagent.promptDatasets.createPromptDataset({
-  id: prompt.id,
-  name: 'Support Tickets',
-});
-
-await mutagent.promptDatasetItems.bulkCreatePromptDatasetItems({
-  id: dataset.id,
-  items: [
-    { input: { query: 'How do I reset my password?' }, expected: '...' },
-    { input: { query: 'What are your business hours?' }, expected: '...' },
-  ],
-});
+async function run() {
+  const profile = await mutagent.userProfile.getProfile();
+  console.log(profile);
 
-// Start optimization
-const job = await mutagent.optimization.optimizePrompt({
-  id: prompt.id,
-  datasetId: dataset.id,
-  metric: 'response_quality',
-});
+  const workspaces = await mutagent.workspaces.listWorkspaces();
+  console.log(workspaces);
+}
 
-console.log(`Optimization started: ${job.id}`);
+run();
 ```
 
 ---
 
 ## Authentication
 
-### API Key
+The `security` option has two fields. Both are read from the environment when you do not pass them.
 
-```typescript
-import { Mutagent } from '@mutagent/sdk';
+| Option | Sent as | Environment variable | Used by |
+|--------|---------|----------------------|---------|
+| `apiKey` | `x-api-key` header | `MUTAGENT_API_KEY` | Every group except `sandbox`, `environments` and `helixSessions` |
+| `bearerAuth` | `Authorization: Bearer` header | `MUTAGENT_BEARER_AUTH` | `sandbox` (except `createSandboxToken`), `environments` and `helixSessions`, which accept no other credential. The other groups also declare it |
 
-const mutagent = new Mutagent({
-  security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
-  },
-});
-```
+When an operation accepts both and both are set, the SDK sends the API key.
 
-### Bearer Token
+### API key
+
+A platform API key starts with `mg_live_`. Create one in the MutagenT app under Settings, API Keys.
 
 ```typescript
+import { Mutagent } from "@mutagent/sdk";
+
 const mutagent = new Mutagent({
-  security: {
-    bearerAuth: process.env.MUTAGENT_BEARER_AUTH,
-  },
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
 });
 ```
 
-### Authentication Schemes
-
-| Scheme | Type | Environment Variable |
-|--------|------|----------------------|
-| `apiKey` | API Key | `MUTAGENT_API_KEY` |
-| `bearerAuth` | HTTP Bearer | `MUTAGENT_BEARER_AUTH` |
-
-Both schemes are supported globally and apply to all operations.
-
----
-
-## Prompts
-
-Prompts are the core resource in MutagenT. Every dataset, evaluation, and optimization job is scoped to a prompt.
+### Sandbox token
 
-### Create a Prompt
+The `sandbox`, `environments` and `helixSessions` operations do not accept an API key. They require a
+short-lived sandbox token, sent as a bearer token. Exchange an API key for one with
+`sandbox.createSandboxToken`. That call takes the API key in its own first argument; it does not read
+the client's `security` option or `MUTAGENT_API_KEY`.
 
 ```typescript
-const prompt = await mutagent.prompt.createPrompt({
-  name: 'Summarizer',
-  content: 'Summarize the following text concisely: {{text}}',
-  variables: ['text'],
-  outputSchema: {
-    type: 'object',
-    properties: {
-      summary: { type: 'string' },
-      keyPoints: { type: 'array', items: { type: 'string' } },
-    },
-    required: ['summary'],
-  },
-});
-```
+import { Mutagent } from "@mutagent/sdk";
 
-### List Prompts
+async function sandboxClient(workspaceId: string): Promise<Mutagent> {
+  const apiKey = process.env["MUTAGENT_API_KEY"] ?? "";
+  const platform = new Mutagent({ security: { apiKey } });
 
-```typescript
-const prompts = await mutagent.prompt.listPrompts();
+  const { token, expiresIn } = await platform.sandbox.createSandboxToken(
+    { apiKey },
+    { workspaceId },
+  );
+  console.log(`sandbox token expires in ${expiresIn}s`);
 
-// With pagination
-for await (const page of prompts) {
-  console.log(page);
+  // apiKey stays in place for the platform groups; bearerAuth is used by
+  // sandbox, environments and helixSessions.
+  return new Mutagent({ security: { apiKey, bearerAuth: token } });
 }
 ```
 
-### Get a Prompt
-
-```typescript
-const prompt = await mutagent.prompt.getPrompt({ id: 'prompt-id' });
-```
-
-### Update a Prompt
-
-```typescript
-await mutagent.prompt.updatePrompt({
-  id: 'prompt-id',
-  content: 'Updated template: {{input}}',
-  name: 'Updated Name',
-});
-```
-
-### Delete a Prompt
-
-```typescript
-await mutagent.prompt.deletePrompt({ id: 'prompt-id' });
-```
-
-### Prompt Versioning
-
-Every update creates a new version. You can also create versions explicitly:
-
-```typescript
-// Create a new version
-const version = await mutagent.prompt.createPromptVersion({
-  id: 'prompt-id',
-  content: 'Revised version of the prompt: {{input}}',
-});
-
-// List all versions
-const versions = await mutagent.prompt.listPromptVersions({ id: 'prompt-id' });
-
-// Get analytics across versions
-const analytics = await mutagent.prompt.getPromptAnalytics({ id: 'prompt-id' });
-
-// Compare model performance across versions
-const comparisons = await mutagent.prompt.getPromptModelComparisons({ id: 'prompt-id' });
-```
+`security` also accepts an async function that returns the credentials, which lets you refresh the
+sandbox token before it expires.
 
 ---
 
-## Datasets
-
-Datasets hold the input/expected-output pairs used for evaluations and optimization.
+## Client groups
 
-### Create a Dataset
-
-```typescript
-const dataset = await mutagent.promptDatasets.createPromptDataset({
-  id: 'prompt-id',
-  name: 'Production Queries',
-  description: 'Real queries sampled from production traffic',
-});
-```
-
-### Add Items
-
-```typescript
-// Single item
-await mutagent.promptDatasetItems.createPromptDatasetItem({
-  id: dataset.id,
-  input: { query: 'What is the return policy?' },
-  expected: { summary: 'Returns accepted within 30 days with receipt.' },
-});
-
-// Bulk add (recommended for large datasets)
-await mutagent.promptDatasetItems.bulkCreatePromptDatasetItems({
-  id: dataset.id,
-  items: [
-    { input: { query: 'How do I cancel?' }, expected: { summary: '...' } },
-    { input: { query: 'Where is my order?' }, expected: { summary: '...' } },
-  ],
-});
-```
+The examples below assume a client built as in [Authentication](#authentication). Examples for
+`sandbox`, `environments` and `helixSessions` need a client that holds a sandbox token.
 
-### List, Get, Update, Delete Items
+### userProfile
 
 ```typescript
-// List items
-const items = await mutagent.promptDatasetItems.listPromptDatasetItems({ id: dataset.id });
+import { Mutagent } from "@mutagent/sdk";
 
-// Get a specific item
-const item = await mutagent.promptDatasetItems.getPromptDatasetItem({
-  id: dataset.id,
-  itemId: 'item-id',
-});
-
-// Update an item
-await mutagent.promptDatasetItems.updatePromptDatasetItem({
-  id: dataset.id,
-  itemId: 'item-id',
-  expected: { summary: 'Corrected expected output.' },
-});
-
-// Delete an item
-await mutagent.promptDatasetItems.deletePromptDatasetItem({
-  id: dataset.id,
-  itemId: 'item-id',
-});
+async function example(mutagent: Mutagent) {
+  const profile = await mutagent.userProfile.getProfile();
+  const sessions = await mutagent.userProfile.listUserSessions();
+  console.log(profile, sessions);
+}
 ```
 
-### Clone and Export
+### organizations
 
 ```typescript
-// Clone a dataset
-const clone = await mutagent.promptDatasets.clonePromptDataset({ id: dataset.id });
+import { Mutagent } from "@mutagent/sdk";
 
-// Export a dataset
-const exported = await mutagent.promptDatasets.exportPromptDataset({ id: dataset.id });
+async function example(mutagent: Mutagent) {
+  const organization = await mutagent.organizations.getOrganizationBySlug({ slug: "acme" });
+  const memberCount = await mutagent.organizations.getOrganizationMemberCount({ orgId: "<org-id>" });
+  console.log(organization, memberCount);
+}
 ```
 
----
-
-## Evaluations
-
-Evaluations score your prompt's outputs against defined criteria using a dataset.
-
-### Create an Evaluation
+### organizationMembers
 
 ```typescript
-const evaluation = await mutagent.promptEvaluations.createEvaluation({
-  promptId: 'prompt-id',
-  datasetId: 'dataset-id',
-  name: 'Quality Check',
-  evalConfig: {
-    criteria: [
-      { name: 'Accuracy', description: 'Is the output factually accurate?' },
-      { name: 'Conciseness', description: 'Is the output appropriately brief?' },
-    ],
-  },
-});
-```
+import { Mutagent } from "@mutagent/sdk";
 
-### Run an Evaluation
-
-```typescript
-await mutagent.promptEvaluations.runEvaluation({ id: evaluation.id });
+async function example(mutagent: Mutagent) {
+  const members = await mutagent.organizationMembers.listOrganizationMembers({ orgId: "<org-id>" });
+  console.log(members);
+}
 ```
 
-### Get Evaluation Results
+### workspaces
 
 ```typescript
-const results = await mutagent.promptEvaluations.getEvaluationResult({
-  id: evaluation.id,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-console.log(`Score: ${results.overallScore}`);
+async function example(mutagent: Mutagent) {
+  const workspace = await mutagent.workspaces.createWorkspace({
+    name: "Support",
+    slug: "support",
+  });
+  await mutagent.workspaces.setDefaultWorkspace({ wsId: workspace.id });
+}
 ```
 
-### Evaluation Version History
+### workspaceMembers
 
 ```typescript
-// Get evaluation version history
-const history = await mutagent.promptEvaluations.getEvaluationHistory({
-  id: evaluation.id,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-// Get results aggregated by prompt version
-const aggregated = await mutagent.promptEvaluations.getEvaluationResultsAggregated({
-  id: evaluation.id,
-});
+async function example(mutagent: Mutagent) {
+  const members = await mutagent.workspaceMembers.listWorkspaceMembers({ wsId: "<workspace-id>" });
+  console.log(members);
+}
 ```
 
----
-
-## Optimization
-
-The optimization engine automatically improves your prompts based on evaluation metrics.
-
-### Start an Optimization Job
+### invitations
 
 ```typescript
-const job = await mutagent.optimization.optimizePrompt({
-  id: 'prompt-id',
-  datasetId: 'dataset-id',
-  metric: 'response_quality',
-  maxIterations: 5,
-  targetScore: 0.95,
-});
+import { Mutagent } from "@mutagent/sdk";
+import { OrganizationRole } from "@mutagent/sdk/models";
 
-console.log(`Job started: ${job.id}`);
+async function example(mutagent: Mutagent) {
+  const invitation = await mutagent.invitations.createInvitation({
+    orgId: "<org-id>",
+    body: { email: "dev@example.com", role: OrganizationRole.Editor },
+  });
+  console.log(invitation.id);
+}
 ```
 
-### Poll Job Status
+### agents
 
 ```typescript
-const status = await mutagent.optimization.getOptimization({ id: job.id });
-
-console.log(`Status: ${status.status}`);  // 'running' | 'paused' | 'completed' | 'failed'
-```
-
-### Track Score Progression
+import { Mutagent } from "@mutagent/sdk";
 
-```typescript
-const progress = await mutagent.optimization.getOptimizationProgress({ id: job.id });
+async function example(mutagent: Mutagent) {
+  const agent = await mutagent.agents.createAgent({
+    name: "Support Agent",
+    slug: "support-agent",
+    systemPrompt: "You answer customer support questions.",
+  });
 
-// Returns an array of (iteration, score) pairs
-for (const point of progress.scores) {
-  console.log(`Iteration ${point.iteration}: ${point.score}`);
+  const sameAgent = await mutagent.agents.getAgentBySlug({ slug: "support-agent" });
+  await mutagent.agents.updateAgent({ id: agent.id, body: { description: "Tier 1 support" } });
+  console.log(sameAgent.id === agent.id);
 }
 ```
 
-### Get Final Results
-
-```typescript
-const results = await mutagent.optimization.getOptimizationResults({ id: job.id });
-
-console.log(`Best version: ${results.bestVersionId}`);
-console.log(`Score improvement: ${results.baselineScore} → ${results.bestScore}`);
-```
-
-### Pause, Resume, and Cancel
+### llmProviders
 
 ```typescript
-await mutagent.optimization.pauseOptimization({ id: job.id });
-await mutagent.optimization.resumeOptimization({ id: job.id });
-await mutagent.optimization.cancelOptimization({ id: job.id });
-```
-
----
-
-## Tracing & Observability
-
-The SDK ships a built-in OpenTelemetry-compatible tracing module. It captures LLM calls, chains, agents, and custom operations and sends them to MutagenT for analysis.
-
-### Initialize Tracing
-
-Call `initTracing` once at application startup:
+import { Mutagent } from "@mutagent/sdk";
+import { LlmProviderType } from "@mutagent/sdk/models";
 
-```typescript
-import { initTracing, shutdownTracing } from '@mutagent/sdk';
-
-initTracing({
-  apiKey: process.env.MUTAGENT_API_KEY!,
-  endpoint: 'https://api.mutagent.io',
-  environment: 'production',
-  batchSize: 10,        // spans per flush batch (default: 10)
-  flushInterval: 5000,  // flush interval in ms (default: 5000)
-});
+async function example(mutagent: Mutagent) {
+  const provider = await mutagent.llmProviders.createProviderConfig({
+    name: "Anthropic",
+    provider: LlmProviderType.Anthropic,
+    apiKey: process.env["ANTHROPIC_API_KEY"] ?? "",
+  });
 
-// Flush and close on app exit
-process.on('SIGTERM', async () => {
-  await shutdownTracing();
-  process.exit(0);
-});
+  const test = await mutagent.llmProviders.testProviderConfig({ id: provider.id });
+  const models = await mutagent.llmProviders.listProviderConfigModels({ id: provider.id });
+  console.log(test, models);
+}
 ```
 
-### @trace Decorator
-
-The easiest way to instrument class methods:
+### managedAgents
 
 ```typescript
-import { trace } from '@mutagent/sdk';
-
-class SupportAgent {
-  @trace({ kind: 'agent', name: 'support-agent' })
-  async handleQuery(query: string) {
-    const response = await this.generate(query);
-    return response;
-  }
+import { Mutagent } from "@mutagent/sdk";
 
-  @trace({ kind: 'llm.chat', name: 'gpt-4o' })
-  private async generate(query: string) {
-    // LLM call — traced automatically with input/output/duration
-    return callOpenAI(query);
+async function example(mutagent: Mutagent) {
+  const agents = await mutagent.managedAgents.listHelixAgents({ limit: 20 });
+  for (const agent of agents.data) {
+    const detail = await mutagent.managedAgents.getHelixAgent({ slug: agent.slug });
+    console.log(detail);
   }
 }
 ```
 
-### withTrace Wrapper
-
-For functional-style code or when you need fine-grained control:
+### traces
 
 ```typescript
-import { withTrace } from '@mutagent/sdk';
-
-async function ragPipeline(query: string) {
-  return await withTrace(
-    { kind: 'chain', name: 'rag-pipeline' },
-    async (span) => {
-      span.setAttributes({ 'gen_ai.model': 'gpt-4o', 'user.query': query });
-
-      const docs = await retrieveDocuments(query);
-      span.addEvent('documents_retrieved', { count: docs.length });
-
-      const answer = await generateAnswer(query, docs);
-      span.setOutput({ text: answer, sources: docs.map(d => d.id) });
+import { Mutagent } from "@mutagent/sdk";
 
-      return answer;
-    }
-  );
+async function example(mutagent: Mutagent) {
+  const traces = await mutagent.traces.listTraces({ limit: 10 });
+  for (const trace of traces.data) {
+    const spans = await mutagent.traces.listTraceSpans({ traceId: trace.traceId });
+    console.log(trace.traceId, spans);
+  }
 }
 ```
 
-### Manual Spans
+### sandbox
 
-```typescript
-import { startSpan, endSpan, getCurrentSpan, getCurrentTraceId } from '@mutagent/sdk';
-
-const span = startSpan({ kind: 'tool', name: 'web-search' });
-span.setAttributes({ query: 'latest AI news' });
-
-try {
-  const results = await webSearch('latest AI news');
-  span.setOutput(results);
-  endSpan(span);
-} catch (err) {
-  span.setStatus('error', String(err));
-  endSpan(span);
-}
-```
-
-### Span Kinds
-
-| SpanKind | Description | Example Use Case |
-|----------|-------------|------------------|
-| `llm.chat` | Chat completion calls | OpenAI ChatGPT, Anthropic Claude |
-| `llm.completion` | Text completion calls | Legacy completions |
-| `llm.embedding` | Embedding generation | OpenAI Embeddings, Cohere Embed |
-| `chain` | Sequential processing pipeline | LangChain chains, RAG pipelines |
-| `agent` | Autonomous agent execution | ReAct agents |
-| `graph` | State graph execution | LangGraph workflows |
-| `node` | Individual graph node | State transitions |
-| `edge` | Graph transition | Conditional routing |
-| `workflow` | Multi-step workflows | Business process automation |
-| `tool` | External tool calls | API calls, calculators |
-| `retrieval` | Document retrieval | Vector search, keyword search |
-| `rerank` | Result reranking | Cohere Rerank, cross-encoders |
-| `guardrail` | Safety/validation checks | PII detection, content filtering |
-| `custom` | Custom operations | Your domain-specific ops |
-
-### Ingest Traces via API
-
-You can also send traces programmatically via the SDK:
+Requires a sandbox token (see [Sandbox token](#sandbox-token)).
 
 ```typescript
-// Ingest a single trace
-await mutagent.traces.ingestTrace({
-  traceId: 'trace-id',
-  spans: [ /* ... */ ],
-});
-
-// Batch ingest
-await mutagent.traces.ingestTraceBatch({
-  traces: [ /* ... */ ],
-});
+import { Mutagent } from "@mutagent/sdk";
+import { SandboxArch } from "@mutagent/sdk/models";
 
-// OTLP ingestion (standard OpenTelemetry format)
-await mutagent.traces.ingestOtlp({ /* OTLP payload */ });
+async function example(mutagent: Mutagent) {
+  // One command in a new sandbox, deleted after the run.
+  const run = await mutagent.sandbox.runSandboxCommand({ command: ["uname", "-a"] });
+  console.log(run.exitCode, run.stdout);
 
-// Query traces
-const traces = await mutagent.traces.listTraces();
-const stats = await mutagent.traces.getTraceStats();
-const summary = await mutagent.traces.getAnalyticsSummary();
+  // A sandbox you keep, run commands in, and delete.
+  const sandbox = await mutagent.sandbox.createSandbox({
+    definition: { name: "build", image: "<image>", arch: SandboxArch.X8664 },
+  });
+  const result = await mutagent.sandbox.execSandboxCommand({
+    id: sandbox.id,
+    body: { command: ["ls", "-la"] },
+  });
+  console.log(result.exitCode, result.stdout, result.stderr);
+  await mutagent.sandbox.deleteSandbox({ id: sandbox.id });
+}
 ```
 
----
-
-## Agents
+### environments
 
-Agents are persistent AI entities backed by a prompt. They maintain conversation history and support streaming.
-
-### Create an Agent
+Requires a sandbox token.
 
 ```typescript
-const agent = await mutagent.agents.createAgent({
-  name: 'Support Agent',
-  description: 'Handles customer support queries',
-  promptId: 'prompt-id',
-});
-```
+import { Mutagent } from "@mutagent/sdk";
 
-### List and Get Agents
+async function example(mutagent: Mutagent) {
+  await mutagent.environments.replaceEnvironment({
+    name: "staging",
+    body: {
+      vars: { LOG_LEVEL: "debug" },
+      secrets: { DATABASE_URL: "<secret>" },
+    },
+  });
 
-```typescript
-const agents = await mutagent.agents.listAgents();
-const agent = await mutagent.agents.getAgent({ id: 'agent-id' });
-const agentBySlug = await mutagent.agents.getAgentBySlug({ slug: 'support-agent' });
+  const environments = await mutagent.environments.listEnvironments();
+  console.log(environments);
+}
 ```
 
-### Update and Delete
-
-```typescript
-await mutagent.agents.updateAgent({ id: 'agent-id', name: 'Updated Name' });
-await mutagent.agents.deleteAgent({ id: 'agent-id' });
-```
+### helixSessions
 
-### Conversations
+Requires a sandbox token. A `headless` session runs the task in its arguments and ends. An
+`interactive` session stays open and reads one JSON command per `sendHelixSessionInput` call.
 
 ```typescript
-// Start a conversation
-const conversation = await mutagent.agentConversations.createAgentConversation({
-  id: agent.id,
-});
+import { Mutagent } from "@mutagent/sdk";
+import { HelixSignal, Mode } from "@mutagent/sdk/models";
 
-// Send a message
-await mutagent.conversations.sendConversationMessage({
-  id: conversation.id,
-  content: 'How do I reset my password?',
-});
-
-// List messages
-const messages = await mutagent.conversations.listConversationMessages({
-  id: conversation.id,
-});
+async function example(mutagent: Mutagent) {
+  const headless = await mutagent.helixSessions.launchHelixSession({
+    mode: Mode.Headless,
+    args: ["-p", "Summarise the README in the working directory"],
+  });
+  console.log(headless.reference, headless.sandboxId);
 
-// Fork a conversation (branch off from a specific point)
-const forked = await mutagent.conversations.forkConversation({
-  id: conversation.id,
-  messageId: 'message-id',
-});
+  const session = await mutagent.helixSessions.launchHelixSession({
+    mode: Mode.Interactive,
+    environment: "staging",
+  });
+  await mutagent.helixSessions.sendHelixSessionInput({
+    reference: session.reference,
+    body: { line: JSON.stringify({ type: "prompt", id: "p1", message: "List the files" }) },
+  });
+  await mutagent.helixSessions.signalHelixSession({
+    reference: session.reference,
+    body: { signal: HelixSignal.Sigint },
+  });
+}
 ```
 
-### Streaming Chat
-
-```typescript
-// Send a streaming message
-await mutagent.agentChatStreaming.sendStreamMessage({
-  id: conversation.id,
-  content: 'Tell me about your return policy.',
-});
-
-// Poll stream events
-const events = await mutagent.agentChatStreaming.getStreamEvents({
-  id: conversation.id,
-});
-```
+Per-method reference, with every parameter and response type, is in [docs/sdks/](./docs/sdks/).
 
 ---
 
-## Playground
-
-The Playground lets you execute and evaluate a prompt without running a full optimization pipeline.
+## Streaming
 
-### Execute a Prompt
+`helixSessions.streamHelixSession` and `sandbox.streamSandbox` request `Accept: text/event-stream`. The
+returned promise resolves to the whole event text as one string after the server closes the stream. The
+SDK does not parse the events and does not yield them while the stream is open. Pass the last `seq` you
+have read as `since` to receive only later events.
 
 ```typescript
-const result = await mutagent.playground.playgroundCall({
-  promptId: 'prompt-id',
-  input: { query: 'What are your hours?' },
-});
-
-console.log(result.output);
-```
-
-### Evaluate in the Playground
+import { Mutagent } from "@mutagent/sdk";
 
-```typescript
-const evalResult = await mutagent.playground.playgroundEval({
-  promptId: 'prompt-id',
-  input: { query: 'What are your hours?' },
-  expected: { summary: 'Open 9 AM to 5 PM, Monday to Friday.' },
-});
-
-console.log(`Score: ${evalResult.score}`);
+async function example(mutagent: Mutagent, reference: string) {
+  const eventText = await mutagent.helixSessions.streamHelixSession({ reference });
+  for (const block of eventText.split("\n\n")) {
+    console.log(block);
+  }
+}
 ```
 
 ---
 
 ## Pagination
 
-All list endpoints return async iterables. Iterate with `for await...of`:
+`agents.listAgents` and `organizations.listOrganizations` return an async iterable of pages. Iterate
+with `for await...of`:
 
 ```typescript
-const result = await mutagent.promptDatasets.listPromptDatasets({
-  promptId: 42,
-  limit: 20,
-  offset: 0,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-for await (const page of result) {
-  console.log(page);
+async function example(mutagent: Mutagent) {
+  const pages = await mutagent.agents.listAgents({ limit: 20, offset: 0 });
+  for await (const page of pages) {
+    console.log(page.result.data.length);
+  }
 }
 ```
 
+`traces.listTraces`, `traces.listLogs`, `managedAgents.listHelixAgents` and
+`helixSessions.listHelixSessions` take `limit` and `cursor` and return `nextCursor`. Pass
+`nextCursor` back as `cursor` to read the next page.
+
 ---
 
 ## Retries
 
-### Per-call Retry Config
+### Per-call retry config
 
 ```typescript
-const result = await mutagent.userProfile.getProfile({
-  retries: {
-    strategy: 'backoff',
-    backoff: {
-      initialInterval: 500,   // ms
-      maxInterval: 30000,     // ms
-      exponent: 1.5,
-      maxElapsedTime: 120000, // ms
+import { Mutagent } from "@mutagent/sdk";
+
+async function example(mutagent: Mutagent) {
+  const profile = await mutagent.userProfile.getProfile({
+    retries: {
+      strategy: "backoff",
+      backoff: {
+        initialInterval: 500,
+        maxInterval: 30000,
+        exponent: 1.5,
+        maxElapsedTime: 120000,
+      },
+      retryConnectionErrors: true,
     },
-    retryConnectionErrors: true,
-  },
-});
+  });
+  console.log(profile);
+}
 ```
 
-### Global Retry Config
-
-Set a default retry policy for all calls:
+### Global retry config
 
 ```typescript
+import { Mutagent } from "@mutagent/sdk";
+
 const mutagent = new Mutagent({
   retryConfig: {
-    strategy: 'backoff',
+    strategy: "backoff",
     backoff: {
       initialInterval: 500,
       maxInterval: 30000,
@@ -740,9 +586,7 @@ const mutagent = new Mutagent({
     },
     retryConnectionErrors: true,
   },
-  security: {
-    apiKey: process.env.MUTAGENT_API_KEY,
-  },
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
 });
 ```
 
@@ -750,273 +594,173 @@ const mutagent = new Mutagent({
 
 ## Error Handling
 
-All HTTP errors extend `MutagentError`:
+Every HTTP error extends `MutagentError`. Most operations document `ErrorResponse`, whose data has
+`error` and `message`.
 
 ```typescript
-import { Mutagent } from '@mutagent/sdk';
-import * as errors from '@mutagent/sdk/models/errors';
-
-try {
-  const prompt = await mutagent.prompt.getPrompt({ id: 'does-not-exist' });
-} catch (error) {
-  if (error instanceof errors.MutagentError) {
-    console.error(`HTTP ${error.statusCode}: ${error.message}`);
+import { Mutagent } from "@mutagent/sdk";
+import * as errors from "@mutagent/sdk/models/errors";
 
-    if (error instanceof errors.ErrorMessage) {
-      console.error('API error:', error.data$.error);
+async function example(mutagent: Mutagent) {
+  try {
+    await mutagent.agents.getAgent({ id: 404 });
+  } catch (error) {
+    if (error instanceof errors.ErrorResponse) {
+      console.error(error.statusCode, error.data$.error, error.data$.message);
+    } else if (error instanceof errors.MutagentError) {
+      console.error(`HTTP ${error.statusCode}: ${error.body}`);
+    } else {
+      throw error;
     }
   }
 }
 ```
 
-### Error Properties
+### Error properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `error.message` | `string` | Human-readable error message |
-| `error.statusCode` | `number` | HTTP status code (e.g. `404`, `401`) |
+| `error.message` | `string` | Error message |
+| `error.statusCode` | `number` | HTTP status code, for example `404` |
 | `error.headers` | `Headers` | HTTP response headers |
-| `error.body` | `string` | Raw HTTP response body |
-| `error.rawResponse` | `Response` | Raw HTTP response object |
-| `error.data$` | varies | Structured error data (where available) |
-
-### Error Classes
-
-**Base class:**
-- `MutagentError` — all HTTP error responses extend this
-
-**Domain errors (extend `MutagentError`):**
-- `ErrorMessage` — general API error message
-- `ErrorMessageStatusCode` — error with explicit status code
-- `ErrorResponse` — standard error response
-- `OptimizationError` — optimization-specific errors
-- `TraceError` — tracing ingestion errors
-- `ProviderError` — provider config errors
-- `WsError` — WebSocket/streaming errors
-- `TestConnectionResultError` — provider connection test failures
-- `ResponseValidationError` — server returned unexpected shape
-
-**Network errors (client-side):**
-- `ConnectionError` — could not reach the server
-- `RequestTimeoutError` — request exceeded the timeout
-- `RequestAbortedError` — request was aborted
-- `InvalidRequestError` — invalid input before the request was sent
-- `UnexpectedClientError` — unrecognised client-side error
-
----
+| `error.body` | `string` | HTTP response body; empty when the response has none |
+| `error.rawResponse` | `Response` | Raw HTTP response |
+| `error.data$` | varies | Structured error data, on error classes that have it |
 
-## Custom HTTP Client
-
-The SDK uses the native Fetch API internally. You can swap in any fetcher — useful for proxying, testing, or custom timeouts:
+### Error classes
 
-```typescript
-import { Mutagent } from '@mutagent/sdk';
-import { HTTPClient } from '@mutagent/sdk/lib/http';
-import { ProxyAgent } from 'undici';
+Extend `MutagentError`: `ErrorResponse`, `ErrorResponseWithStatus`, `ProviderError`, `DeploymentError`,
+`WsError`, `ModelNotInListError`, `ModelResolutionError`, `NoProviderConfiguredError`,
+`TestConnectionResultError`, `WorkspaceModelListingError`, `SandboxProviderUnreachableError`,
+`SandboxPayloadTooLargeError`, `ResponseValidationError`.
 
-const dispatcher = new ProxyAgent('http://proxy.example.com:8080');
+`SandboxPayloadTooLargeError` is the 413 response of `helixSessions.launchHelixSession`,
+`sandbox.startSandboxHelixSession`, `sandbox.execSandboxCommand`, `helixSessions.restoreHelixSession`
+and `sandbox.restoreSandbox` when the sandbox provider refuses the request for its size; its data has
+`error`, `message`, `provider`, `payloadBytes` and `limitBytes`.
 
-const httpClient = new HTTPClient({
-  fetcher: (input, init) =>
-    fetch(input, { ...init, dispatcher } as RequestInit),
-});
+Client-side network errors: `ConnectionError`, `RequestTimeoutError`, `RequestAbortedError`,
+`InvalidRequestError`, `UnexpectedClientError`.
 
-// Add a request timeout and custom header
-httpClient.addHook('beforeRequest', (request) => {
-  const next = new Request(request, {
-    signal: request.signal ?? AbortSignal.timeout(10_000),
-  });
-  next.headers.set('x-app-version', '1.0.0');
-  return next;
-});
-
-// Log errors
-httpClient.addHook('requestError', (error, request) => {
-  console.error(`Request failed: ${request.method} ${request.url}`, error);
-});
-
-const mutagent = new Mutagent({ httpClient, security: { apiKey: process.env.MUTAGENT_API_KEY } });
-```
+The method pages in [docs/sdks/](./docs/sdks/) list which errors each method can throw.
 
 ---
 
-## Tree-shakeable Imports
+## Server Selection
 
-All SDK methods are also available as standalone functions. This is ideal for serverless environments or browser bundles where tree-shaking matters:
+| `serverIdx` | Server | Description |
+|-------------|--------|-------------|
+| `0` (default) | `https://api.mutagent.io` | Production |
+| `1` | `http://localhost:3003` | Development server |
 
 ```typescript
-import {
-  promptCreatePrompt,
-  promptListPrompts,
-  promptDatasetsCreatePromptDataset,
-  promptDatasetItemsBulkCreatePromptDatasetItems,
-  optimizationOptimizePrompt,
-  optimizationGetOptimizationResults,
-} from '@mutagent/sdk/functions';
-
-import { Mutagent } from '@mutagent/sdk';
-
-const client = new Mutagent({ security: { apiKey: process.env.MUTAGENT_API_KEY } });
-
-const prompt = await promptCreatePrompt(client, {
-  name: 'My Prompt',
-  content: 'Template: {{input}}',
-});
+import { Mutagent } from "@mutagent/sdk";
 
-const dataset = await promptDatasetsCreatePromptDataset(client, {
-  id: prompt.id,
-  name: 'My Dataset',
+const local = new Mutagent({
+  serverURL: "http://localhost:3003",
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
 });
 ```
 
-Full list of standalone functions is available in [FUNCTIONS.md](./FUNCTIONS.md).
-
 ---
 
-## TypeScript Support
-
-The SDK is written in TypeScript and ships full type declarations.
-
-### Client Constructor Types
-
-```typescript
-import type { MutagentOptions } from '@mutagent/sdk';
-
-const options: MutagentOptions = {
-  security: { apiKey: process.env.MUTAGENT_API_KEY },
-  serverURL: 'https://api.mutagent.io/v1',
-  retryConfig: { strategy: 'backoff', backoff: { /* ... */ } },
-};
-```
-
-### Response Types
+## Custom HTTP Client
 
-All responses are fully typed. IDE autocomplete works out of the box:
+The SDK sends requests through an `HTTPClient` that wraps `fetch`. You can pass your own fetcher and
+add hooks:
 
 ```typescript
-import type { Prompt, Dataset, EvaluationResult, OptimizationJob } from '@mutagent/sdk/models/components';
+import { Mutagent } from "@mutagent/sdk";
+import { HTTPClient } from "@mutagent/sdk/lib/http";
 
-const prompt: Prompt = await mutagent.prompt.getPrompt({ id: 'prompt-id' });
-```
+const httpClient = new HTTPClient({
+  fetcher: (input, init) => fetch(input, init),
+});
 
-### Debugging
+httpClient.addHook("beforeRequest", (request) => {
+  const next = new Request(request, {
+    signal: request.signal ?? AbortSignal.timeout(10_000),
+  });
+  next.headers.set("x-app-version", "1.0.0");
+  return next;
+});
 
-Enable debug logging to inspect every request and response. Use only in local development — debug logs contain API keys and secrets:
+httpClient.addHook("requestError", (error, request) => {
+  console.error(`Request failed: ${request.method} ${request.url}`, error);
+});
 
-```typescript
-const mutagent = new Mutagent({ debugLogger: console, security: { apiKey: '...' } });
+const mutagent = new Mutagent({
+  httpClient,
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
+});
 ```
 
-Or set `MUTAGENT_DEBUG=true` in your environment.
-
 ---
 
-## Framework Integrations
-
-Use MutagenT with your favourite AI framework. The CLI can generate integration boilerplate automatically:
-
-```bash
-npx @mutagent/cli integrate mastra
-npx @mutagent/cli integrate langchain
-npx @mutagent/cli integrate langgraph
-npx @mutagent/cli integrate vercel-ai
-npx @mutagent/cli integrate openai
-```
+## Standalone functions
 
-### Mastra
+Every method is also exported as a function named `<group><Method>` under `@mutagent/sdk/funcs/`. Use
+them with `MutagentCore` when bundle size matters: a bundler can drop the functions you do not import.
+A standalone function returns a `Result` holding either the value or a known error, instead of throwing
+that error.
 
 ```typescript
-import { MutagentObserver } from '@mutagent/sdk/mastra';
+import { MutagentCore } from "@mutagent/sdk/core.js";
+import { agentsGetAgentBySlug } from "@mutagent/sdk/funcs/agents-get-agent-by-slug.js";
 
-const observer = new MutagentObserver({
-  apiKey: process.env.MUTAGENT_API_KEY,
+const core = new MutagentCore({
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
 });
-```
-
-### LangChain
-
-```typescript
-import { MutagentCallbackHandler } from '@mutagent/sdk/langchain';
-import { ChatOpenAI } from '@langchain/openai';
 
-const handler = new MutagentCallbackHandler({
-  apiKey: process.env.MUTAGENT_API_KEY,
-  promptId: 'my-prompt-id',
-});
+async function run() {
+  const res = await agentsGetAgentBySlug(core, { slug: "support-agent" });
+  if (res.ok) {
+    console.log(res.value);
+  } else {
+    console.error(res.error);
+  }
+}
 
-const llm = new ChatOpenAI({ callbacks: [handler] });
+run();
 ```
 
-### Vercel AI SDK
+The full list is in [FUNCTIONS.md](./FUNCTIONS.md) and in the method pages under [docs/sdks/](./docs/sdks/).
 
-```typescript
-import { withMutagent } from '@mutagent/sdk/vercel-ai';
-import { streamText } from 'ai';
-import { openai } from '@ai-sdk/openai';
-
-const result = await withMutagent(
-  streamText({ model: openai('gpt-4o'), messages }),
-  { apiKey: process.env.MUTAGENT_API_KEY }
-);
-```
+---
 
-### Migration from Langfuse
+## Debugging
+
+Pass a logger that matches `console` to log requests and responses. Debug logs include credentials such
+as API keys and tokens, so use this only in local development.
 
 ```typescript
-// Before (Langfuse)
-import { Langfuse } from 'langfuse';
-const langfuse = new Langfuse({
-  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
-  secretKey: process.env.LANGFUSE_SECRET_KEY,
-});
+import { Mutagent } from "@mutagent/sdk";
 
-// After (MutagenT)
-import { initTracing } from '@mutagent/sdk/tracing';
-initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
+const mutagent = new Mutagent({
+  debugLogger: console,
+  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
+});
 ```
 
+Setting `MUTAGENT_DEBUG=true` enables a default debug logger.
+
 ---
 
 ## API Reference
 
-### Available Namespaces
-
-| Namespace | Key Methods | Description |
-|-----------|-------------|-------------|
-| `prompt` | `createPrompt`, `listPrompts`, `getPrompt`, `updatePrompt`, `deletePrompt`, `createPromptVersion`, `listPromptVersions`, `getPromptAnalytics` | Prompt management and versioning |
-| `promptDatasets` | `createPromptDataset`, `listDatasetsForPrompt`, `getPromptDataset`, `updatePromptDataset`, `deletePromptDataset`, `clonePromptDataset`, `exportPromptDataset` | Dataset operations |
-| `promptDatasetItems` | `createPromptDatasetItem`, `bulkCreatePromptDatasetItems`, `listPromptDatasetItems`, `getPromptDatasetItem`, `updatePromptDatasetItem`, `deletePromptDatasetItem` | Dataset item CRUD |
-| `promptEvaluations` | `createEvaluation`, `listEvaluations`, `getEvaluation`, `runEvaluation`, `getEvaluationResult`, `getEvaluationHistory`, `getEvaluationResultsAggregated` | Evaluation engine |
-| `optimization` | `optimizePrompt`, `getOptimization`, `listOptimizations`, `getOptimizationProgress`, `getOptimizationResults`, `getOptimizationStates`, `pauseOptimization`, `resumeOptimization`, `cancelOptimization` | Auto-optimization jobs |
-| `playground` | `playgroundCall`, `playgroundEval` | Interactive prompt execution |
-| `agents` | `createAgent`, `listAgents`, `getAgent`, `getAgentBySlug`, `updateAgent`, `deleteAgent` | Agent CRUD |
-| `agentConversations` | `createAgentConversation`, `listAgentConversations` | Agent conversation management |
-| `conversations` | `getConversation`, `sendConversationMessage`, `listConversationMessages`, `updateConversation`, `deleteConversation`, `forkConversation` | Conversation operations |
-| `agentChatStreaming` | `sendStreamMessage`, `getStreamEvents` | Real-time streaming chat |
-| `agentDatasets` | `createAgentDataset`, `listAgentDatasets`, `getAgentDataset`, `updateAgentDataset`, `deleteAgentDataset`, `cloneAgentDataset`, `exportAgentDataset` | Agent evaluation datasets |
-| `agentDatasetItems` | `createAgentDatasetItem`, `bulkCreateAgentDatasetItems`, `listAgentDatasetItems`, `getAgentDatasetItem`, `updateAgentDatasetItem`, `deleteAgentDatasetItem` | Agent dataset item operations |
-| `traces` | `ingestTrace`, `ingestTraceBatch`, `ingestOtlp`, `listTraces`, `getTrace`, `getTraceStats`, `getAnalyticsSummary`, `deleteTrace` | Trace observability and ingestion |
-| `providerConfigs` | `createProvider`, `listProviders`, `getProvider`, `updateProvider`, `deleteProvider`, `testProvider`, `listAvailableModels`, `getModelsCatalog` | LLM provider configurations |
-| `workspaces` | `createWorkspace`, `listWorkspaces`, `getWorkspace`, `updateWorkspace`, `deleteWorkspace`, `setDefaultWorkspace` | Workspace management |
-| `workspaceMembers` | `addWorkspaceMember`, `listWorkspaceMembers`, `updateWorkspaceMember`, `removeWorkspaceMember` | Workspace membership |
-| `organizations` | `createOrganization`, `listOrganizations`, `getOrganization`, `updateOrganization`, `deleteOrganization`, `getOrganizationBySlug` | Organization management |
-| `organizationMembers` | `addOrganizationMember`, `listOrganizationMembers`, `updateOrganizationMember`, `removeOrganizationMember` | Organization membership |
-| `userProfile` | `getProfile`, `updateProfile`, `changePassword`, `deleteAccount`, `listSessions`, `deleteSession` | User profile management |
-| `invitations` | `createInvitation`, `listInvitations`, `getInvitation`, `resendInvitation`, `deleteInvitation` | Team invitations |
-| `experiments` | `createExperiment`, `listExperiments`, `getExperiment`, `executeExperiment`, `completeExperiment`, `addExperimentResult`, `deleteExperiment` | Experiments |
-
-For complete per-method docs, see [docs/sdks/](./docs/sdks/).
+- [docs/sdks/](./docs/sdks/): one page per group, with every method, parameter and error
+- [FUNCTIONS.md](./FUNCTIONS.md): standalone functions
+- [RUNTIMES.md](./RUNTIMES.md): supported runtimes and TypeScript compiler options
+- [docs.mutagent.io](https://docs.mutagent.io): platform documentation
 
 ---
 
 ## See Also
 
-- **[@mutagent/cli](https://www.npmjs.com/package/@mutagent/cli)** — Command-line interface for MutagenT
-- **[docs.mutagent.io](https://docs.mutagent.io)** — Full platform documentation
-- **[Integration Guides](https://docs.mutagent.io/integrations/overview)** — Mastra, LangChain, LangGraph, Vercel AI, OpenAI
-- **[Tracing Setup](https://docs.mutagent.io/tracing/setup)** — OTel integration walkthrough
-- **[API Reference](https://docs.mutagent.io/api)** — Complete REST API reference
-- **[mutagent.io](https://mutagent.io)** — Homepage
+- **[@mutagent/cli](https://www.npmjs.com/package/@mutagent/cli)**: command-line interface for MutagenT
+- **[docs.mutagent.io](https://docs.mutagent.io)**: platform documentation
+- **[API Reference](https://docs.mutagent.io/api)**: REST API reference
+- **[mutagent.io](https://mutagent.io)**: homepage
 
 ---