Create, fetch, list, and version prompts across TypeScript, Python, and Java SDKs.

Manage Prompts

The SDK provides two ways to access prompts:

Approach	Usage	When to use
`client.prompt.get()` / `client.prompt.create()`	Via an `AISDK` instance	When you already have a client for tracing, datasets, etc.
`Prompt.get()` / `Prompt.create()`	Static import, no client needed	Standalone scripts, quick access from env vars

import { AISDK, Prompt } from '@browserstack/ai-sdk';

// Option 1: Via AISDK client
const client = new AISDK({
  publicKey: process.env.AISDK_PUBLIC_KEY,
  secretKey: process.env.AISDK_SECRET_KEY,
});
const prompt = await client.prompt.get('my-prompt');

// Option 2: Standalone (reads AISDK_PUBLIC_KEY / AISDK_SECRET_KEY from env)
const prompt = await Prompt.get('my-prompt');

Approach	Usage	When to use
`client.prompt.get()` / `client.prompt.create()`	Via an `AISDK` instance	When you already have a client for tracing, datasets, etc.
`Prompt.get()` / `Prompt.create()`	Static class methods, no client needed	Standalone scripts, quick access from env vars

import os
from browserstack_ai_sdk import AISDK, Prompt

# Option 1: Via AISDK client
client = AISDK(
    public_key=os.environ["AISDK_PUBLIC_KEY"],
    secret_key=os.environ["AISDK_SECRET_KEY"],
)
prompt = client.prompt.get("my-prompt")

# Option 2: Standalone (reads AISDK_PUBLIC_KEY / AISDK_SECRET_KEY from env)
prompt = Prompt.get("my-prompt")

Both approaches use the same underlying API and support the same parameters.

Create a Prompt

Text Prompt

const prompt = await client.prompt.create({
  name: 'summarizer',
  type: 'text',
  prompt: 'Summarize the following in {{language}}: {{text}}',
  labels: ['production']
});

Chat Prompt

const prompt = await client.prompt.create({
  name: 'qa-assistant',
  type: 'chat',
  prompt: [
    { role: 'system', content: 'You are a helpful assistant for {{domain}}.' },
    { role: 'user', content: '{{userQuestion}}' },
  ],
  labels: ['production'],
});

Parameter	Type	Description
`name`	`string`	Unique prompt name
`prompt`	`string \| ChatMessage[]`	Template string (text) or messages array (chat)
`type`	`"text" \| "chat"`	Prompt type
`labels`	`string[]`	Labels for versioning (e.g. `['production']`)

Fetch a Prompt

The client caches fetched prompts to reduce API calls.

// By name (latest version)
const prompt = await client.prompt.get('summarizer');

// By version number
const prompt = await client.prompt.get('summarizer', 3);

// By label
const prompt = await client.prompt.get('summarizer', undefined, {
  label: 'production',
});

// With type and cache control
const prompt = await client.prompt.get('summarizer', undefined, {
  label: 'production',
  type: 'text',
  cacheTtlSeconds: 120,
});

Parameter	Type	Description
`name`	`string`	Prompt name as defined in the dashboard
`version`	`number`	Specific version number. Omit for latest
`options.label`	`string`	Fetch by label (e.g. `'production'`, `'staging'`)
`options.type`	`"text" \| "chat"`	Prompt type (defaults to `"text"`)
`options.cacheTtlSeconds`	`number`	Override default cache TTL
`options.fallback`	`string \| ChatMessage[]`	Fallback value if fetch fails
`options.maxRetries`	`number`	Number of fetch retries
`options.fetchTimeoutMs`	`number`	Fetch timeout in milliseconds

Compile a Prompt

Both text and chat prompts support Mustache template compilation via .compile(). See Template Syntax & Variables for the full syntax reference.

Text Prompts

const prompt = await client.prompt.get('summarizer');

const compiled: string = prompt.compile({
  language: 'French',
  text: 'Paris is the capital of France...',
});

console.log(compiled);
// "Summarize the following in French: Paris is the capital of France..."

Chat Prompts

const promptClient = await client.prompt.get('qa-assistant', undefined, {
  label: 'production',
  type: 'chat',
  cacheTtlSeconds: 60,
});

const messages = promptClient.compile({
  domain: 'quantum computing',
  userQuestion: 'What is superposition?',
});

console.log(messages);
// [
//   { role: 'system', content: 'You are a helpful assistant for quantum computing.' },
//   { role: 'user', content: 'What is superposition?' },
// ]

Update Prompt Labels

await client.prompt.update({
  name: 'summarizer',
  version: 2,
  newLabels: ['production', 'stable'],
});

Parameter	Type	Description
`name`	`string`	Prompt name
`version`	`number`	Version to update
`newLabels`	`string[]`	Replacement label set (replaces all existing labels)

Using with OpenAI

import { AISDK } from '@browserstack/ai-sdk';
import OpenAI from 'openai';

const client = new AISDK();
const openai = new OpenAI();

const prompt = await client.prompt.get('qa-assistant', undefined, {
  label: 'production',
  type: 'chat',
});

const messages = prompt.compile({
  userQuestion: 'What is the boiling point of water?',
});

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: messages,
});

console.log(response.choices[0].message.content);

Prompt Tools

If a prompt has tools attached in the dashboard, they are available via prompt.tools.

const prompt = await client.prompt.get('agent-prompt');
const tools = prompt.tools.compile();

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: prompt.compile({ task: 'Search for recent AI news' }) as any,
  tools: tools,
  tool_choice: 'auto',
});

Complete Example

import { AISDK } from '@browserstack/ai-sdk';
import OpenAI from 'openai';

const client = new AISDK();
const openai = new OpenAI();

async function main() {
  // Create a prompt
  await client.prompt.create({
    name: 'joke-prompt',
    prompt: 'Tell me a funny joke about {{topic}}',
    type: 'text',
    labels: ['production'],
  });

  // Fetch and use the prompt
  const prompt = await client.prompt.get('joke-prompt', undefined, {
    label: 'production',
  });
  const formatted = prompt.compile({ topic: 'programming' });

  // Use with OpenAI
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: formatted }],
  });

  console.log(response.choices[0].message.content);
}

main();

Create a Prompt

Text Prompt

import os
from browserstack_ai_sdk import AISDK

client = AISDK(
    public_key=os.environ["AISDK_PUBLIC_KEY"],
    secret_key=os.environ["AISDK_SECRET_KEY"],
)

result = client.prompt.create(
    name="summarizer",
    prompt="Summarize the following article in 3 bullet points:\n\n{{article}}",
    type="text",
    labels=["production"],
)
print(result)

Chat Prompt

result = client.prompt.create(
    name="support-assistant",
    type="chat",
    prompt=[
        {"role": "system", "content": "You are a helpful support assistant for {{product}}."},
        {"role": "user", "content": "{{user_message}}"},
    ],
    labels=["staging"]
)

`create()` Parameters

Parameter	Type	Default	Description
`name`	`str`	required	Unique prompt name
`prompt`	`str \| list[dict]`	required	Template string (text) or messages list (chat)
`type`	`"text" \| "chat"`	`"text"`	Prompt type
`labels`	`list[str]`	`[]`	Labels (e.g., `["production"]`)

Fetch a Prompt

# By name (latest version)
prompt_client = client.prompt.get("summarizer")

# By version number
prompt_client = client.prompt.get("summarizer", version=3)

# By label
prompt_client = client.prompt.get("summarizer", label="production")

# With cache control
prompt_client = client.prompt.get(
    "summarizer",
    label="production",
    type="text",
    cache_ttl_seconds=120,
)

`get()` Parameters

Parameter	Type	Default	Description
`name`	`str`	required	Prompt name
`type`	`"text" \| "chat"`	`"text"`	Prompt type
`version`	`int`	`None`	Pin to a specific version
`label`	`str`	`"latest"`	Pin to a label (`"production"`, `"staging"`, etc.)
`cache_ttl_seconds`	`int`	`None`	Client-side cache TTL
`fallback`	`str \| list`	`None`	Fallback value if fetch fails
`max_retries`	`int`	`None`	Number of fetch retries
`fetch_timeout_seconds`	`int`	`None`	Fetch timeout

Compile a Prompt

Text Prompts

prompt_client = client.prompt.get("summarizer", label="production")

compiled = prompt_client.compile(
    article="Paris is the capital of France..."
)

print(compiled)
# "Summarize the following article in 3 bullet points:\n\nParis is the capital of France..."

Chat Prompts

prompt_client = client.prompt.get(
    "support-assistant",
    type="chat",
    label="production",
)

messages = prompt_client.compile(
    product="Acme Widget",
    user_message="How do I reset my password?",
)

print(messages)
# [
#   {"role": "system", "content": "You are a helpful support assistant for Acme Widget."},
#   {"role": "user", "content": "How do I reset my password?"},
# ]

Using with OpenAI

import openai

openai_client = openai.OpenAI()

prompt_client = client.prompt.get("support-assistant", type="chat", label="production")
messages = prompt_client.compile(product="Acme Widget", user_message="What are your hours?")

response = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)
print(response.choices[0].message.content)

List Prompts

prompts = client.prompt.list(
    label="production",
    page=1,
    limit=20,
)

for p in prompts:
    print(p["name"])

Prompt Versioning

Each call to create() creates a new version. Labels control which version is fetched by get().

# Publish a new version to production
client.prompt.create(
    name="my-prompt",
    prompt="Updated template: {{topic}}",
    labels=["production"],
    commit_message="Improve clarity",
)

# Always fetches the latest "production" version
prompt = client.prompt.get("my-prompt", label="production")

Complete Example

from browserstack_ai_sdk import AISDK
from openai import OpenAI

client = AISDK(public_key="<public-key>", secret_key="<secret-key>")
openai = OpenAI()

# Create a prompt
client.prompt.create(
    name="joke-prompt",
    prompt="Tell me a funny joke about {{topic}}",
    type="text",
    labels=["production"],
)

# Fetch and use the prompt
prompt = client.prompt.get(name="joke-prompt", label="production")
formatted = prompt.compile(topic="programming")

# Use with OpenAI
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": formatted}],
)

print(response.choices[0].message.content)

Manage Prompts

On this page