Azure/azure-sdk-for-java com.azure+azure-ai-agents_2.2.0

on GitHub

2.2.0 (2026-07-01)

Features Added

• 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

• 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

• 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

• 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.