Azure AI Projects Update Changelog

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:

1. Read the current version from azure/ai/projects/_version.py
2. Fetch the latest released version from PyPI
3. Compare public classes, methods, and properties between current branch and released version
4. 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. If the date is in the past, then this version is already released, report this to the user and stop. If it's today's date, we will update it.
• 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:

1. List all .py files recursively under samples/ in both versions
2. Identify new samples: Files present in current branch but not in released version
3. Identify removed samples: Files present in released version but not in current branch
4. 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
5. Check existing changelog entries: If a sample is already mentioned in the current changelog section, leave it as is
6. 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:

1. 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)

2. 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:

1. The current version and latest PyPI version compared
2. Summary of changes detected:
   • Number of new classes/enums
   • Number of new methods
   • Number of breaking changes
   • Number of removed items
3. 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.