Menu
Managing preview/beta Azure AI SDK dependencies in Python services to prevent build-time drift
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| 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)