LLMObs Document version-pinned prompt composition

.generator/schemas/v2/openapi.yaml

@@ -64047,6 +64047,25 @@ components:
       required:
         - data
       type: object
+    LLMObsPromptAuthoringChatTemplate:
+      description: A chat prompt containing messages, references to specific versions of other prompts, or both.
+      items:
+        $ref: "#/components/schemas/LLMObsPromptAuthoringItem"
+      minItems: 1
+      type: array
+    LLMObsPromptAuthoringItem:
+      description: A chat message or a reference to a specific version of another prompt.
+      oneOf:
+        - $ref: "#/components/schemas/LLMObsPromptChatMessage"
+        - $ref: "#/components/schemas/LLMObsPromptIncludeItem"
+    LLMObsPromptAuthoringMessagesTemplate:
+      description: A chat prompt whose authored items are stored under `messages`.
+      properties:
+        messages:
+          $ref: "#/components/schemas/LLMObsPromptAuthoringChatTemplate"
+      required:
+        - messages
+      type: object
     LLMObsPromptChatMessage:
       description: A single chat message in a prompt template.
       properties:
@@ -64170,6 +64189,48 @@ components:
       required:
         - id
       type: object
+    LLMObsPromptInclude:
+      additionalProperties: false
+      description: >-
+        Includes messages from a specific version of another prompt. Omitting `items` includes every message from that version in its original order. When `items` is present, messages are included in the specified order, including repetitions.
+      properties:
+        items:
+          description: >-
+            Zero-based indexes of messages from the included prompt. For example, `[2, 0, 0]` includes the third message, followed by the first message twice. Omit this field to include all messages in their original order.
+          items:
+            format: int64
+            maximum: 2147483647
+            minimum: 0
+            type: integer
+          minItems: 1
+          type: array
+        prompt_id:
+          description: >-
+            Customer-provided identifier of the included prompt. It cannot contain spaces, tabs, line breaks, braces, equal signs, commas, or quotes.
+          example: "response-policy"
+          minLength: 1
+          pattern: "^[^\\s{}=,\"']+$"
+          type: string
+        version:
+          description: Positive sequential version number of the included prompt.
+          example: 3
+          format: int64
+          maximum: 2147483647
+          minimum: 1
+          type: integer
+      required:
+        - prompt_id
+        - version
+      type: object
+    LLMObsPromptIncludeItem:
+      additionalProperties: false
+      description: Includes all or selected messages from a specific version of another prompt.
+      properties:
+        include:
+          $ref: "#/components/schemas/LLMObsPromptInclude"
+      required:
+        - include
+      type: object
     LLMObsPromptResponse:
       description: Response containing a single Agent Observability prompt.
       example:
@@ -64274,11 +64335,17 @@ components:
         - data
       type: object
     LLMObsPromptTemplate:
-      description: A text template or a list of chat messages.
+      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.
+
+        **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.
       example: "You are a helpful assistant for {{audience}}."
       oneOf:
         - $ref: "#/components/schemas/LLMObsPromptTextTemplate"
         - $ref: "#/components/schemas/LLMObsPromptChatTemplate"
+        - $ref: "#/components/schemas/LLMObsPromptAuthoringMessagesTemplate"
     LLMObsPromptTextTemplate:
       description: A text prompt template.
       minLength: 1
@@ -64309,11 +64376,14 @@ components:
         - attributes
       type: object
     LLMObsPromptVersionDataAttributes:
-      description: Attributes of a specific version of an Agent Observability prompt.
+      description: >-
+        Attributes of a specific version of an Agent Observability prompt. For a composed version, `authoring_template` contains its pinned include-bearing source; ordinary versions omit that attribute.
       properties:
         author:
           description: UUID of the user who authored this version.
           type: string
+        authoring_template:
+          $ref: "#/components/schemas/LLMObsPromptTemplate"
         created_at:
           description: Timestamp stored on this prompt version.
           format: date-time
@@ -173727,7 +173797,10 @@ paths:
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
     post:
-      description: Create a new prompt (and its first version) in the Agent Observability prompt registry.
+      description: |-
+        Create a new prompt (and its first version) in the Agent Observability prompt registry.
+
+        > **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager.
       operationId: CreateLLMObsPrompt
       requestBody:
         content:
@@ -174091,14 +174164,42 @@ paths:
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
     post:
-      description: Create a new version of an existing Agent Observability prompt.
+      description: |-
+        Create a new version of an existing Agent Observability prompt.
+
+        > **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager.
       operationId: CreateLLMObsPromptVersion
       parameters:
         - $ref: "#/components/parameters/LLMObsPromptIDPathParameter"
       requestBody:
         content:
           application/json:
             examples:
+              composed_chat:
+                summary: Create a version that includes all or selected messages from other prompts
+                value:
+                  data:
+                    attributes:
+                      template:
+                        messages:
+                          - include:
+                              prompt_id: "assistant-introduction"
+                              version: 2
+                          - include:
+                              items: [2, 0, 0]
+                              prompt_id: "response-examples"
+                              version: 4
+                          - content: "Answer {{question}}."
+                            role: "user"
+                    type: prompt-template-versions
+              composed_text:
+                summary: Create a version that includes text from another prompt
+                value:
+                  data:
+                    attributes:
+                      description: "Reuse the exact response policy."
+                      template: "{{>response-policy version=3}}\n\nAnswer {{question}}."
+                    type: prompt-template-versions
               default:
                 value:
                   data:
@@ -174119,6 +174220,50 @@ paths:
           content:
             application/json:
               examples:
+                composed_chat:
+                  summary: A composed chat version preserves structured authored includes
+                  value:
+                    data:
+                      attributes:
+                        authoring_template:
+                          messages:
+                            - include:
+                                prompt_id: "assistant-introduction"
+                                version: 2
+                            - include:
+                                items: [2, 0, 0]
+                                prompt_id: "response-examples"
+                                version: 4
+                            - content: "Answer {{question}}."
+                              role: "user"
+                        prompt_id: "support-chat"
+                        prompt_uuid: "4a1a28ff-8a25-5f0f-946f-f48264d772eb"
+                        template:
+                          - content: "You are a helpful assistant."
+                            role: "system"
+                          - content: "Here is one concise example."
+                            role: "assistant"
+                          - content: "You are a helpful assistant."
+                            role: "system"
+                          - content: "You are a helpful assistant."
+                            role: "system"
+                          - content: "Answer {{question}}."
+                            role: "user"
+                        version: 2
+                      id: "d83ab666-61cc-5545-a83b-2424bb85467b"
+                      type: prompt-template-versions
+                composed_text:
+                  summary: A composed text version returns compiled and authored templates
+                  value:
+                    data:
+                      attributes:
+                        authoring_template: "{{>response-policy version=3}}\n\nAnswer {{question}}."
+                        prompt_id: "support-answer"
+                        prompt_uuid: "4a1a28ff-8a25-5f0f-946f-f48264d772eb"
+                        template: "Follow the approved response policy.\n\nAnswer {{question}}."
+                        version: 2
+                      id: "d83ab666-61cc-5545-a83b-2424bb85467b"
+                      type: prompt-template-versions
                 default:
                   value:
                     data:

src/main/java/com/datadog/api/client/v2/api/AgentObservabilityApi.java

@@ -2186,6 +2186,14 @@ public CompletableFuture<LLMObsPromptResponse> createLLMObsPromptAsync(
   /**
    * Create a new prompt (and its first version) in the Agent Observability prompt registry.
    *
+   * <blockquote>
+   *
+   * <p><strong>Preview</strong>: Prompt composition is available in Preview. To request access,
+   * contact <a href="https://docs.datadoghq.com/help/">Datadog Support</a> or your Customer Success
+   * Manager.
+   *
+   * </blockquote>
+   *
    * @param body Create prompt payload. (required)
    * @return ApiResponse&lt;LLMObsPromptResponse&gt;
    * @throws ApiException if fails to make API call
@@ -2340,6 +2348,14 @@ public CompletableFuture<LLMObsPromptVersionResponse> createLLMObsPromptVersionA
   /**
    * Create a new version of an existing Agent Observability prompt.
    *
+   * <blockquote>
+   *
+   * <p><strong>Preview</strong>: Prompt composition is available in Preview. To request access,
+   * contact <a href="https://docs.datadoghq.com/help/">Datadog Support</a> or your Customer Success
+   * Manager.
+   *
+   * </blockquote>
+   *
    * @param promptId The customer-provided identifier of the Agent Observability prompt. (required)
    * @param body Create prompt version payload. (required)
    * @return ApiResponse&lt;LLMObsPromptVersionResponse&gt;

src/main/java/com/datadog/api/client/v2/model/LLMObsCreatePromptDataAttributes.java

@@ -180,7 +180,14 @@ public LLMObsCreatePromptDataAttributes template(LLMObsPromptTemplate template)
   }
 
   /**
-   * A text template or a list of chat messages.
+   * A text template, a list of chat messages, or an authored chat object. Text can include an exact
+   * prompt version with <code>{{&gt;prompt-id version=N}}</code>; other text, including <code>
+   * {{&gt;...}}</code> sequences without a version, remains literal. Use an authored chat object
+   * when including prompts as chat messages. <strong>Preview</strong>: Prompt composition is
+   * available in Preview. To request access, contact <a
+   * href="https://docs.datadoghq.com/help/">Datadog Support</a> 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.
    *
    * @return template
    */

src/main/java/com/datadog/api/client/v2/model/LLMObsCreatePromptVersionDataAttributes.java

@@ -151,7 +151,14 @@ public LLMObsCreatePromptVersionDataAttributes template(LLMObsPromptTemplate tem
   }
 
   /**
-   * A text template or a list of chat messages.
+   * A text template, a list of chat messages, or an authored chat object. Text can include an exact
+   * prompt version with <code>{{&gt;prompt-id version=N}}</code>; other text, including <code>
+   * {{&gt;...}}</code> sequences without a version, remains literal. Use an authored chat object
+   * when including prompts as chat messages. <strong>Preview</strong>: Prompt composition is
+   * available in Preview. To request access, contact <a
+   * href="https://docs.datadoghq.com/help/">Datadog Support</a> 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.
    *
    * @return template
    */