AgentMatrix TypeScript SDK

TypeScript and JavaScript SDK for building applications on AgentMatrix.

Install

npm install @agentmatrix.pro/sdk

The package is ESM-only and supports Node.js 18 or later. Compatible runtimes must provide the standard Fetch, Web Streams, AbortController, TextDecoder, and Web Crypto APIs.

Quickstart

import { AgentMatrix } from "@agentmatrix.pro/sdk";

const client = new AgentMatrix({
  apiKey: process.env.AGENTMATRIX_API_KEY,
  baseURL: process.env.AGENTMATRIX_BASE_URL!,
  namespace: process.env.AGENTMATRIX_NAMESPACE,
});

const sessions = await client.sessions.list({ limit: 20 });

for (const session of sessions.data) {
  console.log(session.session_id, session.current_status);
}

baseURL is the API URL for your AgentMatrix deployment. Keep API keys in environment variables or a secret manager rather than source code.

Configuration

The AgentMatrix constructor accepts:

| Option | Description | | --- | --- | | baseURL | Required AgentMatrix API URL. | | apiKey | API key sent as Bearer authentication. | | namespace | Optional namespace routing value. | | region | Optional region routing value. | | timeoutMs | Optional request deadline in milliseconds. | | maxRetries | Retry count for eligible transient failures. Defaults to 0. | | fetch | Optional Fetch-compatible implementation. |

Request methods also accept per-request timeout, retry, header, and AbortSignal options.

Core APIs

The client provides typed resources for:

• Agent specifications and immutable versions
• Environment specifications and sandbox provider discovery
• Sessions, events, messages, usage, resources, and web previews
• Volume attachments, skills, and artifacts
• Non-secret LLM provider credential discovery for session creation

Use the resource methods directly when you need REST-shaped operations. For a common conversational turn, runTurn sends one user message and yields typed updates until the turn finishes:

const sessionId = process.env.AGENTMATRIX_SESSION_ID!;

for await (const update of client.sessions.runTurn(sessionId, "Hello")) {
  switch (update.type) {
    case "accepted":
      console.log("message accepted", update.event.sequence);
      break;
    case "event":
      if (update.event.type === "agent.message") {
        console.log(update.event.payload.content);
      }
      break;
    case "result":
      console.log("turn finished", update.result.status);
      break;
  }
}

Session event types are discriminated unions, so TypeScript narrows each event payload from its type field.

Event Consumption

For application event loops, use watchWithHistory to consume existing events and continue watching for new ones. Persist the cursor reported through onCursor after your application has processed it.

let afterSequence = 0;

for await (const event of client.sessions.events.watchWithHistory(sessionId, {
  afterSequence,
  onCursor: (cursor) => {
    afterSequence = cursor;
  },
  retry: { maxAttempts: 3 },
})) {
  console.log(event.sequence, event.type);
}

For one message at a time, prefer runTurn. Use client.sessions.events.list, stream, or watchWithHistory when your application needs direct control over history, live events, or cursor storage.

Error Handling

import { APIError, TimeoutError } from "@agentmatrix.pro/sdk";

try {
  await client.sessions.get(sessionId);
} catch (error) {
  if (error instanceof APIError) {
    console.error(error.status, error.code, error.requestId, error.traceId);
  } else if (error instanceof TimeoutError) {
    console.error(`request timed out after ${error.timeoutMs}ms`);
  } else {
    throw error;
  }
}

SDK errors expose the request trace ID when available, which can be used to correlate client failures with AgentMatrix support and service logs.

Tenant Management

Use the companion @agentmatrix.pro/management-sdk package for enterprise tenant administration such as member, namespace, API key, and provider credential management. The two packages version independently and can be used together in the same application.

More Information

Product information, documentation, and support are available at agentmatrix.pro.

License

Apache-2.0