Samples for 2.5.0

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

@@ -10,6 +10,12 @@
 
 ### Other Changes
 
+- Added sync and async conversation samples demonstrating the `x-ms-user-identity` header with the OpenAI ConversationService.
+- Added sync and async samples for draft agent versions, reminder toolbox tools, hosted-agent enable/disable,
+  advanced memory-store workflows, and agent optimization.
+- Improved the Fabric IQ sync and async samples with configurable agent names, readable response and annotation
+  output, and reliable asynchronous cleanup.
+
 ## 2.4.0 (2026-08-19)
 
 ### Features Added

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

@@ -7,7 +7,7 @@ The client library uses a single service version `v1` of the AI Foundry [data pl
 > [!IMPORTANT]
 > **Preview and beta features**
 > - Build `Beta*Client` and `Beta*AsyncClient` instances through `AgentsClientBuilder.beta()`. These clients automatically opt in to their preview service area; you do not need `allowPreview(true)` for them.
-> - Use `AgentsClientBuilder.allowPreview(true)` only when calling preview APIs on non-Beta clients, such as preview hosted-agent sessions, session files, and code package operations on `AgentsClient` / `AgentsAsyncClient`.
+> - Use `AgentsClientBuilder.allowPreview(true)` when calling preview APIs on non-Beta clients, such as draft agent versions, hosted-agent sessions, session files, and code package operations on `AgentsClient` / `AgentsAsyncClient`.
 > - Classes and methods annotated with `@Beta` are preview API surface and may change in future releases. See [Preview operation groups and beta clients](#preview-operation-groups-and-beta-clients) for details.
 
 ## Documentation
@@ -63,7 +63,7 @@ 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. When `allowPreview(true)` is configured, these clients can also use preview hosted-agent sessions, session files, and code package operations.
+- `AgentsClient` / `AgentsAsyncClient`: Perform operations related to agents, such as creating, retrieving, updating, and deleting agents. When `allowPreview(true)` is configured, these clients can also use preview draft versions, hosted-agent sessions, session files, and code package operations.
 - `BetaAgentsClient` / `BetaAgentsAsyncClient` **(preview)**: Perform preview agent optimization operations.
 - `ResponsesClient` / `ResponsesAsyncClient`: Handle responses operations. See the [OpenAI's Responses API documentation][openai_responses_api_docs] for more information.
 - `BetaMemoryStoresClient` / `BetaMemoryStoresAsyncClient` **(preview)**: Manage memory stores and individual memory items for agents.
@@ -110,6 +110,16 @@ ResponseService responseService = responsesClient.getResponseService();
 ConversationService conversationService = openAIClient.conversations();
 ```
 
+### Agent version drafts
+
+Draft agent versions are preview candidates that are not promoted to the agent's latest released version. Create one with
+`CreateAgentVersionInput.setDraft(true)`, and pass `true` as the `includeDrafts` argument to
+`listAgentVersions` when you need to list draft versions. Build the non-Beta client with
+`allowPreview(true)` to opt in to the `DraftAgents=V1Preview` service feature.
+
+See the full samples in [AgentDraftSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/agents/AgentDraftSample.java)
+and [AgentDraftAsyncSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/agents/AgentDraftAsyncSample.java).
+
 ### Agent tools
 
 The SDK supports a variety of tools that can be attached to agent definitions. Some tools are generally available, while others are in **preview** and may change in future releases.
@@ -176,10 +186,21 @@ Build clients whose names start with `Beta` from `AgentsClientBuilder.beta()`. T
 
 The async `Beta*AsyncClient` counterparts follow the same behavior.
 
+### Agent optimization
+
+The preview `BetaAgentsClient` and `BetaAgentsAsyncClient` can create and monitor agent optimization jobs. These jobs
+evaluate an agent against a registered dataset and evaluator, then return scored candidates for instructions, skills,
+tools, or model improvements. Agent optimization is currently in preview and requires an allow-listed Foundry project.
+See [Agent optimizer in Foundry Agent Service][agent_optimizer_overview] for the service workflow and the complete
+examples in [AgentOptimizationSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/optimization/AgentOptimizationSample.java)
+and [AgentOptimizationAsyncSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/optimization/AgentOptimizationAsyncSample.java).
+
 ### Memory item management
 
 `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`. See `MemoryStoreItemsSample` and `MemoryStoreItemsAsyncSample` for complete examples.
 
+For conversational memory workflows, use `beginUpdateMemories` to extract memories from conversation items, `searchMemories` to retrieve relevant memories, and `deleteScope` to remove all memories for a scope. See `MemoryStoreAdvancedSample` and `MemoryStoreAdvancedAsyncSample` for complete synchronous and asynchronous examples.
+
 ### Using OpenAI's official library
 
 If you prefer using the [OpenAI official Java client library][openai_java_sdk] instead, you can do so by including that dependency in your project instead and following the instructions in the linked repository. Additionally, you will have to set up your `OpenAIClient` as shown below:
@@ -244,6 +265,8 @@ conversationsClient.items().create(
 );
 ```
 
+To scope conversation operations to a delegated end user, set `FOUNDRY_USER_IDENTITY` to an opaque application-generated value and apply it as the `x-ms-user-identity` header. The caller must have the `agents/endpoints/UserIdentityImpersonation/action` RBAC permission. See the sync [UserIdentityConversation.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/conversations/UserIdentityConversation.java) and async [UserIdentityConversationAsync.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/conversations/UserIdentityConversationAsync.java) samples.
+
 #### Text generation with Responses
 
 And the final step that ties everything together, we pass the `AgentReference` and the `conversation.id()` as parameters for the `Response` creation:
@@ -525,19 +548,42 @@ See the full sample in [FabricSync.java](https://github.com/Azure/azure-sdk-for-
 
 ---
 
-##### **Fabric IQ (Preview)**
+##### **Fabric IQ (Preview)** ([documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/fabric-iq))
 
 Connect agents to Fabric IQ project connections for enterprise data grounding:
 
 ```java com.azure.ai.agents.define_fabric_iq
 
 FabricIqPreviewTool fabricIqTool = new FabricIqPreviewTool(fabricIqConnectionId)
-    .setServerLabel("fabric_iq")
+    .setServerLabel("fabric-iq-tool")
     .setRequireApproval("never");
 
 ```
 
-See the full sample in [FabricIQSync.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/tools/FabricIQSync.java).
+The samples use `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_NAME`, and the fully qualified
+`FABRIC_IQ_PROJECT_CONNECTION_ID`. `FOUNDRY_AGENT_NAME` and `FABRIC_IQ_USER_INPUT` are optional.
+The response text and any returned annotations are printed before the temporary agent version is deleted.
+
+See the full samples in [FabricIQSync.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/tools/FabricIQSync.java)
+and [FabricIQAsync.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/tools/FabricIQAsync.java).
+
+---
+
+##### **Work IQ (Preview)** ([documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/work-iq))
+
+Ground agent responses in the signed-in user's Microsoft 365 work context through a Work IQ project connection:
+
+```java com.azure.ai.agents.define_work_iq
+// Create a Work IQ tool with a fully qualified project connection resource ID
+WorkIqPreviewTool workIqTool = new WorkIqPreviewTool(workIqConnectionId);
+```
+
+Set `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL_NAME`, and `WORK_IQ_PROJECT_CONNECTION_ID` before running the
+sample. `FOUNDRY_AGENT_NAME` and `WORK_IQ_USER_INPUT` are optional. Work IQ uses delegated authentication and
+honors the signed-in user's Microsoft 365 permissions.
+
+See the full samples in [WorkIQSync.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/tools/WorkIQSync.java)
+and [WorkIQAsync.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/tools/WorkIQAsync.java).
 
 ---
 
@@ -657,6 +703,32 @@ for (ToolboxTool tool : version.getTools()) {
 
 See the full sample in [ToolboxSearchToolboxSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/toolboxes/ToolboxSearchToolboxSample.java).
 
+##### **Reminder (preview)**
+
+The Reminder tool lets a hosted agent schedule itself to run again at a future time. It is connectionless and is available only to hosted agents, not prompt agents.
+
+```java com.azure.ai.agents.toolboxes.ReminderPreviewToolboxSample.createReminderToolbox
+
+ReminderPreviewToolboxTool reminderTool = new ReminderPreviewToolboxTool()
+    .setName("schedule_reminder")
+    .setDescription("Schedule a reminder that re-invokes this agent at a future time.");
+
+ToolboxVersionDetails version = toolboxesClient.createToolboxVersion(
+    toolboxName,
+    Collections.<ToolboxTool>singletonList(reminderTool),
+    "Built-in reminder tool for a self-scheduling agent.",
+    null,
+    null,
+    null);
+
+System.out.printf("Created toolbox: %s%n", version.getName());
+System.out.printf("Toolbox version: %s%n", version.getVersion());
+System.out.printf("Tool type: %s%n", version.getTools().get(0).getType());
+
+```
+
+See the full samples in [ReminderPreviewToolboxSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/toolboxes/ReminderPreviewToolboxSample.java) and [ReminderPreviewToolboxAsyncSample.java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/toolboxes/ReminderPreviewToolboxAsyncSample.java).
+
 ---
 
 ### Streaming responses
@@ -873,3 +945,4 @@ For details on contributing to this repository, see the [contributing guide](htt
 [openai_conversations_api_docs]: https://platform.openai.com/docs/api-reference/conversations
 [logLevels]: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/core/azure-core/src/main/java/com/azure/core/util/logging/LogLevel.java
 [performance_tuning]: https://github.com/Azure/azure-sdk-for-java/blob/main/docs/performance-tuning.md
+[agent_optimizer_overview]: https://learn.microsoft.com/azure/foundry/agents/concepts/agent-optimizer-overview

sdk/ai/azure-ai-agents/src/samples/java/com/azure/ai/agents/agents/AgentDraftAsyncSample.java

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.ai.agents.agents;
+
+import com.azure.ai.agents.AgentsAsyncClient;
+import com.azure.ai.agents.AgentsClientBuilder;
+import com.azure.ai.agents.models.AgentDetails;
+import com.azure.ai.agents.models.AgentVersionDetails;
+import com.azure.ai.agents.models.CreateAgentVersionInput;
+import com.azure.ai.agents.models.PromptAgentDefinition;
+import com.azure.core.util.Configuration;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+import reactor.core.publisher.Mono;
+
+import java.util.UUID;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * Sample demonstrating how to create and inspect draft agent versions using the asynchronous
+ * {@link AgentsAsyncClient}.
+ *
+ * <p>Draft agent versions are a preview feature. They are not promoted to the agent's latest released version and
+ * are excluded from version listings unless drafts are explicitly included.</p>
+ *
+ * <p>Before running the sample, set the {@code FOUNDRY_PROJECT_ENDPOINT} and {@code FOUNDRY_MODEL_NAME} environment
+ * variables.</p>
+ */
+public class AgentDraftAsyncSample {
+    public static void main(String[] args) {
+        String endpoint = Configuration.getGlobalConfiguration().get("FOUNDRY_PROJECT_ENDPOINT");
+        String model = Configuration.getGlobalConfiguration().get("FOUNDRY_MODEL_NAME");
+
+        AgentsAsyncClient agentsAsyncClient = new AgentsClientBuilder()
+            .credential(new DefaultAzureCredentialBuilder().build())
+            .endpoint(endpoint)
+            .allowPreview(true)
+            .buildAgentsAsyncClient();
+
+        String agentName = "java-draft-agent-" + UUID.randomUUID();
+        AtomicBoolean agentCreated = new AtomicBoolean();
+
+        Mono<Void> workflow = agentsAsyncClient.createAgentVersion(agentName,
+                new CreateAgentVersionInput(new PromptAgentDefinition(model)
+                    .setInstructions("You are a prompt agent that gives helpful answers."))
+                    .setDescription("Released agent version created by the draft sample."))
+            .doOnNext(releaseVersion -> {
+                agentCreated.set(true);
+                System.out.printf("Agent created: name: %s, version: %s%n",
+                    releaseVersion.getName(), releaseVersion.getVersion());
+            })
+            .then(agentsAsyncClient.getAgent(agentName))
+            .doOnNext(AgentDraftAsyncSample::printLatestVersion)
+            .then(agentsAsyncClient.createAgentVersion(agentName,
+                new CreateAgentVersionInput(new PromptAgentDefinition(model)
+                    .setInstructions("You are a prompt agent that is still being tested."))
+                    .setDescription("Draft agent version created by the draft sample.")
+                    .setDraft(true)))
+            .doOnNext(draftVersion -> {
+                System.out.printf("Agent draft created: name: %s, version: %s, is draft: %s%n",
+                    draftVersion.getName(), draftVersion.getVersion(), isDraft(draftVersion));
+            })
+            .then(agentsAsyncClient.getAgent(agentName))
+            .doOnNext(agent -> System.out.printf(
+                "The latest released version of agent \"%s\" is still %s.%n",
+                agent.getName(), agent.getVersions().getLatest().getVersion()))
+            .then(agentsAsyncClient.listAgentVersions(agentName)
+                .doOnNext(version -> printVersion("Released", version))
+                .then())
+            .then(agentsAsyncClient.listAgentVersions(agentName, null, null, null, null, true)
+                .doOnNext(version -> printVersion("All", version))
+                .then());
+
+        workflow
+            .onErrorResume(error -> cleanup(agentsAsyncClient, agentName, agentCreated).then(Mono.error(error)))
+            .then(Mono.defer(() -> cleanup(agentsAsyncClient, agentName, agentCreated)))
+            .block();
+    }
+
+    private static Mono<Void> cleanup(AgentsAsyncClient agentsAsyncClient, String agentName,
+        AtomicBoolean agentCreated) {
+        if (!agentCreated.get()) {
+            return Mono.empty();
+        }
+        return agentsAsyncClient.deleteAgent(agentName)
+            .doOnSuccess(unused -> System.out.printf("Agent deleted (name: %s)%n", agentName));
+    }
+
+    private static void printLatestVersion(AgentDetails agent) {
+        System.out.printf("The latest released version of agent \"%s\" is %s.%n",
+            agent.getName(), agent.getVersions().getLatest().getVersion());
+    }
+
+    private static void printVersion(String collection, AgentVersionDetails version) {
+        System.out.printf("%s version: %s (is draft: %s)%n", collection, version.getVersion(), isDraft(version));
+    }
+
+    private static boolean isDraft(AgentVersionDetails version) {
+        return Boolean.TRUE.equals(version.isDraft());
+    }
+}