API Cleanup initial pass(merge sqush jugonzales/agents-optimization-v2preview) (Azure#43927)

* rebase to /feature/foundry-release and merge sqush jugonzales/agents-optimization-v2preview

* resolve missing file

* address comment for minValue of max_candidates

* address comments of OptimizationInlineDatasetInput.type

* address coment of OptimizationJobListItem

Author: YoYoJa

specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.json

@@ -15,7 +15,7 @@ namespace Azure.AI.Projects;
 
 const AgentOptimizationRequiredPreviews = #{
   conditional_previews: #[
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview
+    FoundryFeaturesOptInKeys.agents_optimization_v2_preview
   ],
 };
 
@@ -28,55 +28,31 @@ const AgentOptimizationRequiredPreviews = #{
 #suppress "@azure-tools/typespec-azure-core/long-running-polling-operation-required" "LRO polling is handled by the client via Operation-Location"
 @tag("AgentOptimizationJobs")
 interface AgentOptimizationJobs {
-  /**
-   * Creates an agent optimization job and returns the queued job.
-   * Honors `Operation-Id` for idempotent retry.
-   */
-  @summary("Create an agent optimization job")
+  @summary("Creates an agent optimization job.")
+  @doc("Create an optimization job. Returns 201 with the queued job. Honours `Operation-Id` for idempotent retry.")
   @route("agent_optimization_jobs")
   @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @post
-  create is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      ...WithOperationId;
-
-      @doc("The optimization job inputs.")
-      @body
-      inputs: OptimizationJobInputs;
-    },
-    JobCreatedResponse<OptimizationJob>
+  create is postJobPreview<
+    FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
+    OptimizationJob
   >;
 
-  /**
-   * Retrieves the specified agent optimization job.
-   * Returns 202 while the job is in progress and 200 after it reaches a terminal state.
-   */
-  @summary("Get an agent optimization job")
+  @summary("Get info about an agent optimization job.")
+  @doc("Get an optimization job by id.")
   @route("agent_optimization_jobs/{jobId}")
   @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @get
-  get is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      /** The ID of the job. */
-      @path jobId: string;
-    },
-    OptimizationJob & {
-      @statusCode _: 200 | 202;
-      @header("Retry-After") retryAfter?: int32;
-    }
+  get is queryJobStatusPreview<
+    FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
+    OptimizationJob
   >;
 
-  /**
-   * Returns agent optimization jobs with cursor pagination and optional lifecycle or agent filters.
-   */
-  @summary("List agent optimization jobs")
+  @summary("Returns a list of agent optimization jobs.")
+  @doc("List optimization jobs. Supports cursor pagination and optional status / agent_name filters.")
   @route("agent_optimization_jobs")
   @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
   list is listJobsPreview<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    OptimizationJob,
+    FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
+    OptimizationJobListItem,
     {
       @doc("Filter to jobs in this lifecycle state.")
       @query
@@ -88,175 +64,19 @@ interface AgentOptimizationJobs {
     }
   >;
 
-  /**
-   * Requests cancellation of the specified agent optimization job.
-   * The operation remains idempotent after the job reaches a terminal state.
-   */
-  @summary("Cancel an agent optimization job")
+  @summary("Cancels an agent optimization job.")
+  @doc("Request cancellation of a running or queued job. Returns an error if the job is already in a terminal state.")
   @route("agent_optimization_jobs/{jobId}:cancel")
   @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
   cancel is cancelJobPreview<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
+    FoundryFeaturesOptInKeys.agents_optimization_v2_preview,
     OptimizationJob
   >;
 
-  /**
-   * Deletes the specified agent optimization job and its candidate artifacts.
-   * Cancels the job first when it is still in a non-terminal state.
-   */
-  @summary("Delete an agent optimization job")
+  @summary("Deletes an agent optimization job.")
+  @doc("Delete the job and its candidate artifacts. Cancels first if non-terminal.")
   @route("agent_optimization_jobs/{jobId}")
   @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @delete
-  delete is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The ID of the job to delete.")
-      @path
-      jobId: string;
-
-      @doc("When true, force-delete even if the job is in a non-terminal state.")
-      @query
-      force?: boolean;
-    },
-    NoContentResponse
-  >;
-
-  // ---------------------------------------------------------------------------
-  // Candidate sub-resource operations
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Returns the candidates produced by the specified optimization job.
-   */
-  @summary("List optimization job candidates")
-  @route("agent_optimization_jobs/{jobId}/candidates")
-  @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @get
-  @list
-  listCandidates is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The optimization job id.")
-      @path
-      jobId: string;
+  delete is deleteJobPreview<FoundryFeaturesOptInKeys.agents_optimization_v2_preview>;
 
-      ...CommonPageQueryParameters;
-    },
-    AgentsPagedResult<OptimizationCandidate>
-  >;
-
-  /**
-   * Retrieves metadata, manifest information, and promotion details for the specified candidate.
-   */
-  @summary("Get an optimization candidate")
-  @route("agent_optimization_jobs/{jobId}/candidates/{candidateId}")
-  @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @get
-  getCandidate is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The optimization job id.")
-      @path
-      jobId: string;
-
-      @doc("The candidate id.")
-      @path
-      candidateId: string;
-    },
-    CandidateMetadata
-  >;
-
-  /**
-   * Retrieves the deploy configuration JSON for the specified candidate.
-   * Clients can use it to compose `agents.create_version(...)` requests.
-   */
-  @summary("Get an optimization candidate config")
-  @route("agent_optimization_jobs/{jobId}/candidates/{candidateId}/config")
-  @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @get
-  getCandidateConfig is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The optimization job id.")
-      @path
-      jobId: string;
-
-      @doc("The candidate id.")
-      @path
-      candidateId: string;
-    },
-    CandidateDeployConfig
-  >;
-
-  /**
-   * Retrieves full per-task evaluation results for the specified candidate.
-   */
-  @summary("Get optimization candidate results")
-  @route("agent_optimization_jobs/{jobId}/candidates/{candidateId}/results")
-  @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @get
-  getCandidateResults is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The optimization job id.")
-      @path
-      jobId: string;
-
-      @doc("The candidate id.")
-      @path
-      candidateId: string;
-    },
-    CandidateResults
-  >;
-
-  /**
-   * Streams the specified file from the candidate's blob directory.
-   */
-  @summary("Get an optimization candidate file")
-  @route("agent_optimization_jobs/{jobId}/candidates/{candidateId}/files")
-  @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @get
-  getCandidateFile is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The optimization job id.")
-      @path
-      jobId: string;
-
-      @doc("The candidate id.")
-      @path
-      candidateId: string;
-
-      @doc("Relative path of the file to download (e.g. 'files/examples.jsonl').")
-      @query
-      path: string;
-    },
-    bytes
-  >;
-
-  /**
-   * Promotes the specified candidate and records the deployment timestamp and target agent version.
-   */
-  @summary("Promote an optimization candidate")
-  @route("agent_optimization_jobs/{jobId}/candidates/{candidateId}:promote")
-  @extension("x-ms-foundry-meta", AgentOptimizationRequiredPreviews)
-  @post
-  promoteCandidate is FoundryDataPlanePreviewOperation<
-    FoundryFeaturesOptInKeys.agents_optimization_v1_preview,
-    {
-      @doc("The optimization job id.")
-      @path
-      jobId: string;
-
-      @doc("The candidate id to promote.")
-      @path
-      candidateId: string;
-
-      @doc("Promotion details.")
-      @body
-      candidate_request: PromoteCandidateRequest;
-    },
-    PromoteCandidateResponse
-  >;
 }

specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.yaml

@@ -68,24 +68,3 @@ interface Agents {}
 @@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.list, Agents);
 @@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.cancel, Agents);
 @@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.delete, Agents);
-@@clientLocation(
-  Azure.AI.Projects.AgentOptimizationJobs.listCandidates,
-  Agents
-);
-@@clientLocation(Azure.AI.Projects.AgentOptimizationJobs.getCandidate, Agents);
-@@clientLocation(
-  Azure.AI.Projects.AgentOptimizationJobs.getCandidateConfig,
-  Agents
-);
-@@clientLocation(
-  Azure.AI.Projects.AgentOptimizationJobs.getCandidateResults,
-  Agents
-);
-@@clientLocation(
-  Azure.AI.Projects.AgentOptimizationJobs.getCandidateFile,
-  Agents
-);
-@@clientLocation(
-  Azure.AI.Projects.AgentOptimizationJobs.promoteCandidate,
-  Agents
-);

specification/ai-foundry/data-plane/Foundry/openapi3/virtual-public-preview/microsoft-foundry-openapi3.json

@@ -192,19 +192,6 @@ using Azure.AI.Projects;
 @@clientName(AgentOptimizationJobs.list, "listOptimizationJobs");
 @@clientName(AgentOptimizationJobs.cancel, "cancelOptimizationJob");
 @@clientName(AgentOptimizationJobs.delete, "deleteOptimizationJob");
-@@clientName(
-  AgentOptimizationJobs.listCandidates,
-  "listOptimizationCandidates"
-);
-@@clientName(AgentOptimizationJobs.getCandidate, "getOptimizationCandidate");
-@@clientName(
-  AgentOptimizationJobs.getCandidateConfig,
-  "getOptimizationCandidateConfig"
-);
-@@clientName(
-  AgentOptimizationJobs.getCandidateResults,
-  "getOptimizationCandidateResults"
-);
 
 // DatasetItem model has a property `response_items?: OpenAI.OutputItem[]`. It is used
 // to define Agent optimization request. If emitted as-is, it pulls in a lot of

specification/ai-foundry/data-plane/Foundry/openapi3/virtual-public-preview/microsoft-foundry-openapi3.yaml

@@ -106,7 +106,7 @@ union FoundryFeaturesOptInKeys {
   skills_v1_preview: "Skills=V1Preview",
   data_generation_jobs_v1_preview: "DataGenerationJobs=V1Preview",
   models_v1_preview: "Models=V1Preview",
-  agents_optimization_v1_preview: "AgentsOptimization=V1Preview",
+  agents_optimization_v2_preview: "AgentsOptimization=V2Preview",
 }
 
 alias WithRequiredFoundryPreviewHeader<RequiredPreviewOptInHeader extends