Skip to main content

Examples

Small TypeScript SDK examples for common Custodian workflows. Before running these, install the SDK and configure your API key.

All examples use top-level await; wrap them in an async function if your setup does not support it.

Basic Custodian Agent​

import { createCustodian } from "@custodianlabs/sdk";

const app = await createCustodian({
  model: "gpt-4o",
  prompt: "You are a helpful assistant.",
});

const reply = await app.chat("Give me a short introduction.");
console.log(reply?.response);

Learn more: Create Your First Custodian Agent

Custodian Agent with examples​

import { Custodian } from "@custodianlabs/sdk";

const custodian = new Custodian({
  model: "gpt-4o",
  systemPrompt: "You are a support triage assistant.",
}).addExamples([
  { user: "My order has not arrived.", assistant: "Category: Shipping. Priority: High." },
  { user: "I want to change my email address.", assistant: "Category: Account. Priority: Low." },
]);

const app = await custodian.deploy();
const reply = await app.chat("I was charged twice for my subscription.");
console.log(reply?.response);

Learn more: Custodian Agent Class

Custodian Agent with a knowledge file (RAG)​

import { Custodian } from "@custodianlabs/sdk";

const custodian = new Custodian({
  model: "gpt-4o",
  systemPrompt: "You are a helpful HR policy assistant.",
}).addDataSourceFile("./employee-handbook.pdf");

const app = await custodian.deploy();
const reply = await app.chat("What is the remote work policy?");
console.log(reply?.response);
console.log(reply?.retrievedContexts);

Learn more: Data Sources and RAG

Builder style​

import { CustodianBuilder } from "@custodianlabs/sdk";

const app = await new CustodianBuilder()
  .withModel("gpt-4o")
  .withPrompt("You are a helpful product documentation assistant.")
  .withDataSourceFile("./product-guide.pdf")
  .deploy();

const reply = await app.chat("What does the guide say about setup?");
console.log(reply?.response);

Learn more: Builder API

Agent Team​

import { Agent, AgentTeam } from "@custodianlabs/sdk";

const team = new AgentTeam({
  agents: [
    new Agent({
      name: "billing",
      model: "gpt-4o",
      systemPrompt: "Answer billing questions.",
      topics: ["billing", "invoice", "refund", "payment"],
    }),
    new Agent({
      name: "data",
      model: "gpt-4o",
      systemPrompt: "Answer questions about the uploaded CSV file.",
      topics: ["data", "csv", "customer", "file"],
    }).addDataSourceFile("./pii_data.csv"),
  ],
  routingMode: "single",
});

const app = await team.deploy();
const reply = await app.chat("How many people are in the uploaded file, and which cities do they live in?");
console.log(reply?.response);
console.log(reply?.selectedAgent);

Learn more: Agent Teams

Research → write workflow with a tool​

import { Agent, AgentTeam } from "@custodianlabs/sdk";

const team = new AgentTeam({
  agents: [
    new Agent({
      name: "research",
      model: "gpt-4o",
      systemPrompt: "Research the topic. Produce notes with sources.",
      tools: ["web_search"],
      outputKey: "research_notes",
    }),
    new Agent({
      name: "writer",
      model: "gpt-4o",
      systemPrompt: "Write a one-paragraph brief from the research notes.",
    }),
  ],
  routingMode: "workflow",
  workflowOrder: ["research", "writer"],
});

const app = await team.deploy();
const reply = await app.chat("Give me a brief on RAG evaluation methods.");
console.log(reply?.response);

Learn more: Built-in Tools

Multi-turn conversation​

import { Custodian } from "@custodianlabs/sdk";

const app = await new Custodian({ model: "gpt-4o", systemPrompt: "You are helpful." }).deploy();

await app.chat("My name is Alex.");
const reply = await app.chat("What is my name?");
console.log(reply?.response);

app.resetSession(); // start fresh

Learn more: Chat Sessions

Guardian Layer — text​

import { GuardianLayer } from "@custodianlabs/sdk";

const guardian = new GuardianLayer();
const text = "John Smith lives in Boston and his phone number is 617-555-0100.";

const analysis = await guardian.analyzeProprietary(text);
console.log("Sensitive words:", analysis.sensitiveWords);

const outputs = await guardian.deidentifyTextOutputs(text, {
  maskingType: "redact",
  piiEntities: ["ALL"],
});
for (const item of outputs.outputs) console.log(item.id, item.text);

Learn more: Guardian Layer Client

Guardian Layer — file​

import { GuardianLayer } from "@custodianlabs/sdk";

const guardian = new GuardianLayer();

const result = await guardian.deidentifyFile("./pii_data.csv", {
  maskingType: "transform",
  piiEntities: ["PERSON", "EMAIL_ADDRESS", "PHONE_NUMBER"],
});

console.log(result.filename);
console.log(result.mediaType);
console.log(result.text());

Learn more: Guardian Layer Client

Handling errors​

import { createCustodian, CustodianError } from "@custodianlabs/sdk";

try {
  const app = await createCustodian({ model: "gpt-4o", prompt: "You are helpful." });
  const reply = await app.chat("Hello");
  console.log(reply?.response);
} catch (err) {
  if (err instanceof CustodianError) console.error(err.message);
  else throw err;
}

Learn more: Error Handling