@mutagent / sdk

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

MutagenT平台API的TypeScript客户端。

目录表

• SDK涵盖的内容
• 0.6.0的突破性变化
• 安装
• 快速入门
• 身份验证
• 客户群体
• 流媒体
• 分页
• 重试
• 错误处理
• 服务器选择
• 自定义HTTP客户机
• 独立的功能
• 调试
• API参考
• 看到也
• 许可证

SDK涵盖的内容

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

每个方法也可以作为独立函数使用(参见 独立的功能）。

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行重命名已经有自己名称的操作。

独立函数名遵循相同的更改，包括组前缀。例如 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

npm install @mutagent/sdk

规划

pnpm add @mutagent/sdk

纱

yarn add @mutagent/sdk

包子

bun add @mutagent/sdk

这个包提供了CommonJS (require)和ES模块(import)构建。列出了支持的运行时 在 RUNTIMES.md.

快速入门

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 选项有两个字段。当您不传递它们时，将从环境中读取它们。

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

API密匙

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

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.

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函数，该函数允许您刷新 在沙箱令牌到期之前。

客户群体

下面的示例假设内置了客户机 身份验证． 示例 sandbox， environments 和 helixSessions 需要一个持有沙盒令牌的客户端。

userProfile

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

组织

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

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

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

工作区

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

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

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

邀请

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: "[email protected]", role: OrganizationRole.Editor },
  });
  console.log(invitation.id);
}

代理

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

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

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

痕迹

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

沙盒

需要一个沙盒令牌(参见 沙箱令牌）。

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

环境

需要一个沙盒令牌。

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 呼叫。

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 /.

流媒体

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

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：

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 读下一页。

重试

每呼叫重试配置

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

全局重试配置

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.

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

错误的属性

错误类

扩展 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 / 列出每个方法可能抛出的错误。

服务器选择

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

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

自定义HTTP客户机

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

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 持有值或已知错误，而不是抛出 这样的错误了。

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 在方法页下面 文档/ sdk /.

调试

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

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

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

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

API参考

• 文档/ sdk /：每组一页，包含每个方法、参数和错误
• FUNCTIONS.md：独立功能
• RUNTIMES.md：支持运行时和TypeScript编译器选项
• docs.mutagent.io：平台文档

看到也

• @mutagent / cli： MutagenT的命令行接口
• docs.mutagent.io：平台文档
• API参考： REST API参考
• mutagent.io:主页

许可证

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

(c) 2026 MutagenT。版权所有。

_{由MutagenT团队精心打造}

推特 • 不和 • 网站 • 文档