Prompt Development Guide

Version française : ../../fr/guides/prompt-development.md

This guide shows how to write, check, publish, render and version a prompt of the Prompt Registry. Publishing needs the tenant_admin or developer role; any principal of the tenant can list and render.

Concept

A prompt is a named template with {{variable}} placeholders and typed variables. Each publication with a different template or different variables becomes a new immutable version, numbered from 1, with a sha256: digest; an identical publication is not duplicated. Rendering checks every value against the declared variables before the text is produced, so an agent never sends a half filled prompt to a model.

Prompt fields

The body of POST /v1/prompts:

Field	Type	Default	Description
name	string	required	Lowercase, digits, ., _ and -, 1 to 128 characters.
template	string	required	Text with {{ name }} placeholders; braces must be balanced.
description	string	""	What the prompt is for.
variables	array	derived	Declared variables; without it, every placeholder becomes a required string.
model_hint	string	none	Model the prompt was written for.

Each variable:

Field	Type	Default	Description
name	string	required	Identifier (^[A-Za-z_][A-Za-z0-9_]*$).
type	string	string	string, integer, number, boolean, array or object.
required	boolean	true	A missing required value without default is refused.
default	any	none	Value used when the caller sends none.
description	string	""	Help for the caller.
max_length	integer	none	Maximum length of a string value.
enum	array	none	Allowed values.

Create a prompt

enterprise-ai create prompt writes prompts/<name>.yaml with a template and typed variables; the rules are those of the registry (POST /v1/prompts): declared variables, balanced braces, types string, integer, number, boolean, array or object.

enterprise-ai create prompt invoice-extract

Steps

1. Create the prompt file. The command writes prompts/invoice-extract.yaml with two typed variables and checks it with the rules of the registry. In the portal: Developer Studio > Prompt studio > New.

   enterprise-ai create prompt invoice-extract

   Expected result: the file is listed and marked valid against prompt.

   If it fails: exit code 1 with "exists"; add --force.

2. Write the template and declare the variables. Every placeholder must be a declared variable; type each one and bound strings with max_length or enum. Treat each value as data: never let a variable carry instructions that the template does not frame.

   Expected result: the editor of Prompt studio shows no problem.

   If it fails: "unbalanced or invalid placeholder" or "undeclared variables" names the faulty part.

3. Publish. POST /v1/prompts creates the prompt with version 1, or publishes the next version. In the portal: Save as a new version.

   import yaml
   doc = yaml.safe_load(open("prompts/invoice-extract.yaml"))
   client.prompts.create(doc["name"], doc["template"], description=doc["description"], variables=doc["variables"])

   Expected result: the answer gives latest_version and the version with its digest.

   If it fails: 422 template_error, 400 invalid_request (name), 403 forbidden (role).

4. Test the rendering. POST /v1/prompts/{name}/render renders the latest version, or the version you give, with strict true by default (unknown variables are refused). In the portal: Prompt studio > Render the latest version.

   Expected result: text, chars and estimated_tokens.

   If it fails: 422 missing_variables lists each variable with its error (missing, type, enum, max_length, unknown).

5. Use it from an agent. Render the prompt by name and pin the version in production code, so that a new publication does not change a running agent.

   Expected result: the agent sends the rendered text through the gateway.

   If it fails: 404 not_found with prompt_version means the pinned version does not exist.

6. Publish a new version. Change the template or the variables and publish again. GET /v1/prompts/{name}/versions lists the versions, newest first.

   Expected result: latest_version is raised by one; the former versions stay renderable.

   If it fails: an identical template and variable set returns the existing version, without a new number.

7. Retire a version. The registry has no delete route: versions stay for audit. Move callers to another version and publish a new one that replaces the retired text.

   Expected result: no caller renders the retired version any more.

   If it fails: search the code for the pinned version number.

Versions and rendering

GET /v1/prompts/{name}/versions lists the versions, POST /v1/prompts/{name}/render renders a version with its variables.

client.prompts.render("invoice-extract", version="3", variables={"lang": "fr"})

Troubleshooting

Symptom	Cause	Fix
422 template_error with reason	Unbalanced or invalid placeholder.	Write each placeholder as {{ name }}.
422 template_error with undeclared_variables	A placeholder is not in variables.	Declare it, or remove variables to derive them.
422 template_error with type	Unknown variable type.	Use string, integer, number, boolean, array or object.
422 missing_variables	Missing, mistyped, out of enum, too long or unknown values.	Read errors; send strict: false only to ignore extra values.
400 invalid_request	The name does not follow the pattern.	Use lowercase letters, digits, ., _ and -.
403 forbidden	The caller has neither tenant_admin nor developer.	Ask for the role.
404 not_found	Unknown prompt or version.	List them with enterprise-ai get prompts.

Next steps

• Agent development guide to use the prompt in an agent.
• Pack development guide for the prompts of a pack.
• Testing guide to evaluate the rendered prompts.