Prompts

A Prompt is a tenant-owned named message template. Store one when multiple Turns should reuse the same input shape; Agent instructions define persistent behavior, while a literal message or prompt supplies input for one Turn.

When to store a Prompt

Use a Prompt for centrally managed, reusable Turn input whose values vary by invocation. Use literal input for one-off text, and use Agent instructions for behavior that should apply across executions.

Variables and rendering

Write placeholders as {{variable}}. Whitespace inside braces is trimmed; names must start with an ASCII letter or underscore and continue with ASCII letters, digits, or underscores. Repeated names appear once in the returned variables inventory, in first-seen order.

An invocation must supply all and only that inventory. Missing values and unknown keys are both rejected as invalid_request, with a message naming the mismatched variables. A Prompt with no placeholders can omit variables.

Create and invoke a Prompt

This example verifies the two discovered variables, then renders them for stateless text generation:

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({
  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});
const prompt = await client.prompts.create({
  name: "Release summary",
  template: "Summarize {{ version }} for {{ audience }}.",
});

if (prompt.variables.join(",") !== "version,audience") {
  throw new Error("Unexpected Prompt variables");
}
const result = await client.completion({
  agentId: process.env.AGENT_ID!,
  promptId: prompt.id,
  variables: { version: "2.4", audience: "developers" },
});
console.log(await result.text);

Reuse across generation modes

The same promptId and variables alternative works for stateful chat, stateless text generation and streaming, and structured output. For each mode, choose either literal input or promptId with variables; sending a mixed shape is rejected.

Blazing Agents expands the template before execution. Only the rendered text enters a Session transcript, with no stored Prompt reference, so later Prompt edits or deletion do not change existing history.

Validation, persistence, and attribution

A Tenant can store at most 100 Prompts. Names are trimmed, unique per Tenant, and at most 80 characters; templates are trimmed, non-empty, at most 10,240 characters, and contain at most 10 distinct variables.

Create accepts name, template, and optional userId and metadata. userId is immutable; name, template, and metadata are mutable partial-update fields, and the read-only variables inventory is derived again from the current template. Prompt access is Tenant-scoped, list can filter by userId, and deletion is permanent. Missing or out-of-Tenant IDs return not_found; duplicate names and the Prompt limit are rejected as invalid_request.

See Agents for the distinction between Turn input and Agent configuration.

Follow Generate structured output to use reusable input with a constrained result.

Reference

See the Prompts TypeScript SDK Reference, Generation SDK Reference, Prompts REST API Reference, and Generate endpoint. Return to Configure your Agent for related topics.

On this page