| name | azure-ai-projects-update-changelog |
| license | MIT |
| metadata | {"version":"1.0.0","distribution":"local"} |
| description | Update CHANGELOG.md by comparing public APIs between the current branch and the latest released version on PyPI. WHEN: "update changelog", "generate changelog", "add changelog entry", "what changed in this version". DO NOT USE FOR: other Azure SDK packages. INVOKES: PyPI API, GitHub API (for tags), file operations. |
| compatibility | {"requires":"local azure-sdk-for-python clone, git, internet access"} |
Update azure-ai-projects Changelog
This skill guides Copilot through updating the CHANGELOG.md file for the azure-ai-projects package by comparing public APIs between the current branch and the latest released version.
Working directory: sdk/ai/azure-ai-projects
Overview
The skill performs these steps:
- Read the current version from
azure/ai/projects/_version.py
- Fetch the latest released version from PyPI
- Compare public classes, methods, and properties between current branch and released version
- Update CHANGELOG.md with a new section or update the existing "(Unreleased)" section
Step 1: Read the current version
Read the current version from azure/ai/projects/_version.py. The file contains a line like:
VERSION = "X.Y.Z"
Extract this version number and save it as CURRENT_VERSION.
Step 2: Fetch the latest released version from PyPI
Use the PyPI JSON API to get the latest released version:
https://pypi.org/pypi/azure-ai-projects/json
From the JSON response:
- Extract
info.version as LATEST_PYPI_VERSION
- This is the version we will compare against
Step 3: Determine if CHANGELOG needs updating
Check if CHANGELOG.md already has a section for the current version:
- If there's a section
## {CURRENT_VERSION} (Unreleased) — we will update it
- If there's a section
## {CURRENT_VERSION} (YYYY-MM-DD) with an actual date — the version is already released, report this to the user and stop
- If there's no section for
CURRENT_VERSION — we will create a new one
Step 4: Construct the GitHub tag for the released version
The tag name for a released version follows this pattern:
azure-ai-projects_{VERSION}
For example, for version 2.2.0, the tag is azure-ai-projects_2.2.0.
The source code for that release can be found at:
https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-projects_{VERSION}/sdk/ai/azure-ai-projects
Step 5: Compare public APIs
Compare the public APIs between the current branch and the latest released version. Focus on these locations:
5a. Public classes and enums in azure/ai/projects/models/__init__.py
Compare the __all__ list and imports in both versions to identify:
- New classes/enums: Present in current branch but not in released version
- Removed classes/enums: Present in released version but not in current branch
- Renamed classes/enums: Check if a removed class has a similar new class (likely a rename)
5b. Public operations in azure/ai/projects/operations/__init__.py
Compare the __all__ list to identify new or removed operation classes.
5c. Public methods on sub-clients
For each operations class (like AgentsOperations, BetaOperations, etc.), compare the public methods:
- Look at files under
azure/ai/projects/operations/ and azure/ai/projects/aio/operations/
- Also check
_patch.py files which may define additional public methods
- Public methods are those that don't start with underscore
_
5d. Properties on model classes
For significant model classes, compare public properties (attributes) between versions:
- Properties are defined in
azure/ai/projects/models/_models.py
- Look for new, removed, or renamed properties
- Pay attention to required vs optional changes
5e. Beta sub-clients on BetaOperations
The BetaOperations class exposes beta/preview functionality. Check for:
- New sub-client properties (like
.beta.datasets, .beta.models, .beta.routines, etc.)
- Removed sub-client properties
- Check both
azure/ai/projects/operations/_patch.py and the released version
5f. Sample files in samples/ folder
Compare sample files between the current branch and the released version:
- List all
.py files recursively under samples/ in both versions
- Identify new samples: Files present in current branch but not in released version
- Identify removed samples: Files present in released version but not in current branch
- Ignore async variants: If a sample has both sync and async versions (e.g.,
sample_foo.py and sample_foo_async.py), only report the sync version
- Check existing changelog entries: If a sample is already mentioned in the current changelog section, leave it as is
- Remove stale entries: If a sample mentioned in the changelog has been removed from the codebase, remove it from the changelog
For each new sample, provide a one-line description of what it demonstrates. Read the sample file to understand its purpose — typically the docstring at the top or the if __name__ == "__main__" block explains what it does.
Step 6: Categorize the changes
Organize detected changes into these categories:
Features Added
- New sub-clients (e.g., "New
.beta.routines sub-client with routine operations: create_or_update, get, enable, ...")
- New methods on existing sub-clients (e.g., "New methods on
.beta.agents for optimization jobs: create_optimization_job, get_optimization_job, ...")
- New model classes that represent significant features (e.g., "Support integration of external Agents. See new
ExternalAgentDefinition class.")
- New properties on existing classes (e.g., "New optional
force parameter on agents.delete method.")
- New tools (e.g., "New Agent tool in preview
FabricIQPreviewTool.")
Breaking Changes
List breaking changes in beta methods and classes separately:
- Renamed methods (e.g., "Method
.beta.agents.get_session_files renamed to .beta.agents.list_session_files.")
- Renamed arguments (e.g., "Argument
body in method .beta.skills.create_from_files() renamed to content.")
- Signature changes (e.g., "Method
.beta.skills.create signature changed — now takes name and keyword inline_content: SkillInlineContent; returns SkillVersion.")
- Renamed classes (e.g., "Renamed class
AgentEndpoint to AgentEndpointConfig.")
- Property changes (e.g., "Required property
isolation_key_source removed from class EntraAuthorizationScheme.")
- Renamed properties (e.g., "Property
skill_id renamed to id on class SkillDetails.")
Format for beta changes:
Breaking changes in beta methods:
* ...
Breaking changes in beta classes:
* ...
Bugs Fixed
This section typically contains bug fixes. Leave empty unless you have specific bug fix information to add.
Sample updates
List new sample files that were added, with a one-line description of what they demonstrate:
- Compare sample files in the
samples/ folder between current branch and released version
- Only report the sync version — do not list async samples separately (files ending with
_async.py)
- If a sample is already mentioned in the existing changelog section, preserve that entry
- If a sample mentioned in the changelog has been removed from the codebase, remove it from the changelog
- Group related samples together (e.g., all agent samples, all evaluation samples)
- Use format:
Added \sample_name.py` demonstrating [brief description].`
Step 7: Format the changelog entry
Use this format for the changelog entry:
## {CURRENT_VERSION} (Unreleased)
### Features Added
* [List each feature on its own bullet point]
### Breaking Changes
Breaking changes in beta methods:
* [List method changes]
Breaking changes in beta classes:
* [List class changes]
### Bugs Fixed
* [List bug fixes, if any]
### Sample updates
* [List sample updates, if any]
Guidelines for writing entries:
- For new methods: mention the sub-client and method name, briefly describe what it does. Only report the sync version — do not list both sync and async versions separately.
- For new sub-clients: list all the methods it provides (sync versions only)
- For new tools: just mention the class name
- For property changes: mention the class name and the affected property
- For renames: show "X renamed to Y" format
- Use backticks for code references:
.beta.agents, create_version(), AgentDetails
Step 8: Update CHANGELOG.md
Insert or update the changelog entry in CHANGELOG.md:
-
If updating an existing "(Unreleased)" section:
- Replace the existing section content with the new content
- Preserve any manually-added entries that aren't API-related (like "Sample updates" written by developers)
-
If creating a new section:
- Insert the new section immediately after the
# Release History header
- Keep all previous version sections intact
Step 9: Report to user
After updating the changelog, report:
- The current version and latest PyPI version compared
- Summary of changes detected:
- Number of new classes/enums
- Number of new methods
- Number of breaking changes
- Number of removed items
- Remind the user to:
- Review the generated changelog for accuracy
- Add any bug fixes that were made
- Review sample descriptions for accuracy
- Verify method descriptions are accurate
Tips for API Comparison
Using git to compare files
You can compare files between the current branch and a tag:
git diff azure-ai-projects_{VERSION} -- azure/ai/projects/models/__init__.py
Using GitHub raw URLs
To fetch files from the released version:
https://raw.githubusercontent.com/Azure/azure-sdk-for-python/azure-ai-projects_{VERSION}/sdk/ai/azure-ai-projects/azure/ai/projects/models/__init__.py
Identifying renames vs additions/removals
If a class was removed and a similar class was added, it's likely a rename. Look for:
- Similar names (e.g.,
SkillObject → SkillDetails)
- Similar structure/properties
- Check if there's a corresponding note in the TypeSpec changes
Example Output
Here's an example of a well-formatted changelog entry:
## 2.3.0 (Unreleased)
### Features Added
* Support integration of external Agents (in preview). See new `ExternalAgentDefinition` class.
* New Agent tool in preview `FabricIQPreviewTool`.
* New Agent tool in preview `ToolboxSearchPreviewTool`.
* New methods on `.beta.agents` for
* Code-based hosted agents: `create_version_from_code`, `download_code`.
* Optimization jobs: `create_optimization_job`, `get_optimization_job`, `list_optimization_jobs`, `cancel_optimization_job`, `list_optimization_candidates`.
* Optimization candidate management: `list_optimization_candidates`, `get_optimization_candidate`, `get_optimization_candidate_config`, `get_optimization_candidate_results`, `get_candidate_file`, `promote_candidate`.
* `stop_session` to stop a running agent session.
* New `.beta.datasets` sub-client with data generation job operations: `create_generation_job`, `get_generation_job`, `list_generation_jobs`, `cancel_generation_job`, `delete_generation_job`.
* New `.beta.models` sub-client to handle AI model weights: `create`, `list_versions`, `list`, `get`, `delete`, `update`, `pending_create_version`, `pending_upload`, `get_credentials`.
* New `.beta.routines` sub-client with routine operations: `create_or_update`, `get`, `enable`, `disable`, `list`, `delete`, `list_runs`, `dispatch`.
* New methods on `.beta.evaluators` for evaluator generation jobs: `create_generation_job`, `get_generation_job`, `list_generation_jobs`, `cancel_generation_job`, `delete_generation_job`.
* New methods on `.beta.memory_stores` to handle individual memory items: `create_memory`, `update_memory`, `list_memories`, `get_memory`, `delete_memory`.
* New methods on `.beta.skills` for versioned skill management: `create`, `list_versions`, `get_version`, `download_version`, `delete_version`.
* New optional string properties `description` and `name` added to Agent tools classes which did not have them before.
* New optional `tool_configs` added to Agent tool classes.
* New read-only property `content_hash` on `CodeConfiguration`, returning the SHA-256 hex digest of the uploaded code zip.
* New optional `force` parameter on `agents.delete` and `agents.delete_version` methods.
* New optional `blueprint_reference` parameters on `agents.create_version` method.
### Breaking Changes
Breaking changes in beta methods:
* Argument `isolation_key` in methods `.beta.agents.create_session()` and `.beta.agents.delete_session()` renamed to `user_isolation_key`.
* Argument `body` in methods `.beta.evaluation_taxonomies.create()` and `.beta.evaluation_taxonomies.update()` renamed to `taxonomy`.
* Argument `body` in method `.beta.skills.create_from_files()` renamed to `content`.
* Method `.beta.agents.get_session_files` renamed to `.beta.agents.list_session_files`.
* Method `.beta.skills.create` signature changed — now takes `name` and keyword `inline_content: SkillInlineContent`; returns `SkillVersion`.
* Method `.beta.skills.create_from_package` renamed to `.beta.skills.create_from_files`.
* Method `.beta.skills.create_from_files` signature changed — now takes `name` and `content: CreateSkillVersionFromFilesBody`; returns `SkillVersion`.
* Method `.beta.skills.update` signature changed — now only accepts keyword `default_version`; returns `SkillDetails`.
Breaking changes in beta classes:
* Required property `isolation_key_source` removed from class `EntraAuthorizationScheme`.
* Renamed class `AgentEndpoint` to `AgentEndpointConfig`.
* Renamed class `DeleteSkillResponse` to `DeleteSkillResult`.
* Renamed class `SessionDirectoryListResponse` to `SessionDirectoryListResult`.
* Renamed class `SessionFileWriteResponse` to `SessionFileWriteResult`.
* Renamed class `SkillObject` to `SkillDetails`. Property `skill_id` renamed to `id`. Properties `has_blob` and `metadata` were removed.
* Renamed class `Target` to `EvaluationTarget`.
* Renamed class `TargetConfig` to `RedTeamTargetConfig`.
### Bugs Fixed
* Fixed telemetry instrumentor to correctly call is_recording() as a method on spans, ensuring non-recording spans are properly skipped (e.g., when sampling is configured) ([GitHub issue 46544](https://github.com/Azure/azure-sdk-for-python/issues/46544)).
### Sample updates
* Added new Agent tool samples `sample_agent_work_iq.py` and `sample_agent_work_iq_async.py` demonstrating use of `WorkIQPreviewTool`.
* Added new Agent tool samples `sample_agent_fabric_iq.py` and `sample_agent_fabric_iq_async.py` demonstrating use of `FabricIQPreviewTool`.
* Hosted Agents:
* Added Hosted Agent creation samples `sample_create_hosted_agent.py` and `sample_create_hosted_agent_async.py`, demonstrating hosted agent version creation and retrieval with `AIProjectClient`.
* Added Hosted Agent code-upload samples `sample_create_hosted_agent_from_code.py` and `sample_create_hosted_agent_from_code_async.py`, demonstrating uploading a code package (zip) as a new hosted agent version.
* The Hosted Agent creation sample also demonstrates assigning the hosted agent managed identity the Azure AI User RBAC role on the backing Azure AI account.
* Updated the other Hosted Agent samples to reuse an existing Hosted Agent as a prerequisite, instead of creating a new hosted agent version in each sample.
* Added Toolbox tool-search sample `sample_toolboxes_with_search_preview.py` and `sample_toolboxes_with_search_preview_async.py`, demonstrating creating a Toolbox version with `ToolboxSearchPreviewTool` and invoking `MCPTool`.
* Added `.beta.models` samples under `samples/models/`:
* `sample_models_basic.py` — synchronous end-to-end registration via the `create` helper (uses `azcopy`), followed by `get`, `list_versions`, `list`, `get_credentials`, `update`, and `delete`.
* `sample_models_create_and_poll.py` — alternative synchronous registration that hand-rolls the spec's three-step flow (`pending_upload` → upload via `azure-storage-blob` → `pending_create_version` + poll), without taking a dependency on `azcopy`.
* `sample_models_basic_async.py` — asynchronous version of the same three-step flow using `azure.ai.projects.aio.AIProjectClient` and `azure.storage.blob.aio.ContainerClient`.
* Added new evaluation sample `sample_model_evaluation_instant_model.py` demonstrating model evaluation with an instant model.
* Refreshed evaluation samples under `samples/evaluations/` and `samples/evaluations/agentic_evaluators/` (including `sample_agent_evaluation`, `sample_agent_response_evaluation`, `sample_eval_catalog_prompt_based_evaluators`, `sample_evaluations_ai_assisted`, `sample_evaluations_builtin_with_csv`, `sample_evaluations_builtin_with_dataset_id`, `sample_evaluations_builtin_with_inline_data`, `sample_evaluations_builtin_with_inline_data_oai`, `sample_scheduled_evaluations`, `sample_coherence`, `sample_fluency`, `sample_intent_resolution`, `sample_relevance`, `sample_response_completeness`, `sample_tool_call_accuracy`, `sample_tool_call_success`, `sample_tool_input_accuracy`, `sample_tool_output_utilization`, `sample_tool_selection`, and `sample_generic_agentic_evaluator`).
* New sample `sample_dataset_generation_job_simpleqna_with_prompt_source.py` showing an end-to-end flow that generates a QnA dataset via `.beta.datasets.create_generation_job` and runs an OpenAI evaluation.
