[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699AYC9RP61G590BTPCQ26A":3,"skill-same:01M699AYC9RP61G590BTPCQ26A":73},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":54,"ownerHtmlUrl":55,"ownerBlogUrl":56,"ownerDescription":57,"updatedAt":58,"install":59,"resources":72},"01M699AYC9RP61G590BTPCQ26A","agent-framework-py-release",null,"Use when cutting a Python release for the microsoft\u002Fagent-framework monorepo. Triggers on \"bump py versions\", \"cut a python release\", \"prepare release PR for python\", \"release py packages\", \"bump python to X.Y.Z\", or similar requests to bump Python package versions and prepare a release PR. Handles all four lifecycle tiers with CHANGELOG-driven selective bumps, a reviewed batch manifest, dependency checks, and the protected Azure DevOps release handoff.","microsoft\u002Fagent-framework","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M6999R99RF2DY8AXYFS5HZRM",14676,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fpython\u002F.github\u002Fskills\u002Fagent-framework-py-release\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,9],"agent framework","agent framework py release","release","framework","triggers","lifecycle","for","pr","cut","dependency","changelog","prepare release","packages","batch","when","azure devops","bump","monorepo","python","handoff","2026-11-10 10:12:30",false,"---\nname: agent-framework-py-release\ndescription: Use when cutting a Python release for the microsoft\u002Fagent-framework monorepo. Triggers on \"bump py versions\", \"cut a python release\", \"prepare release PR for python\", \"release py packages\", \"bump python to X.Y.Z\", or similar requests to bump Python package versions and prepare a release PR. Handles all four lifecycle tiers with CHANGELOG-driven selective bumps, a reviewed batch manifest, dependency checks, and the protected Azure DevOps release handoff.\n---\n\n# Agent Framework Python Release\n\nCuts a Python release PR for the `microsoft\u002Fagent-framework` monorepo.\n\nRelease preparation does **not** authorize production tags, draft creation, publication, or deployment. Stop at the\nrequested PR unless a maintainer separately authorizes the release handoff below.\n\n## Core principle: CHANGELOG drives bumps\n\n**No more universal lockstep.** A package only bumps if it has a CHANGELOG entry this cycle. Draft the CHANGELOG first, then derive the bump list from it.\n\nExceptions to selective bumping (these stay coupled regardless of per-package changes):\n\n- **Root `agent-framework` is coupled to `agent-framework-core` via `agent-framework-core[all]==X.Y.Z`** (exact pin in `python\u002Fpyproject.toml`). If `core` bumps, root bumps. Root may also bump independently for its own changes (docs\u002Fmetadata\u002Fextras).\n- **Beta-tier cohort bumps are still allowed** when the user explicitly wants a fresh date stamp across all betas for cohort signaling — but this is a deliberate user decision per release, not a default.\n\nIf the user explicitly states which packages to bump (or hands over a PR list per package), treat that as authoritative.\n\n## Lifecycle tiers and version rules\n\nUse `python\u002F.github\u002Fskills\u002Fpython-package-management\u002FSKILL.md` as the source of truth for lifecycle\nversion patterns, date-stamp cutoffs, classifier alignment, and internal dependency updates.\n\nFor release work, derive the live tier map at release time from `python\u002FPACKAGE_STATUS.md` and the actual\n`version =` lines in each `pyproject.toml`. Do not hardcode counts — packages move between tiers.\n\n## Inputs to confirm before bumping\n\n1. **The changeset**: explicit commits\u002FPRs the release covers, OR derive from `git log ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002F`.\n2. **Per-package CHANGELOG entries**: which packages will get a line in the new release section. This list IS the bump list.\n3. **Per-released-package semver bump**: for each released-tier package that has a CHANGELOG entry, decide PATCH \u002F MINOR \u002F MAJOR.\n4. **Date stamp** (only if any alpha\u002Fbeta is being bumped): default from the `python-package-management`\n   date-stamp rule.\n5. **Optional cohort bump?**: ask if betas should all get a new date stamp regardless of per-package changes. Default: no.\n\nIf the user states target versions or a date explicitly, use exactly what they said — do not \"correct\" based on historical timezones.\n\n## Non-negotiable rules\n\n- **Release workflow owns the CHANGELOG**: individual feature\u002Ffix PRs do not edit\n  `python\u002FCHANGELOG.md`; this workflow creates the entries centrally from merged changes.\n- **CHANGELOG-driven bumps**: only packages mentioned in the new CHANGELOG section get version bumps. Exceptions: root follows core (==pin); user-opted cohort bump on betas.\n- **Follow `python-package-management` for package lifecycle and versioning rules** — do not duplicate those\n  rules in this release workflow.\n- **No `Co-Authored-By` trailer** on any commit.\n- **Use `uv run`** for cross-version Python\u002FPoe commands and add the relevant\n  `tooling\u002Frequirements-*.txt` bundle only for single-version tools.\n- **Never rename an existing CHANGELOG section header** during a new release cut. Only INSERT a new section above existing ones.\n- **Footer reference links are part of the CHANGELOG edit**, not optional.\n- **One batch, one overall tag, one Azure DevOps run.** Generate `python\u002F.github\u002Frelease-\u003Cfulltag>.json` in the same\n  version-bump PR. Keep earlier per-tag manifests unchanged for browsing release-batch history.\n  Never replace the reviewed selection with \"all versions absent from PyPI\", per-package tags, or one run per package.\n- **Azure DevOps is the only production publisher.** GitHub has no Azure DevOps API credentials or federated queue\n  permission. The GitHub release workflow is read-only validation; local production `publish` tasks are retired.\n\n## Workflow\n\n### 1. Orient and create branch\n\n```bash\ngit fetch origin main --tags --quiet\ngit fetch upstream main --tags --quiet 2>\u002Fdev\u002Fnull || true\ngit status\n\n# Fork clones use upstream\u002Fmain as the authoritative release base; direct clones use origin\u002Fmain.\nif git show-ref --verify --quiet refs\u002Fremotes\u002Fupstream\u002Fmain; then\n  RELEASE_BASE=upstream\u002Fmain\nelse\n  RELEASE_BASE=origin\u002Fmain\nfi\ngit log -1 --oneline \"$RELEASE_BASE\"\n```\n\nIf the user already has a `bump-py-ver-release-*` branch checked out, use it. Otherwise:\n\n```bash\ngit checkout -b bump-py-ver-release-YYMMDD \"$RELEASE_BASE\"\n```\n\n### 2. Build the live tier map\n\nRead `python\u002FPACKAGE_STATUS.md` to enumerate current packages and lifecycle stages, and `grep '^version' python\u002Fpyproject.toml python\u002Fpackages\u002F*\u002Fpyproject.toml` to confirm actual versions. Cross-reference — if `PACKAGE_STATUS.md` shows a package as `beta` but its version looks like `1.0.0aYYMMDD`, surface the inconsistency before proceeding.\n\nWatch for: new packages added since the last release, lifecycle transitions (alpha→beta, beta→rc, rc→released), and stale packages that haven't been touched in many cycles.\n\n### 3. Identify changeset\n\nUse the LATEST released tag as the compare base:\n\n```bash\nLAST_RELEASED_TAG=$(\n  git tag -l 'python-*' \\\n    | uv run --directory python python -c 'import re, sys; tags=[t.strip() for t in sys.stdin if re.fullmatch(r\"python-\\d+\\.\\d+\\.\\d+\", t.strip())]; print(max(tags, key=lambda t: tuple(map(int, t[7:].split(\".\")))))'\n)\necho \"Compare base: $LAST_RELEASED_TAG\"\n```\n\nList commits and packages touched:\n\n```bash\ngit log --oneline ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002F ':!python\u002FCHANGELOG.md'\n\n# Per-commit package footprint\nfor sha in $(git log --format='%H' ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002F); do\n  echo \"--- $(git show -s --format='%h %s' $sha) ---\"\n  git show --name-only --format='' $sha | grep '^python\u002Fpackages\u002F' | \\\n    sed 's|^python\u002Fpackages\u002F||' | awk -F\u002F '{print $1}' | sort -u\ndone\n```\n\nWhen both remotes exist, record whether the fork is behind the authoritative base:\n\n```bash\ngit rev-list --left-right --count origin\u002Fmain...upstream\u002Fmain\n```\n\nIf user provides an explicit commit\u002FPR list, treat THAT as authoritative.\n\n#### 3a. Build the authoritative touched-package set\n\nAggregate the per-commit footprint into a single union across the whole range. This is the **source of truth** for what must appear in the CHANGELOG. Save it before drafting entries.\n\n```bash\n# Union of all touched package directories across the range\ngit log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002Fpackages\u002F \\\n  | grep '^python\u002Fpackages\u002F' \\\n  | sed 's|^python\u002Fpackages\u002F||' \\\n  | awk -F\u002F '{print $1}' \\\n  | sort -u\n\n# Root-level files (drive a root agent-framework entry if substantive)\ngit log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} \\\n  -- python\u002Fpyproject.toml python\u002Fagent_framework_meta\u002F python\u002FREADME.md \\\n  2>\u002Fdev\u002Fnull | grep -v '^$' | sort -u\n```\n\n**What \"touched\" means for bump purposes** (apply judgment, document in commit message):\n\n| Change scope under `python\u002Fpackages\u002F\u003Cpkg>\u002F` | Drives a bump? |\n| --- | --- |\n| Source code under `\u003Cpkg>\u002Fagent_framework_*` or the package's library tree | **Yes** — ship-affecting |\n| `pyproject.toml` (deps, classifiers, extras, version metadata) | **Yes** — publishes new metadata |\n| `README.md` substantive changes (env vars, install instructions, usage) | **Yes** — user-facing |\n| `README.md` typo\u002Fwording-only | Judgment — usually no, but record under `### Changed` if you do bump |\n| Tests only (`tests\u002F`) | Usually no — test changes don't ship to PyPI consumers. Bump only if the test change reflects a real behavior change in the package |\n| Package-local samples (alpha packages only, before promotion) | **Yes** for alpha; samples ship with the alpha package |\n| Repo infra touching the package dir (CI config, lint config) | No — record under `- **tests**:`, `- **samples**:`, or `- **docs**:` instead |\n\nRoot `agent-framework` is touched when `python\u002Fpyproject.toml`, `python\u002Fagent_framework_meta\u002F`, or root `README.md` substantive content changed.\n\n### 4. Draft CHANGELOG entries (THIS DRIVES THE BUMP LIST)\n\nIndividual feature\u002Ffix PRs intentionally do not add CHANGELOG entries. During release preparation, derive this section\ncentrally from the merged PRs since the last released tag.\n\nLocate `## [Unreleased]` and the top existing release header. INSERT a new section between them.\n\n**New section structure:**\n\n```markdown\n## [\u003Crelease-label>] - YYYY-MM-DD\n\n### Added\n- **agent-framework-\u003Cpkg>**: \u003Csubject> ([#NNNN](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fpull\u002FNNNN))\n\n### Changed\n- **agent-framework-\u003Cpkg>**: ...\n\n### Fixed\n- **agent-framework-\u003Cpkg>**: ...\n```\n\n`\u003Crelease-label>` is the released-tier target if any released package is bumping (e.g. `1.7.0`), or the date stamp (e.g. `1.0.0b260528`) if the release is prerelease-only. Reflect the user's framing.\n\n**Categorization heuristics (read commit subject + PR title\u002Fbody):**\n- **Added**: new public APIs, new packages, new samples, `feat(...)`, new re-exports from `agent_framework`, new capabilities surfaced from underlying SDKs\n- **Changed**: metadata\u002Fclassifier corrections, dependency upgrades, test infra changes, signature adjustments on existing APIs, renames, doc updates, lifecycle transitions\n- **Fixed**: `fix(...)`, bug\u002Fcrash\u002Fregression repairs, noise reduction (e.g. stop emitting spurious warnings), protocol-compliance fixes\n- **Removed**: deprecations\u002Fdeletions (use `[BREAKING]` prefix if breaking)\n\n**Entry format:**\n- `- **agent-framework-\u003Cpkg>**: \u003Csubject, grammar-normalized> ([#NNNN](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fpull\u002FNNNN))`\n- Multiple packages touched by one PR: comma-separated bold names at the head: `- **agent-framework-core**, **agent-framework-foundry**: ...`\n- Root package changes: use `- **agent-framework**: ...`\n- Test\u002Fsample\u002Frepo infra: `- **tests**: ...`, `- **samples**: ...`, `- **docs**: ...` (these do not drive package bumps)\n\n**Once entries are drafted, the set of `**agent-framework-\u003Cpkg>**` and root `**agent-framework**` mentions IS the bump list.** Anything not mentioned does not bump.\n\n#### 4a. Reconcile mentions against the touched-package set (DO NOT SKIP)\n\nBefore moving on, prove that every ship-affecting touched package has at least one CHANGELOG entry. A package whose code changed but is missing from CHANGELOG will NOT bump — and the fix will not ship to PyPI consumers.\n\n```bash\n# 1. Touched ship-affecting packages and root package files (from step 3a)\nTOUCHED_PACKAGES=$(git log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002Fpackages\u002F \\\n  | grep '^python\u002Fpackages\u002F' \\\n  | sed 's|^python\u002Fpackages\u002F||' \\\n  | awk -F\u002F '{print $1}' \\\n  | sort -u)\n\nROOT_TOUCHED=$(git log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} \\\n  -- python\u002Fpyproject.toml python\u002Fagent_framework_meta\u002F python\u002FREADME.md \\\n  2>\u002Fdev\u002Fnull | grep -v '^$' | sort -u)\n\nTOUCHED=$(\n  {\n    if [ -n \"$TOUCHED_PACKAGES\" ]; then echo \"$TOUCHED_PACKAGES\"; fi\n    if [ -n \"$ROOT_TOUCHED\" ]; then echo \"agent-framework\"; fi\n  } | sort -u\n)\n\n# 2. Packages mentioned in the new CHANGELOG section\n# (Extract from the section you just drafted — adjust the awk range to the new section's bounds)\nMENTIONED=$(awk '\n  \u002F^## \\[\u003Crelease-label>\\]\u002F { in_section=1; next }\n  in_section && \u002F^## \\[\u002F { exit }\n  in_section { print }\n' python\u002FCHANGELOG.md \\\n  | grep -oE '\\*\\*agent-framework(-[a-z0-9_-]+)?\\*\\*' \\\n  | sed 's\u002F\\*\\*\u002F\u002Fg;s\u002F^agent-framework-\u002F\u002F' \\\n  | sort -u)\n\n# 3. Diff — anything in TOUCHED but missing from MENTIONED is a gap\ncomm -23 \u003C(echo \"$TOUCHED\") \u003C(echo \"$MENTIONED\")\n```\n\nFor every gap, decide explicitly with the user:\n\n- **Add a CHANGELOG entry and bump** — the default. Even small package changes (a dep upgrade, a metadata fix) deserve an entry under `### Changed`.\n- **Intentionally skip** — only when the touched files are demonstrably non-shipping (e.g. comments-only, test infra). Note the skip in the commit message body so reviewers see the reasoning.\n\nPackage-name aliasing to watch for: directory `foundry_local` → package `agent-framework-foundry-local`; `github_copilot` → `agent-framework-github-copilot`; `azure-ai-search` → `agent-framework-azure-ai-search`. The directory name and the published PyPI name are not always identical — confirm both when reconciling.\n\n**Footer reference links** (REQUIRED every release):\n\n```bash\ngrep -n \"^\\[.*\\]:\" python\u002FCHANGELOG.md | head -5\n```\n\nTwo edits when a released-tier bump is in play:\n1. Advance `[Unreleased]` compare base from `python-${OLD_RELEASED}...HEAD` to `python-${NEW_RELEASED}...HEAD`.\n2. INSERT a new `[${NEW_RELEASED}]` line ABOVE the previous version's link: `[${NEW_RELEASED}]: https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fcompare\u002Fpython-${OLD_RELEASED}...python-${NEW_RELEASED}`\n\nFor prerelease-only releases (no released-tier bump this cycle), footer links don't change.\n\n### 5. Apply bumps per tier\n\nFor each package in the bump list, choose the rule for its current tier. Use anchored `sed` (`^version = \"...\"$`) so only the project's own version matches. Use `sed -i.bak` plus backup cleanup for portable in-place edits across macOS\u002FBSD sed and GNU sed.\n\n**Released tier (per-package semver):**\n\n```bash\n# Example: openai goes 1.6.0 -> 1.6.1 (PATCH); core stays\nsed -i.bak 's\u002F^version = \"1.6.0\"$\u002Fversion = \"1.6.1\"\u002F' python\u002Fpackages\u002Fopenai\u002Fpyproject.toml\nrm python\u002Fpackages\u002Fopenai\u002Fpyproject.toml.bak\n```\n\n**Root `agent-framework` (only when `core` bumps, OR for its own changes):**\n\n```bash\nsed -i.bak \"s\u002F^version = \\\"${OLD_ROOT}\\\"$\u002Fversion = \\\"${NEW_ROOT}\\\"\u002F\" python\u002Fpyproject.toml\n# AND keep the exact pin in sync with core\nsed -i.bak \"s\u002Fagent-framework-core\\\\[all\\\\]==${OLD_CORE}\u002Fagent-framework-core[all]==${NEW_CORE}\u002F\" python\u002Fpyproject.toml\nrm python\u002Fpyproject.toml.bak\n```\n\n**RC tier (counter increment):**\n\n```bash\n# ag-ui goes 1.0.0rc3 -> 1.0.0rc4 only because it has a CHANGELOG entry\nsed -i.bak 's\u002F^version = \"1.0.0rc3\"$\u002Fversion = \"1.0.0rc4\"\u002F' python\u002Fpackages\u002Fag-ui\u002Fpyproject.toml\nrm python\u002Fpackages\u002Fag-ui\u002Fpyproject.toml.bak\n```\n\n**Alpha\u002FBeta tier (new date stamp):**\n\n```bash\nOLD_DATE=260521\nNEW_DATE=260528\n\n# Only the packages with CHANGELOG entries get the new stamp.\n# Example: anthropic and bedrock had entries, others did not.\nfor pkg in anthropic bedrock; do\n  file=\"python\u002Fpackages\u002F$pkg\u002Fpyproject.toml\"\n  sed -i.bak \"s\u002F1\\\\.0\\\\.0b${OLD_DATE}\u002F1.0.0b${NEW_DATE}\u002Fg\" \"$file\"\n  rm \"${file}.bak\"\ndone\n```\n\nIf the user opts into a cohort-wide beta bump regardless of per-package changes, enumerate every beta package from `PACKAGE_STATUS.md` and stamp all of them. State that this is a cohort bump in the commit message.\n\nSpot-check with `grep '^version' python\u002Fpyproject.toml python\u002Fpackages\u002F*\u002Fpyproject.toml | sort` before moving on.\n\n### 5a. Refresh the `core[all]` release cohort\n\nWhen Core bumps, update every Agent Framework dependency in\n`python\u002Fpackages\u002Fcore\u002Fpyproject.toml` `[project.optional-dependencies].all`:\n\n- Workspace packages use their post-bump version as the lower bound, or their unchanged current version when they\n  are not otherwise releasing this cycle.\n- External Agent Framework packages such as Azure Functions and Durable Task retain a bounded known-good floor.\n- Every entry keeps an upper bound for its supported major version.\n- Preserve environment markers for packages that do not support every Python\u002Fplatform combination.\n\nThese bounds prevent pip from backtracking across old cyclic `core[all] -> integration -> core` combinations. The\nrelease validator rejects missing, stale, or unbounded cohort entries.\n\n### 6. Floor bound updates on `agent-framework-core`\n\nOnly relevant when `core` itself bumped this cycle. Two policies, pick one explicitly with the user:\n\n- **Conservative (default)**: raise `agent-framework-core>=X.Y.Z` to the new core version on every non-core package that is ALSO bumping this cycle. Leaves packages-not-bumped at their existing floor.\n- **Strict per-upstream-doc**: only raise the floor on packages that actually consume a new core API introduced in the bump. This requires per-package code inspection because release probes use the co-released local core and cannot prove compatibility with an older published core floor.\n\nWhen raising a core floor, replace only the `>=OLD` half of the bound you intend to change:\n\n```bash\nfile=\"python\u002Fpackages\u002F\u003Cpkg>\u002Fpyproject.toml\"\nsed -i.bak \"s\u002Fagent-framework-core>=${OLD_CORE}\u002Fagent-framework-core>=${NEW_CORE}\u002F\" \"$file\"\nrm \"${file}.bak\"\n```\n\nIf `core` did not bump this cycle, do not touch floors.\n\n### 7. Generate the reviewed release batch and validate\n\nAfter applying the selected bumps and dependency edits, stage any new workspace package metadata with\n`git add python\u002Fpackages\u002F\u003Cpackage>\u002Fpyproject.toml`. The generator fails explicitly if workspace metadata is still\nuntracked, rather than silently omitting that distribution. Existing tracked metadata need not be staged.\nGenerate the manifest from that same metadata diff:\n\n```bash\nRELEASE_TAG=\"python-\u003Crelease-label>\"\nuv run --directory python --group tool-runtime poe prepare-python-release --base-ref \"$RELEASE_BASE\" --tag \"$RELEASE_TAG\"\n```\n\nThe generator reuses the release validator's changed-`pyproject.toml` selection, then includes only packages whose\nversion increased (or new workspace packages). Compare package identity by canonical distribution name, not directory:\na move does not make an existing version new, and a renamed distribution is a new identity. Dependency-only metadata\nedits remain part of dependency validation but do not select an unchanged version for publication. The generator\nrejects a Core release without a version increase for root `agent-framework`; the explicit cohort decision above\nstill determines other bumps. The excluded standalone Lab workspace is not part of this batch.\n\nCommit **`python\u002F.github\u002Frelease-${RELEASE_TAG}.json` in this same PR**, together with the version and lockfile changes.\nThe filename includes the full tag: `python-1.24.0` produces `python\u002F.github\u002Frelease-python-1.24.0.json`.\nDo not maintain a duplicate list of versions manually. Regenerate the new file after changing the bump list while\nthe PR is open. Once it is part of the release base, it is historical: never edit, replace, or delete it.\nFor example, `python\u002F.github\u002Frelease-python-1.24.0.json` contains:\n\n```json\n{\n  \"tag\": \"python-1.24.0\",\n  \"packages\": {\n    \"agent-framework\": \"1.24.0\",\n    \"agent-framework-core\": \"1.24.0\",\n    \"agent-framework-foundry\": \"1.16.0\"\n  },\n  \"smoke_imports\": {\n    \"agent-framework\": [\"agent_framework:Agent\"],\n    \"agent-framework-core\": [\"agent_framework:Message\"],\n    \"agent-framework-foundry\": [\"agent_framework.foundry:FoundryAgent\"]\n  }\n}\n```\n\nContract:\n\n- `tag` and non-empty `packages` are required. The tag is one overall `python-\u003CPEP440-version>` release label, not\n  a requirement that every selected distribution share a version. No source commit SHA is stored in this file:\n  Azure DevOps resolves the immutable tagged commit and reads `python\u002F.github\u002Frelease-\u003Cfulltag>.json` there.\n  Both sides derive this exact path from the expected full tag. Never scan for the latest file or fall back to\n  the old fixed `.github\u002Frelease.json` or root `release.json` paths.\n  Generation and PR validation reject tags already present in the freshly fetched local tag refs. Fetch tags as in\n  step 1 before preparation. Published-release validation permits its existing tag and checks the qualified\n  `refs\u002Ftags\u002F\u003Cfulltag>` revision; PR checks use the immutable event SHA, not a moving merge ref.\n- Keys are exact canonical distribution names; values are PEP 440 strings equal to the tagged `project.version`.\n  The expected tag must match the manifest tag, preventing reuse of a stale batch. PyPI absence is validation,\n  **never selection**.\n- `smoke_imports` is an optional additive map of public `module:export` checks (classes or functions). The generator\n  emits it for **every** selected distribution. The consumer only has built-in defaults for meta\u002Fcore\u002FFoundry;\n  other packages require explicit reviewed checks. Unknown packages fail until `scripts\u002Fprepare_release.py`\n  has a reviewed public import entry. A check imports the module and resolves the export, without creating an\n  agent, opening a connection, or calling a service.\n- Prefer public `agent_framework.*` bridges. Never derive checks from build configuration (the root's\n  `agent_framework_meta` is not its public API), or substitute a private implementation module.\n  Packages without a bridge use their documented public top-level entry points. The explicit exceptions are\n  `agent_framework_azure_cosmos_memory`, `agent_framework_azure_documentdb`, `agent_framework_duckdb`,\n  `agent_framework_hosting`, `agent_framework_hosting_a2a`, `agent_framework_hosting_mcp`,\n  `agent_framework_hosting_responses`, `agent_framework_hosting_telegram`, `agent_framework_mongodb`,\n  `agent_framework_nvidia`, `agent_framework_oracle`, `agent_framework_postgres`, `agent_framework_qdrant`,\n  `agent_framework_sql_server`, and `agent_framework_typesafe`. See their package READMEs and exported `__all__`;\n  the inventory test checks each selected public export. A new exception must also be reviewed in the consumer\n  allowlist before release.\n\nFrom the repository root, check the generated file against the same base:\n\n```bash\nuv run --directory python --group tool-runtime python -m scripts.prepare_release --check --base-ref \"$RELEASE_BASE\" --tag \"$RELEASE_TAG\"\n```\n\nFor version increases of existing distributions or an explicit manifest change, PR CI requires exactly one new\nper-tag manifest and enforces agreement between its filename, JSON tag, and version changes. Ordinary development\nPRs that only add new distribution identities do not need to choose a release tag or add a manifest. Explicit\nrelease preparation still includes all selected new packages, and a supplied manifest is always validated.\nChanges or deletions of historical manifests fail the check. Earlier files remain browsable on `main`;\ntheir old package versions are not revalidated against current metadata. PRs without version or manifest changes\n(including dependency maintenance) do not need to add a manifest. These files record reviewed intended batches,\nnot proof that publication completed; that evidence is the verified artifact manifest on the published release.\n\n```bash\nuv run --directory python --group tool-runtime poe validate-python-release --base-ref \"$RELEASE_BASE\"\n```\n\nUse the same freshly fetched main ref that the release branch was based on (`upstream\u002Fmain` above; use `origin\u002Fmain`\nwhen that is the authoritative release base). Must exit 0. This task first regenerates `uv.lock`, then discovers the\npackage `pyproject.toml` files changed from that base and runs their published runtime dependencies and\nnon-development extras through lock-independent `lowest-direct` and `highest` import probes. The probes run in\nparallel, derive the minimum supported Python minor from each package's internal editable closure, and share a hard\n300-second deadline. Use `--python` only when the release requires an explicit interpreter override.\n\nThis is the release safety net for selective bumping: the lower probe catches unresolvable or unimportable external\nfloors, internal constraints that reject co-released package versions, and the upper probe catches caps that exclude\nan installable package set. The JSON report records the concrete versions resolved in both scenarios. It does not\nreplace the package-by-package code inspection required by the strict core-floor policy. If it fails, fix the named\npackage\u002Fbound and re-run before committing.\n\nDo not substitute the workspace-wide `validate-dependency-bounds-test` command here. That command runs every\npackage's full tests and Pyright in separate isolated environments and is intentionally reserved for CI or an\nexplicit dependency-range audit. The `Dependency Bounds Validation` check in `python-dependency-bounds.yml` runs that\nfull matrix for version-bump and new-workspace-package PRs and merge groups, while ordinary PRs skip it.\nThe bounded local release probes remain separate and do not replace that regression coverage.\nIf the release itself changes an external dependency range, also run\n`validate-dependency-bounds-project --mode both --package \u003Cpkg> --dependency \u003Cname>` for that dependency.\n\nIf only prereleases changed (no `core` bump, no floor changes), release validation is still required because the\nlockfile and both ends of each changed package's published dependency metadata must remain installable.\n\n### 8. Commit (expect hook retry)\n\nThe project's pre-commit hook runs `poe check` \u002F `poe typing` \u002F `uv lock` and may re-modify `uv.lock` on first commit attempt. Expected pattern — run twice:\n\n```bash\ngit add -u\ngit add \"python\u002F.github\u002Frelease-${RELEASE_TAG}.json\"  # New files are not included by git add -u.\ngit commit -m \"\u003Cmessage>\"   # may fail with \"files were modified by this hook\"\ngit add -u                  # re-stage hook-generated changes\ngit commit -m \"\u003Cmessage>\"   # succeeds\n```\n\n**Commit message format** — HEREDOC, no `Co-Authored-By`:\n\n```bash\ngit commit -m \"$(cat \u003C\u003C'EOF'\nBump Python package versions for \u003Crelease-label> release\n\n\u003COne paragraph explaining:\n - which packages bumped and why (CHANGELOG-driven)\n - semver rationale for any released-tier bumps\n - whether a beta cohort bump was applied\n - whether core floors were raised, and under which policy>\nEOF\n)\"\n```\n\n### 9. Push and report\n\n```bash\ngit push origin bump-py-ver-release-YYMMDD\n```\n\nThe push output includes a `Create a pull request for '\u003Cbranch>' on GitHub by visiting: \u003CURL>` line — surface that to the user.\n\n### 10. Maintainer handoff: tag and existing draft (only when authorized)\n\nAfter the reviewed bump PR merges, the maintainer selects the exact merged commit and creates the **one** overall\ntag matching its `python\u002F.github\u002Frelease-\u003Cfulltag>.json`. The maintainer creates a GitHub **draft** release for that tag.\nThe release title must exactly match the full tag name, including the `python-` prefix (for example, `python-1.26.0`).\nInclude complete release notes and the intended prerelease flag. Do not use a published release as the\ntrigger and do not create per-package tags. Release notes must be complete **before ESRP approval**; do not edit\nthe draft, tag, or selected source while a release run is in progress.\n\nAzure DevOps discovery polls eligible existing drafts and tags. It has a disabled-by-default activation switch,\nan explicit first eligible release ID, and durable claims on one retained ADO ledger run. A shared exclusive-lock\nenvironment serializes discovery, authorization and finalization to admit one run for the whole batch. No Azure\nstorage account is needed. No GitHub workflow calls or queues Azure DevOps.\n\nThe protected pipeline reads `python\u002F.github\u002Frelease-\u003Cfulltag>.json` from the exact tagged commit, validates the requested names,\nversions and tag, builds once, and runs isolated install\u002Fpublic-import checks against the selected artifacts.\nIt then waits for protected ESRP approval\u002Fpublication and verifies the published distributions. Only after that\nverification does it upload the **same built wheels\u002Fsdists and artifact manifest** to the **existing draft**,\nverify those assets, and change `draft` to `false`. It preserves the draft's title, body, and prerelease flag.\nThe source request (`python\u002F.github\u002Frelease-\u003Cfulltag>.json`) and the output artifact manifest (file names, versions, sizes\u002Fchecksums and\nsource provenance) are different records.\n\nThe published-event GitHub workflow validates the tag contract only. It must not build new artifacts, upload\nrelease assets, publish packages, or request Azure DevOps credentials.\n\n### Failure and recovery\n\n- Before approval\u002Fpublication: leave the draft unpublished, inspect the failing checks, and fix the source in a\n  reviewed PR if needed. Do not move an existing release tag or silently replace its manifest. A new release\n  attempt requiring source changes needs a new overall tag and appropriate new package versions.\n- A queued\u002Ffailed batch remains claimed. Use the consumer's audited recovery procedure to retry\u002Freconcile the\n  **same batch and retained artifact set**. Do not delete a claim to create parallel runs, queue individual\n  distributions, or bypass the approval gate with local `uv publish`\u002FTwine.\n- Publication may partially succeed before a failure. PyPI versions are immutable: inspect package versions,\n  retained artifact hashes, and the publication record before retrying. Already-published versions do not change\n  the reviewed selection. Never overwrite or rebuild artifacts and assume they are identical.\n- If publication succeeds but GitHub asset upload or finalization fails, keep the draft unpublished and retry\n  that finalization using the verified retained artifacts. Do not republish packages, create a replacement\n  release, or lose the human-authored release metadata.\n\n### Rollout order (no publication as part of implementation)\n\n1. Merge the Azure DevOps consumer first, with discovery disabled. Review the matching contract, artifact\n   verification, recovery, and draft-only finalization.\n2. Merge this repository's producer and retirement of the old GitHub build\u002Fupload path second.\n3. Reuse the existing Azure DevOps GitHub service connection `github-agent-framework`, already used by the .NET\n   release pipeline, and authorize it for the Python pipelines. Verify its repository and release access; do not\n   introduce a separate GitHub App, private key, or Key Vault token-minting setup. Configure the shared\n   `agent-framework-python-coordination` environment with an exclusive-lock check, initialize a retained discovery\n   run with `initializeLedger: true`, and set its `releaseLedgerRunId` in both ADO pipelines. Keep ledger and release\n   runs retained indefinitely. Verify the Build Service permissions and protected ESRP approval gates outside GitHub.\n   No separate Azure storage identity is needed. Verify the merged upstream revision is compatible. Reusing the\n   connection does not authorize a new pipeline automatically.\n4. Choose the first eligible draft release ID and activate tag\u002Fdraft discovery **last**, only after the previous\n   steps are confirmed. Do not create production tags\u002Fdrafts merely to test rollout.\n\nThe coordinated change requires both PRs and maintainer approval. Merging producer code alone must not enable\na second publisher or silently activate discovery.\n\nConnection reuse does not mean reusing a release task that rewrites metadata or replaces existing assets.\nThe consumer's asset-only REST finalizer must still preserve the existing draft's title, body, and prerelease flag,\nverify the exact retained artifacts, and publish only after verification. GitHub never receives Azure DevOps\ncredentials or queue permission.\n\n## Pitfalls from past cycles — avoid repeating\n\n- **Scoping from the wrong tag.** A release may have been tagged between bump cycles. Always compute `LAST_RELEASED_TAG` fresh — do NOT reuse the previous compare base. Symptom: dragging already-shipped PRs into the new CHANGELOG section.\n- **Bumping packages that had no changes.** This was the old lockstep default. Now: a package without a CHANGELOG entry does not bump. The two exceptions (root follows core, optional beta cohort bump) are explicit choices, not defaults.\n- **Touched package missing from CHANGELOG.** The inverse failure mode of the previous pitfall, and the dangerous one. If a PR landed code into `python\u002Fpackages\u002Ffoo\u002F` but the new CHANGELOG section has no `**agent-framework-foo**:` line, then `foo` will NOT bump, and the fix sits in `main` but never reaches PyPI. Always run the touched-vs-mentioned reconciliation in step 4a before applying bumps.\n- **Directory name vs PyPI name confusion.** Some package dirs use underscores or split names that differ from the published PyPI name (e.g. `foundry_local` → `agent-framework-foundry-local`). When reconciling touched dirs against CHANGELOG mentions, normalize on the PyPI form.\n- **Forgetting root when core bumps.** Root `agent-framework` has `agent-framework-core[all]==EXACT_VERSION`. If `core` bumps and root does not, the pin is broken. Always bump them together and update the pin string.\n- **Renaming an existing section header.** When drafting a new release, do NOT rewrite an existing `## [X.Y.Z]` header to a new label — that wipes the historical section. Always INSERT a new section above.\n- **Forgetting footer reference links.** When a released-tier bump is in play, the `[Unreleased]` line and the new `[X.Y.Z]` link at the bottom MUST be updated. Heading links don't resolve without them.\n- **Wrong footer compare base.** The new `[X.Y.Z]` line compares from the PREVIOUS released tag, not from two releases ago.\n- **Timezone drift.** For alpha\u002Fbeta date stamps, follow the `python-package-management` date-stamp rule;\n  do not infer a local timezone from the user's current shell.\n- **`Co-Authored-By` trailer.** Never add it. Rewrite\u002Famend if it slipped in.\n- **Stale inventory in this skill.** Always read `python\u002FPACKAGE_STATUS.md` for the live tier map. Do not trust a hardcoded list.\n- **Divergent origin vs upstream.** In fork clones, use freshly fetched `upstream\u002Fmain` consistently for branch creation, changeset discovery, and release validation. A stale `origin\u002Fmain` must never become the implicit compare base.\n- **`--pre` README cleanup on promotion.** When a package is promoted to `released` in this cycle, grep for `pip install agent-framework-\u003Cpkg> --pre` in READMEs and drop the `--pre` flag.\n- **RC counter inflation.** Do not increment `1.0.0rcN` without a CHANGELOG entry for that package. The counter tracks iterations, not calendar.\n\n## References\n\n- Package lifecycle and versioning source of truth: `python\u002F.github\u002Fskills\u002Fpython-package-management\u002FSKILL.md`\n- Lifecycle source of truth: `python\u002FPACKAGE_STATUS.md`\n- Release validator: `python\u002Fscripts\u002Fdependencies\u002Fvalidate_dependency_bounds.py --mode release` (changed-package,\n  lock-independent `lowest-direct` and `highest` import probes under a five-minute deadline)\n- Batch generator and read-only validator: `python\u002Fscripts\u002Fprepare_release.py`\n- Read-only PR\u002Fpublished-tag check: `.github\u002Fworkflows\u002Fpython-release.yml`\n- Poe task definitions: `python\u002Fpyproject.toml` `[tool.poe.tasks]`\n","# Agent Framework Python Release\n\nCuts a Python release PR for the `microsoft\u002Fagent-framework` monorepo.\n\nRelease preparation does **not** authorize production tags, draft creation, publication, or deployment. Stop at the\nrequested PR unless a maintainer separately authorizes the release handoff below.\n\n## Core principle: CHANGELOG drives bumps\n\n**No more universal lockstep.** A package only bumps if it has a CHANGELOG entry this cycle. Draft the CHANGELOG first, then derive the bump list from it.\n\nExceptions to selective bumping (these stay coupled regardless of per-package changes):\n\n- **Root `agent-framework` is coupled to `agent-framework-core` via `agent-framework-core[all]==X.Y.Z`** (exact pin in `python\u002Fpyproject.toml`). If `core` bumps, root bumps. Root may also bump independently for its own changes (docs\u002Fmetadata\u002Fextras).\n- **Beta-tier cohort bumps are still allowed** when the user explicitly wants a fresh date stamp across all betas for cohort signaling — but this is a deliberate user decision per release, not a default.\n\nIf the user explicitly states which packages to bump (or hands over a PR list per package), treat that as authoritative.\n\n## Lifecycle tiers and version rules\n\nUse `python\u002F.github\u002Fskills\u002Fpython-package-management\u002FSKILL.md` as the source of truth for lifecycle\nversion patterns, date-stamp cutoffs, classifier alignment, and internal dependency updates.\n\nFor release work, derive the live tier map at release time from `python\u002FPACKAGE_STATUS.md` and the actual\n`version =` lines in each `pyproject.toml`. Do not hardcode counts — packages move between tiers.\n\n## Inputs to confirm before bumping\n\n1. **The changeset**: explicit commits\u002FPRs the release covers, OR derive from `git log ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002F`.\n2. **Per-package CHANGELOG entries**: which packages will get a line in the new release section. This list IS the bump list.\n3. **Per-released-package semver bump**: for each released-tier package that has a CHANGELOG entry, decide PATCH \u002F MINOR \u002F MAJOR.\n4. **Date stamp** (only if any alpha\u002Fbeta is being bumped): default from the `python-package-management`\n   date-stamp rule.\n5. **Optional cohort bump?**: ask if betas should all get a new date stamp regardless of per-package changes. Default: no.\n\nIf the user states target versions or a date explicitly, use exactly what they said — do not \"correct\" based on historical timezones.\n\n## Non-negotiable rules\n\n- **Release workflow owns the CHANGELOG**: individual feature\u002Ffix PRs do not edit\n  `python\u002FCHANGELOG.md`; this workflow creates the entries centrally from merged changes.\n- **CHANGELOG-driven bumps**: only packages mentioned in the new CHANGELOG section get version bumps. Exceptions: root follows core (==pin); user-opted cohort bump on betas.\n- **Follow `python-package-management` for package lifecycle and versioning rules** — do not duplicate those\n  rules in this release workflow.\n- **No `Co-Authored-By` trailer** on any commit.\n- **Use `uv run`** for cross-version Python\u002FPoe commands and add the relevant\n  `tooling\u002Frequirements-*.txt` bundle only for single-version tools.\n- **Never rename an existing CHANGELOG section header** during a new release cut. Only INSERT a new section above existing ones.\n- **Footer reference links are part of the CHANGELOG edit**, not optional.\n- **One batch, one overall tag, one Azure DevOps run.** Generate `python\u002F.github\u002Frelease-\u003Cfulltag>.json` in the same\n  version-bump PR. Keep earlier per-tag manifests unchanged for browsing release-batch history.\n  Never replace the reviewed selection with \"all versions absent from PyPI\", per-package tags, or one run per package.\n- **Azure DevOps is the only production publisher.** GitHub has no Azure DevOps API credentials or federated queue\n  permission. The GitHub release workflow is read-only validation; local production `publish` tasks are retired.\n\n## Workflow\n\n### 1. Orient and create branch\n\n```bash\ngit fetch origin main --tags --quiet\ngit fetch upstream main --tags --quiet 2>\u002Fdev\u002Fnull || true\ngit status\n\n# Fork clones use upstream\u002Fmain as the authoritative release base; direct clones use origin\u002Fmain.\nif git show-ref --verify --quiet refs\u002Fremotes\u002Fupstream\u002Fmain; then\n  RELEASE_BASE=upstream\u002Fmain\nelse\n  RELEASE_BASE=origin\u002Fmain\nfi\ngit log -1 --oneline \"$RELEASE_BASE\"\n```\n\nIf the user already has a `bump-py-ver-release-*` branch checked out, use it. Otherwise:\n\n```bash\ngit checkout -b bump-py-ver-release-YYMMDD \"$RELEASE_BASE\"\n```\n\n### 2. Build the live tier map\n\nRead `python\u002FPACKAGE_STATUS.md` to enumerate current packages and lifecycle stages, and `grep '^version' python\u002Fpyproject.toml python\u002Fpackages\u002F*\u002Fpyproject.toml` to confirm actual versions. Cross-reference — if `PACKAGE_STATUS.md` shows a package as `beta` but its version looks like `1.0.0aYYMMDD`, surface the inconsistency before proceeding.\n\nWatch for: new packages added since the last release, lifecycle transitions (alpha→beta, beta→rc, rc→released), and stale packages that haven't been touched in many cycles.\n\n### 3. Identify changeset\n\nUse the LATEST released tag as the compare base:\n\n```bash\nLAST_RELEASED_TAG=$(\n  git tag -l 'python-*' \\\n    | uv run --directory python python -c 'import re, sys; tags=[t.strip() for t in sys.stdin if re.fullmatch(r\"python-\\d+\\.\\d+\\.\\d+\", t.strip())]; print(max(tags, key=lambda t: tuple(map(int, t[7:].split(\".\")))))'\n)\necho \"Compare base: $LAST_RELEASED_TAG\"\n```\n\nList commits and packages touched:\n\n```bash\ngit log --oneline ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002F ':!python\u002FCHANGELOG.md'\n\n# Per-commit package footprint\nfor sha in $(git log --format='%H' ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002F); do\n  echo \"--- $(git show -s --format='%h %s' $sha) ---\"\n  git show --name-only --format='' $sha | grep '^python\u002Fpackages\u002F' | \\\n    sed 's|^python\u002Fpackages\u002F||' | awk -F\u002F '{print $1}' | sort -u\ndone\n```\n\nWhen both remotes exist, record whether the fork is behind the authoritative base:\n\n```bash\ngit rev-list --left-right --count origin\u002Fmain...upstream\u002Fmain\n```\n\nIf user provides an explicit commit\u002FPR list, treat THAT as authoritative.\n\n#### 3a. Build the authoritative touched-package set\n\nAggregate the per-commit footprint into a single union across the whole range. This is the **source of truth** for what must appear in the CHANGELOG. Save it before drafting entries.\n\n```bash\n# Union of all touched package directories across the range\ngit log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002Fpackages\u002F \\\n  | grep '^python\u002Fpackages\u002F' \\\n  | sed 's|^python\u002Fpackages\u002F||' \\\n  | awk -F\u002F '{print $1}' \\\n  | sort -u\n\n# Root-level files (drive a root agent-framework entry if substantive)\ngit log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} \\\n  -- python\u002Fpyproject.toml python\u002Fagent_framework_meta\u002F python\u002FREADME.md \\\n  2>\u002Fdev\u002Fnull | grep -v '^$' | sort -u\n```\n\n**What \"touched\" means for bump purposes** (apply judgment, document in commit message):\n\n| Change scope under `python\u002Fpackages\u002F\u003Cpkg>\u002F` | Drives a bump? |\n| --- | --- |\n| Source code under `\u003Cpkg>\u002Fagent_framework_*` or the package's library tree | **Yes** — ship-affecting |\n| `pyproject.toml` (deps, classifiers, extras, version metadata) | **Yes** — publishes new metadata |\n| `README.md` substantive changes (env vars, install instructions, usage) | **Yes** — user-facing |\n| `README.md` typo\u002Fwording-only | Judgment — usually no, but record under `### Changed` if you do bump |\n| Tests only (`tests\u002F`) | Usually no — test changes don't ship to PyPI consumers. Bump only if the test change reflects a real behavior change in the package |\n| Package-local samples (alpha packages only, before promotion) | **Yes** for alpha; samples ship with the alpha package |\n| Repo infra touching the package dir (CI config, lint config) | No — record under `- **tests**:`, `- **samples**:`, or `- **docs**:` instead |\n\nRoot `agent-framework` is touched when `python\u002Fpyproject.toml`, `python\u002Fagent_framework_meta\u002F`, or root `README.md` substantive content changed.\n\n### 4. Draft CHANGELOG entries (THIS DRIVES THE BUMP LIST)\n\nIndividual feature\u002Ffix PRs intentionally do not add CHANGELOG entries. During release preparation, derive this section\ncentrally from the merged PRs since the last released tag.\n\nLocate `## [Unreleased]` and the top existing release header. INSERT a new section between them.\n\n**New section structure:**\n\n```markdown\n## [\u003Crelease-label>] - YYYY-MM-DD\n\n### Added\n- **agent-framework-\u003Cpkg>**: \u003Csubject> ([#NNNN](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fpull\u002FNNNN))\n\n### Changed\n- **agent-framework-\u003Cpkg>**: ...\n\n### Fixed\n- **agent-framework-\u003Cpkg>**: ...\n```\n\n`\u003Crelease-label>` is the released-tier target if any released package is bumping (e.g. `1.7.0`), or the date stamp (e.g. `1.0.0b260528`) if the release is prerelease-only. Reflect the user's framing.\n\n**Categorization heuristics (read commit subject + PR title\u002Fbody):**\n- **Added**: new public APIs, new packages, new samples, `feat(...)`, new re-exports from `agent_framework`, new capabilities surfaced from underlying SDKs\n- **Changed**: metadata\u002Fclassifier corrections, dependency upgrades, test infra changes, signature adjustments on existing APIs, renames, doc updates, lifecycle transitions\n- **Fixed**: `fix(...)`, bug\u002Fcrash\u002Fregression repairs, noise reduction (e.g. stop emitting spurious warnings), protocol-compliance fixes\n- **Removed**: deprecations\u002Fdeletions (use `[BREAKING]` prefix if breaking)\n\n**Entry format:**\n- `- **agent-framework-\u003Cpkg>**: \u003Csubject, grammar-normalized> ([#NNNN](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fpull\u002FNNNN))`\n- Multiple packages touched by one PR: comma-separated bold names at the head: `- **agent-framework-core**, **agent-framework-foundry**: ...`\n- Root package changes: use `- **agent-framework**: ...`\n- Test\u002Fsample\u002Frepo infra: `- **tests**: ...`, `- **samples**: ...`, `- **docs**: ...` (these do not drive package bumps)\n\n**Once entries are drafted, the set of `**agent-framework-\u003Cpkg>**` and root `**agent-framework**` mentions IS the bump list.** Anything not mentioned does not bump.\n\n#### 4a. Reconcile mentions against the touched-package set (DO NOT SKIP)\n\nBefore moving on, prove that every ship-affecting touched package has at least one CHANGELOG entry. A package whose code changed but is missing from CHANGELOG will NOT bump — and the fix will not ship to PyPI consumers.\n\n```bash\n# 1. Touched ship-affecting packages and root package files (from step 3a)\nTOUCHED_PACKAGES=$(git log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} -- python\u002Fpackages\u002F \\\n  | grep '^python\u002Fpackages\u002F' \\\n  | sed 's|^python\u002Fpackages\u002F||' \\\n  | awk -F\u002F '{print $1}' \\\n  | sort -u)\n\nROOT_TOUCHED=$(git log --name-only --format='' ${LAST_RELEASED_TAG}..${RELEASE_BASE} \\\n  -- python\u002Fpyproject.toml python\u002Fagent_framework_meta\u002F python\u002FREADME.md \\\n  2>\u002Fdev\u002Fnull | grep -v '^$' | sort -u)\n\nTOUCHED=$(\n  {\n    if [ -n \"$TOUCHED_PACKAGES\" ]; then echo \"$TOUCHED_PACKAGES\"; fi\n    if [ -n \"$ROOT_TOUCHED\" ]; then echo \"agent-framework\"; fi\n  } | sort -u\n)\n\n# 2. Packages mentioned in the new CHANGELOG section\n# (Extract from the section you just drafted — adjust the awk range to the new section's bounds)\nMENTIONED=$(awk '\n  \u002F^## \\[\u003Crelease-label>\\]\u002F { in_section=1; next }\n  in_section && \u002F^## \\[\u002F { exit }\n  in_section { print }\n' python\u002FCHANGELOG.md \\\n  | grep -oE '\\*\\*agent-framework(-[a-z0-9_-]+)?\\*\\*' \\\n  | sed 's\u002F\\*\\*\u002F\u002Fg;s\u002F^agent-framework-\u002F\u002F' \\\n  | sort -u)\n\n# 3. Diff — anything in TOUCHED but missing from MENTIONED is a gap\ncomm -23 \u003C(echo \"$TOUCHED\") \u003C(echo \"$MENTIONED\")\n```\n\nFor every gap, decide explicitly with the user:\n\n- **Add a CHANGELOG entry and bump** — the default. Even small package changes (a dep upgrade, a metadata fix) deserve an entry under `### Changed`.\n- **Intentionally skip** — only when the touched files are demonstrably non-shipping (e.g. comments-only, test infra). Note the skip in the commit message body so reviewers see the reasoning.\n\nPackage-name aliasing to watch for: directory `foundry_local` → package `agent-framework-foundry-local`; `github_copilot` → `agent-framework-github-copilot`; `azure-ai-search` → `agent-framework-azure-ai-search`. The directory name and the published PyPI name are not always identical — confirm both when reconciling.\n\n**Footer reference links** (REQUIRED every release):\n\n```bash\ngrep -n \"^\\[.*\\]:\" python\u002FCHANGELOG.md | head -5\n```\n\nTwo edits when a released-tier bump is in play:\n1. Advance `[Unreleased]` compare base from `python-${OLD_RELEASED}...HEAD` to `python-${NEW_RELEASED}...HEAD`.\n2. INSERT a new `[${NEW_RELEASED}]` line ABOVE the previous version's link: `[${NEW_RELEASED}]: https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fcompare\u002Fpython-${OLD_RELEASED}...python-${NEW_RELEASED}`\n\nFor prerelease-only releases (no released-tier bump this cycle), footer links don't change.\n\n### 5. Apply bumps per tier\n\nFor each package in the bump list, choose the rule for its current tier. Use anchored `sed` (`^version = \"...\"$`) so only the project's own version matches. Use `sed -i.bak` plus backup cleanup for portable in-place edits across macOS\u002FBSD sed and GNU sed.\n\n**Released tier (per-package semver):**\n\n```bash\n# Example: openai goes 1.6.0 -> 1.6.1 (PATCH); core stays\nsed -i.bak 's\u002F^version = \"1.6.0\"$\u002Fversion = \"1.6.1\"\u002F' python\u002Fpackages\u002Fopenai\u002Fpyproject.toml\nrm python\u002Fpackages\u002Fopenai\u002Fpyproject.toml.bak\n```\n\n**Root `agent-framework` (only when `core` bumps, OR for its own changes):**\n\n```bash\nsed -i.bak \"s\u002F^version = \\\"${OLD_ROOT}\\\"$\u002Fversion = \\\"${NEW_ROOT}\\\"\u002F\" python\u002Fpyproject.toml\n# AND keep the exact pin in sync with core\nsed -i.bak \"s\u002Fagent-framework-core\\\\[all\\\\]==${OLD_CORE}\u002Fagent-framework-core[all]==${NEW_CORE}\u002F\" python\u002Fpyproject.toml\nrm python\u002Fpyproject.toml.bak\n```\n\n**RC tier (counter increment):**\n\n```bash\n# ag-ui goes 1.0.0rc3 -> 1.0.0rc4 only because it has a CHANGELOG entry\nsed -i.bak 's\u002F^version = \"1.0.0rc3\"$\u002Fversion = \"1.0.0rc4\"\u002F' python\u002Fpackages\u002Fag-ui\u002Fpyproject.toml\nrm python\u002Fpackages\u002Fag-ui\u002Fpyproject.toml.bak\n```\n\n**Alpha\u002FBeta tier (new date stamp):**\n\n```bash\nOLD_DATE=260521\nNEW_DATE=260528\n\n# Only the packages with CHANGELOG entries get the new stamp.\n# Example: anthropic and bedrock had entries, others did not.\nfor pkg in anthropic bedrock; do\n  file=\"python\u002Fpackages\u002F$pkg\u002Fpyproject.toml\"\n  sed -i.bak \"s\u002F1\\\\.0\\\\.0b${OLD_DATE}\u002F1.0.0b${NEW_DATE}\u002Fg\" \"$file\"\n  rm \"${file}.bak\"\ndone\n```\n\nIf the user opts into a cohort-wide beta bump regardless of per-package changes, enumerate every beta package from `PACKAGE_STATUS.md` and stamp all of them. State that this is a cohort bump in the commit message.\n\nSpot-check with `grep '^version' python\u002Fpyproject.toml python\u002Fpackages\u002F*\u002Fpyproject.toml | sort` before moving on.\n\n### 5a. Refresh the `core[all]` release cohort\n\nWhen Core bumps, update every Agent Framework dependency in\n`python\u002Fpackages\u002Fcore\u002Fpyproject.toml` `[project.optional-dependencies].all`:\n\n- Workspace packages use their post-bump version as the lower bound, or their unchanged current version when they\n  are not otherwise releasing this cycle.\n- External Agent Framework packages such as Azure Functions and Durable Task retain a bounded known-good floor.\n- Every entry keeps an upper bound for its supported major version.\n- Preserve environment markers for packages that do not support every Python\u002Fplatform combination.\n\nThese bounds prevent pip from backtracking across old cyclic `core[all] -> integration -> core` combinations. The\nrelease validator rejects missing, stale, or unbounded cohort entries.\n\n### 6. Floor bound updates on `agent-framework-core`\n\nOnly relevant when `core` itself bumped this cycle. Two policies, pick one explicitly with the user:\n\n- **Conservative (default)**: raise `agent-framework-core>=X.Y.Z` to the new core version on every non-core package that is ALSO bumping this cycle. Leaves packages-not-bumped at their existing floor.\n- **Strict per-upstream-doc**: only raise the floor on packages that actually consume a new core API introduced in the bump. This requires per-package code inspection because release probes use the co-released local core and cannot prove compatibility with an older published core floor.\n\nWhen raising a core floor, replace only the `>=OLD` half of the bound you intend to change:\n\n```bash\nfile=\"python\u002Fpackages\u002F\u003Cpkg>\u002Fpyproject.toml\"\nsed -i.bak \"s\u002Fagent-framework-core>=${OLD_CORE}\u002Fagent-framework-core>=${NEW_CORE}\u002F\" \"$file\"\nrm \"${file}.bak\"\n```\n\nIf `core` did not bump this cycle, do not touch floors.\n\n### 7. Generate the reviewed release batch and validate\n\nAfter applying the selected bumps and dependency edits, stage any new workspace package metadata with\n`git add python\u002Fpackages\u002F\u003Cpackage>\u002Fpyproject.toml`. The generator fails explicitly if workspace metadata is still\nuntracked, rather than silently omitting that distribution. Existing tracked metadata need not be staged.\nGenerate the manifest from that same metadata diff:\n\n```bash\nRELEASE_TAG=\"python-\u003Crelease-label>\"\nuv run --directory python --group tool-runtime poe prepare-python-release --base-ref \"$RELEASE_BASE\" --tag \"$RELEASE_TAG\"\n```\n\nThe generator reuses the release validator's changed-`pyproject.toml` selection, then includes only packages whose\nversion increased (or new workspace packages). Compare package identity by canonical distribution name, not directory:\na move does not make an existing version new, and a renamed distribution is a new identity. Dependency-only metadata\nedits remain part of dependency validation but do not select an unchanged version for publication. The generator\nrejects a Core release without a version increase for root `agent-framework`; the explicit cohort decision above\nstill determines other bumps. The excluded standalone Lab workspace is not part of this batch.\n\nCommit **`python\u002F.github\u002Frelease-${RELEASE_TAG}.json` in this same PR**, together with the version and lockfile changes.\nThe filename includes the full tag: `python-1.24.0` produces `python\u002F.github\u002Frelease-python-1.24.0.json`.\nDo not maintain a duplicate list of versions manually. Regenerate the new file after changing the bump list while\nthe PR is open. Once it is part of the release base, it is historical: never edit, replace, or delete it.\nFor example, `python\u002F.github\u002Frelease-python-1.24.0.json` contains:\n\n```json\n{\n  \"tag\": \"python-1.24.0\",\n  \"packages\": {\n    \"agent-framework\": \"1.24.0\",\n    \"agent-framework-core\": \"1.24.0\",\n    \"agent-framework-foundry\": \"1.16.0\"\n  },\n  \"smoke_imports\": {\n    \"agent-framework\": [\"agent_framework:Agent\"],\n    \"agent-framework-core\": [\"agent_framework:Message\"],\n    \"agent-framework-foundry\": [\"agent_framework.foundry:FoundryAgent\"]\n  }\n}\n```\n\nContract:\n\n- `tag` and non-empty `packages` are required. The tag is one overall `python-\u003CPEP440-version>` release label, not\n  a requirement that every selected distribution share a version. No source commit SHA is stored in this file:\n  Azure DevOps resolves the immutable tagged commit and reads `python\u002F.github\u002Frelease-\u003Cfulltag>.json` there.\n  Both sides derive this exact path from the expected full tag. Never scan for the latest file or fall back to\n  the old fixed `.github\u002Frelease.json` or root `release.json` paths.\n  Generation and PR validation reject tags already present in the freshly fetched local tag refs. Fetch tags as in\n  step 1 before preparation. Published-release validation permits its existing tag and checks the qualified\n  `refs\u002Ftags\u002F\u003Cfulltag>` revision; PR checks use the immutable event SHA, not a moving merge ref.\n- Keys are exact canonical distribution names; values are PEP 440 strings equal to the tagged `project.version`.\n  The expected tag must match the manifest tag, preventing reuse of a stale batch. PyPI absence is validation,\n  **never selection**.\n- `smoke_imports` is an optional additive map of public `module:export` checks (classes or functions). The generator\n  emits it for **every** selected distribution. The consumer only has built-in defaults for meta\u002Fcore\u002FFoundry;\n  other packages require explicit reviewed checks. Unknown packages fail until `scripts\u002Fprepare_release.py`\n  has a reviewed public import entry. A check imports the module and resolves the export, without creating an\n  agent, opening a connection, or calling a service.\n- Prefer public `agent_framework.*` bridges. Never derive checks from build configuration (the root's\n  `agent_framework_meta` is not its public API), or substitute a private implementation module.\n  Packages without a bridge use their documented public top-level entry points. The explicit exceptions are\n  `agent_framework_azure_cosmos_memory`, `agent_framework_azure_documentdb`, `agent_framework_duckdb`,\n  `agent_framework_hosting`, `agent_framework_hosting_a2a`, `agent_framework_hosting_mcp`,\n  `agent_framework_hosting_responses`, `agent_framework_hosting_telegram`, `agent_framework_mongodb`,\n  `agent_framework_nvidia`, `agent_framework_oracle`, `agent_framework_postgres`, `agent_framework_qdrant`,\n  `agent_framework_sql_server`, and `agent_framework_typesafe`. See their package READMEs and exported `__all__`;\n  the inventory test checks each selected public export. A new exception must also be reviewed in the consumer\n  allowlist before release.\n\nFrom the repository root, check the generated file against the same base:\n\n```bash\nuv run --directory python --group tool-runtime python -m scripts.prepare_release --check --base-ref \"$RELEASE_BASE\" --tag \"$RELEASE_TAG\"\n```\n\nFor version increases of existing distributions or an explicit manifest change, PR CI requires exactly one new\nper-tag manifest and enforces agreement between its filename, JSON tag, and version changes. Ordinary development\nPRs that only add new distribution identities do not need to choose a release tag or add a manifest. Explicit\nrelease preparation still includes all selected new packages, and a supplied manifest is always validated.\nChanges or deletions of historical manifests fail the check. Earlier files remain browsable on `main`;\ntheir old package versions are not revalidated against current metadata. PRs without version or manifest changes\n(including dependency maintenance) do not need to add a manifest. These files record reviewed intended batches,\nnot proof that publication completed; that evidence is the verified artifact manifest on the published release.\n\n```bash\nuv run --directory python --group tool-runtime poe validate-python-release --base-ref \"$RELEASE_BASE\"\n```\n\nUse the same freshly fetched main ref that the release branch was based on (`upstream\u002Fmain` above; use `origin\u002Fmain`\nwhen that is the authoritative release base). Must exit 0. This task first regenerates `uv.lock`, then discovers the\npackage `pyproject.toml` files changed from that base and runs their published runtime dependencies and\nnon-development extras through lock-independent `lowest-direct` and `highest` import probes. The probes run in\nparallel, derive the minimum supported Python minor from each package's internal editable closure, and share a hard\n300-second deadline. Use `--python` only when the release requires an explicit interpreter override.\n\nThis is the release safety net for selective bumping: the lower probe catches unresolvable or unimportable external\nfloors, internal constraints that reject co-released package versions, and the upper probe catches caps that exclude\nan installable package set. The JSON report records the concrete versions resolved in both scenarios. It does not\nreplace the package-by-package code inspection required by the strict core-floor policy. If it fails, fix the named\npackage\u002Fbound and re-run before committing.\n\nDo not substitute the workspace-wide `validate-dependency-bounds-test` command here. That command runs every\npackage's full tests and Pyright in separate isolated environments and is intentionally reserved for CI or an\nexplicit dependency-range audit. The `Dependency Bounds Validation` check in `python-dependency-bounds.yml` runs that\nfull matrix for version-bump and new-workspace-package PRs and merge groups, while ordinary PRs skip it.\nThe bounded local release probes remain separate and do not replace that regression coverage.\nIf the release itself changes an external dependency range, also run\n`validate-dependency-bounds-project --mode both --package \u003Cpkg> --dependency \u003Cname>` for that dependency.\n\nIf only prereleases changed (no `core` bump, no floor changes), release validation is still required because the\nlockfile and both ends of each changed package's published dependency metadata must remain installable.\n\n### 8. Commit (expect hook retry)\n\nThe project's pre-commit hook runs `poe check` \u002F `poe typing` \u002F `uv lock` and may re-modify `uv.lock` on first commit attempt. Expected pattern — run twice:\n\n```bash\ngit add -u\ngit add \"python\u002F.github\u002Frelease-${RELEASE_TAG}.json\"  # New files are not included by git add -u.\ngit commit -m \"\u003Cmessage>\"   # may fail with \"files were modified by this hook\"\ngit add -u                  # re-stage hook-generated changes\ngit commit -m \"\u003Cmessage>\"   # succeeds\n```\n\n**Commit message format** — HEREDOC, no `Co-Authored-By`:\n\n```bash\ngit commit -m \"$(cat \u003C\u003C'EOF'\nBump Python package versions for \u003Crelease-label> release\n\n\u003COne paragraph explaining:\n - which packages bumped and why (CHANGELOG-driven)\n - semver rationale for any released-tier bumps\n - whether a beta cohort bump was applied\n - whether core floors were raised, and under which policy>\nEOF\n)\"\n```\n\n### 9. Push and report\n\n```bash\ngit push origin bump-py-ver-release-YYMMDD\n```\n\nThe push output includes a `Create a pull request for '\u003Cbranch>' on GitHub by visiting: \u003CURL>` line — surface that to the user.\n\n### 10. Maintainer handoff: tag and existing draft (only when authorized)\n\nAfter the reviewed bump PR merges, the maintainer selects the exact merged commit and creates the **one** overall\ntag matching its `python\u002F.github\u002Frelease-\u003Cfulltag>.json`. The maintainer creates a GitHub **draft** release for that tag.\nThe release title must exactly match the full tag name, including the `python-` prefix (for example, `python-1.26.0`).\nInclude complete release notes and the intended prerelease flag. Do not use a published release as the\ntrigger and do not create per-package tags. Release notes must be complete **before ESRP approval**; do not edit\nthe draft, tag, or selected source while a release run is in progress.\n\nAzure DevOps discovery polls eligible existing drafts and tags. It has a disabled-by-default activation switch,\nan explicit first eligible release ID, and durable claims on one retained ADO ledger run. A shared exclusive-lock\nenvironment serializes discovery, authorization and finalization to admit one run for the whole batch. No Azure\nstorage account is needed. No GitHub workflow calls or queues Azure DevOps.\n\nThe protected pipeline reads `python\u002F.github\u002Frelease-\u003Cfulltag>.json` from the exact tagged commit, validates the requested names,\nversions and tag, builds once, and runs isolated install\u002Fpublic-import checks against the selected artifacts.\nIt then waits for protected ESRP approval\u002Fpublication and verifies the published distributions. Only after that\nverification does it upload the **same built wheels\u002Fsdists and artifact manifest** to the **existing draft**,\nverify those assets, and change `draft` to `false`. It preserves the draft's title, body, and prerelease flag.\nThe source request (`python\u002F.github\u002Frelease-\u003Cfulltag>.json`) and the output artifact manifest (file names, versions, sizes\u002Fchecksums and\nsource provenance) are different records.\n\nThe published-event GitHub workflow validates the tag contract only. It must not build new artifacts, upload\nrelease assets, publish packages, or request Azure DevOps credentials.\n\n### Failure and recovery\n\n- Before approval\u002Fpublication: leave the draft unpublished, inspect the failing checks, and fix the source in a\n  reviewed PR if needed. Do not move an existing release tag or silently replace its manifest. A new release\n  attempt requiring source changes needs a new overall tag and appropriate new package versions.\n- A queued\u002Ffailed batch remains claimed. Use the consumer's audited recovery procedure to retry\u002Freconcile the\n  **same batch and retained artifact set**. Do not delete a claim to create parallel runs, queue individual\n  distributions, or bypass the approval gate with local `uv publish`\u002FTwine.\n- Publication may partially succeed before a failure. PyPI versions are immutable: inspect package versions,\n  retained artifact hashes, and the publication record before retrying. Already-published versions do not change\n  the reviewed selection. Never overwrite or rebuild artifacts and assume they are identical.\n- If publication succeeds but GitHub asset upload or finalization fails, keep the draft unpublished and retry\n  that finalization using the verified retained artifacts. Do not republish packages, create a replacement\n  release, or lose the human-authored release metadata.\n\n### Rollout order (no publication as part of implementation)\n\n1. Merge the Azure DevOps consumer first, with discovery disabled. Review the matching contract, artifact\n   verification, recovery, and draft-only finalization.\n2. Merge this repository's producer and retirement of the old GitHub build\u002Fupload path second.\n3. Reuse the existing Azure DevOps GitHub service connection `github-agent-framework`, already used by the .NET\n   release pipeline, and authorize it for the Python pipelines. Verify its repository and release access; do not\n   introduce a separate GitHub App, private key, or Key Vault token-minting setup. Configure the shared\n   `agent-framework-python-coordination` environment with an exclusive-lock check, initialize a retained discovery\n   run with `initializeLedger: true`, and set its `releaseLedgerRunId` in both ADO pipelines. Keep ledger and release\n   runs retained indefinitely. Verify the Build Service permissions and protected ESRP approval gates outside GitHub.\n   No separate Azure storage identity is needed. Verify the merged upstream revision is compatible. Reusing the\n   connection does not authorize a new pipeline automatically.\n4. Choose the first eligible draft release ID and activate tag\u002Fdraft discovery **last**, only after the previous\n   steps are confirmed. Do not create production tags\u002Fdrafts merely to test rollout.\n\nThe coordinated change requires both PRs and maintainer approval. Merging producer code alone must not enable\na second publisher or silently activate discovery.\n\nConnection reuse does not mean reusing a release task that rewrites metadata or replaces existing assets.\nThe consumer's asset-only REST finalizer must still preserve the existing draft's title, body, and prerelease flag,\nverify the exact retained artifacts, and publish only after verification. GitHub never receives Azure DevOps\ncredentials or queue permission.\n\n## Pitfalls from past cycles — avoid repeating\n\n- **Scoping from the wrong tag.** A release may have been tagged between bump cycles. Always compute `LAST_RELEASED_TAG` fresh — do NOT reuse the previous compare base. Symptom: dragging already-shipped PRs into the new CHANGELOG section.\n- **Bumping packages that had no changes.** This was the old lockstep default. Now: a package without a CHANGELOG entry does not bump. The two exceptions (root follows core, optional beta cohort bump) are explicit choices, not defaults.\n- **Touched package missing from CHANGELOG.** The inverse failure mode of the previous pitfall, and the dangerous one. If a PR landed code into `python\u002Fpackages\u002Ffoo\u002F` but the new CHANGELOG section has no `**agent-framework-foo**:` line, then `foo` will NOT bump, and the fix sits in `main` but never reaches PyPI. Always run the touched-vs-mentioned reconciliation in step 4a before applying bumps.\n- **Directory name vs PyPI name confusion.** Some package dirs use underscores or split names that differ from the published PyPI name (e.g. `foundry_local` → `agent-framework-foundry-local`). When reconciling touched dirs against CHANGELOG mentions, normalize on the PyPI form.\n- **Forgetting root when core bumps.** Root `agent-framework` has `agent-framework-core[all]==EXACT_VERSION`. If `core` bumps and root does not, the pin is broken. Always bump them together and update the pin string.\n- **Renaming an existing section header.** When drafting a new release, do NOT rewrite an existing `## [X.Y.Z]` header to a new label — that wipes the historical section. Always INSERT a new section above.\n- **Forgetting footer reference links.** When a released-tier bump is in play, the `[Unreleased]` line and the new `[X.Y.Z]` link at the bottom MUST be updated. Heading links don't resolve without them.\n- **Wrong footer compare base.** The new `[X.Y.Z]` line compares from the PREVIOUS released tag, not from two releases ago.\n- **Timezone drift.** For alpha\u002Fbeta date stamps, follow the `python-package-management` date-stamp rule;\n  do not infer a local timezone from the user's current shell.\n- **`Co-Authored-By` trailer.** Never add it. Rewrite\u002Famend if it slipped in.\n- **Stale inventory in this skill.** Always read `python\u002FPACKAGE_STATUS.md` for the live tier map. Do not trust a hardcoded list.\n- **Divergent origin vs upstream.** In fork clones, use freshly fetched `upstream\u002Fmain` consistently for branch creation, changeset discovery, and release validation. A stale `origin\u002Fmain` must never become the implicit compare base.\n- **`--pre` README cleanup on promotion.** When a package is promoted to `released` in this cycle, grep for `pip install agent-framework-\u003Cpkg> --pre` in READMEs and drop the `--pre` flag.\n- **RC counter inflation.** Do not increment `1.0.0rcN` without a CHANGELOG entry for that package. The counter tracks iterations, not calendar.\n\n## References\n\n- Package lifecycle and versioning source of truth: `python\u002F.github\u002Fskills\u002Fpython-package-management\u002FSKILL.md`\n- Lifecycle source of truth: `python\u002FPACKAGE_STATUS.md`\n- Release validator: `python\u002Fscripts\u002Fdependencies\u002Fvalidate_dependency_bounds.py --mode release` (changed-package,\n  lock-independent `lowest-direct` and `highest` import probes under a five-minute deadline)\n- Batch generator and read-only validator: `python\u002Fscripts\u002Fprepare_release.py`\n- Read-only PR\u002Fpublished-tag check: `.github\u002Fworkflows\u002Fpython-release.yml`\n- Poe task definitions: `python\u002Fpyproject.toml` `[tool.poe.tasks]`\n",{"name":5,"description":7},"main","e8e081ee462ce340a07657ea830dedb81445c70f","python\u002F.github\u002Fskills\u002Fagent-framework-py-release",2624,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework","https:\u002F\u002Faka.ms\u002Fagent-framework","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 14:06:55",{"source":8,"skillName":5,"commands":60,"prompt":70,"zipAvailable":71},[61,64,67],{"tool":62,"command":63},"npx","npx skills add microsoft\u002Fagent-framework --skill agent-framework-py-release",{"tool":65,"command":66},"bunx","bunx skills add microsoft\u002Fagent-framework --skill agent-framework-py-release",{"tool":68,"command":69},"pnpm","pnpm dlx skills add microsoft\u002Fagent-framework --skill agent-framework-py-release","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fpython\u002F.github\u002Fskills\u002Fagent-framework-py-release\u002FSKILL.md",true,[],[74,97,122,132,155,172],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":44},"01M70H1GNJPW85ENXA0BCPC6PF","draft-release-notes","Create or rewrite Agent Framework release notes from a generated GitHub release log. Use when preparing Python or .NET release notes, filtering mixed-language changelogs, deduplicating changes, preserving inline contributor credits, or documenting breaking-change migrations from pull requests. Requires the user to provide the generated GitHub log, language, and release version before work begins.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fdraft-release-notes\u002FSKILL.md",[],[81,82,26,83,84,42,24,85,86,87,88,89,90,91,92,93,94,95,96,38],"notes","release notes","draft","draft release notes","pull requests","create","pull","generated","filtering","use","version","log","release version","rewrite","mixed-language","contributor",{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":104,"publishedAt":44},"01M699C55AYGT1ZVZDHWFZNBDB","agent-framework-builder-python","Use this skill when building, modifying, reviewing, evaluating, integrating, or hosting Python applications with Microsoft Agent Framework. Use it for Agent Framework agents, harness agents, workflows, orchestrations, declarative definitions, tools, sessions, middleware, evaluation, observability, integrations, or hosting, even when the user has not yet chosen the correct framework pattern.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fskills\u002Fagent-framework-builder-python\u002FSKILL.md",[103],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[42,24,105,27,106,9,107,108,109,110,111,112,113,114,115,90,116,117,118,119,120,30,121,38],"agent framework builder python","builder","workflows","sessions","microsoft agent framework","harness","observability","Evaluation","applications","correct","integrations","hosting","pattern","middleware","with","orchestrations","declarative",{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":129,"publishedAt":44},"01M699C2PH4WPRCMV90NHANCY9","agent-framework-builder-dotnet","Use this skill when building, modifying, reviewing, evaluating, integrating, or hosting .NET (C#) applications with Microsoft Agent Framework. Use it for Agent Framework agents, harness agents, workflows, orchestrations, declarative definitions, tools, sessions, middleware, evaluation, observability, integrations, or hosting, even when the user has not yet chosen the correct framework pattern.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fskills\u002Fagent-framework-builder-dotnet\u002FSKILL.md",[128],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[24,130,131,27,106,9,107,108,109,110,111,113,114,115,90,118,119,120,30,121,38],"dotnet","agent framework builder dotnet",{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":139,"publishedAt":44},"01M699C0QKV5XEBE61PB8NV544","foundry-hosted-agent-validation","Step-by-step process for validating a Python Foundry hosted agent sample (under python\u002Fsamples\u002F04-hosting\u002Ffoundry-hosted-agents\u002F) end to end — running it locally (native runtime and `azd ai agent run`) and after deploying it to an Azure AI Foundry project with `azd`. Use this when asked to validate a hosted agent sample.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fpython\u002Fscripts\u002Fsample_validation\u002Fskills\u002Ffoundry-hosted-agent-validation\u002FSKILL.md",[138],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[140,141,142,42,143,144,145,146,27,147,148,90,149,150,151,152,153,30,38,154],"foundry","foundry hosted agent validation","validation","ai agent","azure","run","azure ai foundry","tool","model","project","sample","runtime","end","native","running",{"skillNo":156,"name":157,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":161,"publishedAt":44},"01M699BYCYJD8RXC5MYY61WBPR","foundry-config-setup","Resolve missing setup caused by a hardcoded Foundry project endpoint or model in a sample. Use when a sample fails because it uses a placeholder\u002Fhardcoded project_endpoint (for example \"https:\u002F\u002Fyour-project.services.ai.azure.com\") or a hardcoded model instead of reading them from the environment.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fpython\u002Fscripts\u002Fsample_validation\u002Fskills\u002Ffoundry-config-setup\u002FSKILL.md",[],[140,162,163,164,165,144,166,167,168,147,148,169,90,170,149,150,171,119,30,38],"foundry config setup","config","setup","placeholder","tool use","https","services","environment","example","missing",{"skillNo":173,"name":174,"nameZh":6,"description":175,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":176,"categories":177,"keywords":178,"publishedAt":44},"01M699BWSTE6SGCCBY3JFP10GQ","support-style","Contoso Outdoors customer-support tone and formatting guidelines.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagent-framework\u002Fblob\u002Fmain\u002Fpython\u002Fsamples\u002F04-hosting\u002Ffoundry-hosted-agents\u002Fresponses\u002Ffoundry_toolbox_mcp_skills\u002Fskills\u002Fsupport-style\u002FSKILL.md",[],[179,180,181,182,183,184,185],"support","support style","style","customer","guidelines","tone","formatting"]