Release azure-ai-agents and azure-ai-projects 2.2.0

eng/versioning/version_client.txt

@@ -37,7 +37,7 @@ com.azure:azure-data-sdk-parent;1.3.0;1.3.0
 com.azure:azure-sdk-parent;1.6.0;1.6.0
 com.azure:azure-client-sdk-parent;1.7.0;1.7.0
 com.azure:azure-ai-agents-persistent;1.0.0-beta.2;1.0.0-beta.3
-com.azure:azure-ai-agents;2.1.0;2.2.0-beta.1
+com.azure:azure-ai-agents;2.1.0;2.2.0
 com.azure:azure-ai-anomalydetector;3.0.0-beta.5;3.0.0-beta.6
 com.azure:azure-ai-contentsafety;1.0.18;1.1.0-beta.1
 com.azure:azure-ai-contentunderstanding;1.0.0;1.1.0-beta.3
@@ -53,7 +53,7 @@ com.azure:azure-ai-openai-assistants;1.0.0-beta.5;1.0.0-beta.6
 com.azure:azure-ai-openai-realtime;1.0.0-beta.1;1.0.0-beta.1
 com.azure:azure-ai-openai-stainless;1.0.0-beta.1;1.0.0-beta.1
 com.azure:azure-ai-personalizer;1.0.0-beta.1;1.0.0-beta.2
-com.azure:azure-ai-projects;2.1.0;2.2.0-beta.1
+com.azure:azure-ai-projects;2.1.0;2.2.0
 com.azure:azure-ai-speech-transcription;1.0.0;1.1.0-beta.1
 com.azure:azure-ai-textanalytics;5.5.13;5.6.0-beta.1
 com.azure:azure-ai-textanalytics-perf;1.0.0-beta.1;1.0.0-beta.1

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

@@ -1,15 +1,25 @@
 # Release History
 
-## 2.2.0-beta.1 (Unreleased)
+## 2.2.0 (2026-07-01)
 
 ### 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`.
+- Added convenience methods on `AgentsClient` and `AgentsAsyncClient` to read and write hosted-agent files directly from and to disk using a `String` file path. `downloadAgentCode`, `downloadAgentCodeWithResponse`, and `downloadSessionFileWithResponse` write the downloaded content to the supplied path and accept an optional `overwrite` flag; when the flag is omitted the operation fails if a file already exists at the destination. `uploadSessionFileWithResponse` and the new `CodeFileDetails(String)` constructor read the upload content from a `String` file path.
+- Added a flattened convenience overload `createAgentVersionFromCode(String, HostedAgentDefinition, CodeFileDetails, String, Map)` on `AgentsClient` and `AgentsAsyncClient`. It accepts the hosted-agent definition, code zip, description, and metadata directly instead of a nested `CreateAgentVersionFromCodeContent`, and computes the required `x-ms-code-zip-sha256` value from the code automatically.
+- Added `deleteMemory(String, String)` to `BetaMemoryStoresClient` and `BetaMemoryStoresAsyncClient` for deleting an individual memory item from a memory store.
+- Added `ToolboxesClient` and `ToolboxesAsyncClient` have been moved from `beta` to GA.
+- Added a toolbox-specific tool model hierarchy for toolbox versions, including `ToolboxTool`, `ToolboxToolType`, and related `*ToolboxTool` classes such as `CodeInterpreterToolboxTool`, `OpenApiToolboxTool`, and `ToolboxSearchPreviewToolboxTool`.
+- Added support for additional agent tool types, including `NamespaceTool`, `ToolSearchTool`, and `ReminderPreviewTool`.
+- Updated preview agent optimization support to the V2 preview contract on `BetaAgentsClient` and `BetaAgentsAsyncClient`.
 
 ### 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.
+- Memory store preview clients now use beta-prefixed names built through `AgentsClientBuilder.beta()`: `MemoryStoresClient` / `MemoryStoresAsyncClient` renamed to `BetaMemoryStoresClient` / `BetaMemoryStoresAsyncClient`.
+- `BetaToolboxesClient` / `BetaToolboxesAsyncClient` renamed to `ToolboxesClient` / `ToolboxesAsyncClient` and are now built directly with `AgentsClientBuilder.buildToolboxesClient()` / `buildToolboxesAsyncClient()`. The beta-builder methods for toolboxes were removed.
+- Toolbox version APIs now use `ToolboxTool` models instead of agent `Tool` models; for example, `ToolboxSearchPreviewTool` was replaced by `ToolboxSearchPreviewToolboxTool`.
+- Agent optimization APIs were updated to the V2 preview contract and moved to `BetaAgentsClient` / `BetaAgentsAsyncClient`. `FoundryFeaturesOptInKeys.AGENTS_OPTIMIZATION_V1_PREVIEW` renamed to `AGENTS_OPTIMIZATION_V2_PREVIEW`, and candidate-specific APIs and models such as `CandidateDeployConfig`, `CandidateFileInfo`, `CandidateMetadata`, `CandidateResults`, `PromoteCandidateInput`, and `PromoteCandidateResult` were removed or folded into the updated optimization job models.
+- Hosted-agent session and code-package APIs were simplified by removing `AgentDefinitionOptInKeys` parameters. `AgentSessionFilesClient` / `AgentSessionFilesAsyncClient` were removed; use the session-file methods on `AgentsClient` / `AgentsAsyncClient` instead.
+- Tool and protocol models were aligned with the latest service contract. Notable renames include `NamespaceToolParam` → `NamespaceTool`, `ToolSearchToolParam` → `ToolSearchTool`, `AgentIdentifier` → `OptimizationAgentIdentifier`, and `DatasetRef` → `OptimizationEvaluatorRef`; `AgentProtocol` and `IsolationKeySource` were removed.
 
 ### Bugs Fixed
 
@@ -18,6 +28,9 @@
 
 ### Other Changes
 
+- Added samples demonstrating external agent CRUD (`ExternalAgentSample` / `ExternalAgentAsyncSample`) and memory store item CRUD (`MemoryStoreItemsSample` / `MemoryStoreItemsAsyncSample`).
+- Marked preview clients, models, and methods with `@Beta` annotations so preview surface area is explicit in generated API docs.
+
 ## 2.1.0 (2026-06-01)
 
 ### Features Added

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

@@ -4,6 +4,12 @@ Develop Agents using the Azure AI Foundry platform, leveraging an extensive ecos
 
 The client library uses a single service version `v1` of the AI Foundry [data plane REST APIs](https://aka.ms/azsdk/azure-ai-projects/ga-rest-api-reference).
 
+> [!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`.
+> - 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
 
 Various documentation is available to help you get started
@@ -25,7 +31,7 @@ Various documentation is available to help you get started
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-ai-agents</artifactId>
-    <version>2.1.0</version>
+    <version>2.2.0</version>
 </dependency>
 ```
 [//]: # ({x-version-update-end})
@@ -57,11 +63,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 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.
+- `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.
+- `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.
-- `BetaToolboxesClient` / `BetaToolboxesAsyncClient` **(preview)**: Manage toolboxes and toolbox versions.
+- `ToolboxesClient` / `ToolboxesAsyncClient`: 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.
 
@@ -71,7 +77,7 @@ To access each sub-client you need to use your `AgentsClientBuilder()`. The Agen
 AgentsClientBuilder builder = new AgentsClientBuilder()
                 .credential(new DefaultAzureCredentialBuilder().build())
                 .endpoint(endpoint)
-                .allowPreview(true); // Enables preview response types for non-Beta clients that support them.
+                .allowPreview(true); // Only needed for preview APIs on non-Beta clients that support them.
 
 // Agents sub-clients
 AgentsClient agentsClient = builder.buildAgentsClient();
@@ -85,9 +91,9 @@ ResponsesAsyncClient responsesAsyncClient = builder.buildResponsesAsyncClient();
 // Memory Stores sub-clients (preview).
 BetaMemoryStoresClient memoryStoresClient = builder.beta().buildBetaMemoryStoresClient();
 BetaMemoryStoresAsyncClient memoryStoresAsyncClient = builder.beta().buildBetaMemoryStoresAsyncClient();
-// Toolboxes sub-clients (preview).
-BetaToolboxesClient toolboxesClient = builder.beta().buildBetaToolboxesClient();
-BetaToolboxesAsyncClient toolboxesAsyncClient = builder.beta().buildBetaToolboxesAsyncClient();
+// Toolboxes sub-clients.
+ToolboxesClient toolboxesClient = builder.buildToolboxesClient();
+ToolboxesAsyncClient toolboxesAsyncClient = builder.buildToolboxesAsyncClient();
 ```
 
 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:
@@ -115,11 +121,16 @@ The SDK supports a variety of tools that can be attached to agent definitions. S
 | `AzureAISearchTool` | Azure AI Search |
 | `AzureFunctionTool` | Azure Functions |
 | `BingGroundingTool` | Bing grounding |
+| `CaptureStructuredOutputsTool` | Structured output capture |
 | `CodeInterpreterTool` | Code interpreter |
 | `FileSearchTool` | File search |
 | `FunctionTool` | Custom function calling |
 | `ImageGenTool` | Image generation |
+| `McpTool` | Model Context Protocol (MCP) |
+| `NamespaceTool` | Namespaces for grouping function and custom tools |
 | `OpenApiTool` | OpenAPI spec-based tools |
+| `ToolSearchTool` | Deferred tool search |
+| `WebSearchTool` | Web search |
 
 **Preview tools:**
 
@@ -130,11 +141,10 @@ The SDK supports a variety of tools that can be attached to agent definitions. S
 | `BrowserAutomationPreviewTool` | Browser automation |
 | `ComputerUsePreviewTool` | Computer use |
 | `FabricIqPreviewTool` | Fabric IQ |
-| `McpTool` | Model Context Protocol (MCP) |
 | `MemorySearchPreviewTool` | Memory search |
 | `MicrosoftFabricPreviewTool` | Microsoft Fabric |
+| `ReminderPreviewTool` | Reminder scheduling |
 | `SharepointPreviewTool` | SharePoint grounding |
-| `ToolboxSearchPreviewTool` | Toolbox search |
 | `WebSearchPreviewTool` | Web search |
 | `WorkIqPreviewTool` | Work IQ |
 
@@ -144,6 +154,8 @@ Supported tool classes may also expose optional `name`, `description`, and `tool
 
 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.
 
+APIs annotated with `@Beta` are part of the SDK's preview surface, even when they appear on a non-Beta client. These APIs are subject to breaking changes in future releases and should be used with the same compatibility expectations as other preview features.
+
 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
@@ -155,19 +167,18 @@ AgentsClientBuilder builder = new AgentsClientBuilder()
 AgentsClient agentsClient = builder.buildAgentsClient();
 ```
 
-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`.
+Build clients whose names start with `Beta` from `AgentsClientBuilder.beta()`. These clients 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`.
 
 | Beta sub-client | Automatically populated `Foundry-Features` value |
 |---|---|
-| `BetaAgentsClient` | `HostedAgents=V1Preview,WorkflowAgents=V1Preview,AgentEndpoints=V1Preview,CodeAgents=V1Preview,ExternalAgents=V1Preview,AgentsOptimization=V1Preview` |
+| `BetaAgentsClient` | `WorkflowAgents=V1Preview,ExternalAgents=V1Preview,DraftAgents=V1Preview,AgentsOptimization=V2Preview` |
 | `BetaMemoryStoresClient` | `MemoryStores=V1Preview` |
-| `BetaToolboxesClient` | `Toolboxes=V1Preview` |
 
 The async `Beta*AsyncClient` counterparts follow the same behavior.
 
 ### 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`.
+`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.
 
 ### Using OpenAI's official library
 
@@ -522,9 +533,7 @@ Connect agents to Fabric IQ project connections for enterprise data grounding:
 
 FabricIqPreviewTool fabricIqTool = new FabricIqPreviewTool(fabricIqConnectionId)
     .setServerLabel("fabric_iq")
-    .setRequireApproval("never")
-    .setName("fabric_iq_lookup")
-    .setDescription("Use FabricIQ to answer questions grounded in enterprise data.");
+    .setRequireApproval("never");
 
 ```
 
@@ -618,15 +627,15 @@ See the full sample in [OpenApiWithConnectionSync.java](https://github.com/Azure
 
 #### Toolbox Tools
 
-Toolbox tools are defined in toolbox versions and managed through `BetaToolboxesClient` / `BetaToolboxesAsyncClient`.
+Toolbox tools are defined in toolbox versions and managed through `ToolboxesClient` / `ToolboxesAsyncClient`. Toolbox versions use `ToolboxTool` subclasses rather than agent `Tool` subclasses.
 
 ##### **Toolbox Search (Preview)**
 
-Use `ToolboxSearchPreviewTool` inside a toolbox version to let an agent search the available toolbox tools at runtime:
+Use `ToolboxSearchPreviewToolboxTool` inside a toolbox version to let an agent search the available toolbox tools at runtime:
 
 ```java com.azure.ai.agents.toolboxes.ToolboxSearchToolboxSample.createToolboxSearchToolbox
 
-ToolboxSearchPreviewTool toolboxSearchTool = new ToolboxSearchPreviewTool()
+ToolboxSearchPreviewToolboxTool toolboxSearchTool = new ToolboxSearchPreviewToolboxTool()
     .setName("search_tools")
     .setDescription("Search over available toolbox tools at runtime.");
 
@@ -640,7 +649,7 @@ ToolboxVersionDetails version = toolboxesClient.createToolboxVersion(
 
 System.out.printf("Created toolbox: %s%n", version.getName());
 System.out.printf("Toolbox version: %s%n", version.getVersion());
-for (Tool tool : version.getTools()) {
+for (ToolboxTool tool : version.getTools()) {
     System.out.printf("Tool type: %s%n", tool.getType());
 }
 
@@ -723,7 +732,7 @@ The synchronous session log method returns `IterableStream<SessionLogEvent>`, wh
 
 ```java com.azure.ai.agents.session_logs_sync
 IterableStream<SessionLogEvent> sessionLogs =
-    betaAgentsClient.getSessionLogStream(agentName, agentVersion, sessionId);
+    agentsClient.getSessionLogStream(agentName, agentVersion, sessionId);
 
 int logsRead = 0;
 for (SessionLogEvent event : sessionLogs) {
@@ -741,7 +750,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
-betaAgentsAsyncClient.getSessionLogStream(agentName, agentVersion, sessionId)
+agentsAsyncClient.getSessionLogStream(agentName, agentVersion, sessionId)
     .take(100)
     .doOnNext(event -> System.out.printf("[%s] %s%n", event.getEvent(), event.getData()))
     .blockLast();

sdk/ai/azure-ai-agents/cspell.yaml

@@ -3,6 +3,7 @@ import:
 overrides:
   - filename: "**/sdk/ai/azure-ai-agents/*"
     words:
+    - BYOT
     - dedup
     - gitmcp
     - byot