Freeze reusable prompts before production invocation

Learning objective

Create parameterized, versioned prompts in Amazon Bedrock Prompt Management.

Core idea

A reusable prompt separates the application-owned template from the values supplied for one invocation. Amazon Bedrock Prompt management stores that template together with its model and inference configuration. A numbered version freezes a tested configuration for application use; the working draft remains the place to iterate.

Treat the prompt as a configuration artifact with an input contract. A template change, model change, or inference-parameter change can alter behavior even when the application code stays identical. A production release should therefore identify the prompt version and the variable contract it expects. Saving a draft does not establish that release identity.

How it works

Define a stable template and variable contract

Use double braces, such as {{ticket_text}}, for a variable in the template. At runtime, the application supplies the value rather than constructing a different template for every ticket. Choose variable names that describe data roles: ticket_text, product_version, and approved_policy are clearer than a generic input reused for unrelated content.

Parameterization improves reuse, but it does not change trust. A customer’s ticket is still untrusted input. Keep fixed task instructions under application ownership, and distinguish approved policy evidence from arbitrary customer text. See 1.6.1 for enforcement boundaries. A substituted string does not become a system policy merely because Prompt management inserted it.

The CreatePrompt API takes a prompt name, optional defaultVariant, and a variants array. Each variant has its own name, templateType, and templateConfiguration. templateType is TEXT or CHAT; use the matching member of the template-configuration union. The variant can also specify modelId, inferenceConfiguration, and additionalModelRequestFields.

For a chat template, templateConfiguration.chat contains messages, optional system, inputVariables, and optional toolConfiguration. inputVariables names the placeholders the caller supplies, and the chat configuration permits at most 20 input variables. System prompts and tool use depend on the selected model’s capabilities; storing a configuration does not give a model an unsupported capability.

The prompt’s defaultVariant must match the relevant variant’s name. Despite the plural field name, the documented CreatePrompt request permits at most one item in variants. The console can compare alternative configurations, but do not infer that the persisted API accepts an arbitrary array of competing variants. Save the selected configuration, and preserve alternatives in separate candidate artifacts or successive versions when you need a durable comparison record.

Save the complete inference configuration

The base prompt parameters are maxTokens, stopSequences, temperature, and topP. Configure only values valid for the chosen model. Model-specific settings belong in additionalModelRequestFields; they are not interchangeable with the base inference fields. See 1.3.7 for native model-payload validation.

For reproducibility, treat message text and inference configuration as one candidate. A comparison between two prompts is ambiguous if the model or decoding settings changed without being recorded. You can deliberately compare those dimensions, but label the change so an evaluator knows what produced the result.

A CreatePrompt response identifies the working draft with version: DRAFT. Continue editing and testing that draft while developing the candidate. In the console, the values entered under Test variables are temporary and are not saved with the prompt. Keep the representative test inputs and expected outcomes in your evaluation artifact; the prompt library alone does not retain that test set.

Create a snapshot for application use

Call CreatePromptVersion with promptIdentifier when the draft’s configuration is ready. The operation creates a version from the prompt; it is not a request to supply a second, unrelated template body. Its response includes the resulting arn, version, defaultVariant, and variant configuration. Capture that returned identity instead of predicting a version number.

CreatePromptVersion.clientToken provides idempotency for the creation request. Use it when your release automation might retry the same operation, so a retry does not accidentally represent a different release intention. This protects the API operation; it does not prove the content was reviewed. Review and promotion belong to 1.6.3.

Invoke a managed prompt through a runtime request whose modelId is the version-qualified prompt ARN. For Converse, provide the runtime variable values in promptVariables. The field maps a variable name to an object containing its text value; the runtime key is the name without the template’s braces. A request fragment illustrates that boundary:

{
  "modelId": "PROMPT_VERSION_ARN",
  "promptVariables": {
    "ticket_text": { "text": "The replacement arrived damaged." },
    "product_version": { "text": "2026 edition" }
  }
}

Replace PROMPT_VERSION_ARN with the returned ARN for the approved numbered version. Define both variable names in the stored template. The version reference controls the template; the map controls the data for this invocation.

Managed-prompt Converse requests cannot include additionalModelRequestFields, inferenceConfig, system, or toolConfig. Define those settings through Prompt management. If the request contains additional messages, Bedrock appends them after the prompt’s stored messages; it does not replace the template. guardrailConfig remains an independent request control, with coverage determined by any guardContent blocks.

Key distinctions and trade-offs

A variable value changes one invocation’s data. A variant describes an alternative prompt configuration. A draft is editable working state. A numbered version is the snapshot you identify in a release. These are different dimensions, not synonyms for “a different prompt.”

More variables increase reuse but broaden the caller’s contract. A template with many optional-looking inputs can make behavior hard to reproduce. Validate required application inputs before invocation and distinguish missing data from a deliberately empty value. Do not fill missing policy evidence with invented text to satisfy the template.

Centralizing model and inference settings in the prompt improves reproducibility but reduces per-call overrides. If the application needs independent decoding settings for two use cases, create and evaluate the corresponding prompt configurations rather than sending prohibited Converse override fields.

Architecture / decision scenario

A support platform needs one response pattern across thousands of tickets. The team creates a chat prompt with fixed support instructions and variables for ticket text, product version, and approved warranty evidence. It records the selected model and inference settings with the candidate.

The author compares two wordings in the console, saves the selected variant, and creates a numbered version. The application invokes the returned version ARN and supplies ticket-specific promptVariables. Test-variable values remain in the evaluation dataset, not in the production template.

An engineer tries to override system at invocation to add a different escalation rule. The team moves that rule into an evaluated prompt revision because the managed-prompt Converse interface prohibits the override. Production stays on its existing numbered version while the revised draft is tested.

Common exam traps

• Using the editable draft as the production release identity.
• Treating console test-variable values as stored runtime defaults.
• Sending inferenceConfig or system alongside a managed-prompt Converse request.
• Assuming extra messages replace the stored prompt messages.
• Confusing a variable substitution with a prompt variant or numbered version.
• Reading variants as permission to persist multiple candidates despite the one-item API limit.

What to remember

• Parameterize per-request data and retain ownership of fixed instructions.
• Save the selected template, model, and inference settings as one configuration.
• Create a numbered version and invoke its returned ARN.
• Keep evaluation inputs, approval evidence, and deployment routing outside the draft’s identity.

Knowledge check

References

• AWS, CreatePrompt
• AWS, ChatPromptTemplateConfiguration
• AWS, CreatePromptVersion
• AWS, Test a prompt using Prompt management
• AWS, Create a prompt using Prompt management