Examples

This page collects small Python SDK examples for common assistant workflows.

Before running these examples, make sure you have installed the SDK and configured your environment variables. See Installation and Authentication.

Basic Assistant

Use create_assistant() for the shortest path:

from custodian_labs import create_assistant

app = create_assistant(
    model="gpt-4o",
    prompt="You are a helpful assistant.",
)

response = app.chat("Give me a short introduction.")
print(response.response)

Learn more: Create Your First Assistant

Assistant with Examples

Use examples to guide the assistant's tone or response format:

from custodian_labs import Custodian

custodian = Custodian(
    model="gpt-4o",
    system_prompt="You are a support triage assistant.",
)

custodian.add_examples([
    {
        "user": "My order has not arrived.",
        "assistant": "Category: Shipping. Priority: High.",
    },
    {
        "user": "I want to change my email address.",
        "assistant": "Category: Account. Priority: Low.",
    },
])

app = custodian.deploy()

response = app.chat("I was charged twice for my subscription.")
print(response.response)

Learn more: Custodian Class

Assistant with a Knowledge File

Add a file when the assistant should answer from your own content:

from custodian_labs import Custodian

custodian = Custodian(
    model="gpt-4o",
    system_prompt="You are a helpful HR policy assistant.",
)

custodian.add_data_source_file("./employee-handbook.pdf")

app = custodian.deploy()

response = app.chat("What is the remote work policy?")
print(response.response)
print(response.retrieved_contexts)

Learn more: Data Sources and RAG

Builder Style

Use AssistantBuilder if you prefer a chained configuration style:

from custodian_labs import AssistantBuilder

app = (
    AssistantBuilder()
    .with_model("gpt-4o")
    .with_prompt("You are a helpful product documentation assistant.")
    .with_data_source_file("./product-guide.pdf")
    .deploy()
)

response = app.chat("What does the guide say about setup?")
print(response.response)

Learn more: Builder API

Multi-Agent Team

Use Agent and AgentTeam when different topics should route to different specialists:

from custodian_labs import Agent, AgentTeam

team = AgentTeam(
    agents=[
        Agent(
            name="billing",
            model="gpt-4o",
            system_prompt="Answer billing questions.",
            topics=["billing", "invoice", "refund", "payment"],
        ),
        Agent(
            name="data",
            model="gpt-4o",
            system_prompt="Answer questions about the uploaded CSV file.",
            topics=["data", "csv", "customer", "file"],
        ).add_data_source_file("sample_pii_data.csv"),
    ],
    routing_mode="single",
)

app = team.deploy()

reply = app.chat("How many people are in the uploaded file and which cities do they live in?")
if reply is not None:
    print(reply.response)
    print(reply.selected_agent)

Learn more: Multi-Agent Teams

Multi-Turn Conversation

The SDK automatically reuses the latest session ID on the same App instance:

from custodian_labs import create_assistant

app = create_assistant(
    model="gpt-4o",
    prompt="You are a helpful assistant.",
)

app.chat("My name is Alex.")

response = app.chat("What is my name?")
print(response.response)

Start fresh with:

app.reset_session()

Learn more: Chat Sessions

Interactive Terminal Chat

Call .chat() without a message to start an interactive terminal session:

from custodian_labs import create_assistant

app = create_assistant(
    model="gpt-4o",
    prompt="You are a helpful assistant.",
)

app.chat()

Type exit or quit to end the session.

Handling Errors

Catch SDK exceptions when building production applications:

from custodian_labs import AISDKError, create_assistant

try:
    app = create_assistant(
        model="gpt-4o",
        prompt="You are a helpful assistant.",
    )
    response = app.chat("Hello")
    print(response.response)
except AISDKError as error:
    print(error)

Learn more: Error Handling