Add union wrappers to azure-ai-agents types

[Kaylie (kaylieee)]

This pull request makes significant enhancements to the customization logic for union-type properties in the Azure AI Agents Java SDK. The main improvements include supporting string-enum union variants, adding support for immutable union properties with typed constructors, and cleaning up obsolete or redundant code. These changes improve the generated API's type safety, clarity, and maintainability.

Union Type Customization Improvements:

• Added support for string-enum union variants, allowing properties to use strongly-typed enums instead of raw strings, and updated getter/setter generation accordingly. [1] [2] [3] [4]
• Removed obsolete string-variant accessors when a property migrates to a string-enum, ensuring only the correct, current API is exposed.

Immutable Model Enhancements:

• Introduced customizeImmutableUnionProperty to generate public constructor overloads for each union variant on immutable models, improving type safety and usability for required union properties. [1] [2]

API and Code Cleanup:

• Restored and expanded union property customizations for several models, including VoiceAgentDefinition, VoiceAgentSessionResponseConfig, and others, ensuring consistent API coverage. [1] [2]
• Refactored how assignment and getter bodies are generated to centralize logic and support new variant types (string-enum, Azure union types, etc.). [1] [2]

Internal Utility Improvements:

• Added utility methods like binaryDataExpression and hasUnionMarker to streamline code generation and variant management.

These changes collectively modernize and extend the code generation for union properties, making the SDK easier and safer to use for developers.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
35 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

Unresolved duplicate-method generation, ambiguous nullable setters, and string-enum storage issues require fixes before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR adds typed union wrappers, immutable constructors, and serialization support for Azure AI Agents voice and realtime models.

Changes:

• Expands union accessors for enum, model, list, and OpenAI variants.
• Adds immutable union constructors and serialization helpers.
• Adds comprehensive voice and realtime serialization tests.

File summaries

File	Reviewed changes
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceResponseSerializationTests.java	Tests voice response serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceResponseBaseSerializationTests.java	Tests base voice response serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentSessionUpdateConfigSerializationTests.java	Tests session update configuration serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentSessionResponseConfigSerializationTests.java	Tests session response configuration serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentResponseCreateParamsSerializationTests.java	Tests response creation parameters.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentRealtimeResponseSerializationTests.java	Tests realtime response serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentRealtimeResponseBaseSerializationTests.java	Tests base realtime response serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentMcpToolSerializationTests.java	Tests MCP tool union serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentLlmGeneratedGreetingConfigSerializationTests.java	Tests greeting configuration serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/VoiceAgentDefinitionSerializationTests.java	Tests agent definition unions.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/UnionTypeSerializationTestUtils.java	Provides shared serialization test utilities.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/RealtimeSessionCreateRequestGASerializationTests.java	Tests realtime session request unions.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/RealtimeSessionCreateRequestGAAudioOutputSerializationTests.java	Tests audio output variants.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/RealtimeServerEventSessionUpdatedSerializationTests.java	Tests updated-session event serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/RealtimeServerEventSessionCreatedSerializationTests.java	Tests created-session event serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/RealtimeServerEventConversationItemInputAudioTranscriptionCompletedSerializationTests.java	Tests transcription usage serialization.
sdk/ai/azure-ai-agents/src/test/java/com/azure/ai/agents/models/RealtimeClientEventSessionUpdateSerializationTests.java	Tests client session update serialization.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceResponseBase.java	Adds typed base response accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceResponse.java	Adds typed response accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentSessionUpdateConfig.java	Adds session update union wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentSessionResponseConfig.java	Adds session response union wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentResponseCreateParams.java	Adds response parameter wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentRealtimeResponseBase.java	Adds base realtime response accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentRealtimeResponse.java	Adds realtime response accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentMcpTool.java	Adds MCP tool union wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentLlmGeneratedGreetingConfig.java	Adds greeting tool-choice wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/VoiceAgentDefinition.java	Adds definition union wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/RealtimeSessionCreateRequestGAAudioOutput.java	Adds audio output union wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/RealtimeSessionCreateRequestGA.java	Adds realtime request union wrappers.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/RealtimeServerEventSessionUpdated.java	Adds typed session constructors and accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/RealtimeServerEventSessionCreated.java	Adds typed session constructors and accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/RealtimeServerEventConversationItemInputAudioTranscriptionCompleted.java	Adds typed usage constructors and accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/models/RealtimeClientEventSessionUpdate.java	Adds typed session constructors and accessors.
sdk/ai/azure-ai-agents/src/main/java/com/azure/ai/agents/implementation/OpenAIJsonHelper.java	Adds OpenAI union serialization helpers.
sdk/ai/azure-ai-agents/customizations/src/main/java/AgentsCustomizations.java	Generates typed union accessors and constructors.

Review details

Suppressed comments (2)

sdk/ai/azure-ai-agents/customizations/src/main/java/AgentsCustomizations.java:278

• Using the shared setterName for each nullable union variant creates ambiguous calls such as setVoice(null) and setToolChoice(null) because multiple reference-typed overloads match; callers are forced to add casts, as the new tests do. The package's union guidance documents this exact problem and recommends distinct variant-specific setter names (the OpenAI branch uses the same pattern).

                        "public " + className + " " + setterName + "(" + variant[V_SETTER_TYPE] + " " + property

sdk/ai/azure-ai-agents/customizations/src/main/java/AgentsCustomizations.java:380

• The immutable customization has the same rerun problem for constructors: it clones the retained raw BinaryData constructor and unconditionally appends each typed overload. On a partial update, the existing public union constructors remain in the class, so a second customization run introduces duplicate constructors and the generated source no longer compiles. Remove or replace union-marked typed constructors, or check the constructor signature before adding it.

                    clazz.addMember(typedConstructor);

• Files reviewed: 35/35 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Jose Alvarez (jpalvarezl)]

Looks good. Just a couple of nits.