# Prompt Management

> How versioned prompt templates, point-in-time snapshots, and the interactive playground let teams manage, test, and render reusable prompt templates centrally.

When prompt text is hard-coded into application or agent code, changing a single word means shipping a new build, and there is no shared place to test the change before it reaches production. Prompt Management centralises prompt engineering and versioning within Agent Stream. Rather than embedding raw system and user prompts into application code or agent frameworks, clients reference a managed template by ID and variable map, while operators manage, test, and version prompt templates from the dashboard. [Pipeline and stages →](/products/affinidi-trust-fabric/agent-stream/concepts/pipeline-and-stages.md)

## What a Prompt Template renders into a request

A Prompt Template is a versioned, reusable OpenAI messages array with {{variable}} placeholders and an optional default version. Clients reference a prompt in a request ("prompt": { "id", "version?", "variables" }), and prompt reference expansion renders it into messages before the request enters the pipeline. The "prompt" block is stripped so it never reaches the provider.

```json
{
  "prompt": {
    "id": "customer-support-agent",
    "version": "v2",
    "variables": {
      "user_name": "Alice",
      "issue_summary": "Password reset request"
    }
  }
}
```

The rendered messages participate in response caching and PII protection as if supplied directly by the caller.

A request can also include its own "messages" array alongside the "prompt" block. When both are present, the rendered prompt’s messages come first, and the client’s "messages" are appended after them. This lets a client supply, for example, a final user turn following a rendered system prompt and few-shot examples, without having to reproduce the template itself.

## How a Prompt Version stays stable once published

A Prompt Version is a numbered, point-in-time snapshot of a Prompt Template’s messages. A prompt request may pin a specific version; if none is supplied, the template’s default version is used.

Publishing a new default version does not by itself break an existing client that pins a specific version number, since the client’s request still names that number explicitly. Version numbers are not currently enforced as immutable at the API level, though: an editor with permission to edit the template can overwrite an existing version’s content in place. Treat version pinning as a strong convention for stability, not a cryptographic or storage-level guarantee that a given version number’s content can never change.

## Playground

The Playground is the live preview surface on a prompt’s own edit page, within the dashboard’s Prompts section, which renders a template into messages against a supplied variable map so an operator can confirm behaviour before publishing.

## Related

- [Pipeline and stages](/products/affinidi-trust-fabric/agent-stream/concepts/pipeline-and-stages.md): Where Prompt Reference Expansion sits in the inbound pipeline.

- [Guardrails](/products/affinidi-trust-fabric/agent-stream/concepts/guardrails.md): How Prompt Guard inspects rendered messages for sensitive data.

- [Governance records](/products/affinidi-trust-fabric/agent-stream/concepts/governance-records.md): How rendered prompts and template metadata are recorded for audit.

- [Resilience and caching](/products/affinidi-trust-fabric/agent-stream/concepts/resilience-and-caching.md): How rendered prompt messages participate in response caching.

- [PII protection](/products/affinidi-trust-fabric/agent-stream/concepts/pii-protection.md): How rendered prompt messages are checked for sensitive data.