Skip to main content

Custodian Agent Class

The Custodian class configures and deploys a single Custodian Agent. Use it when you want to add examples, attach knowledge files, set tools, or reuse a configuration before deploying.

Create and deploy​

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

const custodian = new Custodian({
  model: "gpt-4o",
  systemPrompt: "You are a helpful support assistant.",
  privacyEnabled: true,
});

const app = await custodian.deploy();
const reply = await app.chat("How do I reset my password?");
console.log(reply?.response);

Constructor options​

OptionTypeNotes
modelstringRequired.
systemPromptstringRequired.
privacyEnabledbooleanDefault false. Masks PII in messages before the LLM sees them. See Guardian Layer.
namestringMetadata for the assistant.
descriptionstringMetadata for the assistant.
toolsstring[]Built-in tools: "web_search", "scrape_url", "parse_document". See Built-in Tools.
inputSchemaobjectJSON Schema constraining structured input.
responseSchemaobjectJSON Schema constraining structured output.
apiKeystringOverrides CUSTODIAN_SDK_API_KEY.
baseUrlstringOverrides CUSTODIAN_SDK_BASE_URL.
timeoutnumberRequest timeout in seconds. Default 30.
maxRetriesnumberRetries on network / 5xx errors. Default 2.

Configuration is local until deploy()​

addExamples() and addDataSourceFile() only stage data on the object. Every network call happens inside .deploy() — assistant creation, example upload, file upload, and deployment, in that order.

const custodian = new Custodian({ model: "gpt-4o", systemPrompt: "Answer from the docs." })
  .addExamples([{ user: "Who are you?", assistant: "I am your assistant." }])
  .addDataSourceFile("./docs/manual.pdf");

// No requests have been made yet.
const app = await custodian.deploy(); // all requests happen here
Difference from the Python SDK

In Python, .add_examples() and .add_data_source_file() each make an immediate API call. The TypeScript SDK defers everything to .deploy() so the fluent chain does not need an await after every method. The end result is identical.

Methods​

MethodPurpose
addExamples(pairs)Stage few-shot examples. Each pair needs non-empty user and assistant. Returns this.
addDataSourceFile(file)Stage a RAG file (path or in-memory bytes). Returns this.
deploy(options?)Create, configure, and deploy. Returns App.
chat(message?, options?)Deploy, then send one message (or start interactive chat).

Deploy options​

await custodian.deploy({
  name: "billing-bot",              // display name for the deployment
  shareMode: "password",            // "public" (default) | "private" | "password"
  sharePassword: "let-me-in",       // required when shareMode is "password"
});

Structured input and output​

const custodian = new Custodian({
  model: "gpt-4o",
  systemPrompt: "Classify the support ticket.",
  responseSchema: {
    type: "object",
    properties: { category: { type: "string" }, urgency: { type: "string" } },
    required: ["category", "urgency"],
  },
});

Next steps​