Getting Started

@personaai/sdk is the official Node.js/TypeScript client for the Persona Developer Platform API — Agents, Skills, Knowledge bases, MCP connectors, named Stores, persistent memory, and streaming chat, all from your own backend. Every method on every resource client is a thin, typed 1:1 wrapper over a real REST endpoint. There is no hidden behavior: what the SDK sends, and what it returns, is exactly what the API Reference documents for the endpoint it wraps.

Server-side only. Every method sends your Project’s credential — a server-side secret. Never construct PersonaClient in a browser bundle, a mobile app, or a Next.js Client Component. See the Integration Guide for the full reasoning and a per-resource “who calls this, and when” table.

Prerequisites

Node.js 18+ (or any runtime with a global fetch, FormData, and ReadableStream — the SDK uses the built-ins, no heavy HTTP dependency). This includes Next.js Edge runtime and Deno/Bun runtimes that expose the standard web APIs.
A Project credential shaped "<keyId>.<secret>", minted in Developer Studio. This is what authenticates every call.- TypeScript 5.x if you’re using TypeScript (types ship with the package — the package builds against 5.7; see Compatibility). Plain JavaScript works too — the package ships both ESM and CommonJS builds plus .d.ts types.

Install

npm install @personaai/sdk

pnpm add @personaai/sdk

The package ships ESM (dist/index.js), CommonJS (dist/index.cjs), and TypeScript declarations (dist/index.d.ts) — import and require both work, and one import covers the client, every resource, and every type. There is no separate @personaai/sdk/types entry point.

Initialization

Create a PersonaClient with a baseUrl and your credential:

import { PersonaClient } from '@personaai/sdk';

const persona = new PersonaClient({
  baseUrl: 'https://api.persona.hasanraiyan.me',
  credential: process.env.PERSONA_CREDENTIAL!, // "<keyId>.<secret>", minted via Studio
});

Both baseUrl and credential are required — constructing the client without them throws synchronously. baseUrl trailing slashes are stripped automatically.

The two client modes

The same client class serves two different identities, and which one you build determines what you can do:

Mode	How	Acts as	Typical calls
Control-plane	omit `externalUserId`	The Project itself	`whoami()`, Providers, Agent/Skill/KB/MCP/Store config CRUD, audit logs
Runtime-plane	set `externalUserId`	One of your own end users	Threads, Files, Memory, Chat, per-user ownership

// Control-plane — Project-level calls only.
const persona = new PersonaClient({
  baseUrl: '...',
  credential: process.env.PERSONA_CREDENTIAL!,
});

// Runtime-plane — acts on behalf of one specific end user of yours.
// Construct this per request, after YOUR OWN auth confirms who the user is.
const userClient = new PersonaClient({
  baseUrl: '...',
  credential: process.env.PERSONA_CREDENTIAL!,
  externalUserId: currentUser.id,
});

Full details on every option, defaults, and environment variables live in Configuration.

Minimal working example

import { PersonaClient } from '@personaai/sdk';

const persona = new PersonaClient({
  baseUrl: 'https://api.persona.hasanraiyan.me',
  credential: process.env.PERSONA_CREDENTIAL!,
});

async function main() {
  // 1. Sanity-check your credential wiring — side-effect free.
  const who = await persona.whoami();
  console.log(`Authenticated as ${who.principalType} in domain ${who.domain}`);

  // 2. Provision an Agent (one-time, control-plane call).
  const agent = await persona.agents.create({
    name: 'Career Launchpad',
    systemPrompt: 'You help students find internships.',
    providerId: '...', // an existing Provider's id — see below
    visibility: 'unlisted',
  });

  console.log('Created agent:', agent._id);
}

main().catch(console.error);

Before that Agent can run, it needs a Provider (the LLM endpoint it talks to):

const provider = await persona.providers.create({
  label: 'OpenAI (prod)',
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!, // encrypted at rest; never returned in any response
  defaultModel: 'gpt-4o-mini',
});

First real operation: streaming chat

Chat runs as a specific end user, so you need a runtime-plane client:

const userClient = new PersonaClient({
  baseUrl: 'https://api.persona.hasanraiyan.me',
  credential: process.env.PERSONA_CREDENTIAL!,
  externalUserId: 'user_123', // your own id for this person
});

// Full AG-UI event stream — for building your own UI.
for await (const event of userClient.chat.stream(agent._id, {
  messages: [{ role: 'user', content: 'What internships are open right now?' }],
})) {
  if (event.type === 'TEXT_MESSAGE_CHUNK' && event.delta) process.stdout.write(event.delta);
}

// Or the convenience wrapper — drains the stream, returns the final text.
const result = await userClient.chat.sendMessage(agent._id, {
  messages: [{ role: 'user', content: 'What internships are open right now?' }],
});
console.log(result.text);

Framework recipes

Express

No special handling — construct the client once at module scope (or a factory), and per-request runtime-plane clients in your route handlers.

// persona.ts
export function personaFor(externalUserId?: string) {
  return new PersonaClient({
    baseUrl: process.env.PERSONA_BASE_URL!,
    credential: process.env.PERSONA_CREDENTIAL!,
    externalUserId,
  });
}

// routes/chat.ts
app.post('/api/chat', async (req, res) => {
  const persona = personaFor(req.user.id); // your own auth already ran
  const result = await persona.chat.sendMessage(req.body.agentId, {
    messages: req.body.messages,
  });
  res.json(result);
});

NestJS

Wrap PersonaClient in an @Injectable() provider so it plugs into Nest’s DI container like any other third-party client — the SDK itself needs no Nest-specific support.

// persona.service.ts
import { Injectable } from '@nestjs/common';
import { PersonaClient } from '@personaai/sdk';

@Injectable()
export class PersonaService {
  forUser(externalUserId: string) {
    return new PersonaClient({
      baseUrl: process.env.PERSONA_BASE_URL!,
      credential: process.env.PERSONA_CREDENTIAL!,
      externalUserId,
    });
  }
}

Next.js — read this one carefully

Next.js blurs server and client code in one codebase more than Express or Nest does, which makes it the one framework people actually leak the credential in by accident.

Only import this SDK in Server Components, Route Handlers (app/api/.../route.ts), or Server Actions. Never in a "use client" component. Constructing PersonaClient in client code bundles your Project credential straight into the JavaScript shipped to the browser.

// app/api/chat/route.ts — Route Handler, runs server-side only
import { PersonaClient } from '@personaai/sdk';

export async function POST(req: Request) {
  const { agentId, messages } = await req.json();
  const userId = await getCurrentUserId(req); // your own auth
  const persona = new PersonaClient({
    baseUrl: process.env.PERSONA_BASE_URL!,
    credential: process.env.PERSONA_CREDENTIAL!,
    externalUserId: userId,
  });
  const result = await persona.chat.sendMessage(agentId, { messages });
  return Response.json(result);
}

Because the SDK uses native fetch, it also works in Next.js’s Edge runtime, not just Node — no extra configuration needed. For a live-streaming chat UI, a Route Handler can return a ReadableStream directly, relaying the AG-UI event stream onward to your own browser client:

export async function POST(req: Request) {
  const { agentId, messages } = await req.json();
  const persona = new PersonaClient({
    /* ... */ externalUserId: await getCurrentUserId(req),
  });

  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();
      for await (const event of persona.chat.stream(agentId, { messages })) {
        controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
      }
      controller.close();
    },
  });
  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream' } });
}

Where to go next

You want to…	Read
Every configuration option, env var, and default	Configuration
The client surface & `whoami()`	PersonaClient
The low-level HTTP layer	HttpClient
Error classes and how to handle failures	Errors
A specific resource’s full API	Resources (one page each)
Streaming chat, interrupts, and run errors	Chat
The conversational Agent Architect	Architect
Every exported type, field by field	Types
Retries, pagination, idempotency, edge cases	Behavior & edge cases
Realistic end-to-end scenarios	Workflows
Common problems and fixes	Troubleshooting
Runtimes, frameworks, and version support	Compatibility

Out of scope

Project/Members/Credentials management (creating Projects, inviting Members, minting/revoking credentials) is intentionally not part of this SDK — those are Clerk-session (human admin) operations with a completely different auth model than the machine-credential calls this SDK makes. Manage them from Developer Studio instead.

Node.js SDK Reference

React SDK Reference

UI Components Reference

Next.js Adapter

Express Adapter

NestJS Adapter

Python SDK Reference

Runtime Reference

Prerequisites

Install

Initialization

The two client modes

Minimal working example

First real operation: streaming chat

Framework recipes

Express

NestJS

Next.js — read this one carefully

Where to go next

Out of scope

​Prerequisites

​Install

​Initialization

​The two client modes

​Minimal working example

​First real operation: streaming chat

​Framework recipes

​Express

​NestJS

​Next.js — read this one carefully

​Where to go next

​Out of scope

Prerequisites

Install

Initialization

The two client modes

Minimal working example

First real operation: streaming chat

Framework recipes

Express

NestJS

Next.js — read this one carefully

Where to go next

Out of scope