Node.js SDK

git clone https://github.com/hasanraiyan/agent-marketplace.git
cd agent-marketplace/sdk
npm install
npm run build      # compiles src/ -> dist/ (ESM + CJS + .d.ts)

npm install /path/to/agent-marketplace/sdk

# in agent-marketplace/sdk
npm link

# in your project
npm link @personaai/sdk

npm install @personaai/sdk

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

// Control-plane client — acts as the Project itself.
const persona = new PersonaClient({
  baseUrl: process.env.PERSONA_BASE_URL!,
  credential: process.env.PERSONA_CREDENTIAL!,
});

// Runtime-plane client — acts as one specific end user of yours.
const userClient = new PersonaClient({
  baseUrl: process.env.PERSONA_BASE_URL!,
  credential: process.env.PERSONA_CREDENTIAL!,
  externalUserId: currentUser.id,
});

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

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

const who = await persona.whoami();
console.log(who.principalType, who.domain);

const agent = await persona.agents.create({
  name: "Career Launchpad",
  systemPrompt: "You help students find internships.",
  providerId: "...", // an existing Provider's id
  visibility: "unlisted",
});

const userClient = new PersonaClient({
  baseUrl: "https://api.personaai.com",
  credential: process.env.PERSONA_CREDENTIAL!,
  externalUserId: currentUser.id,
});

const thread = await userClient.threads.create({ agentId: agent._id });

const who = await persona.whoami();

import {
  PersonaApiError,
  PersonaAuthError,
  PersonaValidationError,
} from "@personaai/sdk";

try {
  await persona.agents.create({
    name: "",
    systemPrompt: "...",
    providerId: "...",
  });
} catch (err) {
  if (err instanceof PersonaValidationError) {
    console.error(`Bad request (${err.code}): ${err.message}`);
  } else if (err instanceof PersonaAuthError) {
    console.error(`Auth problem (${err.statusCode}): ${err.message}`);
  } else if (err instanceof PersonaApiError) {
    console.error(`API error (${err.statusCode}/${err.code}): ${err.message}`);
  } else {
    throw err; // not a Persona error — a network failure, abort, etc.
  }
}

const patientClient = new PersonaClient({
  baseUrl: "...",
  credential: "...",
  maxRetries: 5, // retry up to 5 times on 429 before throwing
});

const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // give up after 30s

await userClient.chat.sendMessage(agent._id, {
  messages: [{ role: "user", content: "..." }],
  signal: controller.signal,
});

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

const { success, message } = await persona.providers.testConnection(
  provider.id,
);
const models = await persona.providers.getModels(provider.id);

const skill = await persona.skills.create({
  name: "Resume Reviewer",
  description: "Reviews a resume and suggests concrete edits.",
  instructions: "You are an expert resume reviewer...",
  isPublic: false,
  files: [{ path: "rubric.md", content: "# Scoring rubric\n..." }],
});

const mine = await userClient.skills.list({ scope: "mine", search: "resume" });
const full = await persona.skills.get(skill._id);
await persona.skills.update(skill._id, { description: "Updated description." });
await persona.skills.delete(skill._id);

const agent = await persona.agents.create({
  name: "Career Launchpad",
  systemPrompt: "You help students find internships.",
  providerId: provider.id,
  description: "Your internship search co-pilot.",
  category: "productivity",
  visibility: "unlisted",
  webSearchEnabled: true,
  skills: [skill._id],
});

const discovered = await persona.agents.list({
  category: "productivity",
  search: "career",
});
const full = await persona.agents.get(agent._id); // skills/mcps/knowledgeBases populated as objects
await persona.agents.update(agent._id, {
  tagline: "Find your next internship.",
});
await persona.agents.delete(agent._id);

const kb = await persona.knowledge.create({
  name: "Placement Office FAQ",
  providerId: provider.id, // required — no "my default provider" concept on this API
  chunkSize: 1000,
  chunkOverlap: 200,
  topK: 5,
});

// Upload from a Node Buffer (fs.readFile) or an already-built Blob.
import { readFile } from "node:fs/promises";
const pdf = await readFile("./faq.pdf");
const result = await persona.knowledge.uploadDocuments(kb._id, [
  { filename: "faq.pdf", content: pdf, contentType: "application/pdf" },
]);
// result: { documentCount, chunkCount, files: [{ fileName, fileSize, mimeType, chunkCount }] }

const docs = await persona.knowledge.listDocuments(kb._id);
await persona.knowledge.deleteDocument(kb._id, "faq.pdf");

const hits = await persona.knowledge.search(
  kb._id,
  "What's the deadline to apply?",
  { topK: 3 },
);
// hits: { text, source, score }[]

const mcp = await persona.mcps.create({
  name: "Internal Ticketing",
  transport: "http",
  url: "https://mcp.example.com",
  authType: "apiKey",
  apiKey: process.env.TICKETING_MCP_KEY!,
});

const { tools, resources, resourceTemplates } =
  await persona.mcps.testConnection(mcp._id);
const result = await persona.mcps.callTool(mcp._id, "create_ticket", {
  title: "Bug report",
});
const { text, mimeType } = await persona.mcps.readResource(
  mcp._id,
  resources[0].uri,
);

const thread = await userClient.threads.create({ agentId: agent._id });
const mine = await userClient.threads.list({ page: 1, limit: 20 });
await userClient.threads.updateTitle(thread._id, "Summer internship search");
const { messages, state } = await userClient.threads.getMessages(thread._id);
await userClient.threads.delete(thread._id);

import { readFile } from "node:fs/promises";

const resume = await readFile("./resume.pdf");
const file = await userClient.files.upload({
  filename: "resume.pdf",
  content: resume,
  contentType: "application/pdf",
  threadId: thread._id, // optional — associates the file with a conversation
});

const mine = await userClient.files.list({ page: 1, limit: 20 });

const response = await userClient.files.download(file.id); // raw Response, not JSON
const bytes = await response.arrayBuffer();

await userClient.files.delete(file.id);

// Full 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);

for await (const event of userClient.chat.stream(agent._id, { messages })) {
  switch (event.type) {
    case "TEXT_MESSAGE_CHUNK":
      process.stdout.write(event.delta ?? "");
      break;
    case "TOOL_CALL_RESULT":
      console.log("tool result:", event);
      break;
    case "RUN_FINISHED":
      console.log("done");
      break;
  }
}

const result = await userClient.chat.sendMessage(agent._id, { messages });

if (result.interrupt) {
  console.log(result.interrupt.kind); // 'hitl' | 'clarification'
  console.log(result.interrupt.value); // whatever detail the interrupt carries
}

if (result.interrupt) {
  await userClient.chat.sendMessage(agent._id, {
    threadId: thread._id,
    messages: [],
    resume: { decisions: [{ action: "delete_agent", decision: "approve" }] },
  });
}

// 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);
  const result = await persona.chat.sendMessage(req.body.agentId, {
    messages: req.body.messages,
  });
  res.json(result);
});

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

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

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