- SDK
- Create & update assistants
SDK
Create & update assistants
Use the SDK to create, list, update, and delete assistants—the saved AI profiles your threads attach to.
Overview
Use these methods when you want a named AI profile with stable defaults: instructions, tools, RAG settings, memory prompts, and embeddings. End-users still chat in threads; each thread links to one assistant.
For day-to-day messaging patterns (thread_id, assistant_id), see Continuing conversations and First Message.
Create an assistant
Python
JavaScript
TypeScript
import asyncio
from backboard import BackboardClient
async def main():
client = BackboardClient(api_key="YOUR_API_KEY")
assistant = await client.create_assistant(
name="Technical Support",
system_prompt="You are a concise technical support assistant.",
tok_k=15,
tools=[{
"type": "function",
"function": {
"name": "search_kb",
"description": "Search the knowledge base",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"}
},
"required": ["query"]
}
}
}]
)
print(f"Created: {assistant.assistant_id}")
if __name__ == "__main__":
asyncio.run(main())
Configuration options
| Parameter | Type | Mutable? | Description |
|---|---|---|---|
name | string | Yes | Human-readable name (1–255 chars, required) |
system_prompt | string | Yes | Instructions defining the assistant’s behavior |
tools | array | Yes | Tool definitions for function calling |
tok_k | integer | Yes | Document chunks retrieved per query (1–100, default 10) |
custom_fact_extraction_prompt | string | Yes | Custom prompt for memory fact extraction |
custom_update_memory_prompt | string | Yes | Custom prompt for memory update decisions |
embedding_provider | string | No | Embedding provider (openai, google, cohere, etc.) |
embedding_model_name | string | No | Embedding model (e.g. text-embedding-3-large) |
embedding_dims | integer | No | Embedding dimensions (e.g. 3072) |
Embedding configuration is immutable. embedding_provider, embedding_model_name, and embedding_dims cannot be changed after creation. Choose carefully based on your needs.
Get an assistant
Python
JavaScript
TypeScript
assistant = await client.get_assistant(assistant_id)
print(f"{assistant.name} — created {assistant.created_at}")
List assistants
Supports skip/limit pagination and an exact-match name filter.
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
skip | integer | 0 | 0–10 000 | Number of records to skip |
limit | integer | 100 | 1–200 | Maximum number of records to return |
name | string | — | ≤255 chars | Return only assistants with exactly this name (case-sensitive, no substring match). Useful for resolving an assistant by name without downloading the full list. |
Python
JavaScript
TypeScript
assistants = await client.list_assistants(skip=0, limit=50)
for a in assistants:
print(f"{a.assistant_id}: {a.name}")
# Resolve a single assistant by its exact name
[support_bot] = await client.list_assistants(name="Support Bot", limit=1)
Update an assistant
All fields are optional. tools replaces the existing list entirely. Set a custom prompt to an empty string to revert to the default.
Python
JavaScript
TypeScript
updated = await client.update_assistant(
assistant_id,
system_prompt="Updated instructions here",
tok_k=20,
custom_fact_extraction_prompt="Extract only personal preferences."
)
Clone an assistant
Duplicates an assistant into a new one owned by the caller. The clone is a point-in-time snapshot — its configuration, knowledge-base documents (with vectors preserved), and active memories are copied across, then evolve independently from the source.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | "{source name} Copy" | Name for the cloned assistant |
system_prompt | string | source’s value | Optional system prompt override |
copy_documents | boolean | true | Whether to clone indexed assistant-level documents |
copy_memories | boolean | true | Whether to clone active assistant memories |
The response includes the new assistant plus counts of what was copied.
Python
JavaScript
TypeScript
result = await client.clone_assistant(
assistant_id,
name="Technical Support (Staging)",
copy_documents=True,
copy_memories=True,
)
print(f"Cloned: {result.assistant.assistant_id}")
print(f"Docs cloned: {result.documents_cloned}")
print(f"Memories cloned: {result.memories_cloned}")
The embedding model is always copied verbatim from the source so vector spaces stay compatible. The clone receives its own Turbopuffer namespace.
Delete an assistant
Permanently deletes the assistant, all its threads, documents, and memories.
Python
JavaScript
TypeScript
result = await client.delete_assistant(assistant_id)
Related
- Assistant profiles — what an assistant represents
- Continuing conversations —
thread_idandassistant_idin practice - Documents — upload docs to an assistant or thread