PoC: Beta class annotation for preview API for `azure-ai-agents` and `azure-ai-projects` by jpalvarezl · Pull Request #49506 · Azure/azure-sdk-for-java

jpalvarezl · 2026-06-15T12:13:30Z

Introduced a @Beta. Happy to migrate if there is something more suitable
Using a custom emitter
Here is the configuration for that emitter

* Fixed sample issues * Fix agent-scoped OpenAI endpoint URL; reorganize hosted-agents sample utils - Fix the agent-scoped OpenAI client in AgentsClientBuilder so requests to a hosted-agent endpoint use the unified Azure URL path mode and send api-version=v1. Previously the path was duplicated (.../protocols/openai/openai/responses) and used an unsupported default api-version, causing 400 errors when invoking the Responses API or streaming session logs through an agent endpoint. - Move CodeAgentSampleUtils and HostedAgentsSampleUtils into a com.azure.ai.agents.hostedagents.utils subpackage and update sample/test imports. - Close the endless session-log SSE stream client-side after a short timeout. - Add a CHANGELOG entry for the bug fix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* add back missing overload * add revapi suppressions * add suppressions for all beta clients * cleanup

…ion_poc

Copilot

Pull request overview

This PR introduces a CSV-driven mechanism to consistently mark preview (beta) APIs in the azure-ai-agents and azure-ai-projects Java SDKs by generating and applying a custom @Beta annotation to specific classes and members during customization.

Changes:

Added a @Beta annotation type to both libraries (in each package’s util namespace).
Added beta-annotations.csv files and customization logic to parse them and apply @Beta to targeted classes/fields (including accessors).
Updated many generated model types to import and use @Beta(...) with preview warning text.

Reviewed changes

Copilot reviewed 96 out of 96 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/util/Beta.java	Adds `@Beta` annotation for preview API marking in Projects.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/TimerRoutineTrigger.java	Marks routine trigger model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/ScheduleRoutineTrigger.java	Marks routine trigger model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineTriggerType.java	Marks routine trigger discriminator enum as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineTrigger.java	Marks base routine trigger model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineRunPhase.java	Marks routine run phase enum as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineRun.java	Marks routine run model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineDispatchPayloadType.java	Marks dispatch payload discriminator enum as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineDispatchPayload.java	Marks base dispatch payload model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineAttemptSource.java	Marks attempt source enum as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineActionType.java	Marks routine action discriminator enum as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/RoutineAction.java	Marks base routine action model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/Routine.java	Marks routine model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/InvokeAgentResponsesApiRoutineAction.java	Marks responses API routine action model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/InvokeAgentResponsesApiDispatchPayload.java	Marks responses API dispatch payload model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/InvokeAgentInvocationsApiRoutineAction.java	Marks invocations API routine action model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/InvokeAgentInvocationsApiDispatchPayload.java	Marks invocations API dispatch payload model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/GitHubIssueRoutineTrigger.java	Marks GitHub issue trigger model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/GitHubIssueEvent.java	Marks GitHub issue event enum as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/EvaluatorCredentialInput.java	Marks evaluator credential input model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/EvaluationRule.java	Marks evaluation rule member/accessor as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/DispatchRoutineResult.java	Marks dispatch result model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/CustomRoutineTrigger.java	Marks custom trigger model as preview via `@Beta`.
sdk/ai/azure-ai-projects/src/main/java/com/azure/ai/projects/models/CodeBasedEvaluatorDefinition.java	Marks evaluator fields/accessors as preview via `@Beta`.
sdk/ai/azure-ai-projects/customizations/src/main/java/ProjectsCustomizations.java	Adds CSV parsing + AST customization to apply `@Beta` in Projects.
sdk/ai/azure-ai-projects/customizations/beta-annotations.csv	Adds Projects CSV source-of-truth for preview annotations.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/util/Beta.java	Adds `@Beta` annotation for preview API marking in Agents.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/WorkflowAgentDefinition.java	Marks workflow agent model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VersionSelectorType.java	Marks version selector type enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VersionSelector.java	Marks version selector model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VersionSelectionRule.java	Marks version selection rule model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VersionRefIndicator.java	Marks version ref indicator model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VersionIndicatorType.java	Marks version indicator type enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VersionIndicator.java	Marks version indicator model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/UserProfileMemoryItem.java	Marks memory item model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryTransportProtocol.java	Marks telemetry enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryEndpointKind.java	Marks telemetry enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryEndpointAuthType.java	Marks telemetry enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryEndpointAuth.java	Marks telemetry auth model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryEndpoint.java	Marks telemetry endpoint model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryDataKind.java	Marks telemetry enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/TelemetryConfig.java	Marks telemetry config model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/SessionLogEventType.java	Marks session log enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/SessionLogEvent.java	Marks session log event model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/ProceduralMemoryItem.java	Marks memory item model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/OtlpTelemetryEndpoint.java	Marks OTLP endpoint model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreUpdateStatus.java	Marks memory store enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreUpdateResponse.java	Marks memory store response model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreUpdateCompletedResult.java	Marks memory store result model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreSearchResponse.java	Marks memory store search response model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreOperationUsage.java	Marks memory store usage model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreKind.java	Marks memory store enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreDetails.java	Marks memory store details model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreDefinition.java	Marks base memory store definition model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreDefaultOptions.java	Marks memory store options model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryStoreDefaultDefinition.java	Marks memory store definition model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemorySearchOptions.java	Marks memory search options model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemorySearchItem.java	Marks memory search item model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryOperationKind.java	Marks memory operation enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryOperation.java	Marks memory operation model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryItemKind.java	Marks memory item enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/MemoryItem.java	Marks base memory item model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/ManagedAgentIdentityBlueprintReference.java	Marks blueprint reference model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/IsolationKeySourceKind.java	Marks isolation key enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/IsolationKeySource.java	Marks isolation key source model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/HostedAgentDefinition.java	Marks hosted agent model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/HeaderTelemetryEndpointAuth.java	Marks telemetry auth model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/HeaderIsolationKeySource.java	Marks isolation key source model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/FixedRatioVersionSelectionRule.java	Marks selection rule model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/ExternalAgentDefinition.java	Marks external agent model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/EntraIsolationKeySource.java	Marks isolation key source model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/EntraAuthorizationScheme.java	Marks authorization scheme model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/CreateAgentVersionInput.java	Marks create-version input model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/CreateAgentVersionFromCodeMetadata.java	Marks code-metadata model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/CreateAgentVersionFromCodeContent.java	Marks code-content model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/ContainerConfiguration.java	Marks container configuration model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/CodeConfiguration.java	Marks code configuration model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/ChatSummaryMemoryItem.java	Marks memory item model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/BotServiceRbacAuthorizationScheme.java	Marks bot auth scheme model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/BotServiceAuthorizationScheme.java	Marks bot auth scheme model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentVersionDetails.java	Marks agent version details members/accessors as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentSessionStatus.java	Marks session status enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentSessionResource.java	Marks session resource model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentIdentity.java	Marks agent identity model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentEndpointConfig.java	Marks endpoint config model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentEndpointAuthorizationSchemeType.java	Marks endpoint auth enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentEndpointAuthorizationScheme.java	Marks endpoint auth scheme model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentDetails.java	Marks specific members/accessors as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentDefinition.java	Marks base agent definition model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentCardSkill.java	Marks agent card skill model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentCard.java	Marks agent card model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentBlueprintReferenceType.java	Marks blueprint ref type enum as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/AgentBlueprintReference.java	Marks blueprint ref model as preview via `@Beta`.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/implementation/models/CreateAgentFromCodeContent.java	Marks implementation model as preview via `@Beta`.
sdk/ai/azure-ai-agents/customizations/src/main/java/AgentsCustomizations.java	Adds CSV parsing + AST customization to apply `@Beta` in Agents.
sdk/ai/azure-ai-agents/customizations/beta-annotations.csv	Adds Agents CSV source-of-truth for preview annotations.

+            // Skip the header row (type;class_name;annotation_description;member_name).
+            if (lineNumber == 1) {
+                continue;
+            }


+            String type = columns[0].trim();
+            String className = columns[1].trim();
+            String description = columns[2];
+            String member = columns.length >= 4 ? columns[3].trim() : "";
+            if (className.isEmpty() || description.isEmpty()) {
+                logger.error("Line {} of {} requires a class_name and an annotation_description: {}", lineNumber,
+                    CSV_FILE_NAME, line);
+                throw new IllegalStateException("Line " + lineNumber + " of " + CSV_FILE_NAME
+                    + " requires a class_name and an annotation_description: " + line);
+            }
+            if ("field".equals(type) && member.isEmpty()) {
+                logger.error("Line {} of {} is a field entry but has no member_name: {}", lineNumber, CSV_FILE_NAME,
+                    line);
+                throw new IllegalStateException("Line " + lineNumber + " of " + CSV_FILE_NAME
+                    + " is a field entry but has no member_name: " + line);
+            }


+            // Skip the header row (type;class_name;annotation_description;member_name).
+            if (lineNumber == 1) {
+                continue;
+            }


+            String type = columns[0].trim();
+            String className = columns[1].trim();
+            String description = columns[2];
+            String member = columns.length >= 4 ? columns[3].trim() : "";
+            if (className.isEmpty() || description.isEmpty()) {
+                logger.error("Line {} of {} requires a class_name and an annotation_description: {}", lineNumber,
+                    CSV_FILE_NAME, line);
+                throw new IllegalStateException("Line " + lineNumber + " of " + CSV_FILE_NAME
+                    + " requires a class_name and an annotation_description: " + line);
+            }
+            if ("field".equals(type) && member.isEmpty()) {
+                logger.error("Line {} of {} is a field entry but has no member_name: {}", lineNumber, CSV_FILE_NAME,
+                    line);
+                throw new IllegalStateException("Line " + lineNumber + " of " + CSV_FILE_NAME
+                    + " is a field entry but has no member_name: " + line);
+            }


+class;com.azure.ai.agents.models.AgentBlueprintReferenceType;Preview API. AgentEndpoints=V1Preview;
+class;com.azure.ai.agents.models.AgentCard;Preview API. AgentEndpoints=V1Preview;
+class;com.azure.ai.agents.models.AgentCardSkill;Preview API. AgentEndpoints=V1Preview;
+class;com.azure.ai.agents.models.AgentDefinition;Preview API. CodeAgents=V1Preview, ExternalAgents=V1Preview, HostedAgents=V1Preview, WorkflowAgents=V1Preview;


+class;com.azure.ai.agents.models.ContainerConfiguration;Preview API. CodeAgents=V1Preview;
+class;com.azure.ai.agents.models.CreateAgentVersionFromCodeContent;Preview API. CodeAgents=V1Preview;
+class;com.azure.ai.agents.models.CreateAgentVersionFromCodeMetadata;Preview API. CodeAgents=V1Preview;
+class;com.azure.ai.agents.models.CreateAgentVersionInput;Preview API. CodeAgents=V1Preview, ExternalAgents=V1Preview, HostedAgents=V1Preview, WorkflowAgents=V1Preview;


…ion_poc

jpalvarezl and others added 23 commits June 8, 2026 13:49

Code gen from spec tuned for beta client

e17bdc0

Ported client builder changes

7c0ed61

Samples, tests, docs port

1335dc3

Adjusted samples

2c7a6b5

Both projects compile

a68dcf9

Builder fixes

69d10c7

style checks

b8781c4

projects behaves the same as agents

16e74c6

Latest commit

8ca0e74

Removed unnecessary allowPreview setting

47f333c

README adjustments

d0e10a8

restored names for the tsp-location.yaml files

75b5562

Extracted policy creating and pipeline handling + PR feedback

6d0c8a8

Unit tests

38c6ab0

moved some test files

7f74e10

Added suppresion

eccd56a

propagated changes to azure-ai-projects

ef0559a

Updated changelog

b12113f

Revapi suppressions (#49484)

1fb955c

* add back missing overload * add revapi suppressions * add suppressions for all beta clients * cleanup

Added annotation support and @beta annotation

29da3a4

Added beta annotation for azure-ai-agents

fcb6580

azure-ai-projects annotations

065d750

jpalvarezl requested review from a team, dargilco, glecaros, kaylieee and trrwilson as code owners June 15, 2026 12:13

github-actions Bot added AI Agents AI Projects labels Jun 15, 2026

jpalvarezl changed the title ~~Jpalvarezl/feature/class member beta annotation poc~~ PoC: Beta class annotation for preview API for azure-ai-agents and azure-ai-projects Jun 15, 2026

Base automatically changed from jpalvarezl/feature/foundry_sdk_beta_client_refactor to main June 16, 2026 19:50

alzimmermsft requested review from JonathanGiles, Netyyyy, alzimmermsft, moarychan, rujche, saragluna and srnagar as code owners June 16, 2026 19:50

Merge branch 'main' into jpalvarezl/feature/class_member_beta_annotat…

5daa976

…ion_poc

Copilot AI review requested due to automatic review settings June 17, 2026 07:12

Copilot started reviewing on behalf of jpalvarezl June 17, 2026 07:12 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Merge branch 'main' into jpalvarezl/feature/class_member_beta_annotat…

f8cbd87

…ion_poc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PoC: Beta class annotation for preview API for `azure-ai-agents` and `azure-ai-projects`#49506

PoC: Beta class annotation for preview API for `azure-ai-agents` and `azure-ai-projects`#49506
jpalvarezl wants to merge 25 commits into
mainfrom
jpalvarezl/feature/class_member_beta_annotation_poc

jpalvarezl commented Jun 15, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jpalvarezl commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jpalvarezl commented Jun 15, 2026 •

edited

Loading