Add environment retrieval to the LLMObs prompt API

.generator/schemas/v2/openapi.yaml

@@ -1080,6 +1080,16 @@ components:
       required: true
       schema:
         type: string
+    LLMObsPromptEnvironmentQueryParameter:
+      description: >-
+        Optional `DD_ENV` value used to resolve the prompt version deployed to the matching Feature Flags environment. This value is not a Feature Flags environment UUID. Using this parameter additionally requires the `feature_flag_config_read` and `feature_flag_environment_config_read` permissions. This parameter cannot be used with `label`.
+      example: production
+      in: query
+      name: environment
+      required: false
+      schema:
+        minLength: 1
+        type: string
     LLMObsPromptIDPathParameter:
       description: The customer-provided identifier of the Agent Observability prompt.
       example: "customer-support-assistant"
@@ -1090,7 +1100,7 @@ components:
         type: string
     LLMObsPromptLabelQueryParameter:
       description: >-
-        **Deprecated.** Optional label of the prompt version to return. Do not use this parameter for new integrations. If omitted, the latest version is returned. If the prompt has no labels, the latest version is returned even when a label is requested. If the prompt has labels but none match the requested label, a 404 response is returned.
+        **Deprecated.** Optional label of the prompt version to return. Do not use this parameter for new integrations. If omitted, the latest version is returned. If the prompt has no labels, the latest version is returned even when a label is requested. If the prompt has labels but none match the requested label, a 404 response is returned. This parameter cannot be used with `environment`.
       in: query
       name: label
       required: false
@@ -167110,11 +167120,13 @@ 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/).
     get:
-      description: Get the latest version of an Agent Observability prompt by prompt ID.
+      description: >-
+        Get an Agent Observability prompt by prompt ID. When `environment` is omitted, this returns the latest version or uses the deprecated `label` behavior and requires `llm_observability_read`. When `environment` is supplied, it must be a nonempty `DD_ENV` value, cannot be combined with `label`, and additionally requires `feature_flag_config_read` and `feature_flag_environment_config_read`. An empty environment or combining it with `label` returns 400, and missing either additional permission returns 403. A missing prompt or deployment returns 404 without falling back to the latest version. An environment resolution failure returns 500.
       operationId: GetLLMObsPrompt
       parameters:
         - $ref: "#/components/parameters/LLMObsPromptIDPathParameter"
         - $ref: "#/components/parameters/LLMObsPromptLabelQueryParameter"
+        - $ref: "#/components/parameters/LLMObsPromptEnvironmentQueryParameter"
       responses:
         "200":
           content:
@@ -167137,6 +167149,14 @@ paths:
               schema:
                 $ref: "#/components/schemas/LLMObsPromptSDKResponse"
           description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: |-
+            Bad Request
+            The environment is empty, or environment and label are both supplied.
         "401":
           content:
             application/json:
@@ -167148,15 +167168,28 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/JSONAPIErrorResponse"
-          description: Forbidden
+          description: |-
+            Forbidden
+            The application key lacks `llm_observability_read`, or environment resolution was requested without both
+            `feature_flag_config_read` and `feature_flag_environment_config_read`.
         "404":
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/JSONAPIErrorResponse"
-          description: Not Found
+          description: |-
+            Not Found
+            The prompt does not exist, or no prompt deployment can be resolved for the supplied environment.
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
+        "500":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: |-
+            Internal Server Error
+            Environment resolution failed.
       security:
         - apiKeyAuth: []
           appKeyAuth: []

examples/v2/agent-observability/GetLLMObsPrompt_2452494832.rb

@@ -0,0 +1,11 @@
+# Get an Agent Observability prompt by environment returns "OK" response
+
+require "datadog_api_client"
+DatadogAPIClient.configure do |config|
+  config.unstable_operations["v2.get_llm_obs_prompt".to_sym] = true
+end
+api_instance = DatadogAPIClient::V2::AgentObservabilityAPI.new
+opts = {
+  environment: "production",
+}
+p api_instance.get_llm_obs_prompt("prompt_id", opts)

features/scenarios_model_mapping.rb

@@ -1036,6 +1036,7 @@
     "v2.GetLLMObsPrompt" => {
             "prompt_id" => "String",
             "label" => "String",
+            "environment" => "String",
     },
     "v2.UpdateLLMObsPrompt" => {
             "prompt_id" => "String",

features/v2/agent_observability.feature

@@ -766,6 +766,23 @@ Feature: Agent Observability
     When the request is sent
     Then the response status is 200 OK
 
+  @skip @team:DataDog/ml-observability
+  Scenario: Get an Agent Observability prompt by environment returns "OK" response
+    Given operation "GetLLMObsPrompt" enabled
+    And new "GetLLMObsPrompt" request
+    And request contains "prompt_id" parameter from "REPLACE.ME"
+    And request contains "environment" parameter with value "production"
+    When the request is sent
+    Then the response status is 200 OK
+
+  @generated @skip @team:DataDog/ml-observability
+  Scenario: Get an Agent Observability prompt returns "Bad Request" response
+    Given operation "GetLLMObsPrompt" enabled
+    And new "GetLLMObsPrompt" request
+    And request contains "prompt_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 400 Bad Request
+
   @generated @skip @team:DataDog/ml-observability
   Scenario: Get an Agent Observability prompt returns "Not Found" response
     Given operation "GetLLMObsPrompt" enabled

lib/datadog_api_client/v2/api/agent_observability_api.rb

@@ -2414,11 +2414,12 @@ def get_llm_obs_prompt(prompt_id, opts = {})
 
     # Get an Agent Observability prompt.
     #
-    # Get the latest version of an Agent Observability prompt by prompt ID.
+    # Get an Agent Observability prompt by prompt ID. When `environment` is omitted, this returns the latest version or uses the deprecated `label` behavior and requires `llm_observability_read`. When `environment` is supplied, it must be a nonempty `DD_ENV` value, cannot be combined with `label`, and additionally requires `feature_flag_config_read` and `feature_flag_environment_config_read`. An empty environment or combining it with `label` returns 400, and missing either additional permission returns 403. A missing prompt or deployment returns 404 without falling back to the latest version. An environment resolution failure returns 500.
     #
     # @param prompt_id [String] The customer-provided identifier of the Agent Observability prompt.
     # @param opts [Hash] the optional parameters
-    # @option opts [String] :label **Deprecated.** Optional label of the prompt version to return. Do not use this parameter for new integrations. If omitted, the latest version is returned. If the prompt has no labels, the latest version is returned even when a label is requested. If the prompt has labels but none match the requested label, a 404 response is returned.
+    # @option opts [String] :label **Deprecated.** Optional label of the prompt version to return. Do not use this parameter for new integrations. If omitted, the latest version is returned. If the prompt has no labels, the latest version is returned even when a label is requested. If the prompt has labels but none match the requested label, a 404 response is returned. This parameter cannot be used with `environment`.
+    # @option opts [String] :environment Optional `DD_ENV` value used to resolve the prompt version deployed to the matching Feature Flags environment. This value is not a Feature Flags environment UUID. Using this parameter additionally requires the `feature_flag_config_read` and `feature_flag_environment_config_read` permissions. This parameter cannot be used with `label`.
     # @return [Array<(LLMObsPromptSDKResponse, Integer, Hash)>] LLMObsPromptSDKResponse data, response status code and response headers
     def get_llm_obs_prompt_with_http_info(prompt_id, opts = {})
       unstable_enabled = @api_client.config.unstable_operations["v2.get_llm_obs_prompt".to_sym]
@@ -2435,12 +2436,16 @@ def get_llm_obs_prompt_with_http_info(prompt_id, opts = {})
       if @api_client.config.client_side_validation && prompt_id.nil?
         fail ArgumentError, "Missing the required parameter 'prompt_id' when calling AgentObservabilityAPI.get_llm_obs_prompt"
       end
+      if @api_client.config.client_side_validation && !opts[:'environment'].nil? && opts[:'environment'].to_s.length < 1
+        fail ArgumentError, 'invalid value for "opts[:"environment"]" when calling AgentObservabilityAPI.get_llm_obs_prompt, the character length must be great than or equal to 1.'
+      end
       # resource path
       local_var_path = '/api/v2/llm-obs/v1/prompts/{prompt_id}'.sub('{prompt_id}', CGI.escape(prompt_id.to_s).gsub('%2F', '/'))
 
       # query parameters
       query_params = opts[:query_params] || {}
       query_params[:'label'] = opts[:'label'] if !opts[:'label'].nil?
+      query_params[:'environment'] = opts[:'environment'] if !opts[:'environment'].nil?
 
       # header parameters
       header_params = opts[:header_params] || {}