Add sample routines for hosted agents with various triggers

[howieleung]

Description

Please add an informative description that covers that changes made by the pull request and link all relevant issues.

If an SDK is being regenerated based on a new API spec, a link to the pull request containing these API spec changes should be included above.

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
9 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]

Pull request overview

Updates hosted-agent routine samples to self-provision temporary agent versions and adds GitHub issue trigger coverage.

Changes:

• Adds a GitHub issue-triggered routine sample.
• Makes existing routine samples create and clean up temporary hosted-agent versions.
• Documents required model and trigger configuration.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
sample_routines_with_timer_trigger.py	Self-provisions an agent for timer routines.
sample_routines_with_schedule_trigger.py	Self-provisions an agent for scheduled routines.
sample_routines_with_github_issue_trigger.py	Adds GitHub issue-triggered routine usage.
sample_routines_with_dispatch.py	Self-provisions an agent for dispatched routines.
sample_routines_crud.py	Self-provisions an agent for CRUD demonstrations.

Comments suppressed due to low confidence (3)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:74

• The temporary agent version is cleaned up when this context exits, but the routine is deleted only on the normal path. Any polling/service error or KeyboardInterrupt after creation leaves an enabled timer routine behind while restoring/deleting the agent version it was intended to invoke. Wrap the routine lifecycle in try/finally, as the schedule-trigger sample does, so the routine is deleted before this context unwinds.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:79
• The temporary agent version is cleaned up when this context exits, but the routine is deleted only on the normal path. If dispatching or polling raises, the sample leaves a stale routine behind after restoring/deleting its backing agent version. Please protect the routine lifecycle with try/finally, matching the schedule-trigger sample's cleanup pattern.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_crud.py:72
• The new temporary hosted-agent context always removes/restores its version, but the routine cleanup remains normal-path only. If any CRUD call fails after creation, this leaves a routine referring to an agent whose temporary version has already been removed. Please place routine deletion in a finally block inside this context.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:77

• This sample is automatically included by test_hosted_agents_samples, but servicePreparer does not define GITHUB_CONNECTION_NAME, GITHUB_USERNAME, or GITHUB_REPOSITORY. The sample test will therefore raise KeyError while importing this module. Exclude this externally triggered sample from the hosted-agent parametrization, or add a dedicated test configuration that supplies all three values.

github_connection_name = os.environ["GITHUB_CONNECTION_NAME"]
poll_interval_seconds = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))

github_owner = os.environ["GITHUB_USERNAME"]
github_repository = os.environ["GITHUB_REPOSITORY"]

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:83

• If dispatching or polling raises, this context manager deletes the temporary hosted-agent version while the routine created below is never deleted, leaving a routine bound to a removed/restored agent route. Wrap routine creation and use in try/finally and delete the routine in the finally block before this context exits, as the schedule-trigger sample does.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_crud.py:76
• If any CRUD operation raises, this context manager still deletes the temporary hosted-agent version, but the routine created below remains and points at a removed/restored agent route. Put the routine lifecycle in try/finally and delete the routine in finally before the hosted-agent context exits.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:78
• If routine creation or polling raises, the temporary hosted-agent version is cleaned up by this context manager but the timer routine is left behind, bound to a removed/restored agent route. Protect the routine lifecycle with try/finally and delete the routine in finally before exiting this context.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:41

• The sample describes this value as a repository name but tells users to provide a full clone URL, while owner is supplied separately to GitHubIssueRoutineTrigger. This makes the required filter format ambiguous and can cause the trigger never to match. Please document the exact service-accepted value (repository name/slug versus URL) consistently.

    6) GITHUB_REPOSITORY - The GitHub repository name in the format of https://github.com/xxx/xxx.git.

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:125

• This inline comment is not Black-formatted (two spaces are required before it), and the sentence is ungrammatical. This newly added sample can therefore fail formatting validation.

                    connection_id=github_connection_name, # currently it accept connection name

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:77

• Opening the zip stream at module import makes main() one-shot: the first call closes the stream, so a second call uploads from a closed file, and importing without calling main() leaks the open handle. Create the stream inside main(), as the new GitHub-trigger sample does.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:41

• owner is supplied separately to GitHubIssueRoutineTrigger, so repository should be only the repository name. Following the documented full-URL format passes that URL unchanged as the repository filter and can prevent the trigger from matching issues.

    6) GITHUB_REPOSITORY - The GitHub repository name in the format of https://github.com/xxx/xxx.git.

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:125

• Correct the grammar in this explanatory comment.

                    connection_id=github_connection_name, # currently it accept connection name

sdk/ai/azure-ai-projects/tests/samples/test_samples.py:305

• Correct the grammar and GitHub capitalization in this skip reason.

                "sample_routines_with_github_issue_trigger.py",  # Cannot run without interact on Github

[github-actions]

[Pilot] PR Pipeline Failure Analysis

A CI pipeline failed on this pull request. Here is an automated analysis of what went wrong and how to get the build green.

What failed

A single test — TestSamples.test_hosted_agents_samples[sample_routines_crud] — is failing across all platforms and all packaging modes (mindependency, whl, sdist) on macOS 3.11, Ubuntu 3.10 (including coverage), Ubuntu 3.13, Ubuntu 3.14, and Windows 3.12. Because the failure is reproducible everywhere (not isolated to one agent or OS), this is a test/code failure, not an infrastructure fluke. The failing test exercises the sample_routines_crud sample introduced by this PR.

Recommended next steps

• Run the failing test locally: pytest sdk/ai/azure-ai-projects/tests/samples/test_samples.py -k sample_routines_crud -v to reproduce and inspect the failure message.
• Review the sample file added/modified in this PR (likely sdk/ai/azure-ai-projects/samples/agents/ for the routines CRUD sample) and ensure it matches the current SDK API for hosted-agent routines.
• Check that any new client methods, request/response models, or imports referenced by the sample are present in the package being tested.
• If the sample relies on a live service call that is expected to be recorded, verify the test recording is present and up to date.
• See the CI troubleshooting guide: https://aka.ms/ci-fix
• Push new commits to address the failures; this comment updates automatically on the next failing run.

Raw pipeline analysis (azsdk ci analyze)

Analyzing pipeline https://github.com/Azure/azure-sdk-for-python/pull/48121...
--------------------------------------------------------------------------------
Failed Tests
--------------------------------------------------------------------------------
Failing test (all platforms & packaging modes):
  sdk.ai.azure-ai-projects.tests.samples.test_samples.TestSamples.test_hosted_agents_samples[sample_routines_crud]

Affected jobs:
  - macos311        (mindependency, whl, sdist)
  - ubuntu2404_310_coverage (mindependency, whl, sdist)
  - ubuntu2404_310  (mindependency, whl, sdist)
  - Ubuntu2404_313  (mindependency, whl, sdist)
  - Ubuntu2404_314  (mindependency, whl, sdist)
  - windows2022_312 (mindependency, whl, sdist)

Copilot detected the failing pipeline and generated the analysis above. To have it attempt a fix automatically, reply with @copilot please fix the failing pipeline on this PR.

Generated by Pipeline Analysis - Next Steps · 19.2 AIC · ⌖ 6.19 AIC · ⊞ 6.6K · ◷

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (7)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:77

• select_basic_agent_code_zip immediately opens the generated zip stream, but this happens at module import while only main() closes it. Importing the sample without calling main() leaks the descriptor, and calling main() twice reuses a closed stream. Create the stream inside main(), as the new GitHub sample does.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:74
• Once this context is added, an exception or Ctrl+C after the routine is created exits the helper and deletes the temporary agent version, but the routine deletion at the bottom is skipped. That leaves a timer routine referring to a restored/deleted agent setup. Wrap the routine lifecycle in try/finally and delete the routine in the finally, as the schedule sample does.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:79
• An exception or Ctrl+C after routine creation skips the bottom-of-file delete. The newly added helper context still restores the endpoint and deletes the temporary agent version, leaving the dispatch routine orphaned. Put routine cleanup in a finally block, matching the schedule and GitHub samples.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:53
• This newly added hosted-agent setup calls the stable project_client.agents.create_version_from_code API through the helper, but that API moved from .beta.agents only in 2.3.0 (CHANGELOG.md:9). The sample still tells users to install azure-ai-projects>=2.2.0, so that documented environment cannot run the sample; raise the prerequisite to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:57
• This newly added hosted-agent setup uses the stable .agents.create_version_from_code path through the helper, which became available in 2.3.0 (CHANGELOG.md:9). The sample's prerequisite remains azure-ai-projects>=2.2.0, so update it to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:57
• The added hosted-agent setup invokes stable .agents.create_version_from_code via the helper, but that API moved from .beta.agents in 2.3.0 (CHANGELOG.md:9). Keeping the documented azure-ai-projects>=2.2.0 minimum makes the sample fail for users on that version; raise it to 2.3.0.
  sdk/ai/azure-ai-projects/tests/samples/test_samples.py:305
• Use the product name's canonical capitalization and make the skip reason grammatical.

                "sample_routines_with_github_issue_trigger.py",  # Cannot run without interact on Github

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:79

• If any operation after routine creation raises (including dispatch, list_runs, or Ctrl+C), this context manager deletes the temporary hosted-agent version while the routine deletion at the end is skipped. That leaves a live routine targeting a deleted version. Put the routine lifecycle in a try/finally and tolerate ResourceNotFoundError during cleanup, as the schedule-trigger sample does.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:74
• If routine creation succeeds and polling later raises or is interrupted, this context manager removes the temporary hosted-agent version but the routine deletion at the end is never reached. The remaining timer routine then targets a deleted version. Wrap the routine lifecycle in a try/finally and tolerate ResourceNotFoundError during cleanup, matching the schedule-trigger sample.
  sdk/ai/azure-ai-projects/samples/routines/sample_routines_crud.py:1
• Deleting this sample leaves the current unreleased CHANGELOG entry (CHANGELOG.md:47) claiming that sample_routines_crud.py is being added. Please either retain/move the sample or update the release notes so they do not point users to a nonexistent file.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:10
• The unreleased CHANGELOG has a dedicated “Sample updates” list (CHANGELOG.md:41-52) but does not mention this newly added GitHub issue-trigger sample. Add an entry so the new user-facing sample is included in the package release notes.

    This sample demonstrates how to create a Routine that fires when a GitHub
    issue is opened in a GitHub repository.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (7)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:34

• This sample now calls create_version_from_code, whose helper uses the stable project_client.agents.create_version_from_code API. The package changelog documents that API as moving from .beta.agents to .agents in 2.3.0, but this sample still tells users that 2.2.0 is sufficient. Following the documented install command can therefore fail; raise the minimum version to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:36
• This sample now calls create_version_from_code, whose helper uses the stable project_client.agents.create_version_from_code API. The package changelog documents that API as moving from .beta.agents to .agents in 2.3.0, but this sample still tells users that 2.2.0 is sufficient. Following the documented install command can therefore fail; raise the minimum version to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:38
• This sample now calls create_version_from_code, whose helper uses the stable project_client.agents.create_version_from_code API. The package changelog documents that API as moving from .beta.agents to .agents in 2.3.0, but this sample still tells users that 2.2.0 is sufficient. Following the documented install command can therefore fail; raise the minimum version to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:83
• The routine is deleted only on the success path, while this new context manager always restores/deletes the temporary hosted-agent version during unwinding. Any dispatch, polling, or interruption error leaves an enabled routine behind after its intended agent version is removed (or after routing is restored to a pre-existing version). Wrap the routine lifecycle in try/finally, as the schedule and GitHub samples do, so the routine is always deleted before this context exits.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:78
• The routine is deleted only on the success path, while this new context manager always restores/deletes the temporary hosted-agent version during unwinding. Any polling or interruption error leaves an enabled timer routine behind after its intended agent version is removed (or after routing is restored to a pre-existing version). Wrap the routine lifecycle in try/finally, as the schedule and GitHub samples do, so the routine is always deleted before this context exits.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:10
• This adds a new user-facing GitHub-trigger sample and the PR also removes the CRUD sample, but CHANGELOG.md has no entry for either change. Add an unreleased sample-updates entry so the package history reflects the added and removed samples, as required for significant SDK changes.

"""
DESCRIPTION:
    This sample demonstrates how to create a Routine that fires when a GitHub
    issue is opened in a GitHub repository.

sdk/ai/azure-ai-projects/tests/samples/test_samples.py:305

• Use “Cannot run without interaction on GitHub” for correct grammar and product capitalization.

                "sample_routines_with_github_issue_trigger.py",  # Cannot run without interact on Github

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:74

• This newly added setup calls create_version_from_code, whose helper uses the stable project_client.agents.create_version_from_code API. That API moved to .agents in 2.3.0 (CHANGELOG.md:9), but this sample still instructs users to install azure-ai-projects>=2.2.0; a 2.2.x environment will fail before the routine runs. Please raise the sample's documented minimum to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:85
• This newly added setup calls create_version_from_code, whose helper uses the stable project_client.agents.create_version_from_code API. That API moved to .agents in 2.3.0 (CHANGELOG.md:9), but this sample still instructs users to install azure-ai-projects>=2.2.0; a 2.2.x environment will fail before the routine runs. Please raise the sample's documented minimum to 2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:79
• This newly added setup calls create_version_from_code, whose helper uses the stable project_client.agents.create_version_from_code API. That API moved to .agents in 2.3.0 (CHANGELOG.md:9), but this sample still instructs users to install azure-ai-projects>=2.2.0; a 2.2.x environment will fail before the routine runs. Please raise the sample's documented minimum to 2.3.0.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:40

• The new hosted-agent setup uses the stable project_client.agents.create_version_from_code API through create_version_from_code, but this sample still tells users to install 2.2.0. In 2.2.0 that operation was under .beta.agents and had the older signature (see CHANGELOG.md:7-9,28), so following these prerequisites causes the sample to fail. Require azure-ai-projects>=2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:36
• The new hosted-agent setup uses the stable project_client.agents.create_version_from_code API through create_version_from_code, but this sample still tells users to install 2.2.0. In 2.2.0 that operation was under .beta.agents and had the older signature (see CHANGELOG.md:7-9,28), so following these prerequisites causes the sample to fail. Require azure-ai-projects>=2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:39
• The new hosted-agent setup uses the stable project_client.agents.create_version_from_code API through create_version_from_code, but this sample still tells users to install 2.2.0. In 2.2.0 that operation was under .beta.agents and had the older signature (see CHANGELOG.md:7-9,28), so following these prerequisites causes the sample to fail. Require azure-ai-projects>=2.3.0.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:41
• GitHubIssueRoutineTrigger takes owner and repository separately, so repository must be the repository name (for example, azure-sdk-for-python), not a full clone URL. Following the documented URL format sends the wrong repository filter and the issue event will not match.

    6) GITHUB_REPOSITORY - The GitHub repository name in the format of https://github.com/xxx/xxx.git.

sdk/ai/azure-ai-projects/tests/samples/test_samples.py:305

• Use the correct GitHub capitalization and replace the ungrammatical skip reason.

                "sample_routines_with_github_issue_trigger.py",  # Cannot run without interact on Github

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (7)

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:74

• This context manager always deletes the temporary hosted-agent version on exit, but the routine is deleted only on the happy path at line 144. If dispatch polling raises or the user interrupts after create_or_update, the sample leaves a timer routine referencing a deleted agent version. Put the routine lifecycle in a try/finally, as the schedule and GitHub-trigger samples do.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:79
• This context manager always deletes the temporary hosted-agent version on exit, but the routine is deleted only on the happy path at line 162. If dispatch or polling raises, the sample leaves a routine referencing a deleted agent version. Put the routine lifecycle in a try/finally, as the schedule and GitHub-trigger samples do.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_github_issue_trigger.py:41
• The trigger already receives the owner separately, and repository expects a repository filter/name rather than a full GitHub URL. A user following this URL example will pass the wrong value to GitHubIssueRoutineTrigger, so document a repository-name example instead.

    6) GITHUB_REPOSITORY - The GitHub repository name in the format of https://github.com/xxx/xxx.git.

sdk/ai/azure-ai-projects/tests/samples/test_samples.py:305

• Correct the grammar and GitHub capitalization in this skip reason.

                "sample_routines_with_github_issue_trigger.py",  # Cannot run without interact on Github

sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_timer_trigger.py:34

• Because this newly required model setting is used by the temporary hosted agent created through stable project_client.agents.create_version_from_code, the installation instruction above must require 2.3.0, where that method moved from .beta.agents. An existing 2.2.0 installation currently satisfies the documented command but cannot run this updated sample.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_schedule_trigger.py:36
• Because this newly required model setting is used by the temporary hosted agent created through stable project_client.agents.create_version_from_code, the installation instruction above must require 2.3.0, where that method moved from .beta.agents. An existing 2.2.0 installation currently satisfies the documented command but cannot run this updated sample.
  sdk/ai/azure-ai-projects/samples/hosted_agents/sample_routines_with_dispatch.py:38
• Because this newly required model setting is used by the temporary hosted agent created through stable project_client.agents.create_version_from_code, the installation instruction above must require 2.3.0, where that method moved from .beta.agents. An existing 2.2.0 installation currently satisfies the documented command but cannot run this updated sample.