build
Builds and returns the complete system prompt as a string.
This is the primary output method of the builder. It generates a structured prompt document containing all the configuration you’ve provided, formatted as a system prompt ready to send to an AI model.
The generated prompt includes sections for:
- Identity (who/what the agent is)
- Capabilities (what it can do)
- Available Tools (with parameter documentation)
- Behavioral Guidelines (constraints organized by severity)
- Communication Style (tone)
- Output Format (response structure)
Only sections with content are included - empty sections are omitted to keep the prompt clean and focused.
build(format?: PromptFormat): string
Optional format override. If not provided, uses the format set via withFormat() (defaults to ‘markdown’)
A formatted system prompt string ready for use with AI models
Examples
toAiSdk
Exports a complete AI SDK configuration object.
This is a convenience method that returns both the system prompt and tools in a single object, ready to spread into Vercel AI SDK function calls.
The returned object contains:
system: The complete system prompt (same as calling .build())tools: Tools in AI SDK format (same as calling .toAiSdkTools())
An object with system and tools properties ready for AI SDK
Example
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { createPromptBuilder } from 'promptsmith';
import { z } from 'zod';
const builder = createPromptBuilder()
.withIdentity("You are a helpful weather assistant")
.withCapabilities(["Provide weather information", "Give forecasts"])
.withTool({
name: "get_weather",
description: "Get current weather for a location",
schema: z.object({
location: z.string().describe("City name")
}),
execute: async ({ location }) => {
const response = await fetch(`https://api.weather.com/${location}`);
return response.json();
}
})
.withConstraint("must", "Always verify location exists before providing weather")
.withTone("Be friendly and helpful");
// Ultra clean usage with spread operator
const response = await generateText({
model: openai('gpt-4'),
...builder.toAiSdk(),
prompt: "What's the weather in Paris?",
maxSteps: 5
});
// Or destructured if you prefer
const { system, tools } = builder.toAiSdk();
const response2 = await generateText({
model: openai('gpt-4'),
system,
tools,
prompt: "What's the weather?"
});
hasIdentity
Checks if an identity has been set for the builder.
True if identity is set (non-empty string), false otherwise
Example
const builder = createPromptBuilder();
console.log(builder.hasIdentity()); // false
builder.withIdentity("You are a helpful assistant");
console.log(builder.hasIdentity()); // true
Checks if any tools have been registered with the builder.
True if at least one tool is registered, false otherwise
Example
const builder = createPromptBuilder()
.withIdentity("Assistant");
console.log(builder.hasTools()); // false
builder.withTool({
name: "search",
description: "Search the web",
schema: z.object({ query: z.string() })
});
console.log(builder.hasTools()); // true
getSummary
Returns a summary of the builder’s current state.
Provides a quick overview of what has been configured, useful for debugging, logging, or validation purposes.
getSummary(): {
hasIdentity: boolean;
capabilitiesCount: number;
toolsCount: number;
constraintsCount: number;
constraintsByType: {
must: number;
must_not: number;
should: number;
should_not: number;
};
examplesCount: number;
hasGuardrails: boolean;
forbiddenTopicsCount: number;
hasContext: boolean;
hasTone: boolean;
hasOutputFormat: boolean;
hasErrorHandling: boolean;
format: PromptFormat;
}
An object containing counts and flags for all builder sections
Example
const builder = createPromptBuilder()
.withIdentity("Assistant")
.withCapabilities(["Answer questions", "Provide help"])
.withTool({ name: "search", description: "Search", schema: z.object({}) })
.withConstraint("must", "Be helpful")
.withGuardrails();
const summary = builder.getSummary();
console.log(summary);
// {
// hasIdentity: true,
// capabilitiesCount: 2,
// toolsCount: 1,
// constraintsCount: 1,
// examplesCount: 0,
// hasGuardrails: true,
// forbiddenTopicsCount: 0,
// hasContext: false,
// hasTone: false,
// hasOutputFormat: false,
// hasErrorHandling: false,
// format: 'markdown'
// }
debug
Outputs detailed debug information about the builder’s current state.
This method provides comprehensive logging of the builder’s configuration, including all sections, counts, warnings, and suggestions for improvement. Useful for debugging, development, and understanding how the prompt will be structured.
The debug output includes:
- Configuration summary with counts
- Detailed section breakdowns
- Validation warnings (missing sections, potential issues)
- Suggestions for completeness
- Preview of the first 500 characters of the built prompt
The builder instance for method chaining
Example
const builder = createPromptBuilder()
.withIdentity("Assistant")
.withCapabilities(["Answer questions", "Provide help"])
.withTool({ name: "search", description: "Search", schema: z.object({}) })
.debug(); // Logs detailed information to console
// Continue chaining after debug
const prompt = builder
.debug()
.withConstraint("must", "Be helpful")
.build();