Critical Migration Guide
The azure-ai-projects v2.0.0 GA release introduced breaking changes that require attention from all existing Foundry developers.
Breaking Changes Summary
| Change | Before (v1.x) | After (v2.x) |
|---|
| Agent Package | Separate azure-ai-agents | Removed — agents live in azure-ai-projects |
| Thread Concept | Threads | Replaced by Conversations |
| Tool Classes | Old names | Suffixed with Tool (GA) or PreviewTool |
| Tracing Spans | Custom names | OpenTelemetry gen_ai.* conventions |
| Protocol | Assistants API | OpenAI Responses API protocol internally |
Critical Retirement Deadlines
| Deadline | What's Retiring | Action Required |
|---|
| May 30, 2026 | azure-ai-inference package | Migrate to the openai package |
| June 30, 2026 | AzureML SDK v1 | Migrate to azure-ai-projects v2 |
| August 26, 2026 | Assistants API | Rewrite agents using Foundry Agent Service |
Migration Checklist
pip uninstall azure-ai-agents # Remove old package
pip install "azure-ai-projects>=2.0.0" # Install unified SDK
# Update: Threads → Conversations
# Update: Tool class names (add Tool/PreviewTool suffix)
# Update: KQL dashboards for new gen_ai.* span names
🚧 Important: The allow_preview boolean on the AIProjectClient constructor replaces previous per-method feature flags. Set it to True to access preview features like Memory Service and MCP Server.