agentmatrix

TypeScript SDK for AgentMatrix PaaS — teams, agents, threads, messages, attachments, skills, and volumes.

Install

npm install agentmatrix

Quick Start

import { AgentMatrixClient } from "agentmatrix";

const client = new AgentMatrixClient({
  baseUrl: "https://your-paas-api.example.com",
  apiKey: "csp_your_api_key",
});

// Create a team (auto-creates a persistent Volume)
const team = await client.teams.create({ name: "my-team" });

// Add a Claude agent
const agent = await client.teams.addAgent(team.teamId, {
  agentId: "coder",
  acpxAgent: "claude",
  config: { systemPrompt: "You are a helpful coding assistant." },
});

// Upload an attachment
const attachment = await client.attachments.upload(
  team.teamId,
  new Blob(["task content"], { type: "text/plain" }),
  { filename: "task.txt", contentType: "text/plain" },
);

// Create a thread and send a message with the attachment
const thread = await client.threads.create(team.teamId);
const result = await client.messages.send(team.teamId, thread.threadId, "coder", {
  text: "Please read the attached file and complete the task.",
  attachmentIds: [attachment.attachmentId],
  timeoutMs: 300_000,
});

console.log(result.reply);

API

AgentMatrixClient

| Property | Description | |----------|-------------| | teams | Team & Agent CRUD | | threads | Thread CRUD | | messages | Send messages (sync/async), broadcast, multicast, query history | | attachments | Upload/download/list/delete attachments | | artifacts | Thread session file operations (list/read/write/delete/archive) | | skills | Create/update/list/delete reusable skill packages | | volumes | Direct volume file operations | | health | Health check | | admin | Admin operations (refresh env) | | apiKeys | API key lifecycle (create/list/revoke) |

Teams

client.teams.create({ name: "my-team", metadata?: { ... } })
client.teams.list()
client.teams.get(teamId)
client.teams.destroy(teamId)
client.teams.addAgent(teamId, { agentId, acpxAgent?, config?, envVars?, timeoutSeconds?, metadata? })
client.teams.getAgent(teamId, agentId)
client.teams.updateAgent(teamId, agentId, config)
client.teams.removeAgent(teamId, agentId)

Threads

client.threads.create(teamId, metadata?)
client.threads.list(teamId, { limit?, offset? })
client.threads.get(teamId, threadId)
client.threads.archive(teamId, threadId)

Messages

// Synchronous (waits for agent reply)
client.messages.send(teamId, threadId, agentId, { text, attachmentIds?, timeoutMs?, requestId? })

// Asynchronous (returns immediately)
client.messages.sendAsync(teamId, threadId, agentId, { text, attachmentIds?, timeoutMs?, requestId? })

// Broadcast to all agents
client.messages.sendAll(teamId, threadId, { text, attachmentIds?, timeoutMs?, requestId? })
client.messages.sendAllAsync(teamId, threadId, { text, attachmentIds?, timeoutMs?, requestId? })

// Multicast to specific agents
client.messages.sendSome(teamId, threadId, { text, agentIds, attachmentIds?, timeoutMs?, requestId? })
client.messages.sendSomeAsync(teamId, threadId, { text, agentIds, attachmentIds?, timeoutMs?, requestId? })

// Query history
client.messages.list(teamId, threadId, { limit?, offset? })

Attachments

// Upload (atomic: presigned URL → R2 direct upload → NFS sync)
client.attachments.upload(teamId, file, { filename, contentType? })

client.attachments.list(teamId)
client.attachments.getDownloadUrl(teamId, attachmentId)
client.attachments.delete(teamId, attachmentId)

Artifacts

// List artifacts in a thread session
client.artifacts.list(teamId, threadId, dir?)

// Read an artifact (returns download URL or content)
client.artifacts.read(teamId, threadId, path)

// Write content to an artifact
client.artifacts.write(teamId, threadId, { path, content, encoding? })

// Delete an artifact
client.artifacts.delete(teamId, threadId, path)

// Download all artifacts as tar.gz archive
client.artifacts.archive(teamId, threadId)

Skills

// Create + upload (atomic: metadata → upload zip → confirm)
const skill = await client.skills.create(teamId, {
  name: "code-reviewer",
  description: "Reviews code for bugs and security issues",
  file: readFileSync("./my-skill.zip"),  // optional, contains SKILL.md + resources
});

// Update
client.skills.update(teamId, skillId, { name?, description?, file? })

// CRUD
client.skills.list(teamId)
client.skills.get(teamId, skillId)
client.skills.delete(teamId, skillId)

// Bind to agent via config.skills
client.teams.addAgent(teamId, {
  agentId: "reviewer",
  config: { skills: [{ skillId: skill.skillId }] },
})

Volumes

client.volumes.uploadFile(volumeId, file, { filename })
client.volumes.getUploadUrl(volumeId, filename)
client.volumes.uploadToR2(presignedUrl, file)
client.volumes.sync(volumeId, r2Key)

Health

const status = await client.health.check();
// { ok: true, uptimeMs: 12345, agents: 3, wsClients: 1 }

Admin

const result = await client.admin.refreshEnv();
// { total: 5, success: 5, failed: [] }

API Keys

// Create (requires bootstrap key)
const { key } = await client.apiKeys.create("my-team");

client.apiKeys.list()
client.apiKeys.revoke(id)

Error Handling

import { AgentMatrixError } from "agentmatrix";

try {
  await client.teams.get("nonexistent");
} catch (err) {
  if (err instanceof AgentMatrixError) {
    console.log(err.statusCode); // 404
    console.log(err.message);    // "team not found"
  }
}

License

MIT