azure-ai-agents and azure-ai-projects package refactor for better beta feature isolation

eng/lintingconfigs/revapi/track2/revapi.json

@@ -1963,6 +1963,117 @@
           "code": "java.method.returnTypeChanged",
           "old": "method double com.azure.ai.projects.models.ModelSamplingParams::getTopP()",
           "justification": "Breaking change in beta operation: return type changed from primitive double to boxed Double to support optional values."
+        },
+        {
+          "ignore": true,
+          "code": "java.class.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "class com\\.azure\\.ai\\.agents\\.(AgentSessionFiles|MemoryStores|Toolboxes)(Async)?Client"
+          },
+          "justification": "Beta operations were moved out of the main agents client into dedicated beta clients: the AgentSessionFiles, MemoryStores and Toolboxes sub-clients are removed and their operations now live on BetaAgentsClient/BetaAgentsAsyncClient, BetaMemoryStoresClient/BetaMemoryStoresAsyncClient and BetaToolboxesClient/BetaToolboxesAsyncClient."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "method com\\.azure\\.ai\\.agents\\.(AgentSessionFiles|MemoryStores|Toolboxes)(Async)?Client com\\.azure\\.ai\\.agents\\.AgentsClientBuilder::build(AgentSessionFiles|MemoryStores|Toolboxes)(Async)?Client\\(\\)"
+          },
+          "justification": "Beta operations were moved into dedicated beta clients: the AgentsClientBuilder factory methods for the AgentSessionFiles, MemoryStores and Toolboxes sub-clients are removed and replaced by buildBetaAgentsClient/buildBetaMemoryStoresClient/buildBetaToolboxesClient (and their async variants)."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "method .* com\\.azure\\.ai\\.agents\\.Agents(Async)?Client::(createSession|getSession|listSessions|deleteSession|stopSession|getSessionLogStream|cancelOptimizationJob|createOptimizationJob|deleteOptimizationJob|getOptimizationJob|listOptimizationJobs|getOptimizationCandidate|listOptimizationCandidates|promoteOptimizationCandidate|createAgentVersionFromCode|updateAgentDetails|updateAgentFromCode|downloadAgentCode)\\w*\\(.*\\)"
+          },
+          "justification": "Beta operations were moved out of AgentsClient/AgentsAsyncClient into the dedicated beta clients: session, optimization-job/candidate and agent-version/code operations were removed from the main client and now live on BetaAgentsClient/BetaAgentsAsyncClient."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.numberOfParametersChanged",
+          "old": {
+            "matcher": "regex",
+            "match": "method .* com\\.azure\\.ai\\.agents\\.Agents(Async)?Client::createAgentVersion\\(.*\\)"
+          },
+          "justification": "Breaking change in beta operation: createAgentVersion is retained on AgentsClient/AgentsAsyncClient but the AgentDefinitionOptInKeys parameter was dropped from its signature. The opt-in key is now sent implicitly, so users are no longer meant to pass opt-in keys directly."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "method .* com\\.azure\\.ai\\.agents\\.Agents(Async)?Client::createAgentVersion\\(.*\\)"
+          },
+          "justification": "Breaking change in beta operation: the createAgentVersion overload taking AgentDefinitionOptInKeys (and AgentBlueprintReference) was removed from AgentsClient/AgentsAsyncClient. The opt-in key is now sent implicitly, so users are no longer meant to pass opt-in keys directly; callers that need to set a blueprint reference should supply the blueprint reference via the CreateAgentVersionInput model instead."
+        },
+        {
+          "ignore": true,
+          "code": "java.class.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "enum com\\.azure\\.ai\\.agents\\.models\\.(AgentDefinitionOptInKeys|FoundryFeaturesOptInKeys)"
+          },
+          "justification": "Breaking change in beta operation: the AgentDefinitionOptInKeys and FoundryFeaturesOptInKeys opt-in enums were removed from the public models package and relocated to implementation.models (made internal). The opt-in key is now sent implicitly, so users are no longer meant to use the opt-in keys directly."
+        },
+        {
+          "ignore": true,
+          "code": "java.class.removed",
+          "old": "class com.azure.ai.agents.models.OptimizationCandidatePagedResult",
+          "justification": "Breaking change in beta operation: OptimizationCandidatePagedResult was removed; listOptimizationCandidates now returns standard PagedIterable<OptimizationCandidate> instead of a custom paged-result wrapper."
+        },
+        {
+          "ignore": true,
+          "code": "java.class.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "class com\\.azure\\.ai\\.projects\\.(DataGenerationJobs|EvaluationTaxonomies|Evaluators|Insights|Models|RedTeams|Routines|Schedules|Skills)(Async)?Client"
+          },
+          "justification": "Beta operations were moved out of the AI Projects client into dedicated beta clients: these sub-clients are removed and their operations now live on the matching BetaEvaluationTaxonomies/BetaEvaluators/BetaInsights/BetaModels/BetaRedTeams/BetaRoutines/BetaSchedules/BetaSkills clients (data generation job operations moved onto BetaDatasetsClient)."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "method com\\.azure\\.ai\\.projects\\.\\w+ com\\.azure\\.ai\\.projects\\.AIProjectClientBuilder::build(DataGenerationJobs|EvaluationTaxonomies|Evaluators|Insights|Models|RedTeams|Routines|Schedules|Skills)(Async)?Client\\(\\)"
+          },
+          "justification": "Beta operations were moved into dedicated beta clients: the AIProjectClientBuilder factory methods for these sub-clients are removed and replaced by the corresponding buildBeta*Client factory methods (and their async variants)."
+        },
+        {
+          "ignore": true,
+          "code": "java.class.removed",
+          "old": "enum com.azure.ai.projects.models.FoundryFeaturesOptInKeys",
+          "justification": "Breaking change in beta operation: the FoundryFeaturesOptInKeys opt-in enum was removed from the public models package and relocated to implementation.models (made internal). The opt-in key is now sent implicitly, so users are no longer meant to use the opt-in keys directly."
+        },
+        {
+          "ignore": true,
+          "code": "java.class.removed",
+          "old": "class com.azure.ai.projects.models.Skill",
+          "justification": "Breaking change in beta operation: the Skill model was removed and replaced by the restructured SkillDetails/SkillVersion (and related) models."
+        },
+        {
+          "ignore": true,
+          "code": "java.method.removed",
+          "old": {
+            "matcher": "regex",
+            "match": "method .* com\\.azure\\.ai\\.projects\\.EvaluationRules(Async)?Client::createOrUpdateEvaluationRule\\(.*FoundryFeaturesOptInKeys\\)"
+          },
+          "justification": "Breaking change in beta operation: EvaluationRulesClient/EvaluationRulesAsyncClient are retained; only the overload of createOrUpdateEvaluationRule that took FoundryFeaturesOptInKeys was removed. The opt-in key is now sent implicitly, so users are no longer meant to pass opt-in keys directly."
+        },
+        {
+          "regex": true,
+          "code": "java\\..*",
+          "old": ".*com\\.azure\\.ai\\.agents\\.Beta\\w*(Async)?Client.*",
+          "justification": "Breaking changes are accepted on the azure-ai-agents beta clients (Beta*Client/Beta*AsyncClient, e.g. BetaAgentsClient, BetaMemoryStoresClient, BetaToolboxesClient). These clients expose preview operations whose API surface is allowed to change until the operations are promoted to a stable client."
+        },
+        {
+          "regex": true,
+          "code": "java\\..*",
+          "old": ".*com\\.azure\\.ai\\.projects\\.Beta\\w*(Async)?Client.*",
+          "justification": "Breaking changes are accepted on the azure-ai-projects beta clients (Beta*Client/Beta*AsyncClient, e.g. BetaDatasetsClient, BetaEvaluatorsClient, BetaModelsClient, BetaRedTeamsClient, BetaSchedulesClient, BetaSkillsClient). These clients expose preview operations whose API surface is allowed to change until the operations are promoted to a stable client."
         }
       ]
     }

sdk/ai/azure-ai-agents/CHANGELOG.md

@@ -4,10 +4,18 @@
 
 ### Features Added
 
+- Added protocol-style `listOptimizationCandidates(String, com.azure.core.http.rest.RequestOptions)` overloads on `AgentsClient` and `AgentsAsyncClient` for listing raw optimization candidate pages as `BinaryData`.
+
 ### Breaking Changes
 
+- Preview operation groups now use beta-prefixed clients built through `AgentsClientBuilder.beta()`: `MemoryStoresClient` / `MemoryStoresAsyncClient` renamed to `BetaMemoryStoresClient` / `BetaMemoryStoresAsyncClient`, `ToolboxesClient` / `ToolboxesAsyncClient` renamed to `BetaToolboxesClient` / `BetaToolboxesAsyncClient`, and preview agent/session operations moved to `BetaAgentsClient` / `BetaAgentsAsyncClient`. `AgentSessionFilesClient` / `AgentSessionFilesAsyncClient` were removed; use the session-file methods on `BetaAgentsClient` / `BetaAgentsAsyncClient` instead.
+- `listOptimizationCandidates` on `AgentsClient` and `AgentsAsyncClient` now returns paged optimization candidates (`PagedIterable<OptimizationCandidate>` / `PagedFlux<OptimizationCandidate>`) instead of `OptimizationCandidatePagedResult` / `Mono<OptimizationCandidatePagedResult>`. The `OptimizationCandidatePagedResult` model was removed. The protocol methods where adjusted accordingly.
+
 ### Bugs Fixed
 
+- Fixed the agent-scoped OpenAI client returned by `AgentsClientBuilder.buildAgentScopedOpenAIClient` and `buildAgentScopedOpenAIAsyncClient` so requests to a hosted-agent endpoint target the correct URL. Previously the request path was duplicated (`.../protocols/openai/openai/responses`) and used an unsupported default `api-version`, causing `400` errors when invoking the OpenAI Responses API or streaming session logs through an agent endpoint. The client now uses the unified Azure URL path mode and sends `api-version=v1`.
+- Fixed OpenAI and Responses clients built from `AgentsClientBuilder` to honor a custom `HttpPipeline` supplied through `pipeline(...)`, preserving custom policies while still adding required preview feature headers for applicable preview clients.
+
 ### Other Changes
 
 ## 2.1.0 (2026-06-01)