Azure · dargilco · Jul 25, 2026 · Jul 1, 2026 · Jul 6, 2026 · Jul 7, 2026
@@ -1,17 +1,29 @@
 # CoPilot skills for azure-ai-projects development
 
-## Prerequisite
+## General Prerequisite
 
 * Clone the `azure-sdk-for-python` repo to your local machine, if you don't already have it:
   ```
   git clone https://github.com/Azure/azure-sdk-for-python.git
   ```
 * Change to the directory `sdk\ai\azure-ai-projects`. 
-* Switch to the current feature branch, for example: `git switch feature/azure-ai-projects/2.3.0`.
+* Switch to the feature branch staging the next release: `git switch feature/azure-ai-projects/vnext`.
 * Make sure you don't have any files edited or added in this branch (clean `git status` state).
 
 ## Emit from TypeSpec and create a PR
 
+### Skill Prerequisite
+
+1. Windows machine with PowerShell (Windows PowerShell 5.1+)<br>Install: `winget install --id Microsoft.PowerShell --source winget`
+1. Git CLI, configured user identity, and authenticated access to GitHub remote<br>Install: `winget install --id Git.Git --source winget`<br>Configure: `git config --global user.name "<your-name>"` and `git config --global user.email "<your-email>"`
+1. GitHub CLI (gh), authenticated (for PR creation)<br>Install: `winget install --id GitHub.cli --source winget`<br>Login: `gh auth login`
+1. Python 3.9 or newer (matches pyproject.toml requires-python >=3.9)<br>Install: `winget install --id Python.Python.3 --source winget`
+1. `pip` installed<br>Setup/upgrade: `python -m ensurepip --upgrade` and `python -m pip install --upgrade pip`
+1. TypeSpec tsp-client command available in PATH (used by skill Step 4)<br>Install: `npm install -g @azure-tools/typespec-client-generator-cli`
+1. Node.js + npm (typically required to install/use tsp-client)<br>Install: `winget install --id OpenJS.NodeJS.LTS --source winget`
+1. Dependencies for developing azure-ai-projects, per dev_requirements.txt (this covers tools such as black and azpysdk support)<br>Install: `python -m pip install -r dev_requirements.txt`
+1. Local clone of Azure/azure-rest-api-specs only if using the local TypeSpec source option<br>Setup: `git clone https://github.com/Azure/azure-rest-api-specs.git`
+
 ### Using GitHub CoPilot in VSCode
 
 * Open VSCode in the current folder.

@@ -18,21 +18,135 @@ applying post-emitter fixes, updating the changelog, installing package from sou
 
 ---
 
-## Step 1: Gather information from the user
+## Step 1: Preflight checks (required)
+
+Before asking workflow questions, validate prerequisites in this section.
+
+If any required check fails:
+- Stop immediately and report the failing check.
+- Show the exact install/fix command.
+- Do not continue until the user confirms it is fixed.
+
+Run these checks in order:
+
+### 1a. Confirm required commands are available
+
+Run:
+
+```
+pwsh --version
+git --version
+gh --version
+python --version
+pip --version
+node --version
+npm --version
+tsp-client --version
+```
+
+If any command is missing, stop and show the matching install command:
+- PowerShell: `winget install --id Microsoft.PowerShell --source winget`
+- Git: `winget install --id Git.Git --source winget`
+- GitHub CLI: `winget install --id GitHub.cli --source winget`
+- Python 3: `winget install --id Python.Python.3 --source winget`
+- Node.js LTS (includes npm): `winget install --id OpenJS.NodeJS.LTS --source winget`
+- TypeSpec client generator: `npm install -g @azure-tools/typespec-client-generator-cli`
+
+### 1b. Confirm working directory
+
+Run:
+
+```
+git rev-parse --show-toplevel
+git rev-parse --show-prefix
+```
+
+Expected:
+- `git rev-parse --show-prefix` returns exactly `sdk/ai/azure-ai-projects/`
+
+If not, stop and ask the user to switch to the `sdk/ai/azure-ai-projects` folder.
+
+### 1c. Confirm Python version is supported
+
+Run:
+
+```
+python -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)"
+```
+
+If this fails, stop and ask the user to install or activate Python 3.9+.
+
+### 1d. Confirm GitHub CLI authentication
+
+Run:
+
+```
+gh auth status
+```
+
+If not authenticated, stop and ask the user to run:
+
+```
+gh auth login
+```
+
+### 1e. Confirm Git identity is configured
+
+Run:
+
+```
+git config user.name
+git config user.email
+```
+
+If either value is empty, stop and ask the user to run:
+
+```
+git config user.name "<your-name>"
+git config user.email "<your-email>"
+```
+
+### 1f. Confirm repository is clean
+
+Run:
+
+```
+git status --porcelain
+```
+
+If output is not empty, stop and ask the user to commit/stash/discard local changes before continuing.
+
+### 1g. Install development dependencies
+
+Run:
+
+```
+python -m pip install -r dev_requirements.txt
+```
+
+If this command fails, stop and report the error to the user.
+
+Important:
+- Azure CLI (`az`) is not required for this skill workflow and must not be checked in preflight.
+- Do not proceed to Step 2 until all required preflight checks pass.
+
+---
+
+## Step 2: Gather information from the user
 
 Ask the user the following questions **one at a time**, waiting for each answer before proceeding.
 
-### 1a. Topic branch name
+### 2a. Topic branch name
 
 Ask the user to choose **one** of the following two options for the target topic branch:
 
 1. **Create a new topic branch (with default branch name)**  – Create a new topic branch for the emitted changes. If selected, this default branch name will be used "<github-userid>/<emit-from-typespec-DD-MM-HH-MM>", where `github-userid` is the user's personal GitHub ID (not the Microsoft Enterprise Managed User (EMU) account!) and `DD-MM-HHMM` is the current date-time using date, month, hour and minute. For example, if the GitHub ID is "dargilco" and the current date and time is May 1st, 2026 at 8:13am, the default branch name would be `dargilco/emit-from-typespec-01-05-0813`. This should be the default option, and the default branch name should be displayed. If you press enter without typing anything, this option will be selected.
 
-2. **Create a new topic branch (branch name given by user)** - Ask the user for the branch name. Mention that a common format is "<github-userid>/<work-title>". If the user enters a branch name `feature/azure-ai-projects/2.3.0` then stop and report that they cannot emit directly to the current feature branch.
+2. **Create a new topic branch (branch name given by user)** - Ask the user for the branch name. Mention that a common format is "<github-userid>/<work-title>". If the user enters a branch name `feature/azure-ai-projects/vnext` then stop and report that they cannot emit directly to the current feature branch.
 
-3. **Emit to current branch** – Emit directly to the current branch without creating a new topic branch. This is not common, but may be necessary if the user is re-running this workflow because of a previous failure, where the topic branch was already created. If the current branch is named `feature/azure-ai-projects/2.3.0` then stop and report that they cannot emit directly to the current feature branch.
+3. **Emit to current branch** – Emit directly to the current branch without creating a new topic branch. This is not common, but may be necessary if the user is re-running this workflow because of a previous failure, where the topic branch was already created. If the current branch is named `feature/azure-ai-projects/vnext` then stop and report that they cannot emit directly to the current feature branch.
 
-### 1b. TypeSpec source
+### 2b. TypeSpec source
 
 Ask the user to choose **one** of the following three options for the TypeSpec source:
 
@@ -44,7 +158,7 @@ Ask the user to choose **one** of the following three options for the TypeSpec s
 
 ---
 
-## Step 2: Record the current branch
+## Step 3: Record the current branch
 
 Before creating the topic branch, record the name of the **current Git branch**. This is the branch that the topic branch will be created from, and the branch the PR will target.
 
@@ -56,7 +170,7 @@ Save this as `BASE_BRANCH`.
 
 ---
 
-## Step 3: Create the topic branch
+## Step 4: Create the topic branch
 
 Create the topic branch off the current branch and switch to it:
 
@@ -65,11 +179,11 @@ git fetch
 git switch -c <topic-branch> origin/<BASE_BRANCH>
 ```
 
-Replace `<topic-branch>` with the name provided by the user in Step 1a.
+Replace `<topic-branch>` with the name provided by the user in Step 2a.
 
 ---
 
-## Step 4: Emit SDK from TypeSpec
+## Step 5: Emit SDK from TypeSpec
 
 If you are emitting from latest commit or a given commit number, edit file `tsp-location.yaml` to update the full hash commit number, then in the folder `sdk/ai/azure-ai-projects` run the command: `tsp-client update --debug`
 
@@ -81,7 +195,7 @@ Note:
 
 ---
 
-## Step 5: Revert changes to files pyproject.toml and MANIFEST.in
+## Step 6: Revert changes to files pyproject.toml and MANIFEST.in
 
 After the emit, there will be changes to `pyproject.toml` and `MANIFEST.in` that are not needed. Revert any changes to these files by running:
 
@@ -91,7 +205,7 @@ git restore pyproject.toml MANIFEST.in
 
 ---
 
-## Step 6: Commit and push
+## Step 7: Commit and push
 
 Stage all changes (excluding file names that start with `.env`), commit, and push the topic branch:
 
@@ -105,7 +219,7 @@ git push -u origin <topic-branch>
 
 ---
 
-## Step 7: Run post-emitter fixes
+## Step 8: Run post-emitter fixes
 
 After a successful emit, run the PowerShell script named `PostEmitter.ps1` located in the `sdk/ai/azure-ai-projects` folder.
 
@@ -115,7 +229,7 @@ This script applies azure-ai-projects specific corrections to the emitted code (
 
 ---
 
-## Step 8: Commit and push
+## Step 9: Commit and push
 
 Stage all changes (excluding file names that start with `.env`), commit, and push the topic branch:
 
@@ -129,7 +243,7 @@ git push -u origin <topic-branch>
 
 ---
 
-## Step 9: Fix patched code related to preview feature headers
+## Step 10: Fix patched code related to preview feature headers
 
 The emitted code may have introduced another beta sub-client (a new property on class `BetaOperations`). It may have also added another enum value to the existing internal class `_FoundryFeaturesOptInKeys`. This means that the client library needs to set a new HTTP request header when making REST API calls to the service, to opt-in to the new service features which are still in preview. If that's the case, do the following:
 
@@ -145,7 +259,7 @@ Important: Under the `azure\ai\projects` folder, you are only allowed to edit Py
 
 ---
 
-## Step 10: Update samples and tests
+## Step 11: Update samples and tests
 
 If there were any breaking changes in existing APIs, like class or method renames:
 * update the patched code accordingly in the client library to reflect those changes. Changes should be made to Python source file names that start with "_patch", under the `azure\ai\projects` folder.
@@ -154,13 +268,13 @@ If there were any breaking changes in existing APIs, like class or method rename
 
 ---
 
-## Step 11: Install package from sources
+## Step 12: Install package from sources
 
 In the folder `sdk\ai\azure-ai-projects`, run `pip install -e .` to install the package from sources. If there are any errors, stop and report the error to the user. Do not continue.
 
 ---
 
-## Step 12: Run `apiview-stub-generator` to update api.md and api.metadata.yml files
+## Step 13: Run `apiview-stub-generator` to update api.md and api.metadata.yml files
 
 In the folder `sdk\ai\azure-ai-projects`, run the following command:
 
@@ -178,7 +292,7 @@ rmdir /s /q build
 
 ---
 
-## Step 13: Commit and push
+## Step 14: Commit and push
 
 Stage all changes (excluding file names that start with `.env`), commit, and push the topic branch:
 
@@ -192,9 +306,9 @@ git push -u origin <topic-branch>
 
 ---
 
-## Step 14: Create a Pull Request
+## Step 15: Create a Pull Request
 
-Create a draft PR from the **topic branch** to the **base branch** (recorded in Step 2):
+Create a draft PR from the **topic branch** to the **base branch** (recorded in Step 3):
 
 ```
 gh pr create --draft --base <BASE_BRANCH> --head <topic-branch> --assignee @me --title "<PR title>" --body "<PR body>"
@@ -205,23 +319,8 @@ gh pr create --draft --base <BASE_BRANCH> --head <topic-branch> --assignee @me -
 
 You must show the user the resulting PR URL on screen when done, before you continue to the next step.
 
-Open a new tab in the default browser and navigate to the PR URL.
+Open a new tab in the default operating system browser and navigate to the PR URL (do not use the built-in browser in VS Code, if running this skill in the VS Code GitHub CoPilot chat window). 
 
 ---
 
-## Step 15: Optionally run tests locally
-
-Prompt the user with this message: "Tests will run as part of the Pull Request. However, you can optionally run tests locally in a Python virtual environment, right now. It will take a few minutes. Do you want to run tests locally? (yes/no)"
-
-If the user answers "yes", run all tests from recordings. Follow these guidelines:
-* Run tests in a local Python virtual environment. Create this virtual environment if it does not already exists:
-  ```
-  python -m venv .venv
-  ```
-  and activate it:
-  ```
-  .venv\Scripts\activate
-  ```
-* Show test progress on screen, as tests are run.
-
 
@@ -56,7 +56,7 @@ From the JSON response:
 
 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 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
 
 ---

@@ -1,5 +1,42 @@
 # Release History
 
+## 2.4.0 (2026-07-24)
+
+### Features Added
+
+* New stable toolbox tool `ToolSearchToolboxTool` (discriminator `toolbox_search`) for storing a tool-search tool in a toolbox.
+This replaces `ToolboxSearchPreviewToolboxTool`, which is still present but will be removed in a future release of the package. Please migrate your code to use the stable tool.
+* New class `TaskGenerationDataGenerationJobOptions` (discriminator `task_generation`) with data generation job options for multi-turn evaluation scenarios.
+* Support for non-fatal input-quality advisories from rubric evaluator generation. See new class `RubricGenerationInputQualityWarning` and new enums `RubricGenerationInputQualityWarningCode`, `RubricGenerationInputQualityWarningSeverity`, and `RubricGenerationInputQualityWarningSource`.
+* New enum `GenerationWarningType`.
+* New enum `AgentIdentityStatus` and new optional `status` property on class `AgentIdentity`.
+* New read-only property `input_quality_warnings` on class `EvaluatorGenerationJob`.
+* New read-only properties `generation_job_id` and `warnings` on class `EvaluatorVersion`.
+* New optional property `max_stalls` on class `OptimizationOptions`.
+
+### Breaking Changes
+
+Breaking changes in beta methods:
+* Method `.beta.evaluators.create_generation_job` renamed to `.beta.evaluators.begin_create_generation_job` and is now a long-running operation returning `LROPoller[EvaluatorVersion]` (previously returned `EvaluatorGenerationJob`).
+* Method `.beta.datasets.create_generation_job` renamed to `.beta.datasets.begin_create_generation_job` and is now a long-running operation returning `LROPoller[DataGenerationJobResult]`.
+* Method `.beta.agents.create_optimization_job` renamed to `.beta.agents.begin_create_optimization_job` and is now a long-running operation returning `LROPoller[OptimizationJobResult]`.
+
+### Sample updates
+
+* Added new optimization polling samples `sample_optimization_job_basic_polling.py` and `sample_optimization_job_basic_polling_async.py` under `samples/agents/optimization/`.
+* Added new evaluation samples `sample_endpoint_evaluator_with_api_key.py` and `sample_endpoint_evaluator_with_entra_id.py` under `samples/evaluations/`.
+* Added new Hosted Agent sample `sample_agent_user_identity_isolation.py` under `samples/hosted_agents/`, demonstrating per-user response-chain isolation with delegated end-user identities sent in the `x-ms-user-identity` header.
+* Added new Hosted Agent routine samples `sample_routines_with_github_issue_trigger.py` and `sample_routines_with_teams_message_trigger.py`, demonstrating GitHub issue and Microsoft Teams channel-message triggers for routines backed by a temporary Hosted Agent version.
+* Added new Hosted Agent sample `sample_toolbox_with_reminder_preview.py` under `samples/hosted_agents/`, demonstrating a Reminder Preview toolbox tool wired through a Foundry Toolbox MCP endpoint.
+* Updated Hosted Agent toolbox asset `samples/hosted_agents/assets/toolbox-agent/main.py` to use `FoundryToolbox` and `as_skills_provider()` for toolbox MCP skill discovery and wiring, replacing the earlier manual MCP session, auth, and HTTP client setup.
+* Renamed toolbox tool-search samples `sample_toolboxes_with_search_preview.py` and `sample_toolboxes_with_search_preview_async.py` to `sample_toolboxes_with_search.py` and `sample_toolboxes_with_search_async.py`.
+* Renamed the Hosted Agent image-based creation samples from `sample_create_hosted_agent.py` and `sample_create_hosted_agent_async.py` to `sample_create_hosted_agent_from_image.py` and `sample_create_hosted_agent_from_image_async.py`.
+* Relocated Hosted Agent routine trigger samples `sample_routines_with_dispatch.py`, `sample_routines_with_schedule_trigger.py`, and `sample_routines_with_timer_trigger.py` from `samples/routines/` to `samples/hosted_agents/`.
+* Removed Hosted Agent endpoint samples `sample_agent_endpoint.py` and `sample_agent_endpoint_async.py`.
+* Removed routine sample `samples/routines/sample_routines_crud.py`.
+* Removed prompt-agent toolbox skill sample `samples/agents/tools/sample_agent_toolbox_skill.py` because skill-in-toolbox is not yet supported in Prompt Agents.
+* Updated Hosted Agent toolbox samples to create temporary Hosted Agent versions for execution flows, assign Azure AI User RBAC before invoking Toolbox MCP endpoints, restore the prior endpoint, and clean up temporary resources during teardown.
+
 ## 2.3.0 (2026-07-01)
 
 ### Features Added

@@ -24,9 +24,8 @@ resources in your [Microsoft Foundry](https://ai.azure.com/) Project. Use it to:
   * Model Context Protocol (MCP)
   * OpenAPI
   * Reminder Tool (Preview)
-  * Toolbox Search (Preview)
+  * Toolbox Search
   * Web Search
-  * Web Search (Preview)
   * Work IQ (Preview)
 * **Get an OpenAI client** using `.get_openai_client()` method to run Responses, Conversations, Evaluations and Fine-Tuning operations with your Agent.
 * **Create and version toolboxes** that bundle collections of tools and skills for your agents, using `.toolboxes` operations.