Prompt studio

The Prompt studio screen lets you write a prompt template with its typed variables, publish it as a new version, read its versions and render the latest one with test values. Portal path: /studio/prompts. It is used by developers and tenant administrators who maintain the prompts of their agents.

What the screen shows

• On the left, the list of the prompts of the tenant (GET /v1/prompts), paginated, with the New button on top. An empty list shows No prompt yet and a New action.
• Name: the name of the prompt (for example support-triage). Typing an existing name opens its versions.
• Three tabs:
  • Editor: Template (Markdown editor; a placeholder is a variable name between double braces and must be declared), Variables (JSON) (a JSON list checked live against a schema: name, type, required, default, description, max_length, enum), the editor problems ("Line n: message" or No problem found by the editor.) and the template problems: The template is empty., A placeholder is unbalanced or invalid., Variable x is used but not declared.
  • Render: a JSON editor with the values of the variables and the rendered text.
  • Versions (with their number): a table with the columns Version, Digest, Author, Date, newest first (GET /v1/prompts/{name}/versions).
• Under the button, the hint Saving requires the tenant_admin or developer role. when your roles do not allow saving.

Actions

Button or action	What it does	API call	Roles
New	Clears the name and loads the starter template with its two variables.	None	Everyone
Click a prompt in the list	Selects it and loads its versions.	GET /v1/prompts/{name}/versions	Every signed in user
Save as a new version	Publishes the template and the variables; an existing name gets a new version. Enabled only when the name is set and there is no problem.	POST /v1/prompts	tenant_admin, developer
Click a row of Versions	Loads the template and the variables of that version in Editor.	None	Every signed in user
Render the latest version	Renders the latest version with the values (strict mode). Enabled once the versions are loaded.	POST /v1/prompts/{name}/render	Every signed in user
Retry (error state of the list)	Reads the list again.	GET /v1/prompts	Every signed in user

Roles

The portal enables Save as a new version for STUDIO_WRITERS (tenant_admin, developer, in portal/src/screens/studio.tsx). The Control Plane checks the same roles on POST /v1/prompts (services/control-plane/src/eai/domains/prompts/__init__.py) and answers forbidden otherwise. Reading the list, the versions and rendering only need a signed in user of the tenant.

Typical tasks

Publish a new prompt

1. Start from the template. It shows the expected shape. Click New. Expected result: the starter template and two variables team and language. If it fails: reload the page.
2. Name the prompt. The name identifies the prompt in the agents. Type it in Name (lowercase letters, digits, dot, dash or underscore). Expected result: the save button becomes active once there is no problem. If it fails: the server answers invalid_request for an invalid name.
3. Write the template and the variables. Each placeholder must be declared. Edit Template and Variables (JSON). Expected result: No problem found by the editor. and no red message. If it fails: declare the variable named by the message or close the braces.
4. Save. Click Save as a new version. Expected result: the toast Saved as version n and the prompt in the list. If it fails: read the error under the button (see Troubleshooting).

Render the latest version

1. Select the prompt. Click it in the list. Expected result: the Versions tab shows a count. If it fails: an unpublished name has no version.
2. Fill the values. Open Render and edit the JSON (for example {"team": "support", "language": "English"}). Expected result: valid JSON. If it fails: fix the JSON syntax.
3. Render. Click Render the latest version. Expected result: the rendered text under the button. If it fails: missing_variables means a required variable has no value.

Restore an older version

1. Open the versions. Open Versions and click the row of the version. Expected result: Editor opens with that template. If it fails: No version yet means the prompt was never published.
2. Publish it again. Click Save as a new version. Expected result: a new version with the old content. If it fails: check your role.

Troubleshooting

Symptom	Cause	Fix
Saving requires the tenant_admin or developer role.	Your roles cannot publish.	Ask a tenant administrator for the developer role.
Error forbidden (403) on save	The server refused the role.	Same as above.
Error invalid_request (400) on save	The name breaks the naming rule.	Use lowercase letters, digits, dot, dash or underscore.
Error template_error (422)	Unbalanced placeholder, wrong variable type or undeclared variable.	Fix the template or declare the variable.
Error missing_variables (422) on render	A required variable has no value.	Add it to the JSON of Render.
Error not_found (404) on render	The prompt or the version does not exist.	Publish the prompt first.

Related pages

• Prompt development
• Prompts (data)
• Skill studio
• Policy studio
• Developer portal guide