Skip to content

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 assistants is enabled for the demo tenant (see app/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/upload so you have at least one attachment.id to attach to an assistant (knowledge_file_ids are 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_models in 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.tool

Expect 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) ​

  1. Open Assistant from the chat chrome (or Create from the assistant dropdown if exposed).
  2. Name (required, 1–200 characters): e.g. Northwind Product FAQ.
  3. Description (up to 2000 characters): one line for the picker tooltip/card.
  4. Instructions (up to 50,000 characters): the behavioral system prompt—tone, cite-only-from-context rules, escalation, etc.
  5. Icon: optional emoji or short label your team uses in lists.
  6. Starter message (up to 10,000 characters): e.g. “Summarize our SLA tiers in three bullets for a CIO.”
  7. Knowledge file attachments: pick uploaded files so their IDs populate knowledge_file_ids.
  8. Default models: enter two to four model IDs that your comparison UI can use (order matters for column slots).
  9. max_tokens (optional, 1–65536): stored on the assistant profile for documentation and API-driven flows.
  10. max_tool_rounds (optional, 1–15): same—captured on the assistant record.
  11. 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.”

“AssistantCreate is 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/assistants returns the new row with your knowledge_file_ids, default_models, max_tokens, and max_tool_rounds.

Demo 2: Use in Chat (~2 min) ​

Story: Select the assistant, watch starter text and system behavior; confirm knowledge context.

Steps ​

  1. In ChatWindow, open AssistantPicker and select Northwind Product FAQ.
  2. If the input was empty, the starter message should appear in the composer (frontend behavior).
  3. Send a question that should use both instructions and attached files.

Behind the scenes (accurate) ​

  • The client sends assistant_id on POST /api/chat or the streaming chat endpoint.
  • Server-side resolution: instructions become custom_system_prompt when the client did not already set one.
  • knowledge_file_ids are appended to attachments (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 ​

  1. Edit the assistant and enable Share with organization (is_shared: true). Save.
  2. Sign in as another user in the same organization_id (or use a second browser).
  3. Open the assistant picker: the shared assistant should list alongside their own.

Access rules (cite in Q&A) ​

  • Read/use: creator or (organization_id matches and is_shared is true).
  • Update/delete: creator only (403 otherwise).

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 user organization_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 403 if they try the API).

Demo 4: Duplicate and Customize (~2 min) ​

Story: Clone for another department; tweak instructions and sharing.

Steps ​

  1. On a shared or private assistant, use Duplicate (UI) or call POST /api/assistants/{id}/duplicate.
  2. Observe the new name suffix (Copy), is_shared: false, and created_by equal to the current user.
  3. Edit the copy: change instructions and starter message for Support vs Sales; adjust knowledge_file_ids if Support uses different PDFs.
  4. 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 ​

  1. Navigate to Compare / ComparisonChat.
  2. Open AssistantPicker and select the assistant whose default_models you set in Demo 1.
  3. Confirm each comparison column’s model updates up to the number of slots and available models (frontend maps default_models[i] onto column i when the model is allowed).
  4. Run a short prompt and note parallel streams honor those models.

Also mention ​

  • Compare requests support assistant_id on POST /api/chat/compare; the same merge rules apply for instructions → custom_system_prompt and knowledge file IDs → attachments.
  • CompareRequest accepts max_tokens per 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 ​

SymptomLikely causeRecovery
Assistant routes 403assistants feature offEnable flag for tenant; retry
Empty pickerNot logged in or fetch failedRefresh token; check browser console
404 on GET /api/assistants/{id}Wrong UUIDCopy ID from list response
403 edit/deleteNot the creatorDuplicate to owned copy, then edit
Knowledge not affecting answersBad file IDs or indexing pendingRe-upload; wait for indexing; verify IDs in GET
Compare models unchangedModel string not in availableModelsPick allowed model IDs for default_models
Org peer cannot see assistantis_shared false or different orgToggle share; verify same organization_id

Flow Cheat Sheet ​

  1. Create → POST /api/assistants with AssistantCreate body.
  2. List mine + org shared → GET /api/assistants.
  3. List org catalog only → GET /api/assistants?shared_only=true.
  4. Fetch one → GET /api/assistants/{assistant_id} (access-checked).
  5. Update → PUT /api/assistants/{assistant_id} (creator only).
  6. Delete → DELETE /api/assistants/{assistant_id} (creator only, 204).
  7. Duplicate → POST /api/assistants/{assistant_id}/duplicate (201, new owner).
  8. Chat → include assistant_id on POST /api/chat or stream; optional custom_system_prompt overrides instructions merge.
  9. Compare → include assistant_id on POST /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) ​

DemoMinutes
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).

SOC 2 Type II Certified | BAA Available | HIPAA-Ready