Azure · jpalvarezl · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
@@ -4,8 +4,13 @@
 
 ### 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
 
 ### Other Changes

@@ -57,11 +57,11 @@ AgentsAsyncClient agentsAsyncClient = new AgentsClientBuilder()
 ``` 
 
 The Agents client library has the following sub-clients which group the different operations that can be performed: 
-- `AgentsClient` / `AgentsAsyncClient`: Perform operations related to agents, such as creating, retrieving, updating, and deleting agents. Also includes hosted-agent sessions, code package operations and preview agent optimization operations.
+- `AgentsClient` / `AgentsAsyncClient`: Perform generally available operations related to agents, such as creating, retrieving, updating, and deleting agents.
+- `BetaAgentsClient` / `BetaAgentsAsyncClient` **(preview)**: Perform preview agent operations, including hosted-agent sessions, session files, code package operations, and preview agent optimization operations.
 - `ResponsesClient` / `ResponsesAsyncClient`: Handle responses operations. See the [OpenAI's Responses API documentation][openai_responses_api_docs] for more information.
-- `MemoryStoresClient` / `MemoryStoresAsyncClient` **(preview)**: Manage memory stores and individual memory items for agents. This operation group requires the `MemoryStores=V1Preview` feature opt-in flag and is automatically set by the SDK on every request.
-- `ToolboxesClient` / `ToolboxesAsyncClient` **(preview)**: Manage toolboxes and toolbox versions. This operation group requires the `Toolboxes=V1Preview` feature opt-in flag and is automatically set by the SDK on every request.
-- `AgentSessionFilesClient` / `AgentSessionFilesAsyncClient` **(preview)**: Work with files in an agent session, including uploading, downloading, listing, and deleting session files.
+- `BetaMemoryStoresClient` / `BetaMemoryStoresAsyncClient` **(preview)**: Manage memory stores and individual memory items for agents.
+- `BetaToolboxesClient` / `BetaToolboxesAsyncClient` **(preview)**: Manage toolboxes and toolbox versions.
 
 Conversation operations are accessed through the [OpenAI Official Java SDK][openai_java_sdk]'s `ConversationService`. See the [OpenAI's Conversation API documentation][openai_conversations_api_docs] for more information.
 
@@ -70,30 +70,38 @@ To access each sub-client you need to use your `AgentsClientBuilder()`. The Agen
 ```java
 AgentsClientBuilder builder = new AgentsClientBuilder()
                 .credential(new DefaultAzureCredentialBuilder().build())
-                .endpoint(endpoint);
+                .endpoint(endpoint)
+                .allowPreview(true); // Enables preview response types for non-Beta clients that support them.
 
 // Agents sub-clients
 AgentsClient agentsClient = builder.buildAgentsClient();
 AgentsAsyncClient agentsAsyncClient = builder.buildAgentsAsyncClient();
+// Beta* clients automatically opt in to their preview service area.
+BetaAgentsClient betaAgentsClient = builder.beta().buildBetaAgentsClient();
+BetaAgentsAsyncClient betaAgentsAsyncClient = builder.beta().buildBetaAgentsAsyncClient();
 // Responses sub-clients.
 ResponsesClient responsesClient = builder.buildResponsesClient();
 ResponsesAsyncClient responsesAsyncClient = builder.buildResponsesAsyncClient();
 // Memory Stores sub-clients (preview).
-MemoryStoresClient memoryStoresClient = builder.buildMemoryStoresClient();
-MemoryStoresAsyncClient memoryStoresAsyncClient = builder.buildMemoryStoresAsyncClient();
-//Toolboxes sub-clients (preview).
-ToolboxesClient toolboxesClient = builder.buildToolboxesClient();
-ToolboxesAsyncClient toolboxesAsyncClient = builder.buildToolboxesAsyncClient();
-// Agent Session Files sub-clients (preview).
-AgentSessionFilesClient agentSessionFilesClient = builder.buildAgentSessionFilesClient();
-AgentSessionFilesAsyncClient agentSessionFilesAsyncClient = builder.buildAgentSessionFilesAsyncClient();
+BetaMemoryStoresClient memoryStoresClient = builder.beta().buildBetaMemoryStoresClient();
+BetaMemoryStoresAsyncClient memoryStoresAsyncClient = builder.beta().buildBetaMemoryStoresAsyncClient();
+// Toolboxes sub-clients (preview).
+BetaToolboxesClient toolboxesClient = builder.beta().buildBetaToolboxesClient();
+BetaToolboxesAsyncClient toolboxesAsyncClient = builder.beta().buildBetaToolboxesAsyncClient();
 ```
 
 The [OpenAI Official Java SDK][openai_java_sdk] is imported transitively and can be built directly from the `AgentsClientBuilder`. Use it to access conversation operations and other OpenAI services:
 
 ```java
 OpenAIClient openAIClient = builder.buildOpenAIClient();
 OpenAIClientAsync openAIAsyncClient = builder.buildOpenAIAsyncClient();
+
+// OpenAI SDK ResponseService accessed from ResponsesClient
+ResponsesClient responsesClient = builder.buildResponsesClient();
+ResponseService responseService = responsesClient.getResponseService();
+
+// OpenAI SDK ConversationService accessed from OpenAIClient
+ConversationService conversationService = openAIClient.conversations();
 ```
 
 ### Agent tools
@@ -132,41 +140,34 @@ The SDK supports a variety of tools that can be attached to agent definitions. S
 
 Supported tool classes may also expose optional `name`, `description`, and `toolConfigs` properties for user-defined labels and per-tool configuration.
 
-### Experimental features and opt-in flags
+### Preview operation groups and beta clients
 
-Some features require an opt-in via the `Foundry-Features` HTTP header. The SDK provides two enums for these flags:
+Several operation groups in the Agents client library expose **preview** service features. These features require the `Foundry-Features` HTTP header. The SDK populates that header for you; you do not need to set the header value manually.
 
-- **`AgentDefinitionOptInKeys`** — Used when creating or updating agents. Passed as a parameter to `createAgent`, `updateAgent`, `createAgentVersion`, and related methods. Available keys: `HOSTED_AGENTS_V1_PREVIEW`, `WORKFLOW_AGENTS_V1_PREVIEW`, `AGENT_ENDPOINT_V1_PREVIEW`, `CODE_AGENTS_V1_PREVIEW`, `EXTERNAL_AGENTS_V1_PREVIEW`.
-- **`FoundryFeaturesOptInKeys`** — Defines all known opt-in keys, including: `EVALUATIONS_V1_PREVIEW`, `SCHEDULES_V1_PREVIEW`, `RED_TEAMS_V1_PREVIEW`, `INSIGHTS_V1_PREVIEW`, `MEMORY_STORES_V1_PREVIEW`, `ROUTINES_V1_PREVIEW`, `TOOLBOXES_V1_PREVIEW`, `SKILLS_V1_PREVIEW`, `DATA_GENERATION_JOBS_V1_PREVIEW`, `MODELS_V1_PREVIEW`, `AGENTS_OPTIMIZATION_V1_PREVIEW`.
-
-> **Note:** The `MemoryStoresClient` automatically sets the `MemoryStores=V1Preview` opt-in flag on every request. The `ToolboxesClient` automatically sets the `Toolboxes=V1Preview` opt-in flag on every request. Agent optimization methods accept `FoundryFeaturesOptInKeys.AGENTS_OPTIMIZATION_V1_PREVIEW`; code-based hosted agents and external agents use the corresponding `AgentDefinitionOptInKeys` values.
+Use `AgentsClientBuilder.allowPreview(true)` when building non-Beta clients that support preview service behavior. For example, `AgentsClient` and `AgentsAsyncClient` use this builder setting to allow the service to return preview response types:
 
 ```java
-// OpenAI SDK ResponseService accessed from ResponsesClient
-ResponsesClient responsesClient = builder.buildResponsesClient();
-ResponseService responseService = responsesClient.getResponseService();
+AgentsClientBuilder builder = new AgentsClientBuilder()
+    .credential(new DefaultAzureCredentialBuilder().build())
+    .endpoint(endpoint)
+    .allowPreview(true);
 
-// OpenAI SDK ConversationService accessed from OpenAIClient
-OpenAIClient openAIClient = builder.buildOpenAIClient();
-ConversationService conversationService = openAIClient.conversations();
+AgentsClient agentsClient = builder.buildAgentsClient();
 ```
 
-### Preview hosted-agent capabilities
+Clients whose names start with `Beta` always opt in to their corresponding preview service area. Requests sent by these clients automatically include the appropriate `Foundry-Features` header, and their APIs can send or return preview/beta request and response types. You do not need to call `allowPreview(true)` to use a `Beta*Client`.
 
-Hosted-agent previews are exposed on `AgentsClient` and `AgentsAsyncClient`. The following capabilities require the corresponding opt-in flag when you create or modify preview resources:
-
-| Capability | APIs and models | Opt-in flag |
-|---|---|---|
-| Code-based hosted agents | `createAgentVersionFromCode`, `updateAgentFromCode`, `downloadAgentCode`, `CodeConfiguration`, `CodeDependencyResolution` | `AgentDefinitionOptInKeys.CODE_AGENTS_V1_PREVIEW` |
-| External agents | `ExternalAgentDefinition`, `AgentKind.EXTERNAL` | `AgentDefinitionOptInKeys.EXTERNAL_AGENTS_V1_PREVIEW` |
-| Agent endpoints and sessions | `AgentEndpointConfig`, `createSession`, `listSessions`, `stopSession`, `AgentSessionFilesClient` | `AgentDefinitionOptInKeys.AGENT_ENDPOINT_V1_PREVIEW` |
-| Agent optimization | `createOptimizationJob`, `listOptimizationJobs`, `listOptimizationCandidates`, `promoteOptimizationCandidate` | `FoundryFeaturesOptInKeys.AGENTS_OPTIMIZATION_V1_PREVIEW` |
+| Beta sub-client | Automatically populated `Foundry-Features` value |
+|---|---|
+| `BetaAgentsClient` | `HostedAgents=V1Preview,WorkflowAgents=V1Preview,AgentEndpoints=V1Preview,CodeAgents=V1Preview,ExternalAgents=V1Preview,AgentsOptimization=V1Preview` |
+| `BetaMemoryStoresClient` | `MemoryStores=V1Preview` |
+| `BetaToolboxesClient` | `Toolboxes=V1Preview` |
 
-For code-based hosted agents, `CodeConfiguration.getContentSha256()` returns the service-computed SHA-256 hash of the uploaded code package. Session APIs that need per-user isolation can use overloads that accept `userIsolationKey`, or set the `x-ms-user-isolation-key` header through `RequestOptions`. To delete hosted agents or agent versions that still have active sessions, add the `force=true` query parameter through `RequestOptions` when calling the corresponding `deleteAgentWithResponse` or `deleteAgentVersionWithResponse` method.
+The async `Beta*AsyncClient` counterparts follow the same behavior.
 
 ### Memory item management
 
-`MemoryStoresClient` and `MemoryStoresAsyncClient` manage memory stores and individual memory items. In addition to store-level operations, use `createMemory`, `updateMemory`, `listMemories`, `getMemory`, and `deleteMemory` to manage individual memories. `ListMemoriesOptions` supports filtering by scope and `MemoryItemKind`, including `MemoryItemKind.PROCEDURAL`.
+`BetaMemoryStoresClient` and `BetaMemoryStoresAsyncClient` manage memory stores and individual memory items. In addition to store-level operations, use `createMemory`, `updateMemory`, `listMemories`, `getMemory`, and `deleteMemory` to manage individual memories. `ListMemoriesOptions` supports filtering by scope and `MemoryItemKind`, including `MemoryItemKind.PROCEDURAL`.
 
 ### Using OpenAI's official library
 
@@ -617,7 +618,7 @@ See the full sample in [OpenApiWithConnectionSync.java](https://github.com/Azure
 
 #### Toolbox Tools
 
-Toolbox tools are defined in toolbox versions and managed through `ToolboxesClient` / `ToolboxesAsyncClient`.
+Toolbox tools are defined in toolbox versions and managed through `BetaToolboxesClient` / `BetaToolboxesAsyncClient`.
 
 ##### **Toolbox Search (Preview)**
 
@@ -722,7 +723,7 @@ The synchronous session log method returns `IterableStream<SessionLogEvent>`, wh
 
 ```java com.azure.ai.agents.session_logs_sync
 IterableStream<SessionLogEvent> sessionLogs =
-    agentsClient.getSessionLogStream(agentName, agentVersion, sessionId);
+    betaAgentsClient.getSessionLogStream(agentName, agentVersion, sessionId);
 
 int logsRead = 0;
 for (SessionLogEvent event : sessionLogs) {
@@ -740,7 +741,7 @@ for (SessionLogEvent event : sessionLogs) {
 The asynchronous session log method returns `Flux<SessionLogEvent>`, integrating naturally with Reactor pipelines:
 
 ```java com.azure.ai.agents.session_logs_async
-agentsAsyncClient.getSessionLogStream(agentName, agentVersion, sessionId)
+betaAgentsAsyncClient.getSessionLogStream(agentName, agentVersion, sessionId)
     .take(100)
     .doOnNext(event -> System.out.printf("[%s] %s%n", event.getEvent(), event.getData()))
     .blockLast();

@@ -3,24 +3,8 @@
 <!-- This file is generated by the /eng/scripts/linting_suppression_generator.py script. -->
 
 <suppressions>
-  <suppress files="com.azure.ai.agents.models.InvokeAzureAgentWorkflowActionOutputItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesAssistantMessageItemParam.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesAssistantMessageItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesDeveloperMessageItemParam.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesDeveloperMessageItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesMessageItemParam.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesMessageItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesSystemMessageItemParam.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesSystemMessageItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesUserMessageItemParam.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.ResponsesUserMessageItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
-  <suppress files="com.azure.ai.agents.models.WorkflowActionOutputItemResource.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
   <suppress files="com.azure.ai.agents.ResponsesAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
   <suppress files="com.azure.ai.agents.ResponsesClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
-  <suppress files="com.azure.ai.agents.ConversationsAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
-  <suppress files="com.azure.ai.agents.ConversationsClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
-  <suppress files="com.azure.ai.agents.MemoryStoresAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
-  <suppress files="com.azure.ai.agents.MemoryStoresClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
   <suppress files="com.azure.ai.agents.AgentsClientBuilder.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
   <suppress files="com.azure.ai.agents.AgentsAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
   <suppress files="com.azure.ai.agents.AgentsClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
@@ -31,5 +15,8 @@
   <suppress files="com.azure.ai.agents.implementation.MultipartFormDataHelper.java" checks="io.clientcore.linting.extensions.checkstyle.checks.EnforceFinalFieldsCheck" />
   <suppress files="com.azure.ai.agents.AgentsClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ServiceClientCheck" />
   <suppress files="com.azure.ai.agents.AgentsAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ServiceClientCheck" />
-  <suppress files="com.azure.ai.agents.models.DatasetItem.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
+  <suppress files="com.azure.ai.agents.BetaMemoryStoresAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
+  <suppress files="com.azure.ai.agents.BetaMemoryStoresClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ExternalDependencyExposedCheck" />
+  <suppress files="com.azure.ai.agents.BetaAgentsClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ServiceClientCheck" />
+  <suppress files="com.azure.ai.agents.BetaAgentsAsyncClient.java" checks="io.clientcore.linting.extensions.checkstyle.checks.ServiceClientCheck" />
 </suppressions>