add skills for azure-ai-agents and azure-ai-projects#49002
add skills for azure-ai-agents and azure-ai-projects#49002
Conversation
kaylieee
requested review from
a team,
dargilco,
glecaros,
jpalvarezl and
trrwilson
as code owners
There was a problem hiding this comment.
Pull request overview
Adds GitHub “skills” documentation to support TypeSpec-based SDK regeneration and maintenance workflows for azure-ai-agents and azure-ai-projects, plus several shared sdk/ai skills used during post-generation cleanup and troubleshooting.
Changes:
- Add package-specific skills + reference docs for
azure-ai-agentsandazure-ai-projects. - Add shared
sdk/ai/.github/skills/*guides covering common post-codegen tasks (api diffing, dedup vs openai-java, union wrappers, type overrides, naming collisions, running tests, pushing recordings, etc.). - Register the two new package skills in the repo-level “find package skill” registry.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/ai/azure-ai-projects/.github/skills/azure-ai-projects/SKILL.md | Package-level post-regeneration guidance for azure-ai-projects. |
| sdk/ai/azure-ai-projects/.github/skills/azure-ai-projects/references/architecture.md | Architecture/source layout reference for azure-ai-projects. |
| sdk/ai/azure-ai-projects/.github/skills/azure-ai-projects/references/customizations.md | Status/intent reference for ProjectsCustomizations. |
| sdk/ai/azure-ai-agents/.github/skills/azure-ai-agents/SKILL.md | Package-level post-regeneration guidance for azure-ai-agents. |
| sdk/ai/azure-ai-agents/.github/skills/azure-ai-agents/references/architecture.md | Architecture/source layout reference for azure-ai-agents. |
| sdk/ai/azure-ai-agents/.github/skills/azure-ai-agents/references/customizations.md | Per-customization documentation for AgentsCustomizations. |
| sdk/ai/.github/skills/api-diff/SKILL.md | Process for identifying/bucketing new public API additions. |
| sdk/ai/.github/skills/codegen/SKILL.md | How to run tsp-client update/sync/generate for these modules. |
| sdk/ai/.github/skills/codegen-survival-rules/SKILL.md | Rules for making manual edits survive regeneration. |
| sdk/ai/.github/skills/dedup-openai/SKILL.md | Workflow to suppress actionable model duplicates vs openai-java and bridge serialization. |
| sdk/ai/.github/skills/dup-classes/SKILL.md | How to verify whether generated models duplicate openai-java models. |
| sdk/ai/.github/skills/github/SKILL.md | How to use gh CLI for PR/issue/run inspection (skill doc). |
| sdk/ai/.github/skills/release-notes/SKILL.md | Guidance for updating CHANGELOG/README based on a PR. |
| sdk/ai/.github/skills/run-tests/SKILL.md | How to run Maven tests, including common troubleshooting flags. |
| sdk/ai/.github/skills/samples/SKILL.md | How to author Java samples for these SDKs, referencing Python samples. |
| sdk/ai/.github/skills/search-m2/SKILL.md | How to locate/inspect dependency classes in ~/.m2. |
| sdk/ai/.github/skills/test-proxy/SKILL.md | How to push test-proxy recordings/assets. |
| sdk/ai/.github/skills/tsp-naming-collision/SKILL.md | How to fix *Request1 naming collisions via @@clientName. |
| sdk/ai/.github/skills/tsp-type-override/SKILL.md | How to use @@alternateType to map TSP types to Java-native/external types. |
| sdk/ai/.github/skills/union-type-wrappers/SKILL.md | How to wrap union-typed BinaryData with typed getters/setters. |
| .github/skills/find-package-skill/SKILL.md | Adds registry entries pointing to the new package skills. |
| | String value (ID, enum token) | `BinaryData.fromString(value)` | Writes as JSON string via `writeString()` | | ||
| | Numeric / boolean primitive | `BinaryData.fromObject(value)` | Writes as raw JSON value | | ||
| | Azure `JsonSerializable` model | `BinaryData.fromObject(value)` | JacksonAdapter handles serialization | | ||
| | Stainless (openai-java) type | `BinaryData.fromObject(value)` | Jackson handles serialization | |
There was a problem hiding this comment.
The guidance for union variants that are openai-java (“Stainless”) types is incorrect here: using BinaryData.fromObject(value) will use the Azure-core JacksonAdapter/ObjectMapper and can fail to serialize Kotlin/openai-java models (e.g., the Kotlin SynchronizedLazyImpl issue noted in the agents/projects package skills). Update this row to recommend using the OpenAIJsonHelper bridge (or openai-java ObjectMappers.jsonMapper() via a helper) to produce BinaryData safely for openai-java types, instead of BinaryData.fromObject directly.
| | Stainless (openai-java) type | `BinaryData.fromObject(value)` | Jackson handles serialization | | |
| | Stainless (openai-java) type | `OpenAIJsonHelper.toBinaryData(value)` | Use the OpenAI JSON bridge (or a helper backed by openai-java `ObjectMappers.jsonMapper()`) to serialize safely; do not call `BinaryData.fromObject(value)` directly for openai-java models | |
|
|
||
| - **This package depends on `azure-ai-agents`.** Changes to the agents package (especially model renames or module-info changes) can break this package. Always build both together. | ||
| - **Never serialize openai-java types with `BinaryData.fromObject()`.** Use `OpenAIJsonHelper.toBinaryData()` from the agents package — the default Jackson ObjectMapper cannot handle Kotlin internals. | ||
| - **The HTTP pipeline bridge is hand-written and fragile.** `HttpClientHelper` and `AzureHttpResponseAdapter` adapt Azure's HTTP stack to openai-java's contract. If either SDK's HTTP interfaces change, these break silently at runtime, not compile time. |
There was a problem hiding this comment.
This statement says interface changes in the hand-written OpenAI HTTP bridge "break silently at runtime, not compile time", but the bridge adapters in this module implement openai-java interfaces (e.g., AzureHttpResponseAdapter implements com.openai.core.http.HttpResponse, HttpClientWrapper implements com.openai.core.http.HttpClient). If openai-java changes these interfaces, this should typically surface as a compile-time error. Consider rewording to distinguish compile-time breaks (signature changes) from runtime breaks (behavioral/semantic changes).
| - **The HTTP pipeline bridge is hand-written and fragile.** `HttpClientHelper` and `AzureHttpResponseAdapter` adapt Azure's HTTP stack to openai-java's contract. If either SDK's HTTP interfaces change, these break silently at runtime, not compile time. | |
| - **The HTTP pipeline bridge is hand-written and fragile.** `HttpClientHelper` and `AzureHttpResponseAdapter` adapt Azure's HTTP stack to openai-java's contract. API or signature changes in either SDK will usually fail at compile time, but behavioral or semantic contract changes can still compile and only surface at runtime. |
| exports com.azure.ai.projects; | ||
| exports com.azure.ai.projects.models; | ||
| opens com.azure.ai.projects.models to com.azure.core; | ||
| opens com.azure.ai.projects.implementation.models to com.azure.core; |
There was a problem hiding this comment.
The module-info.java excerpt here doesn’t match the actual sdk/ai/azure-ai-projects/src/main/java/module-info.java. In particular, it shows opens com.azure.ai.projects.implementation.models to com.azure.core;, but that package isn’t present in this module and the module descriptor currently only opens com.azure.ai.projects.models. Please update the snippet to reflect the real module descriptor so readers don’t chase non-existent packages/JPMS directives.
| opens com.azure.ai.projects.implementation.models to com.azure.core; |
samvaity
left a comment
samvaity
left a comment
There was a problem hiding this comment.
Thank you for using the create-package-skill wizard. If you have any suggestions for additions to the base template, please feel free to add them so you won't need to make individual modifications each time.
| @@ -0,0 +1,340 @@ | |||
| --- | |||
| name: union-type-wrappers | |||
There was a problem hiding this comment.
Curious, on how these skills are referenced, I don't see them part of the main SKILL.md?
|
|
||
| ### All tests (default) | ||
| ```bash | ||
| mvn test |
There was a problem hiding this comment.
Some of these overlap with the https://aka.ms/azsdk/agent, please confirm we don't duplicate for the patterns that are already helping from the azsdk-mcp
| description: 'Generate Java samples for azure-ai-agents or azure-ai-projects by referencing existing Java samples for format and equivalent Python samples for CRUD flows. WHEN: write samples for a feature area; generate Java samples; create sample code; write agent samples; new feature samples.' | ||
| --- | ||
|
|
||
| # Generate Java Samples |
There was a problem hiding this comment.
Same as before, @deyaaeldeen can fill in more, but we have the azure-sdk-mcp to help with these tasks, we could include those instead of specific skills?
| | -------------------------- | ------------------------------------------------------------------------------------------------- | | ||
| | `azure-ai-agents` | `sdk/ai/azure-ai-agents/.github/skills/azure-ai-agents/SKILL.md` | | ||
| | `azure-ai-projects` | `sdk/ai/azure-ai-projects/.github/skills/azure-ai-projects/SKILL.md` | | ||
| | `azure-search-documents` | `sdk/search/azure-search-documents/.github/skills/azure-search-documents/SKILL.md` | |
There was a problem hiding this comment.
Oh Cool! I did not know about this file. I see it in the Python repo as well. I'll need to update it to point to my skill. Thanks!
| name: release-notes | ||
| description: 'Update CHANGELOG.md and README.md for an Azure SDK for Java package based on a GitHub PR. WHEN: write release notes; update changelog; update readme from PR; write changelog entries; document PR changes.' | ||
| --- | ||
|
|
There was a problem hiding this comment.
Some of the skills you added under /sdk/ai/.github/skills seem generic (not unique to your SDK). Aren't these skills already available at the root under /.github/skills?
Add skills for SDK generation for azure-ai-agents and azure-ai-projects packages