[bmehta001]

Motivation & Context

The Foundry Local integration still uses SDK 0.5.1. This updates it to work with SDK 2.2.1.

Description & Review Guide

• What are the major changes? Updates SDK setup and model loading for SDK 2.2.1, adds support for SDK-registered local models, and keeps the existing chat, streaming, and tool support.
• What is the impact of these changes? Requires Python 3.11-3.14 and SDK 2.2.1 or later, below 3.0. Older SDK versions are no longer supported. prepare_model=False still loads the configured model on the first request, including streaming; manual loading is not required.
• What do you want reviewers to focus on? Model setup, loading on first use, and cleanup when setup fails.

Image support has not been verified. Audio and embeddings are outside this PR.

Related Issue

Fixes #9321.

Original report: microsoft/homebrew-foundrylocal#31.

Maintainer agreement and human review are pending.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. Human review is pending.

AI assistance details: GitHub Copilot helped with the code, tests, documentation, and this description.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) -- a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Python 3.15 compatibility declarations and CI gating are inconsistent, and singleton construction has a concurrency race.

5 open findings

• Exclude this package from the Python 3.15 workspace job · New
• Gate the all extra for Python versions supported by the SDK · New
• Synchronize concurrent manager initialization · New
• Bound adapter Python support to SDK-compatible versions · New
• Document the SDK-compatible Python upper bound · New

What changed in this PR

Migrates the Python Foundry Local integration to SDK 2.1, addressing #9321 while retaining Agent Framework’s OpenAI transport.

Changes:

• Adopts the SDK singleton, catalog/model lifecycle, and built-in web service.
• Raises support to Python 3.11+ and updates dependencies and CI.
• Expands migration documentation and regression tests.

File	Description
.github/​workflows/​python-tests.yml	Updates Python-version exclusions.
python/​packages/​core/​pyproject.toml	Gates the Foundry Local extra.
python/​packages/​foundry_local/​AGENTS.md	Updates package guidance.
python/​packages/​foundry_local/​README.md	Documents usage and migration.
python/​packages/​foundry_local/​agent_framework_foundry_local/​_foundry_local_client.py	Implements SDK 2.1 integration.
python/​packages/​foundry_local/​pyproject.toml	Updates Python and SDK requirements.
python/​packages/​foundry_local/​tests/​conftest.py	Adds SDK-aware fixtures.
python/​packages/​foundry_local/​tests/​test_foundry_local_client.py	Expands lifecycle and transport tests.
python/​samples/​02-agents/​providers/​foundry/​foundry_local_agent.py	Updates sample APIs and cleanup.
python/​uv.lock	Resolves SDK 2.1 dependencies.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[bmehta001]

Eduard van Valkenburg (@eavanvalkenburg) Thanks for the comment. I have updated the PR to support raw JSON schema as well.

[Eduard van Valkenburg (eavanvalkenburg)]

bmehta001 Please address the inline automatic-tool-selection finding before merge.

[bmehta001]

Eduard van Valkenburg (@eavanvalkenburg) Thanks; have addressed. I restored the original function-layer generic, unsupported decoder controls are explicitly rejected, and automatic tool selection with structured output is explicitly rejected while required/named tool flows are preserved. The earlier raw-schema compatibility fix and its agent-framework-openai 1.6.0-style regression coverage remain in place; no dependency-floor changes were made. One existing check limitation remains: Zuban reports the same two SupportsChatGetResponse.client errors at test_foundry_local_client.py:77-78 on both the prior branch head and this commit.

[Eduard van Valkenburg (eavanvalkenburg)]

bmehta001 One material regression remains in python/packages/foundry_local/agent_framework_foundry_local/_foundry_local_client.py:219 and :328. Forwarding response_format={"type": "text"} to Foundry Local SDK 2.2.1 sets tool_choice="none", so an agent requesting ordinary text can silently skip tools it needs in both streaming and non-streaming calls. Please remove that explicit text format from the outgoing options, or otherwise preserve the caller’s automatic tool choice, and add regressions for omitted/automatic tool selection in both response modes.

[bmehta001]

Eduard van Valkenburg (@eavanvalkenburg) Addressed in 9819191. Explicit response_format={"type":"text"} is now omitted from outgoing requests, preserving automatic tool selection in SDK 2.2.1 without mutating caller options or changing structured-output handling.

Expanded the HTTP tool-loop regressions for omitted, string auto, and dictionary-form automatic selection in streaming and non-streaming modes (plus required tools and disabled local invocation). They verify no text format reaches either request, exactly-once tool execution, the matching tool-result message, and the final text response. The new text cases failed before the fix.