# @mutagent/sdk 中文文档

规范地址：https://npmcn.com/package/%40mutagent/sdk/

版本：0\.12\.51
npm 元数据更新时间：2026-11-01T22:39:31.527Z
中文译文更新时间：2026-11-01T23:17:39.019Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40mutagent/sdk
原文对照：https://npmcn.com/package/%40mutagent/sdk/?lang=original
项目主页：https://docs.mutagent.io/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：32.7 MB，10320 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-08T04:40:22.850Z
- 最新版本发布：2026-11-01T22:39:31.364Z
- 已发布版本数：360（近 12 个月 360 个）

## 中文简介



## 安装

```sh
npm install @mutagent/sdk
```

也可以使用：`pnpm add @mutagent/sdk`、`yarn add @mutagent/sdk`、`bun add @mutagent/sdk`

## README

# @mutagent / sdk

```
  ███╗   ███╗██╗   ██╗████████╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗
  ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
  ██╔████╔██║██║   ██║   ██║   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║
  ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║
  ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║
  ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝
                          ███████╗██████╗ ██╗  ██╗
                          ██╔════╝██╔══██╗██║ ██╔╝
                          ███████╗██║  ██║█████╔╝
                          ╚════██║██║  ██║██╔═██╗
                          ███████║██████╔╝██║  ██╗
                          ╚══════╝╚═════╝ ╚═╝  ╚═╝
```

[![npm](https://img.shields.io/npm/v/@mutagent/sdk?style=for-the-badge&color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@mutagent/sdk) [![Node.js](https://img.shields.io/badge/Node-18+-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/) [![Bun](https://img.shields.io/badge/Bun-1.1+-f472b6?style=for-the-badge&logo=bun&logoColor=white)](https://bun.sh/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![License: Proprietary](https://img.shields.io/badge/License-Proprietary-ff6b6b?style=for-the-badge)](https://npmcn.com/package/%40mutagent/sdk/#readme-license)

_MutagenT平台API的TypeScript客户端。_

* * *

## 目录表

-   [SDK涵盖的内容](https://npmcn.com/package/%40mutagent/sdk/#readme-what-the-sdk-covers)
-   [0.6.0的突破性变化](https://npmcn.com/package/%40mutagent/sdk/#readme-060-breaking-changes)
-   [安装](https://npmcn.com/package/%40mutagent/sdk/#readme-installation)
-   [快速入门](https://npmcn.com/package/%40mutagent/sdk/#readme-quick-start)
-   [身份验证](https://npmcn.com/package/%40mutagent/sdk/#readme-authentication)
-   [客户群体](https://npmcn.com/package/%40mutagent/sdk/#readme-client-groups)
-   [流媒体](https://npmcn.com/package/%40mutagent/sdk/#readme-streaming)
-   [分页](https://npmcn.com/package/%40mutagent/sdk/#readme-pagination)
-   [重试](https://npmcn.com/package/%40mutagent/sdk/#readme-retries)
-   [错误处理](https://npmcn.com/package/%40mutagent/sdk/#readme-error-handling)
-   [服务器选择](https://npmcn.com/package/%40mutagent/sdk/#readme-server-selection)
-   [自定义HTTP客户机](https://npmcn.com/package/%40mutagent/sdk/#readme-custom-http-client)
-   [独立的功能](https://npmcn.com/package/%40mutagent/sdk/#readme-standalone-functions)
-   [调试](https://npmcn.com/package/%40mutagent/sdk/#readme-debugging)
-   [API参考](https://npmcn.com/package/%40mutagent/sdk/#readme-api-reference)
-   [看到也](https://npmcn.com/package/%40mutagent/sdk/#readme-see-also)
-   [许可证](https://npmcn.com/package/%40mutagent/sdk/#readme-license)

* * *

## SDK涵盖的内容

`@mutagent/sdk` 是从MutagenT平台OpenAPI文档生成的。一个 `Mutagent` 客户端 公开了13组方法：

| 集团 | 它叫什么？ |
| --- | --- |
| `userProfile` | 登录用户的配置文件、密码和登录会话 |
| `organizations` | 组织，鼻涕虫查找和成员计数 |
| `organizationMembers` | 组织成员和角色 |
| `workspaces` | 工作区和默认工作区 |
| `workspaceMembers` | 工作空间成员和角色 |
| `invitations` | 组织的邀请 |
| `agents` | 代理记录：创建、读取、更新、删除、按段查找 |
| `llmProviders` | LLM提供程序配置、模型目录、连接测试 |
| `managedAgents` | 托管代理部署：插槽、修订、操作 |
| `traces` | 跟踪的摄取和读取痕迹，跨度和日志 |
| `sandbox` | 沙箱提供商、预设、沙箱生命周期、命令、沙箱令牌交换和Helix会话由沙箱id处理 |
| `environments` | 工作空间环境（命名的变量和秘密集） |
| `helixSessions` | 螺旋会议地址的会话参考：启动，列表，输入，信号，检查点，恢复，流 |

每个方法也可以作为独立函数使用(参见 [独立的功能](https://npmcn.com/package/%40mutagent/sdk/#readme-standalone-functions)）。

* * *

## 0.6.0的突破性变化

0.6.0是0.5.x之后的一个突破性版本。代码是针对0.5编写的。X需要进行以下更改。

**客户群体**

-   `sandbox` 保存沙箱提供程序、预设、沙箱生命周期、命令、令牌交换 （`createSandboxToken`)和由沙盒id寻址的会话路由。
-   新组 `helixSessions`： `launchHelixSession`， `listHelixSessions`， `sendHelixSessionInput`， `closeHelixSessionInput`， `signalHelixSession`， `checkpointHelixSession`， `listHelixSessionCheckpoints`， `restoreHelixSession`， `streamHelixSession`， `getHelixModels`， `setHelixDefaultModels`． 在0.5中存在的那些。X是 `sandbox`.
-   新组 `environments`． 在0.5。它的操作是 `sandbox`.
-   `helixAgentDeployments` 重命名 `managedAgents`． 它的方法名不变。
-   `providerConfigs` 重命名 `llmProviders`． 它的方法也被重命名；见下表。
-   `userProfile` 保留它的名字。它的两个方法被重命名；见下表。

**操作名称**

重命名39项操作。在前27行中，0.5。X名称来源于路由。最后一个 12行重命名已经有自己名称的操作。

| 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` |

独立函数名遵循相同的更改，包括组前缀。例如 `sandboxGetApiSandboxById` 现在是 `sandboxGetSandbox`, `providerConfigsTestProvider` 现在是 `llmProvidersTestProviderConfig`.

**模型、枚举和错误名称**

例如，模型、枚举和错误类的名称来自API文档中的模式名称 `Mode`， `HelixArm`， `HelixSignal`， `HelixLaunchRequest`， `LlmProviderType` 和 `ErrorResponse`． 命名于0.5年发明的发电机。X，例如 `Schemadefaul7`， `ModeArmModel` 和 `NameSlugDescription5`，已不复存在。

**会话模式值**

Helix会话模式是 `headless` 或者 `interactive` （`Mode.Headless`， `Mode.Interactive`）. 这个 0.5.x值 `oneshot` 和 `rpc` 已经一去不复返了。

**默认的服务器**

默认服务器为 `https://api.mutagent.io`． 在0.5。原来是这样 `http://localhost:3003`． 打电话给… 本地服务器，通过 `serverURL: "http://localhost:3003"` 或者 `serverIdx: 1`.

**流**

`streamHelixSession` 和 `streamSandbox` 发送 `Accept: text/event-stream`． 他们决心解决这个问题 当服务器关闭流时，文本作为一个字符串。它们到达时不会产生事件。

* * *

## 安装

### npm

```bash
npm install @mutagent/sdk
```

### 规划

```bash
pnpm add @mutagent/sdk
```

### 纱

```bash
yarn add @mutagent/sdk
```

### 包子

```bash
bun add @mutagent/sdk
```

这个包提供了CommonJS (`require`)和ES模块(`import`)构建。列出了支持的运行时 在 [RUNTIMES.md](https://npmcn.com/package/%40mutagent/sdk/RUNTIMES.md).

* * *

## 快速入门

```typescript
import { Mutagent } from "@mutagent/sdk";

const mutagent = new Mutagent({
  security: {
    apiKey: process.env["MUTAGENT_API_KEY"] ?? "",
  },
});

async function run() {
  const profile = await mutagent.userProfile.getProfile();
  console.log(profile);

  const workspaces = await mutagent.workspaces.listWorkspaces();
  console.log(workspaces);
}

run();
```

* * *

## 身份验证

这个 `security` 选项有两个字段。当您不传递它们时，将从环境中读取它们。

| 选项 | 发送 | 环境变量 | 所使用的 |
| --- | --- | --- | --- |
| `apiKey` | `x-api-key` 头 | `MUTAGENT_API_KEY` | 每个组，除了 `sandbox`， `environments` 和 `helixSessions` |
| `bearerAuth` | `Authorization: Bearer` 头 | `MUTAGENT_BEARER_AUTH` | `sandbox` (除了 `createSandboxToken`)， `environments` 和 `helixSessions`，不接受其他凭证。其他组织也宣布了这一点 |

当一个操作都接受并且都设置时，SDK发送API密钥。

### API密匙

平台API密钥以 `mg_live_`． 在MutagenT应用程序的设置，API密钥下创建一个。

```typescript
import { Mutagent } from "@mutagent/sdk";

const mutagent = new Mutagent({
  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
});
```

### 沙箱令牌

这个 `sandbox`， `environments` 和 `helixSessions` 操作不接受API密钥。他们需要一个 短暂的沙盒令牌，作为承载令牌发送。将API密钥交换为 `sandbox.createSandboxToken`． 那个调用在它自己的第一个参数中接受API键；它不读 客户的 `security` 选择或 `MUTAGENT_API_KEY`.

```typescript
import { Mutagent } from "@mutagent/sdk";

async function sandboxClient(workspaceId: string): Promise<Mutagent> {
  const apiKey = process.env["MUTAGENT_API_KEY"] ?? "";
  const platform = new Mutagent({ security: { apiKey } });

  const { token, expiresIn } = await platform.sandbox.createSandboxToken(
    { apiKey },
    { workspaceId },
  );
  console.log(`sandbox token expires in ${expiresIn}s`);

  // apiKey stays in place for the platform groups; bearerAuth is used by
  // sandbox, environments and helixSessions.
  return new Mutagent({ security: { apiKey, bearerAuth: token } });
}
```

`security` 还接受返回凭据的async函数，该函数允许您刷新 在沙箱令牌到期之前。

* * *

## 客户群体

下面的示例假设内置了客户机 [身份验证](https://npmcn.com/package/%40mutagent/sdk/#readme-authentication)． 示例 `sandbox`， `environments` 和 `helixSessions` 需要一个持有沙盒令牌的客户端。

### userProfile

```typescript
import { Mutagent } from "@mutagent/sdk";

async function example(mutagent: Mutagent) {
  const profile = await mutagent.userProfile.getProfile();
  const sessions = await mutagent.userProfile.listUserSessions();
  console.log(profile, sessions);
}
```

### 组织

```typescript
import { Mutagent } from "@mutagent/sdk";

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);
}
```

### organizationMembers

```typescript
import { Mutagent } from "@mutagent/sdk";

async function example(mutagent: Mutagent) {
  const members = await mutagent.organizationMembers.listOrganizationMembers({ orgId: "<org-id>" });
  console.log(members);
}
```

### 工作区

```typescript
import { Mutagent } from "@mutagent/sdk";

async function example(mutagent: Mutagent) {
  const workspace = await mutagent.workspaces.createWorkspace({
    name: "Support",
    slug: "support",
  });
  await mutagent.workspaces.setDefaultWorkspace({ wsId: workspace.id });
}
```

### workspaceMembers

```typescript
import { Mutagent } from "@mutagent/sdk";

async function example(mutagent: Mutagent) {
  const members = await mutagent.workspaceMembers.listWorkspaceMembers({ wsId: "<workspace-id>" });
  console.log(members);
}
```

### 邀请

```typescript
import { Mutagent } from "@mutagent/sdk";
import { OrganizationRole } from "@mutagent/sdk/models";

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);
}
```

### 代理

```typescript
import { Mutagent } from "@mutagent/sdk";

async function example(mutagent: Mutagent) {
  const agent = await mutagent.agents.createAgent({
    name: "Support Agent",
    slug: "support-agent",
    systemPrompt: "You answer customer support questions.",
  });

  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);
}
```

### llmProviders

```typescript
import { Mutagent } from "@mutagent/sdk";
import { LlmProviderType } from "@mutagent/sdk/models";

async function example(mutagent: Mutagent) {
  const provider = await mutagent.llmProviders.createProviderConfig({
    name: "Anthropic",
    provider: LlmProviderType.Anthropic,
    apiKey: process.env["ANTHROPIC_API_KEY"] ?? "",
  });

  const test = await mutagent.llmProviders.testProviderConfig({ id: provider.id });
  const models = await mutagent.llmProviders.listProviderConfigModels({ id: provider.id });
  console.log(test, models);
}
```

### managedAgents

```typescript
import { Mutagent } from "@mutagent/sdk";

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);
  }
}
```

### 痕迹

```typescript
import { Mutagent } from "@mutagent/sdk";

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);
  }
}
```

### 沙盒

需要一个沙盒令牌(参见 [沙箱令牌](https://npmcn.com/package/%40mutagent/sdk/#readme-sandbox-token)）。

```typescript
import { Mutagent } from "@mutagent/sdk";
import { SandboxArch } from "@mutagent/sdk/models";

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);

  // 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 });
}
```

### 环境

需要一个沙盒令牌。

```typescript
import { Mutagent } from "@mutagent/sdk";

async function example(mutagent: Mutagent) {
  await mutagent.environments.replaceEnvironment({
    name: "staging",
    body: {
      vars: { LOG_LEVEL: "debug" },
      secrets: { DATABASE_URL: "<secret>" },
    },
  });

  const environments = await mutagent.environments.listEnvironments();
  console.log(environments);
}
```

### helixSessions

需要一个沙盒令牌。一个 `headless` 会话在其参数中运行任务并结束。一个 `interactive` session保持打开状态，每个session读取一个JSON命令 `sendHelixSessionInput` 呼叫。

```typescript
import { Mutagent } from "@mutagent/sdk";
import { HelixSignal, Mode } from "@mutagent/sdk/models";

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);

  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 },
  });
}
```

包含每个参数和响应类型的每个方法引用都在 [文档/ sdk /](https://npmcn.com/package/%40mutagent/sdk/docs/sdks/).

* * *

## 流媒体

`helixSessions.streamHelixSession` 和 `sandbox.streamSandbox` 请求 `Accept: text/event-stream`。这个 在服务器关闭流后，返回的promise将整个事件文本解析为一个字符串。这个 SDK不会解析事件，也不会在流打开时生成事件。传递最后一个 `seq` 你 读过 `since` 只接收稍后的事件。

```typescript
import { Mutagent } from "@mutagent/sdk";

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);
  }
}
```

* * *

## 分页

`agents.listAgents` 和 `organizations.listOrganizations` 返回页面的异步可迭代对象。迭代 与 `for await...of`：

```typescript
import { Mutagent } from "@mutagent/sdk";

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` 和 `helixSessions.listHelixSessions` 采取 `limit` 和 `cursor` 并返回 `nextCursor`。通过 `nextCursor` 在 `cursor` 读下一页。

* * *

## 重试

### 每呼叫重试配置

```typescript
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,
    },
  });
  console.log(profile);
}
```

### 全局重试配置

```typescript
import { Mutagent } from "@mutagent/sdk";

const mutagent = new Mutagent({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 500,
      maxInterval: 30000,
      exponent: 1.5,
      maxElapsedTime: 120000,
    },
    retryConnectionErrors: true,
  },
  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
});
```

* * *

## 错误处理

每个HTTP错误扩展 `MutagentError`． 大多数操作文档 `ErrorResponse`，其数据 `error` 和 `message`.

```typescript
import { Mutagent } from "@mutagent/sdk";
import * as errors from "@mutagent/sdk/models/errors";

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.message` | `string` | 错误消息 |
| `error.statusCode` | `number` | 例如，HTTP状态码 `404` |
| `error.headers` | `Headers` | HTTP响应头 |
| `error.body` | `string` | HTTP响应体；当响应没有时为空 |
| `error.rawResponse` | `Response` | 原始HTTP响应 |
| `error.data$` | 不同 | 结构化错误数据，在拥有它的错误类上 |

### 错误类

扩展 `MutagentError`： `ErrorResponse`， `ErrorResponseWithStatus`， `ProviderError`， `DeploymentError`， `WsError`， `ModelNotInListError`， `ModelResolutionError`， `NoProviderConfiguredError`， `TestConnectionResultError`， `WorkspaceModelListingError`， `SandboxProviderUnreachableError`， `SandboxPayloadTooLargeError`， `ResponseValidationError`.

`SandboxPayloadTooLargeError` 413的响应是 `helixSessions.launchHelixSession`， `sandbox.startSandboxHelixSession`， `sandbox.execSandboxCommand`， `helixSessions.restoreHelixSession` 和 `sandbox.restoreSandbox` 当沙箱提供商拒绝其大小的请求时；它的数据 `error`， `message`， `provider`， `payloadBytes` 和 `limitBytes`.

客户端网络错误： `ConnectionError`， `RequestTimeoutError`， `RequestAbortedError`， `InvalidRequestError`， `UnexpectedClientError`.

方法页在 [文档/ sdk /](https://npmcn.com/package/%40mutagent/sdk/docs/sdks/) 列出每个方法可能抛出的错误。

* * *

## 服务器选择

| `serverIdx` | 服务器 | 描述 |
| --- | --- | --- |
| `0` (默认) | `https://api.mutagent.io` | 生产 |
| `1` | `http://localhost:3003` | 开发服务器 |

```typescript
import { Mutagent } from "@mutagent/sdk";

const local = new Mutagent({
  serverURL: "http://localhost:3003",
  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
});
```

* * *

## 自定义HTTP客户机

SDK通过接口发送请求 `HTTPClient` 包装 `fetch`． 你可以传递你自己的取回器和 增加挂钩:

```typescript
import { Mutagent } from "@mutagent/sdk";
import { HTTPClient } from "@mutagent/sdk/lib/http";

const httpClient = new HTTPClient({
  fetcher: (input, init) => fetch(input, init),
});

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;
});

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"] ?? "" },
});
```

* * *

## 独立的功能

每个方法也被导出为一个名为 `<group><Method>` 下 `@mutagent/sdk/funcs/`。使用 它们与 `MutagentCore` 当绑定包的大小很重要时：绑定器可以删除你没有导入的函数。 独立函数返回A `Result` 持有值或已知错误，而不是抛出 这样的错误了。

```typescript
import { MutagentCore } from "@mutagent/sdk/core.js";
import { agentsGetAgentBySlug } from "@mutagent/sdk/funcs/agents-get-agent-by-slug.js";

const core = new MutagentCore({
  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
});

async function run() {
  const res = await agentsGetAgentBySlug(core, { slug: "support-agent" });
  if (res.ok) {
    console.log(res.value);
  } else {
    console.error(res.error);
  }
}

run();
```

完整的名单已经出来了 [FUNCTIONS.md](https://npmcn.com/package/%40mutagent/sdk/FUNCTIONS.md) 在方法页下面 [文档/ sdk /](https://npmcn.com/package/%40mutagent/sdk/docs/sdks/).

* * *

## 调试

传递一个匹配的记录器 `console` 记录请求和响应。调试日志包括如下凭据 作为API密钥和令牌，因此仅在本地开发中使用它。

```typescript
import { Mutagent } from "@mutagent/sdk";

const mutagent = new Mutagent({
  debugLogger: console,
  security: { apiKey: process.env["MUTAGENT_API_KEY"] ?? "" },
});
```

设置 `MUTAGENT_DEBUG=true` 启用默认调试日志记录器。

* * *

## API参考

-   [文档/ sdk /](https://npmcn.com/package/%40mutagent/sdk/docs/sdks/)：每组一页，包含每个方法、参数和错误
-   [FUNCTIONS.md](https://npmcn.com/package/%40mutagent/sdk/FUNCTIONS.md)：独立功能
-   [RUNTIMES.md](https://npmcn.com/package/%40mutagent/sdk/RUNTIMES.md)：支持运行时和TypeScript编译器选项
-   [docs.mutagent.io](https://docs.mutagent.io/)：平台文档

* * *

## 看到也

-   **[@mutagent / cli](https://www.npmjs.com/package/@mutagent/cli)**： MutagenT的命令行接口
-   **[docs.mutagent.io](https://docs.mutagent.io/)**：平台文档
-   **[API参考](https://docs.mutagent.io/api)**： REST API参考
-   **[mutagent.io](https://mutagent.io/)**:主页

* * *

## 许可证

本软件是专有和保密的。未经授权的复制、分发或使用是严格禁止的。

(c) 2026 MutagenT。版权所有。

* * *

由MutagenT团队精心打造

[推特](https://twitter.com/mutagent) • [不和](https://discord.gg/mutagent) • [网站](https://mutagent.io/) • [文档](https://docs.mutagent.io/)

## 常见问题

### 如何安装 @mutagent/sdk？

在项目目录运行 npm install @mutagent/sdk，或使用 pnpm add / yarn add / bun add。

### @mutagent/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @mutagent/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @mutagent/sdk 可以商用吗？

@mutagent/sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @mutagent/sdk 还在维护吗？

最新版本 0\.12\.51 发布于 2026/11/02（1 天前）；至今共发布 360 个版本，其中过去 12 个月发布了 360 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。