Dynamic injection of AgentRun prompt variables
Duplicating an AgentRuntime for each user, business line, or scenario increases maintenance costs. Dynamic prompt variable injection avoids this by allowing a single AgentRuntime to adopt different roles and behaviors per request. To do this, you write the prompt as a template and pass different variable values in each call.
Prerequisites
Before you use dynamic prompt variable injection, ensure that you meet the following conditions:
You have created an invokable AgentRuntime and published its endpoint. If you have not done so, see Quickly create an agent (no-code).
The system prompt for the AgentRuntime includes placeholders in the
{variable_name}format.
Variable sources and precedence
The core principle of dynamic prompt variable injection is to write the stable part of a prompt as a template and pass the changing parts as variables with each call. When AgentRuntime receives a request, it automatically replaces the placeholders with the corresponding values to generate the final system prompt.
For example, you can write a system prompt template as follows:
You are a {role} who is an expert in {expertise}. Please answer user questions in a {tone} tone.When invoking the AgentRuntime, pass different variable values, such as role=Enterprise knowledge base assistant. AgentRuntime then automatically replaces the placeholders with these values.
AgentRuntime processes prompt variables in the following order of precedence:
Prompt template (contains {variable_name} placeholders)
↓
Default variables (runtime configuration, e.g., the PROMPT_VARIABLES environment variable)
↓
Request-level variables (forwardedProps.system_prompt_vars, higher precedence)
↓
Expanded system promptDefault variables serve as a fallback, ensuring a complete prompt is generated even if the caller omits some variables. Request-level variables are passed with each API call and override default variables with the same key.
Default variables
You can provide default values for prompt placeholders by using the PROMPT_VARIABLES environment variable in the AgentRuntime configuration. We recommend using a JSON object format:
PROMPT='You are a {role} who is an expert in {expertise}. Please answer user questions in a {tone} tone.'
PROMPT_VARIABLES='{"role":"AI assistant","expertise":"general Q&A","tone":"clear and polite"}'PROMPT_VARIABLES also supports an array format, which is useful for converting from console form configurations:
[
{"variable_key": "role", "variable_value": "AI assistant"},
{"variable_key": "expertise", "variable_value": "general Q&A"},
{"variable_key": "tone", "variable_value": "clear and polite"}
]Request-level variables
When you invoke an AgentRuntime, pass the system_prompt_vars within the top-level forwardedProps object in the request body. This is a JSON object where the keys correspond to the {variable_name} placeholders in the prompt.
{
"forwardedProps": {
"system_prompt_vars": {
"role": "Enterprise knowledge base assistant",
"expertise": "retrieving and summarizing the internal knowledge base",
"tone": "concise and professional"
}
}
}If a key exists in both the default and request-level variables, the value from the request-level variable takes precedence. Keys that are not overridden will continue to use their default values.
Invoke AgentRuntime with injected variables
You can invoke AgentRuntime using the OpenAI-compatible or AG-UI protocol. Both support passing request-level variables in forwardedProps.system_prompt_vars, and the variable merging rules are identical. Choose the protocol that best fits your integration scenario:
Protocol | Use cases |
OpenAI-compatible protocol | You have an existing OpenAI SDK integration or want to reuse the standard request/response structure of the Chat Completions API. |
AG-UI protocol | You need AG-UI event stream capabilities or are using an AG-UI client framework. |
Invoke using the OpenAI-compatible protocol
When invoking an AgentRuntime using the OpenAI-compatible protocol, include forwardedProps directly in the request body:
curl "https://{account-id}.agentrun-data.{region}.aliyuncs.com/agent-runtimes/{agent-name}/endpoints/{endpoint-name}/invocations/openai/v1/chat/completions" \
-X POST \
-H "Content-Type: application/json" \
-H "x-agentrun-session-id: {your-session-id}" \
-d '{
"messages": [
{"role": "user", "content": "Please introduce your capabilities."}
],
"stream": true,
"forwardedProps": {
"system_prompt_vars": {
"role": "Enterprise knowledge base assistant",
"expertise": "retrieving and summarizing the internal knowledge base",
"tone": "concise and professional"
}
}
}'The preceding request replaces the placeholders in the prompt template with the following values:
Placeholder | Value |
|
|
|
|
|
|
If you do not pass forwardedProps.system_prompt_vars, AgentRuntime expands the prompt using the default variables.
The following table describes the parameters in the request URL.
Parameter | Description |
| Your Alibaba Cloud account ID. |
| The region where the AgentRuntime is located, for example, |
| The name of the AgentRuntime. |
| The name of the endpoint. |
| The session ID, used to maintain context in a multi-turn conversation. |
Invoke using the AG-UI protocol
The AG-UI protocol also supports passing request-level variables by using forwardedProps.system_prompt_vars. The AG-UI response is an SSE (Server-Sent Events) stream, and the client must process the returned data as an event stream:
curl "https://{account-id}.agentrun-data.{region}.aliyuncs.com/agent-runtimes/{agent-name}/endpoints/{endpoint-name}/invocations/ag-ui/agent" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-H "x-agentrun-session-id: {your-session-id}" \
-d '{
"threadId": "{thread-id}",
"runId": "{run-id}",
"messages": [
{"role": "user", "content": "Please introduce your capabilities."}
],
"forwardedProps": {
"system_prompt_vars": {
"role": "Enterprise knowledge base assistant",
"expertise": "retrieving and summarizing the internal knowledge base",
"tone": "concise and professional"
}
}
}'Compared to the OpenAI-compatible protocol, an AG-UI protocol request includes the following additional parameters:
Parameter | Description |
| The conversation thread ID. |
| A unique identifier for the execution. |
Verify the injection result
After sending the request, the agent's response should reflect the injected role and tone. Using the preceding examples, the agent should respond as an "Enterprise knowledge base assistant" in a "concise and professional" manner. If the response contains the original placeholder text, such as {role}, variable replacement failed. See the FAQ section for troubleshooting steps.
Expansion rules
Rule | Description |
Placeholder format | Use the |
Matching | Variable names must match exactly and are case-sensitive. |
Override order |
|
Missing variables | Placeholders without a provided value remain unchanged. This does not cause an error. |
Variable value type | Non-string values are automatically converted to strings before insertion into the prompt. |
We recommend configuring default values for all placeholders. This ensures that AgentRuntime always generates a complete prompt even if the caller omits a variable, preventing raw placeholders from being exposed to the model.
Security recommendations
Do not include sensitive information such as API keys, AccessKeys, phone numbers, national ID numbers, or customer IDs in prompt variables.
Do not expose full invocation domains, authorization headers, account IDs, or real session IDs in sample code, logs, screenshots, or support tickets.
If a variable's value comes from external user input, validate it against a business-defined allowlist or a set of enumerated values before passing it to AgentRuntime.
For critical variables that define roles, permission boundaries, or compliance rules, generate them on the server side. Do not trust values passed from the client side.
FAQ
Q: Where should I place system_prompt_vars?
Place it inside the top-level forwardedProps object in the request body:
{
"forwardedProps": {
"system_prompt_vars": {
"role": "Enterprise knowledge base assistant"
}
}
}Do not place it inside messages, metadata, or the request headers.
Q: Do request-level variables override all default variables?
No. Request-level variables only override keys with the same name. For example, if the default variables include keys for role, expertise, and tone, but the request only passes a new tone, the final prompt will use the default role and expertise along with the request-provided tone.
Q: Can I use user input directly as a variable value?
Yes, but you must perform business validation first. After expansion, the variable becomes part of the system prompt, which is a high-priority context that influences the agent's behavior. Do not allow unvalidated user input to directly control critical fields such as role definitions, permission boundaries, or tool usage rules.
Q: Why were my prompt variables not replaced as expected?
Check the following in order:
Do the placeholders in the prompt template use the
{variable_name}format? (Note: Use single curly braces{}, not double curly braces.)Verify that the key names in
system_prompt_varsexactly match the variable names in the placeholders. The match is case-sensitive.Confirm that
forwardedPropsis at the top level in the request body (at the same level asmessages) and not nested within another field.Ensure that the value of the
PROMPT_VARIABLESenvironment variable is valid JSON.Check the logs for any messages indicating variable parsing failures or missing placeholders.
Related links
AgentRun Console: https://functionai.console.aliyun.com/
AgentRun Python SDK: https://github.com/Serverless-Devs/agentrun-sdk-python
Agent integration and publishing: https://www.alibabacloud.com/help/en/doc-detail/2998775.html