@prisme.ai/sdk-agents

Official Node.js SDK for the Prisme.ai Agent Factory and Storage APIs.

Installation

npm install @prisme.ai/sdk-agents

Quick Start

import { PrismeAI } from '@prisme.ai/sdk-agents';

const client = new PrismeAI({
  apiKey: process.env.PRISMEAI_API_KEY,
  environment: 'production', // or 'sandbox'
  agentFactoryWorkspaceId: 'your-workspace-id',
  storageWorkspaceId: 'your-storage-workspace-id', // optional
});

Authentication

The SDK supports two authentication methods:

// API Key (recommended for server-side)
const client = new PrismeAI({
  apiKey: 'sk-...',
  agentFactoryWorkspaceId: 'ws-id',
});

// Bearer Token (for user-scoped access)
const client = new PrismeAI({
  bearerToken: 'eyJ...',
  agentFactoryWorkspaceId: 'ws-id',
});

Environment variables PRISMEAI_API_KEY and PRISMEAI_BEARER_TOKEN are also supported.

Usage Examples

Agents

// List agents
const agents = client.agents.list();
for await (const agent of agents) {
  console.log(agent.name);
}

// Create an agent
const agent = await client.agents.create({
  name: 'My Agent',
  description: 'A helpful assistant',
  model: 'claude-sonnet-4-20250514',
  instructions: 'You are a helpful assistant.',
});

// Get, update, delete
const fetched = await client.agents.get(agent.id);
const updated = await client.agents.update(agent.id, { name: 'Renamed Agent' });
await client.agents.delete(agent.id);

// Publish / discard draft
await client.agents.publish(agent.id);
await client.agents.discardDraft(agent.id);

Messages

// Send a message (non-streaming)
const response = await client.agents.messages.send('agent-id', {
  message: 'Hello, how are you?',
  conversationId: 'conv-id', // optional
});
console.log(response);

// Stream a message (SSE)
const stream = await client.agents.messages.stream('agent-id', {
  message: 'Tell me a story',
});
for await (const event of stream) {
  if (event.type === 'delta') {
    process.stdout.write(event.content ?? '');
  }
}

Conversations

// List conversations
for await (const conv of client.agents.conversations.list()) {
  console.log(conv.id, conv.title);
}

// Create and manage
const conv = await client.agents.conversations.create({ agentId: 'agent-id' });
await client.agents.conversations.update(conv.id, { title: 'New Title' });

// Get messages in a conversation
for await (const msg of client.agents.conversations.messages(conv.id)) {
  console.log(msg.role, msg.content);
}

A2A (Agent-to-Agent)

// Send a message to another agent
const result = await client.agents.a2a.send('target-agent-id', {
  message: 'Perform this task',
});

// Stream A2A response
const a2aStream = await client.agents.a2a.sendSubscribe('target-agent-id', {
  message: 'Perform this task',
});
for await (const event of a2aStream) {
  console.log(event);
}

// Get agent card
const card = await client.agents.a2a.getCard('agent-id');

Files (Storage)

// Upload a file
const file = await client.storage.files.upload(
  Buffer.from('Hello World'),
  { filename: 'hello.txt' },
);

// List files
for await (const f of client.storage.files.list()) {
  console.log(f.name, f.size);
}

// Download
const response = await client.storage.files.download(file.id);

Vector Stores (Storage)

// Create a vector store
const vs = await client.storage.vectorStores.create({
  name: 'My Knowledge Base',
});

// Search
const results = await client.storage.vectorStores.search(vs.id, {
  query: 'How do I reset my password?',
  limit: 5,
});

// Manage files in a vector store
await client.storage.vectorStores.files.add(vs.id, {
  fileId: 'file-id',
});

for await (const file of client.storage.vectorStores.files.list(vs.id)) {
  console.log(file.name, file.status);
}

Tasks

for await (const task of client.tasks.list({ status: 'running' })) {
  console.log(task.id, task.status);
}

const task = await client.tasks.get('task-id');
await client.tasks.cancel('task-id');

Pagination

All list methods return async iterables that auto-paginate:

// Auto-pagination with for-await
for await (const agent of client.agents.list()) {
  console.log(agent.name);
}

// Manual page control
const page = client.agents.list({ limit: 10 });
const firstPage = await page.getPage();
console.log(firstPage.data, firstPage.total);

// Collect all into array
const allAgents = await client.agents.list().toArray();

Error Handling

import {
  PrismeAIError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  ValidationError,
} from '@prisme.ai/sdk-agents';

try {
  await client.agents.get('nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Agent not found');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${error.retryAfter}ms`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid credentials');
  } else if (error instanceof PrismeAIError) {
    console.log(error.message, error.status);
  }
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | PRISMEAI_API_KEY env | API key for authentication | | bearerToken | string | PRISMEAI_BEARER_TOKEN env | Bearer token for auth | | environment | string | 'production' | 'sandbox' or 'production' | | baseURL | string | — | Custom API base URL (overrides environment) | | agentFactoryWorkspaceId | string | required | Workspace ID for Agent Factory | | storageWorkspaceId | string | — | Workspace ID for Storage API | | timeout | number | 60000 | Request timeout in ms | | maxRetries | number | 2 | Max retries on 429/5xx |

Requirements

• Node.js 18+
• No runtime dependencies (uses native fetch)

License

MIT