Open History to see the last commit
System Prompts - Quick Start Guide#
What is it?#
System prompts let you define instructions once and have them automatically prepended to all chat conversations. No more manually adding system messages!
Quick Example#
Before ❌#
const SYSTEM_PROMPT = "You are a helpful assistant.";
// Had to manually add system message every time
const allMessages = messages[0]?.role === "system"
? messages
: [{ role: "system", content: SYSTEM_PROMPT }, ...messages];
const result = await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: allMessages, // Manual handling
});
After ✅#
const ai = new AI({
adapters: { /* ... */ },
systemPrompts: ["You are a helpful assistant."], // Define once
});
// System prompts automatically added!
const result = await ai.chat({
adapter: "openai",
model: "gpt-4",
messages, // Just pass messages directly
});
Basic Usage#
1. Constructor-Level (Default for All Calls)#
const ai = new AI({
adapters: {
openai: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
},
systemPrompts: [
"You are a helpful assistant.",
"Always be concise and friendly.",
],
});
// All chat calls use these prompts automatically
await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [{ role: "user", content: "Hello!" }],
});
2. Per-Call Override#
// Override for a specific conversation
await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [{ role: "user", content: "Explain quantum physics" }],
systemPrompts: [
"You are a physics professor.", // Replaces constructor prompts
"Use simple analogies.",
],
});
3. Multiple Prompts (Array)#
// Layer multiple instructions
const ai = new AI({
adapters: { /* ... */ },
systemPrompts: [
"You are a customer support agent.", // Role
"Our business hours are 9 AM - 5 PM EST.", // Context
"Always ask for order numbers.", // Behavior
],
});
Key Features#
✅ Works with Everything#
// Works with tools
await ai.chat({
messages: [/* ... */],
tools: ["getTool"],
// systemPrompts automatically included
});
// Works with streaming
const stream = ai.chat({
messages: [/* ... */],
as: "stream" as const,
// systemPrompts work here too
});
// Works with Response mode
const response = ai.chat({
messages: [/* ... */],
as: "response" as const,
// And here!
});
🔄 Priority Order#
- Per-call
systemPrompts(highest - overrides constructor) - Constructor
systemPrompts(default) - No prompts (if neither provided)
const ai = new AI({
systemPrompts: ["Default"], // Used by default
});
await ai.chat({
systemPrompts: ["Override"], // This one wins!
messages: [/* ... */],
});
🚫 Skip Prompts#
// Pass empty array to skip for one call
await ai.chat({
systemPrompts: [], // No system prompts for this call
messages: [/* ... */],
});
Common Use Cases#
1. Application-Wide Persona#
const ai = new AI({
adapters: { /* ... */ },
systemPrompts: [
"You are a customer support agent for TechCorp.",
"Always be polite and professional.",
],
});
2. Tool Usage Guidelines#
const ai = new AI({
adapters: { /* ... */ },
tools: { getWeather: { /* ... */ } },
systemPrompts: [
"You are a weather assistant.",
"Always use the getWeather tool for weather queries.",
],
});
3. Role Switching#
const ai = new AI({
systemPrompts: ["You are a friendly assistant."], // Default role
});
// Switch role for specific task
await ai.chat({
systemPrompts: ["You are a code reviewer."], // Override
messages: [/* ... */],
});
Migration Example#
Your Current Code (api.tanchat.ts)#
const SYSTEM_PROMPT = "You are a helpful assistant...";
export const Route = createFileRoute("/demo/api/tanchat")({
server: {
handlers: {
POST: async ({ request }) => {
const { messages } = await request.json();
// Manual system message handling
const allMessages = messages[0]?.role === "system"
? messages
: [{ role: "system", content: SYSTEM_PROMPT }, ...messages];
return ai.chat({
adapter: "openAi",
model: "gpt-4o",
messages: allMessages, // Manual handling
});
},
},
},
});
Updated Code (Cleaner!)#
const SYSTEM_PROMPT = "You are a helpful assistant...";
const ai = new AI({
adapters: { /* ... */ },
tools,
systemPrompts: [SYSTEM_PROMPT], // ← Define once here
});
export const Route = createFileRoute("/demo/api/tanchat")({
server: {
handlers: {
POST: async ({ request }) => {
const { messages } = await request.json();
// System prompts automatically handled!
return ai.chat({
adapter: "openAi",
model: "gpt-4o",
messages, // ← Just pass messages directly
});
},
},
},
});
TypeScript Support#
Fully typed with autocomplete:
const ai = new AI({
adapters: { /* ... */ },
systemPrompts: ["Prompt"], // ✅ Type: string[]
});
await ai.chat({
messages: [/* ... */],
systemPrompts: ["Override"], // ✅ Type: string[]
});
More Information#
- Full Documentation: See
SYSTEM_PROMPTS.md - Examples: See
examples/system-prompts-example.ts - Your Updated File:
examples/ts-chat/src/routes/demo/api.tanchat.ts
Quick Tips#
- Keep prompts focused - One instruction per string
- Layer instructions - General → Specific
- Override when needed - Use per-call prompts for special cases
- Document them - Use constants for reusable prompts
That's It!#
You now have cleaner, more maintainable code with automatic system prompt handling. 🎉