diff --git a/sdk/ai/azure-ai-agents/REVAPI_REPORT.md b/sdk/ai/azure-ai-agents/REVAPI_REPORT.md new file mode 100644 index 000000000000..0cef6214d38e --- /dev/null +++ b/sdk/ai/azure-ai-agents/REVAPI_REPORT.md @@ -0,0 +1,56 @@ +# RevAPI failure report + +Baseline command: + +```powershell +mvn clean install +``` + +Result: the build failed in `org.revapi:revapi-maven-plugin:0.15.1:check` while comparing +`com.azure:azure-ai-agents:2.1.0` against `2.2.0-beta.1`. Tests and coverage completed before the +RevAPI check. + +## Version resolution + +RevAPI resolves the old artifact from Maven's active repositories because this package does not set +`revapi.oldArtifacts` or `revapi.oldVersion`. The inherited parent config sets +`^\d+\.\d+\.\d+$`, so `RELEASE` resolves to the latest stable version +matching that pattern and excludes beta versions. In this build, that resolved to +`com.azure:azure-ai-agents:2.1.0`; the new artifact is the local project version, +`2.2.0-beta.1`. + +## Beta-annotated surface + +The 2.1.0 source jar contains no `@Beta` annotations, including on removed classes. The RevAPI +findings below are on types that are `@Beta(warningText = "Preview API. AgentsOptimization=V2Preview")` +in the current source, but the corresponding 2.1.0 API was not beta-annotated. + +| Current beta type | RevAPI changes | +| --- | --- | +| `OptimizationCandidate` | Removed `getConfig()`, `getPassRate()`, `getTaskScores()`, and `isParetoOptimal()`. | +| `OptimizationJob` | Public no-arg constructor visibility increased; removed `getDataset()`. | +| `OptimizationJobInputs` | Constructor changed from `(AgentIdentifier, DatasetRef)` to `(OptimizationAgentIdentifier, OptimizationDatasetInput, List)`; `getAgent()` return type changed; `getEvaluators()` list element type changed; removed train/validation dataset reference getters and affected setters. | +| `OptimizationJobProgress` | Removed `getCurrentIteration()`. | +| `OptimizationJobResult` | `getBaseline()` and `getBest()` now return `String` instead of `OptimizationCandidate`; removed `getOptions()`, `getWarnings()`, and `isAllTargetAttributesFailed()`. | +| `OptimizationOptions` | Removed `getMaxIterations()` and `setMaxIterations(Integer)`. | + +## Other non-beta API changes + +These RevAPI failures are outside the beta-annotated surface: + +| Area | RevAPI changes | +| --- | --- | +| `AgentsClient` / `AgentsAsyncClient` | `deleteSession`, `downloadAgentCode`, `getSession`, and `listSessions` signatures changed by removing the `AgentDefinitionOptInKeys` parameter. | +| Removed models | `AgentIdentifier`, `AgentProtocol`, `CandidateDeployConfig`, `CandidateFileInfo`, `CandidateMetadata`, `CandidateResults`, `DatasetInfo`, `DatasetRef`, `OptimizationAgentDefinition`, `OptimizationTaskResult`, `PromoteCandidateInput`, and `PromoteCandidateResult` were removed. None were `@Beta` in 2.1.0. | +| `ProtocolVersionRecord` | Constructor parameter and `getProtocol()` return type changed from `AgentProtocol` to `AgentEndpointProtocol`. | + +## Least-verbose exception shape + +The concise exception set is four grouped RevAPI rules: + +1. `java.method.numberOfParametersChanged` for the affected `AgentsClient` / `AgentsAsyncClient` methods. +2. `java.class.removed` for the removed optimization/protocol model names. +3. A regex covering optimization model method removals, return-type changes, constructor parameter changes, and visibility increase. +4. A regex covering `ProtocolVersionRecord` parameter/return type changes. + +Those exceptions are in `revapi.json` and appended from `pom.xml` so the inherited RevAPI config remains active. diff --git a/sdk/ai/azure-ai-agents/pom.xml b/sdk/ai/azure-ai-agents/pom.xml index d4cc6ac15e96..d25b13858730 100644 --- a/sdk/ai/azure-ai-agents/pom.xml +++ b/sdk/ai/azure-ai-agents/pom.xml @@ -112,6 +112,17 @@ + + org.revapi + revapi-maven-plugin + + + + ${project.basedir}/revapi.json + + + + diff --git a/sdk/ai/azure-ai-agents/revapi.json b/sdk/ai/azure-ai-agents/revapi.json new file mode 100644 index 000000000000..e3f8957a4ca0 --- /dev/null +++ b/sdk/ai/azure-ai-agents/revapi.json @@ -0,0 +1,38 @@ +[ + { + "extension": "revapi.differences", + "configuration": { + "ignore": true, + "differences": [ + { + "code": "java.method.numberOfParametersChanged", + "old": { + "matcher": "regex", + "match": "method .* com\\.azure\\.ai\\.agents\\.Agents(Async)?Client::(deleteSession|downloadAgentCode|getSession|listSessions)\\(.*\\)" + }, + "justification": "Breaking change in beta operation: session and hosted-agent code methods no longer expose AgentDefinitionOptInKeys. The opt-in key is now sent implicitly and userIsolationKey/agentVersion are the public parameters." + }, + { + "code": "java.class.removed", + "old": { + "matcher": "regex", + "match": "class com\\.azure\\.ai\\.agents\\.models\\.(AgentIdentifier|AgentProtocol|CandidateDeployConfig|CandidateFileInfo|CandidateMetadata|CandidateResults|DatasetInfo|DatasetRef|OptimizationAgentDefinition|OptimizationTaskResult|PromoteCandidateInput|PromoteCandidateResult)" + }, + "justification": "Breaking change in beta operation: optimization and agent protocol models were renamed, restructured, or removed to align with the current service contract." + }, + { + "regex": true, + "code": "java\\.method\\.(numberOfParametersChanged|removed|returnTypeChanged|returnTypeTypeParametersChanged|visibilityIncreased)", + "old": "method .* com\\.azure\\.ai\\.agents\\.models\\.Optimization(Candidate|Job|JobInputs|JobProgress|JobResult|Options)::.*", + "justification": "Breaking change in beta operation: optimization models were restructured to align with the current AgentsOptimization preview contract." + }, + { + "regex": true, + "code": "java\\.method\\.(parameterTypeChanged|returnTypeChanged)", + "old": "(method|parameter) .* com\\.azure\\.ai\\.agents\\.models\\.ProtocolVersionRecord::.*", + "justification": "AgentProtocol was renamed to AgentEndpointProtocol to align protocol-version records with the current service contract." + } + ] + } + } +] diff --git a/sdk/ai/azure-ai-projects/REVAPI_REPORT.md b/sdk/ai/azure-ai-projects/REVAPI_REPORT.md new file mode 100644 index 000000000000..18e179e56373 --- /dev/null +++ b/sdk/ai/azure-ai-projects/REVAPI_REPORT.md @@ -0,0 +1,51 @@ +# RevAPI failure report + +Baseline command: + +```powershell +mvn clean install +``` + +Result: the build failed in `org.revapi:revapi-maven-plugin:0.15.1:check` while comparing +`com.azure:azure-ai-projects:2.1.0` against `2.2.0-beta.1`. Tests and coverage completed before the +RevAPI check. + +## Version resolution + +RevAPI resolves the old artifact from Maven's active repositories because this package does not set +`revapi.oldArtifacts` or `revapi.oldVersion`. The inherited parent config sets +`^\d+\.\d+\.\d+$`, so `RELEASE` resolves to the latest stable version +matching that pattern and excludes beta versions. In this build, that resolved to +`com.azure:azure-ai-projects:2.1.0`; the new artifact is the local project version, +`2.2.0-beta.1`. + +## Beta-annotated surface + +The 2.1.0 source jar contains no `@Beta` annotations. The only RevAPI failure on a type that is +`@Beta` in the current source is: + +| Current beta type | RevAPI change | +| --- | --- | +| `RoutineRun` | `getStatus()` return type changed from `String` to `BinaryData`. | + +`RoutineRun` is currently annotated with `@Beta(warningText = "Preview API. Routines=V1Preview")`, +but it was not `@Beta` in the 2.1.0 source. + +## Other non-beta API changes + +These RevAPI failures are outside the beta-annotated surface: + +| Area | RevAPI changes | +| --- | --- | +| `ModelVersion` | Removed `getSystemData()`, which returned `SystemDataV3`. | +| Removed models | `SystemDataV3` was removed. It was not `@Beta` in 2.1.0. | + +## Least-verbose exception shape + +The concise exception set is three exact RevAPI rules: + +1. `java.method.removed` for `ModelVersion.getSystemData()`. +2. `java.class.removed` for `SystemDataV3`. +3. `java.method.returnTypeChanged` for `RoutineRun.getStatus()`. + +Those exceptions are in `revapi.json` and appended from `pom.xml` so the inherited RevAPI config remains active. diff --git a/sdk/ai/azure-ai-projects/pom.xml b/sdk/ai/azure-ai-projects/pom.xml index d5eaa4caf9c8..d794f6cb7d29 100644 --- a/sdk/ai/azure-ai-projects/pom.xml +++ b/sdk/ai/azure-ai-projects/pom.xml @@ -113,6 +113,17 @@ Code generated by Microsoft (R) TypeSpec Code Generator. + + org.revapi + revapi-maven-plugin + + + + ${project.basedir}/revapi.json + + + + diff --git a/sdk/ai/azure-ai-projects/revapi.json b/sdk/ai/azure-ai-projects/revapi.json new file mode 100644 index 000000000000..21f63574ff6a --- /dev/null +++ b/sdk/ai/azure-ai-projects/revapi.json @@ -0,0 +1,26 @@ +[ + { + "extension": "revapi.differences", + "configuration": { + "ignore": true, + "differences": [ + { + "code": "java.method.removed", + "old": "method com.azure.ai.projects.models.SystemDataV3 com.azure.ai.projects.models.ModelVersion::getSystemData()", + "justification": "SystemDataV3 was removed from ModelVersion because the current service contract no longer exposes system data on model versions." + }, + { + "code": "java.class.removed", + "old": "class com.azure.ai.projects.models.SystemDataV3", + "justification": "SystemDataV3 was removed because the current service contract no longer exposes this model." + }, + { + "code": "java.method.returnTypeChanged", + "old": "method java.lang.String com.azure.ai.projects.models.RoutineRun::getStatus()", + "new": "method com.azure.core.util.BinaryData com.azure.ai.projects.models.RoutineRun::getStatus()", + "justification": "Breaking change in beta operation: RoutineRun status changed from String to BinaryData to align with the current Routines preview contract." + } + ] + } + } +]