Skip to main content

Create Your First Custodian Agent

A Custodian Agent is one configured AI assistant — a model, a system prompt, and optional examples, knowledge files, and tools. In the SDK it is the Custodian class. This page shows the fastest way to deploy one and chat with it.

Before you begin​

Fastest path: createCustodian()​

createCustodian() creates and deploys a Custodian Agent in a single call and returns an App you can chat with.

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

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

console.log(app.chatUrl);

const reply = await app.chat("What should a new admin do first?");
console.log(reply?.response);

You can pass few-shot examples and enable inline privacy masking here too:

const app = await createCustodian({
  model: "gpt-4o",
  prompt: "You are a terse, no-fluff support agent.",
  privacyEnabled: true,
  examples: [
    { user: "Is my data safe?", assistant: "Yes. Data is encrypted at rest and in transit." },
  ],
});

Continue the conversation​

The returned App retains the chat session automatically, so a follow-up message keeps the earlier context:

const followUp = await app.chat("Can you say that in one sentence?");
console.log(followUp?.response);

See Chat Sessions for the details.

The chat response​

app.chat() resolves to a ChatResponse (or null in interactive mode):

FieldDescription
responseThe agent's reply text.
sessionIdThe session identifier returned by the API.
retrievedContextsData source chunks used for the response, if any.
messagesConversation messages returned by the API.
selectedAgentFor agent teams: which agent answered. null for a single Custodian Agent.
handoffPath / contributingAgentsFor agent teams: routing detail.
rawPayloadThe unmodified API response.

Configure sharing at deploy time​

Sharing is set when the app is deployed, not on the Custodian Agent itself:

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

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

const app = await custodian.deploy({ shareMode: "private" });
// or: { shareMode: "password", sharePassword: "s3cret" }
shareModeBehavior
"public"Anyone with the link can chat. Default.
"private"Only the owner can access it.
"password"Access requires sharePassword.

Interactive terminal chat​

Call .chat() with no argument to start an interactive REPL (Node.js TTY only):

await app.chat();
// Type "exit" or "quit" to end the session.

Next steps​