Appearance
Custom Assistants Demo Script
Five demos. About twelve minutes. Reusable “GPT-style” profiles with instructions, knowledge attachments, and sensible defaults.
This script walks through GhostAI Custom Assistants: creating a profile in the UI, using it from standard chat and from Comparison Chat, sharing with the organization, and cloning for another team. Under the hood, sending assistant_id on chat causes the backend to load the assistant (if you own it or it is org-shared), merge instructions into custom_system_prompt when you did not override it yourself, and append knowledge_file_ids to attachments.
Pre-Demo Checklist
- [ ] GhostAI backend and frontend are running and reachable
- [ ] Feature flag
assistantsis enabled for the demo tenant (seeapp/middleware/feature_flags.py) - [ ] Demo user is authenticated; for org-sharing demos, the user has an
organization_id - [ ] Two browser profiles or two users in the same org ready (optional but best for Demo 3)
- [ ] Sample knowledge files uploaded via Files /
POST /api/files/uploadso you have at least oneattachment.idto attach to an assistant (knowledge_file_idsare file IDs, not arbitrary strings) - [ ] Chat and Compare views load; Assistant control (AssistantPicker) visible in the composer area
- [ ] You know two or more model IDs your tenant allows (for
default_modelsin Demo 1 and Demo 5)
Optional API smoke test
bash
curl -s -H "Authorization: Bearer $GHOSTAI_API_KEY" \
http://localhost:8000/api/assistants | python3 -m json.toolExpect 200 and a JSON array (possibly empty). A 403 or missing route usually means the assistants feature flag is off.
The Story
Riley is a sales engineer who wants a Product FAQ assistant with fixed instructions, a starter prompt for prospects, and two policy PDFs always in context. Morgan (same org) should discover Riley’s assistant when Riley marks it shared, without editing Riley’s original. A Support variant should start from the same base but different instructions—duplicate handles that in one click.
Demo 1: Create an Assistant (~3 min)
Story: Open assistant creation, fill every meaningful field, attach knowledge files, set defaults.
Steps (UI)
- Open Assistant from the chat chrome (or Create from the assistant dropdown if exposed).
- Name (required, 1–200 characters): e.g.
Northwind Product FAQ. - Description (up to 2000 characters): one line for the picker tooltip/card.
- Instructions (up to 50,000 characters): the behavioral system prompt—tone, cite-only-from-context rules, escalation, etc.
- Icon: optional emoji or short label your team uses in lists.
- Starter message (up to 10,000 characters): e.g. “Summarize our SLA tiers in three bullets for a CIO.”
- Knowledge file attachments: pick uploaded files so their IDs populate
knowledge_file_ids. - Default models: enter two to four model IDs that your comparison UI can use (order matters for column slots).
- max_tokens (optional, 1–65536): stored on the assistant profile for documentation and API-driven flows.
- max_tool_rounds (optional, 1–15): same—captured on the assistant record.
- Leave Share with organization off until Demo 3; save.
Talking points
“This is our answer to custom GPTs: long-form instructions, optional starter text, and file IDs that the server merges into the real chat request. Names and descriptions are bounded so tenants can’t overload the catalog.”
“
AssistantCreateis strict: name 1–200, description ≤2000, instructions ≤50000, starter_message ≤10000, and optional caps on tokens and tool rounds.”
Expected outcome
- Assistant appears in your picker.
GET /api/assistantsreturns the new row with yourknowledge_file_ids,default_models,max_tokens, andmax_tool_rounds.
Demo 2: Use in Chat (~2 min)
Story: Select the assistant, watch starter text and system behavior; confirm knowledge context.
Steps
- In ChatWindow, open AssistantPicker and select Northwind Product FAQ.
- If the input was empty, the starter message should appear in the composer (frontend behavior).
- Send a question that should use both instructions and attached files.
Behind the scenes (accurate)
- The client sends
assistant_idonPOST /api/chator the streaming chat endpoint. - Server-side resolution:
instructionsbecomecustom_system_promptwhen the client did not already set one. knowledge_file_idsare appended toattachments(deduplicated) so RAG/file prep runs like manually attached files.
Talking points
“You’re not pasting a system prompt every thread—the assistant ID pulls the right prompt and files on every turn.”
“PII handling for the merged system prompt follows the same path as user-authored custom system prompts.”
Expected outcome
- Replies follow the assistant’s tone and constraints.
- File-grounded answers appear when the question hits indexed attachment content.
Demo 3: Share with Organization (~2 min)
Story: Toggle sharing; a colleague sees the assistant read-only in their picker.
Steps
- Edit the assistant and enable Share with organization (
is_shared: true). Save. - Sign in as another user in the same
organization_id(or use a second browser). - Open the assistant picker: the shared assistant should list alongside their own.
Access rules (cite in Q&A)
- Read/use: creator or (
organization_idmatches andis_sharedis true). - Update/delete: creator only (
403otherwise).
API angle
- Full list for the current user:
GET /api/assistants(own + org shared). - Only org-shared catalog:
GET /api/assistants?shared_only=true(requires userorganization_id; otherwise behavior falls back to the personal list per implementation).
Expected outcome
- Morgan sees Riley’s assistant, selects it, and chats successfully.
- Morgan cannot edit or delete Riley’s original (show
403if they try the API).
Demo 4: Duplicate and Customize (~2 min)
Story: Clone for another department; tweak instructions and sharing.
Steps
- On a shared or private assistant, use Duplicate (UI) or call
POST /api/assistants/{id}/duplicate. - Observe the new name suffix
(Copy),is_shared: false, andcreated_byequal to the current user. - Edit the copy: change instructions and starter message for Support vs Sales; adjust knowledge_file_ids if Support uses different PDFs.
- Optionally share only the Support copy.
Talking points
“Duplicate is a true fork: new UUID, new owner, sharing reset to private so you don’t accidentally broadcast a draft.”
Expected outcome
- Original assistant unchanged.
- Copy appears in your picker; org members do not see it until you share again.
Demo 5: Comparison Chat (~2 min)
Story: Same assistant inside ComparisonChat; default_models populate comparison columns.
Steps
- Navigate to Compare / ComparisonChat.
- Open AssistantPicker and select the assistant whose
default_modelsyou set in Demo 1. - Confirm each comparison column’s model updates up to the number of slots and available models (frontend maps
default_models[i]onto columniwhen the model is allowed). - Run a short prompt and note parallel streams honor those models.
Also mention
- Compare requests support
assistant_idonPOST /api/chat/compare; the same merge rules apply for instructions →custom_system_promptand knowledge file IDs →attachments. CompareRequestacceptsmax_tokensper request; set explicit values in API clients when you need hard caps on comparison turns.
Expected outcome
- Side-by-side columns reflect assistant defaults without hand-picking models again.
- Responses stay consistent with the assistant’s instructions across models.
Recovery Steps
| Symptom | Likely cause | Recovery |
|---|---|---|
| Assistant routes 403 | assistants feature off | Enable flag for tenant; retry |
| Empty picker | Not logged in or fetch failed | Refresh token; check browser console |
404 on GET /api/assistants/{id} | Wrong UUID | Copy ID from list response |
| 403 edit/delete | Not the creator | Duplicate to owned copy, then edit |
| Knowledge not affecting answers | Bad file IDs or indexing pending | Re-upload; wait for indexing; verify IDs in GET |
| Compare models unchanged | Model string not in availableModels | Pick allowed model IDs for default_models |
| Org peer cannot see assistant | is_shared false or different org | Toggle share; verify same organization_id |
Flow Cheat Sheet
- Create →
POST /api/assistantswithAssistantCreatebody. - List mine + org shared →
GET /api/assistants. - List org catalog only →
GET /api/assistants?shared_only=true. - Fetch one →
GET /api/assistants/{assistant_id}(access-checked). - Update →
PUT /api/assistants/{assistant_id}(creator only). - Delete →
DELETE /api/assistants/{assistant_id}(creator only,204). - Duplicate →
POST /api/assistants/{assistant_id}/duplicate(201, new owner). - Chat → include
assistant_idonPOST /api/chator stream; optionalcustom_system_promptoverrides instructions merge. - Compare → include
assistant_idonPOST /api/chat/compare.
FAQ
What fields does AssistantCreate accept?name (1–200), description (≤2000), instructions (≤50000), knowledge_file_ids (list of file ID strings), is_shared (bool), icon (string), default_models (list of strings), starter_message (≤10000), optional max_tokens (1–65536), optional max_tool_rounds (1–15).
Who can see an assistant?
The creator always sees their assistants. Other users see it only if is_shared is true and their organization_id matches the assistant’s organization_id.
Who can edit or delete?
Only the creator. Shared users consume, not mutate.
How does duplicate work?POST /api/assistants/{id}/duplicate creates a new assistant owned by the caller, copies instructions/metadata/knowledge lists, sets is_shared to false, and names it {original name} (Copy).
How does chat use an assistant?
Send assistant_id. The backend loads the assistant with access checks, merges knowledge_file_ids into attachments, and sets custom_system_prompt from instructions when the client did not already supply custom_system_prompt.
Do assistant max_tokens / max_tool_rounds auto-apply to every browser chat?
They are stored on the assistant and honored where the client or API request passes them. Standard chat resolution merges instructions and knowledge files; send max_tokens (and tool settings your deployment supports) on the chat request when you need explicit per-turn caps.
How do I get knowledge file IDs?
Upload with POST /api/files/upload (multipart field file). Use attachment.id from the JSON response in knowledge_file_ids.
Time Box (~12 minutes)
| Demo | Minutes |
|---|---|
| 1 Create | ~3 |
| 2 Chat | ~2 |
| 3 Share | ~2 |
| 4 Duplicate | ~2 |
| 5 Compare | ~2 |
| Buffer / questions | ~1 |
Adjust depth if the prospect cares more about governance (Demos 3–4) than comparison (Demo 5).