Document managed prompt message placeholders

.generator/schemas/v2/openapi.yaml

@@ -64945,12 +64945,20 @@ components:
         - content
       type: object
     LLMObsPromptChatTemplate:
-      description: A chat prompt template.
+      description: >-
+        A chat prompt template containing messages and optional named message placeholders.
+
+        **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager.
       items:
-        $ref: "#/components/schemas/LLMObsPromptChatMessage"
+        $ref: "#/components/schemas/LLMObsPromptChatTemplateItem"
       minItems: 1
       type: array
       x-generate-alias-as-model: true
+    LLMObsPromptChatTemplateItem:
+      description: A chat message or a named message placeholder in a prompt template.
+      oneOf:
+        - $ref: "#/components/schemas/LLMObsPromptChatMessage"
+        - $ref: "#/components/schemas/LLMObsPromptMessagePlaceholder"
     LLMObsPromptConfig:
       additionalProperties: {}
       description: >-
@@ -65103,6 +65111,33 @@ components:
       required:
         - include
       type: object
+    LLMObsPromptMessagePlaceholder:
+      additionalProperties: false
+      description: >-
+        A named placeholder that inserts a list of messages when a compatible SDK formats the prompt.
+
+        **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager.
+      properties:
+        name:
+          description: Name used to supply the message list when formatting the prompt.
+          example: "history"
+          minLength: 1
+          pattern: "^\\w+$"
+          type: string
+        type:
+          $ref: "#/components/schemas/LLMObsPromptMessagePlaceholderType"
+      required:
+        - type
+        - name
+      type: object
+    LLMObsPromptMessagePlaceholderType:
+      description: Type of chat-template item.
+      enum:
+        - placeholder
+      example: "placeholder"
+      type: string
+      x-enum-varnames:
+        - PLACEHOLDER
     LLMObsPromptResponse:
       description: Response containing a single Agent Observability prompt.
       example:
@@ -65158,9 +65193,11 @@ components:
       properties:
         chat_template:
           description: >-
-            Chat template for this prompt version, as a list of role and content messages. Omitted for text templates.
+            Chat template for this prompt version, as a list of messages and named message placeholders. Omitted for text templates.
+
+            **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager.
           items:
-            $ref: "#/components/schemas/LLMObsPromptChatMessage"
+            $ref: "#/components/schemas/LLMObsPromptChatTemplateItem"
           type: array
         config:
           $ref: "#/components/schemas/LLMObsPromptConfig"
@@ -65195,6 +65232,8 @@ components:
             chat_template:
               - content: "You are a helpful customer support assistant for {{company_name}}."
                 role: "system"
+              - name: "history"
+                type: "placeholder"
               - content: "Help {{customer_name}} with this question: {{question}}"
                 role: "user"
             config:
@@ -65213,11 +65252,13 @@ components:
       type: object
     LLMObsPromptTemplate:
       description: >-
-        A text template, a list of chat messages, or an authored chat object. Text can include an exact prompt version with `{{>prompt-id version=N}}`; other text, including `{{>...}}` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
+        A text template, a list of chat messages and named message placeholders, or an authored chat object. Text can include an exact prompt version with `{{>prompt-id version=N}}`; other text, including `{{>...}}` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
 
         **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager.
 
         Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution.
+
+        **Preview:** Message placeholders are available in Preview. To request access, contact [Datadog Support](https://www.datadoghq.com/support/) or your Customer Success Manager.
       example: "You are a helpful assistant for {{audience}}."
       oneOf:
         - $ref: "#/components/schemas/LLMObsPromptTextTemplate"

src/datadog_api_client/v2/model/llm_obs_create_prompt_data_attributes.py

@@ -17,10 +17,12 @@
     from datadog_api_client.v2.model.llm_obs_prompt_config import LLMObsPromptConfig
     from datadog_api_client.v2.model.llm_obs_prompt_version_label import LLMObsPromptVersionLabel
     from datadog_api_client.v2.model.llm_obs_prompt_template import LLMObsPromptTemplate
-    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
     from datadog_api_client.v2.model.llm_obs_prompt_authoring_messages_template import (
         LLMObsPromptAuthoringMessagesTemplate,
     )
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
 
 
 class LLMObsCreatePromptDataAttributes(ModelNormal):
@@ -62,7 +64,10 @@ def __init__(
         self_,
         prompt_id: str,
         template: Union[
-            LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage], LLMObsPromptAuthoringMessagesTemplate
+            LLMObsPromptTemplate,
+            str,
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+            LLMObsPromptAuthoringMessagesTemplate,
         ],
         config: Union[LLMObsPromptConfig, UnsetType] = unset,
         description: Union[str, UnsetType] = unset,
@@ -90,9 +95,10 @@ def __init__(
         :param prompt_id: Customer-provided identifier for the new prompt.
         :type prompt_id: str
 
-        :param template: A text template, a list of chat messages, or an authored chat object. Text can include an exact prompt version with ``{{>prompt-id version=N}}`` ; other text, including ``{{>...}}`` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
+        :param template: A text template, a list of chat messages and named message placeholders, or an authored chat object. Text can include an exact prompt version with ``{{>prompt-id version=N}}`` ; other text, including ``{{>...}}`` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
             **Preview** : Prompt composition is available in Preview. To request access, contact `Datadog Support <https://docs.datadoghq.com/help/>`_ or your Customer Success Manager.
             Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution.
+            **Preview:** Message placeholders are available in Preview. To request access, contact `Datadog Support <https://www.datadoghq.com/support/>`_ or your Customer Success Manager.
         :type template: LLMObsPromptTemplate
 
         :param title: Optional title of the prompt.

src/datadog_api_client/v2/model/llm_obs_create_prompt_version_data_attributes.py

@@ -17,10 +17,12 @@
     from datadog_api_client.v2.model.llm_obs_prompt_config import LLMObsPromptConfig
     from datadog_api_client.v2.model.llm_obs_prompt_version_label import LLMObsPromptVersionLabel
     from datadog_api_client.v2.model.llm_obs_prompt_template import LLMObsPromptTemplate
-    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
     from datadog_api_client.v2.model.llm_obs_prompt_authoring_messages_template import (
         LLMObsPromptAuthoringMessagesTemplate,
     )
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
 
 
 class LLMObsCreatePromptVersionDataAttributes(ModelNormal):
@@ -51,7 +53,10 @@ def openapi_types(_):
     def __init__(
         self_,
         template: Union[
-            LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage], LLMObsPromptAuthoringMessagesTemplate
+            LLMObsPromptTemplate,
+            str,
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+            LLMObsPromptAuthoringMessagesTemplate,
         ],
         config: Union[LLMObsPromptConfig, UnsetType] = unset,
         description: Union[str, UnsetType] = unset,
@@ -75,9 +80,10 @@ def __init__(
         :param labels: Optional labels to attach to this version. Do not use this attribute for new integrations. **Deprecated**.
         :type labels: [LLMObsPromptVersionLabel], optional
 
-        :param template: A text template, a list of chat messages, or an authored chat object. Text can include an exact prompt version with ``{{>prompt-id version=N}}`` ; other text, including ``{{>...}}`` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
+        :param template: A text template, a list of chat messages and named message placeholders, or an authored chat object. Text can include an exact prompt version with ``{{>prompt-id version=N}}`` ; other text, including ``{{>...}}`` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
             **Preview** : Prompt composition is available in Preview. To request access, contact `Datadog Support <https://docs.datadoghq.com/help/>`_ or your Customer Success Manager.
             Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution.
+            **Preview:** Message placeholders are available in Preview. To request access, contact `Datadog Support <https://www.datadoghq.com/support/>`_ or your Customer Success Manager.
         :type template: LLMObsPromptTemplate
 
         :param user_version: Optional user-supplied version identifier for this version.

src/datadog_api_client/v2/model/llm_obs_prompt_chat_template_item.py

@@ -0,0 +1,49 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelComposed,
+    cached_property,
+)
+
+
+class LLMObsPromptChatTemplateItem(ModelComposed):
+    def __init__(self, **kwargs):
+        """
+        A chat message or a named message placeholder in a prompt template.
+
+        :param content: Content of the message.
+        :type content: str
+
+        :param role: Role of the message (for example `system`, `user`, or `assistant`).
+        :type role: str
+
+        :param name: Name used to supply the message list when formatting the prompt.
+        :type name: str
+
+        :param type: Type of chat-template item.
+        :type type: LLMObsPromptMessagePlaceholderType
+        """
+        super().__init__(kwargs)
+
+    @cached_property
+    def _composed_schemas(_):
+        # we need this here to make our import statements work
+        # we must store _composed_schemas in here so the code is only run
+        # when we invoke this method. If we kept this at the class
+        # level we would get an error because the class level
+        # code would be run when this module is imported, and these composed
+        # classes don't exist yet because their module has not finished
+        # loading
+        from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+        from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
+
+        return {
+            "oneOf": [
+                LLMObsPromptChatMessage,
+                LLMObsPromptMessagePlaceholder,
+            ],
+        }

src/datadog_api_client/v2/model/llm_obs_prompt_message_placeholder.py

@@ -0,0 +1,59 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder_type import LLMObsPromptMessagePlaceholderType
+
+
+class LLMObsPromptMessagePlaceholder(ModelNormal):
+    validations = {
+        "name": {
+            "min_length": 1,
+        },
+    }
+
+    @cached_property
+    def additional_properties_type(_):
+        return None
+
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder_type import (
+            LLMObsPromptMessagePlaceholderType,
+        )
+
+        return {
+            "name": (str,),
+            "type": (LLMObsPromptMessagePlaceholderType,),
+        }
+
+    attribute_map = {
+        "name": "name",
+        "type": "type",
+    }
+
+    def __init__(self_, name: str, type: LLMObsPromptMessagePlaceholderType, **kwargs):
+        """
+        A named placeholder that inserts a list of messages when a compatible SDK formats the prompt.
+        **Preview:** Message placeholders are available in Preview. To request access, contact `Datadog Support <https://www.datadoghq.com/support/>`_ or your Customer Success Manager.
+
+        :param name: Name used to supply the message list when formatting the prompt.
+        :type name: str
+
+        :param type: Type of chat-template item.
+        :type type: LLMObsPromptMessagePlaceholderType
+        """
+        super().__init__(kwargs)
+
+        self_.name = name
+        self_.type = type

src/datadog_api_client/v2/model/llm_obs_prompt_message_placeholder_type.py

@@ -0,0 +1,35 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class LLMObsPromptMessagePlaceholderType(ModelSimple):
+    """
+    Type of chat-template item.
+
+    :param value: If omitted defaults to "placeholder". Must be one of ["placeholder"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "placeholder",
+    }
+    PLACEHOLDER: ClassVar["LLMObsPromptMessagePlaceholderType"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+LLMObsPromptMessagePlaceholderType.PLACEHOLDER = LLMObsPromptMessagePlaceholderType("placeholder")

src/datadog_api_client/v2/model/llm_obs_prompt_sdk_data_attributes.py

@@ -14,18 +14,20 @@
 
 
 if TYPE_CHECKING:
-    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
     from datadog_api_client.v2.model.llm_obs_prompt_config import LLMObsPromptConfig
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
 
 
 class LLMObsPromptSDKDataAttributes(ModelNormal):
     @cached_property
     def openapi_types(_):
-        from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+        from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
         from datadog_api_client.v2.model.llm_obs_prompt_config import LLMObsPromptConfig
 
         return {
-            "chat_template": ([LLMObsPromptChatMessage],),
+            "chat_template": ([LLMObsPromptChatTemplateItem],),
             "config": (LLMObsPromptConfig,),
             "labels": ([str],),
             "prompt_id": (str,),
@@ -46,7 +48,10 @@ def openapi_types(_):
 
     def __init__(
         self_,
-        chat_template: Union[List[LLMObsPromptChatMessage], UnsetType] = unset,
+        chat_template: Union[
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+            UnsetType,
+        ] = unset,
         config: Union[LLMObsPromptConfig, UnsetType] = unset,
         labels: Union[List[str], UnsetType] = unset,
         prompt_id: Union[str, UnsetType] = unset,
@@ -58,8 +63,9 @@ def __init__(
         """
         Attributes of a flattened prompt version returned for SDK consumption. Exactly one of ``template`` and ``chat_template`` is returned. Empty ``config`` is omitted when configuration authoring is disabled for the organization. Non-empty saved configuration is always returned.
 
-        :param chat_template: Chat template for this prompt version, as a list of role and content messages. Omitted for text templates.
-        :type chat_template: [LLMObsPromptChatMessage], optional
+        :param chat_template: Chat template for this prompt version, as a list of messages and named message placeholders. Omitted for text templates.
+            **Preview:** Message placeholders are available in Preview. To request access, contact `Datadog Support <https://www.datadoghq.com/support/>`_ or your Customer Success Manager.
+        :type chat_template: [LLMObsPromptChatTemplateItem], optional
 
         :param config: Versioned prompt configuration is in Preview. To request access, contact `Datadog Support <https://www.datadoghq.com/support/>`_ or your Customer Success Manager. Customer-owned configuration delivered with a prompt version. Datadog stores and returns the object without interpolating it, validating provider-specific keys, or applying it to model calls. Do not include secrets.
         :type config: LLMObsPromptConfig, optional