Menu
Managing preview/beta Azure AI SDK dependencies in Python services to prevent build-time drift
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | preview-sdk-pinning |
| description | Managing preview/beta Azure AI SDK dependencies in Python services to prevent build-time drift |
| domain | dependency-management |
| confidence | high |
| source | earned (eval-403 incident, issue #137, commit 0b6255a) |
Preview-channel Azure AI SDKs (agent-framework-*, azure-ai-inference betas, azure-ai-projects prereleases) do not follow semantic versioning guarantees. Minor version bumps often introduce breaking API changes. Using wildcard ("*") or open-ended ranges (">=1.0.0b9,<2.0.0") in pyproject.toml causes non-deterministic builds — every pip install or container rebuild resolves to the latest PyPI release, potentially breaking working code.
Incident example (eval-403):
agent-framework-core = "*"This skill applies when:
< 1.0.0agent-framework-core, agent-framework-foundry, azure-ai-inference betasRule: All preview-channel Azure AI SDKs use exact version pins (no ranges, no wildcards).
# ✅ CORRECT
agent-framework-core = "1.2.2"
agent-framework-foundry = "1.2.2"
azure-ai-inference = "1.0.0b9"
# ❌ WRONG (allows arbitrary upgrades)
agent-framework-core = "*"
agent-framework-foundry = ">=1.2.0,<2.0.0"
azure-ai-inference = ">=1.0.0b9,<2.0.0"
Exception to repo standard: Normal Python deps use ^ or >=min,<next-major ranges to prevent transitive conflicts (per .squad/decisions.md memory). Preview SDKs are the only exception — exact pins prevent silent breakage.
Before pinning, identify the version published before the breaking change:
# Get all releases sorted chronologically
curl -s https://pypi.org/pypi/agent-framework-core/json \
| jq -r '.releases | to_entries | .[] | "\(.key): \(.value[0].upload_time)"' \
| sort -V
# Filter releases after a specific date
curl -s https://pypi.org/pypi/agent-framework-core/json \
| jq -r '.releases | to_entries | .[] | select(.value[0].upload_time > "2026-05-13T00:00:00") | "\(.key): \(.value[0].upload_time)"'
# Get just version numbers (for quick listing)
curl -s https://pypi.org/pypi/agent-framework-core/json \
| jq -r '.releases | keys | .[]' | sort -V | tail -10
Pattern: Use the last version published before your container stopped working (look at Docker build timestamps or deployment logs).
When bumping preview SDKs, commit message MUST include:
git commit -m "build(deps): bump agent-framework-core 1.2.2 → 1.3.1
Upgrade for async streaming support in FoundryAgent.
Tested:
- Eval pipeline: ✅ (prompt-134 passes)
- Chatbot streaming: ✅ (no token lag)
- AI service anomaly detection: ✅
Refs: #142
"
Do not exact-pin stable libraries — transitive dependency conflicts will occur.
# ✅ CORRECT (stable libs use ranges)
fastapi = "^0.115.0"
pydantic = "^2.9.0"
redis = "^5.2.1"
azure-identity = "^1.17.0" # stable API
# Preview SDKs get exact pins
agent-framework-core = "1.2.2"
# ❌ WRONG (exact-pinning everything causes dep hell)
fastapi = "0.115.3"
pydantic = "2.9.2"
redis = "5.2.1"
Rule of thumb: If the package version is < 1.0.0, has "beta" / "rc" suffix, or is in the azure-ai-* preview family, exact-pin it. Everything else uses ranges.
# 1. Query PyPI for last-good version (before 2026-05-13)
curl -s https://pypi.org/pypi/agent-framework-core/json \
| jq -r '.releases | to_entries | .[] | "\(.key): \(.value[0].upload_time)"' \
| sort -V
# Result: 1.2.2 published 2026-04-29, 1.3.0 published 2026-05-08 (breaking)
# Last-known-good: 1.2.2
# 2. Edit all affected services
vi src/ai-service/pyproject.toml
vi src/chatbot-service/pyproject.toml
vi src/account-opening-service/pyproject.toml
# Change:
# agent-framework-core = "*" → "1.2.2"
# agent-framework-foundry = "*" → "1.2.2"
# azure-ai-inference = ">=1.0.0b9,<2.0.0" → "1.0.0b9"
# 3. Commit with detailed message
git add src/*/pyproject.toml
git commit -m "fix(deps): exact-pin agent-framework preview SDKs to stop daily-build drift"
# Scenario: ai-service has open-ended ^1.3.0 (pin-guard violation),
# account-opening and chatbot are at 1.7.0. User wants all at 1.8.1.
# 1. Edit all three pyproject.toml files
vi src/ai-service/pyproject.toml
vi src/account-opening-service/pyproject.toml
vi src/chatbot-service/pyproject.toml
# Change:
# agent-framework-core = "^1.3.0" → "1.8.1"
# agent-framework-foundry = "^1.3.0" → "1.8.1"
# (and same for other two services from 1.7.0 → 1.8.1)
# 2. Test each service with 1.8.1 installed (isolated venvs)
cd src/ai-service && python3 -m venv .venv-test
source .venv-test/bin/activate
pip install agent-framework-core==1.8.1 agent-framework-foundry==1.8.1
pip install pytest pytest-asyncio <other test deps>
python -m pytest tests/ -q
# Result: 113 passed ✅
cd ../account-opening-service && python3 -m venv .venv-test
source .venv-test/bin/activate
pip install agent-framework-core==1.8.1 agent-framework-foundry==1.8.1
pip install pytest pytest-asyncio <other test deps>
python -m pytest tests/ -q
# Result: 150 passed ✅
cd ../chatbot-service && python3 -m venv .venv-test
source .venv-test/bin/activate
pip install agent-framework-core==1.8.1 agent-framework-foundry==1.8.1
pip install pytest pytest-asyncio <other test deps>
python -m pytest tests/ -q
# Result: 27 passed ✅
# 3. Verify pin-guard passes
grep -nHE '^agent-framework[a-z-]*[[:space:]]*=[[:space:]]*"(\*|[\^~>].*|>=.*)"' src/*/pyproject.toml
# Result: no output ✅
# 4. Commit with detailed message
git add src/*/pyproject.toml
git commit -m "build(deps): upgrade agent-framework to 1.8.1 (exact-pin)
Upgrades all three services to agent-framework-core/foundry 1.8.1
(from 1.7.0 in account-opening/chatbot, ^1.3.0 in ai-service).
Fixes pin-guard violation in ai-service that blocked Dependabot PRs.
Breaking changes: NONE (1.8.1 is backward-compatible with 1.7.0).
Tested:
- ai-service: 113 passed
- account-opening-service: 150 passed
- chatbot-service: 27 passed
- Pin-guard: passes (no violations)
Decision: .squad/decisions/inbox/turk-af-181-upgrade.md
"
Key takeaway: 1.7.0 → 1.8.1 was a clean upgrade with zero breaking changes. Always verify with isolated venvs + full test suites before committing.
[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.115.0"
pydantic = "^2.9.0"
# New preview SDK — exact-pin from day 1
azure-ai-contentunderstanding = "0.1.0a3" # ← exact version
agent-framework-core = "*"
azure-ai-inference = "*"
Why wrong: Every pip install resolves to latest PyPI. Non-deterministic builds, silent breakage on container rebuild.
azure-ai-inference = ">=1.0.0b9,<2.0.0"
Why wrong: Still allows arbitrary beta upgrades (b9 → b10 → b11, all with breaking changes). Lock to exact beta.
fastapi = "0.115.3"
pydantic = "2.9.2"
Why wrong: Transitive deps (uvicorn, starlette, etc.) need wiggle room. Exact pins cause "cannot resolve dependency" errors. Only preview SDKs get exact pins.
# Someone bumps agent-framework-core 1.2.2 → 1.4.0 without testing
# Eval pipeline breaks in production
Why wrong: Eval contract is fragile. Always smoke-test POST /evals/run after upgrading agent-framework-*.
agent-framework.*= "\*".github/workflows/preview-sdk-pin-guard.ymltask lint:preview-sdk-pins.squad/decisions/inbox/basher-137-preview-sdk-pinning.md.squad/decisions.md line 4250 (normal deps use >=min,<next-major, preview SDKs are exception)