SDKs Overview & Concepts
Custodian Labs ships two official SDKs that wrap the same platform:
- Python SDK —
pip install custodian-labs - TypeScript / JavaScript SDK —
npm install @custodianlabs/sdk
Both talk to the same backend, expose the same capabilities, and produce the same deployed apps. This page explains the concepts they share. The language-specific sections then show the exact API for each.
Core objects
| Concept | What it is |
|---|---|
Custodian Agent (Custodian) | Your configuration for one AI agent: model, system prompt, few-shot examples, optional knowledge files, optional built-in tools, and whether privacy masking is on. |
| App | A deployed Custodian Agent. It has an ID and a chat URL, and it accepts chat messages. |
| Multi-agent team | A deployed group of specialized agents that route or pipeline a conversation. Python calls this a Custodian Squad; the TypeScript SDK calls it an Agent Team. Same feature. |
| Data source | A file (PDF, DOCX, XLSX, TXT) attached to a Custodian or agent, chunked and indexed for retrieval-augmented generation (RAG). |
| Chat session | A conversation that keeps context across messages. The SDK retains a session ID for you and resends it automatically. |
| Guardian Layer | A standalone service for detecting and masking PII/PHI in text and files (images coming soon). Available as its own SDK client (GuardianLayer), or automatically inline during chat when privacy is enabled. |
Lifecycle
Configure a Custodian Agent → deploy it as an App → chat (session retained for you)
- Python
- TypeScript
app = Custodian(model="gpt-4o", system_prompt="…").deploy()
app.chat("Hello")
const app = await new Custodian({ model: "gpt-4o", systemPrompt: "…" }).deploy();
await app.chat("Hello");
Multi-agent teams follow the same shape: configure agents → group into a team → deploy → chat.
Routing modes (multi-agent teams)
| Mode | Behavior |
|---|---|
single | One agent is selected per message based on topics. |
chain | Agents can hand off to each other, up to a max-handoffs limit. |
workflow | Agents run in a fixed order you specify; each agent's output feeds the next. |
Built-in tools
An agent can be given tools so it can act beyond its uploaded documents:
web_search— search the live webscrape_url— fetch and read a specific pageparse_document— extract text from a document by URL
External connections (Gmail) are coming soon. See Built-in Tools in each SDK section.
Two backend services
| Service | Purpose | Base URL |
|---|---|---|
| Platform API | Agents, apps, multi-agent, chat | https://platform.custodianlabs.io/v1 |
| Guardian Layer | De-identification | https://privacy.custodianlabs.io |
Both use the same Custodian API key (X-API-Key). The SDKs handle it — see
Authentication for Python or
TypeScript.