AI Governance Center Prompt Management Guide - Microservices Engine

Overview

Prompt management is a core capability of AI Registry (AI Governance Center) that provides unified registration, version management, debugging, publishing, and governance for Prompts.

With Prompt management, you can:

Centrally host Prompts scattered across code and configurations, eliminating the "modify-and-redeploy" release cycle.
Implement canary releases and one-click rollback through multi-version management and label mapping.
Debug Prompts directly in the console to quickly verify their effectiveness.
Lower the barrier to Prompt engineering with built-in AI-assisted optimization.

The following sections walk you through full-lifecycle Prompt management on the AI Registry console.

Prerequisites

You have an Alibaba Cloud account and have activated the AI Registry service.
You have created at least one workspace. If you have not yet created one, see AI Registry Workspace Management Guide.
The current account has the required permissions to perform Prompt operations. To grant permissions to a RAM user, see Configure RAM Permissions for AI Registry.

1. Core concepts

Familiarize yourself with the following key concepts before you begin:

Concept	Description
Prompt	A Prompt resource entity, uniquely identified by `promptKey`. It contains metadata such as the description, business tags, and the version collection.
Version	A snapshot of the Prompt at a specific point in time. Each version contains the template content, variable definitions, and a commit message.
Draft	An unpublished version that can be modified at any time.
Online	A published version that can be retrieved and used by clients.
Label	A movable alias for a version, such as `latest` or `stable`. Clients can use a label to retrieve the specific version it points to.

2. Access the Prompt management page

Log on to the AI Registry console.
In the left-side navigation pane, choose Prompt to enter the Prompt management page.
At the top of the Prompt management page, select a Workspace to enter the Prompt list page of the corresponding Workspace.

3. Create a Prompt

Procedure

On the Prompt list page, click New Prompt.
In the dialog box that appears, configure the following items:

Item	Description	Required
Prompt Name	A more readable display name.	Yes
Prompt Description	A brief explanation of the Prompt's purpose.	No
Prompt Content	Enter the Prompt content.	Yes
Tags	Custom business tags used for classification and filtering.	No

Click Create Now to complete the creation.

After creation, the system initializes a draft version with version number 0.0.1. You can then open the draft editing page to refine the template content.

4. Edit a Prompt draft

A draft is the initial state of a Prompt version. You can modify it at any time until it is submitted for review or published.

Procedure

On the Prompt list page, find the target Prompt and click Details.
Click Edit Draft to enter the editing page of the draft version.
On the editing page, you can edit the following items:

Item	Description
Prompt Content	The body of the Prompt template. Use the `{{variableName}}` syntax to define variable placeholders.
Change Description	A description of this change for version traceability.

During editing, you can click Save Draft to retain the changes. This does not affect the published online version.

Variables explained

Variables are dynamic placeholders in the Prompt template that inject business data at runtime, enabling the same template to serve multiple scenarios.

1. Variable syntax

In the template content, use double curly braces {{variableName}} to declare a variable placeholder. For example:

You are a {{role}}. Please answer the following question in {{language}}:
{{question}}

When rendering, the client passes in role=customer service representative, language=English, and question=How do I get a refund?. The final Prompt sent to the model is:

You are a customer service representative. Please answer the following question in English:
How do I get a refund?

2. Variable naming conventions

Only English letters, digits, and underscores are supported, and the name must start with a letter (such as userName or order_id).
Names are case-sensitive. {{Name}} and {{name}} are two different variables.
We recommend that you use camelCase or snake_case to keep the global naming style consistent.
Variable names must not conflict with system reserved words (such as system or context).

3. Variable definition fields

In the Variable Definition area, each variable has the following attributes:

Field	Description	Required
Name	Must exactly match the `{{variableName}}` in the template.	Yes
Default	The fallback value used when the client does not pass in this variable.	No
Description	Explains the variable's purpose and value range to help other developers understand and use it correctly.	No

4. Automatic variable detection

When you edit the template content, the system automatically scans for {{variableName}} placeholders and generates the corresponding variable entries in the Variable Definition area. You only need to fill in additional information such as the default value and the description.

If you remove a placeholder from the template, the system prompts you to confirm whether to also remove the corresponding variable definition, preventing "defined but not used" or "used but not defined" mismatches.

5. Best practices

Choose an appropriate variable granularity: Avoid stuffing an entire piece of business logic into a single variable, and do not split a single sentence into multiple variables. Aim for a semantically complete minimum unit.
Provide a description for each variable: A clear description significantly reduces the comprehension cost for other developers, and is also important context for AI-assisted Prompt optimization.
Always pass critical variables explicitly: For critical variables (such as user identity or order number), the client must pass them explicitly. Avoid relying on default values, which may cause the online environment to fall back to default values unexpectedly.
Cover multiple values during debugging: Before publishing, use the debug panel to test the Prompt's behavior with different variable values. Pay particular attention to empty values, boundary values, and abnormal values.

5. Debug a Prompt

Before publishing, you can debug a Prompt directly in the console and view the model output in real time.

Procedure

On the Prompt draft editing page or version details page, click the Debug button to enter the debug panel.
In the Prompt content edit box, dynamically adjust the Prompt content.
In the debug panel, configure the following debug parameters:

Parameter	Description
Prompt Version	The version number.
Model Service	Select the model used for debugging from the list of supported models.
Max Tokens	The maximum number of tokens to generate.
TopP	A parameter that controls the sampling range. Valid values: 0 to 1.
Temperature	A parameter that controls the randomness of the output. Valid values are typically 0 to 2.

Fill in User Input, and click Generate Answer. The system returns the model response in SSE streaming output mode.

6. AI-assisted Prompt optimization

If a Prompt does not perform as expected, use the built-in AI-assisted optimization feature to refine it automatically.

Procedure

On the Prompt draft editing page, click the Smart Optimize button.
In the dialog box that appears, you can fill in Optimization Requirements (Optional) (such as "Make the output more concise" or "Add more emotional expression").
Click Start Optimization. The system returns the optimized Prompt content in streaming mode. You can choose to adopt the optimized result or keep the original content.

7. Submit and publish

After completing the draft, publish the version to make it available for client retrieval.

Publishing flow

AI Registry currently supports the following publishing path:

Direct publish: No review is required, and the draft becomes the online version directly.

Publish-with-review will be supported later:

Submit for review and publish: For enterprise scenarios that require a review process.

Procedure

On the Prompt details page, click the Publish Version button.
After publishing, the version state changes to Published, and clients can retrieve the version by its version number or by a label.

8. Version management

View the version list

On the Prompt details page, you can view all versions of the Prompt:

Column	Description
Version	The semantic version number entered when publishing.
Status	Draft / Reviewing / Online.
Version Labels	The labels currently pointing to this version, such as `latest`.

9. Client integration

Published Prompts can be retrieved in the following ways:

Retrieve by version number: namespaceId + promptKey + version retrieves a fixed version.
Retrieve by label: namespaceId + promptKey + label (such as stable) retrieves the version that the label points to.

Before client integration, ensure that:

VPC private network access is configured.
The access account or RAM role is properly configured.

FAQ

Q: Can the Prompt Key be modified?
A: No. The Prompt Key serves as the unique business identifier and cannot be modified after creation. To change it, create a new Prompt and gradually migrate client references.

Q: Can published online versions be deleted?
A: To ensure stable client operation, online versions cannot be deleted directly. To take a version offline, publish a new version to override it, or contact technical support for assistance.

Q: How can a client switch to a new version transparently?
A: We recommend that you use label mapping. The client always retrieves the stable label. After publishing a new version, point the stable label to the new version on the console to perform a transparent switch on the client. If issues occur, point the label back to the previous version for a one-click rollback.

Q: How many versions can a single Prompt have at most?
A: There is no hard limit on the number of versions. However, we recommend that you clean up draft versions that are no longer used in a timely manner to keep the version list readable.