Custodian Class

Use the Custodian class when you want to configure an assistant step by step before deploying it as an App.

For the shortest path to a working assistant, start with Create Your First Assistant. Use the Custodian class when you need to add examples, attach knowledge files, or reuse an assistant configuration before deployment.

Create an Assistant

from custodian_labs import Custodian

custodian = Custodian(
    model="gpt-4o",
    system_prompt="You are a helpful customer support assistant.",
    privacy_enabled=True,
)

Constructor Parameters

Parameter	Type	Required	Default	Description
model	str	Yes	-	The model used by the assistant.
system_prompt	str	Yes	-	Instructions that define the assistant's role and behavior.
name	str	No	-	A friendly name for the Custodian.
description	str	No	-	Optional description used for routing in a Custodian Squad.
tools	list[str]	No	-	Built-in tools to enable, such as ["web_search", "scrape_url"].
examples	list[dict]	No	-	Few-shot examples with user and assistant fields.
input_schema	dict	No	-	Input contract for the Custodian.
response_schema	dict	No	-	Structured output contract; responses are returned as JSON matching this schema.
privacy_enabled	bool	No	False	Mask sensitive data before it is sent to the model.
api_key	str	No	Environment variable	Custodian Labs API key.
base_url	str	No	Environment variable	Platform API base URL.
timeout	float	No	30.0	Request timeout in seconds.
max_retries	int	No	2	Number of retries for failed server requests.

For API key and API URL configuration, see Authentication.

Methods

Method	Purpose	Learn more
.add_examples(examples)	Add sample conversations to guide responses. Each example requires user and assistant fields. Few shot training for LLMs	See the example below. More info: https://www.ibm.com/think/topics/few-shot-prompting
.add_data_source_file(path)	Attach a local knowledge file to the assistant.	Data Sources and RAG
.deploy(name, share_mode, share_password)	Deploy the configured assistant and return a chat-ready App.	Chat Sessions
.chat(message)	Deploy the assistant and send a message in one call.	Chat Sessions

Tools

Pass tools to give the Custodian built-in capabilities such as web search and page scraping:

custodian = Custodian(
    model="gpt-4o",
    system_prompt="You are a web research assistant. Use web search to find current information and cite sources.",
    tools=["web_search", "scrape_url"],
)

Available built-in tools:

Tool	Purpose
web_search	Search the web for current information about a topic.
scrape_url	Extract the full content from a specific webpage URL.

Response Schema

Set response_schema to ask the Custodian to return structured JSON. Responses then include a structured_output field matching your schema.

custodian = Custodian(
    model="gpt-4o",
    system_prompt="Assess the risk and reply as JSON.",
    response_schema={
        "type": "object",
        "properties": {"verdict": {"type": "string"}, "confidence": {"type": "number"}},
        "required": ["verdict", "confidence"],
    },
)

app = custodian.deploy()
reply = app.chat("Assess the risk for ACME Corp (low).")
print(reply.structured_output)  # {"verdict": "low", "confidence": 0.95}

Sharing

A Custodian's sharing is set at deploy time on the container — never on the objects themselves:

share_mode	Behavior
"public"	Anyone with the link can chat. Default.
"private"	Only the owner can access it.
"password"	Access is protected by share_password.

app = custodian.deploy()                                      # public (default)
app = custodian.deploy(share_mode="private")
app = custodian.deploy(share_mode="password", share_password="s3cret")

Example

from custodian_labs import Custodian

custodian = Custodian(
    model="gpt-4o",
    system_prompt="You are a helpful assistant for customer support.",
    privacy_enabled=True,
    tools=["web_search", "scrape_url"],
)

custodian.add_examples(
    [
        {
            "user": "How do I reset my password?",
            "assistant": "Go to settings, open security, and choose reset password.",
        }
    ]
)

app = custodian.deploy(share_mode="public")

reply = app.chat("How do I invite a new teammate?")
if reply is not None:
    print(reply.response)
    print(reply.session_id)

Use the returned App to start a conversation. For chat methods and session behavior, see Chat Sessions.

Next Steps

• Builder API: configure an assistant with a fluent builder style.
• Data Sources and RAG: add knowledge files and understand retrieval.
• Chat Sessions: manage multi-turn conversations.