Add named variables to an agent prompt, preserve typed placeholder values in a draft, and review eligible publication.
Dynamic variables let you write reusable text such as Hello {{customer_name}}. and store example values alongside the agent configuration. Use fictitious values while preparing a prompt so you can review which information it expects.
This guide covers template and placeholder authoring. Conversation execution is currently gated; a saved placeholder does not demonstrate live substitution or a working client integration. Review current availability.
Open an editable agent and select the intended branch. Use a desktop window to access Vars in the editor header. Edits remain in the local working copy until saved through an eligible workflow. Voice and custom-model publication are unavailable; preserve their values in a complete server draft.Decide which values the text needs. For a support-process example, customer_name can use Sample customer and support_topic can use Delivery questions. Keep account credentials and real customer records out of example values.
In Agent Configuration, edit the prompt or First message and insert a reference using double braces. For example:
Hello {{customer_name}}. I can explain our support process for {{support_topic}}.
Use the same spelling wherever you mean the same value. A variable reference identifies expected data; it does not fetch an account record or grant access to a tool.
2
Set typed placeholder values
Open Vars in the editor header. The Dynamic variables panel lists custom variables found in the configuration and marks missing placeholder values.Choose a type for each placeholder: String, Number, Boolean, List, or Null. For the example above, choose String and enter Sample customer and Delivery questions.
Screenshot pending: the Vars panel with fictitious placeholder values. Follow the written steps above.
3
Review the text and values together
Check that each reference uses the intended name and each placeholder has the intended type. The text should remain appropriate for the data it requests; a name or topic value should not be treated as permission to access an account.Review the prompt and first message together. A variable may also be referenced by other supported configuration fields, so check existing references before renaming it.
4
Publish and inspect the saved document
Review both the template text and placeholder map, then save a complete server draft on the selected branch. For an eligible managed text-only configuration, select Publish, inspect Review Changes, and confirm the branch and Commit message. Inspect the resulting draft or published version according to the workflow you used.Reopen the saved version or use Get agent. Confirm the values under conversation_config.agent.dynamic_variables.dynamic_variable_placeholders and record the version ID. This completes the configuration check.
Names must begin with a letter or underscore. After that, use letters, numbers, underscores, or hyphens. The accepted pattern is [A-Za-z_][A-Za-z0-9_-]*. For example, customer_name is valid; customer.name is not a variable name.
Value type
Example
Authoring note
String
"Sample customer"
Use for short example text.
Number
3
Preserve a numeric value when the configuration expects one.
Boolean
false
Store a boolean rather than the string "false".
List
["Delivery", "Returns"]
Lists can contain supported values, including nested lists.
Null
null
An explicit value, distinct from a missing map entry.
The public placeholder input does not accept objects or maps as values. The placeholder map itself pairs variable names with the supported value types above.
The following fragment shows the stored relationship between first-message text and placeholders. It is a conversation-configuration fragment, not a complete agent or server-draft request.
{ "agent": { "first_message": "Hello {{customer_name}}. I can explain our support process for {{support_topic}}.", "dynamic_variables": { "dynamic_variable_placeholders": { "customer_name": "Sample customer", "support_topic": "Delivery questions" } } }}
Place this structure under conversation_config when preparing the corresponding agent change. Update agent requires an explicit branch_id for conversation-configuration updates. If you create a complete server draft, preserve its other fields and follow versions and drafts.
Names beginning with system__ are reserved for platform-provided values. You cannot define them as custom placeholders. Their appearance in a schema or editor list does not establish availability in every runtime context.Names beginning with secret__ may be referenced only in supported request-header variable slots. They cannot be read from prompts, first messages, or general tool parameters. A prefix is not a substitute for credential storage or access control; use the supported credential configuration for a tool and keep real secrets out of examples.
The header control is shown on desktop layouts. Widen the window and check that you are editing an agent rather than viewing a historical version. Version previews and restore operations make placeholder values read-only.
Does a placeholder become every caller's real value?
A placeholder is saved example data in the agent configuration. Supplying authenticated per-conversation values needs a supported session path and its own verification. This guide does not establish a working runtime integration.
Why is a variable marked as missing?
Check that the placeholder map contains the exact referenced name. An explicit null, false, or 0 is a value; an absent map entry is missing. Also check the name format and reserved prefixes.
Can I use variables to look up customer data?
A reference does not perform a lookup. Data access requires a separately configured, authorized integration. Review tools before designing a prompt that depends on private records.
