[bmehta001]

Motivation & Context

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

Description & Review Guide

• What are the major changes? Updates SDK setup and model loading for SDK 2.3.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.3.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.

[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.

[bmehta001]

Thanks Eduard van Valkenburg (@eavanvalkenburg) - I have fixed the merge conflicts

[bmehta001]

Eduard van Valkenburg (@eavanvalkenburg) I have updated the PR again to fix merge conflicts and use Foundry Local 2.3.1

[Eduard van Valkenburg (eavanvalkenburg)]

bmehta001 The SDK migration makes the standard install unsatisfiable on Intel macOS. The all extra still selects Foundry Local on CPython 3.13/macOS/x86_64, but foundry-local-sdk 2.3.1 and its native dependencies publish ARM64-only macOS wheels and no source distribution. Please gate the Foundry Local dependencies by supported platform/architecture so users who do not use this integration can still install the rest of the framework on Intel Macs.

[bmehta001]

Eduard van Valkenburg (@eavanvalkenburg) Addressed in d0577d4. Added matching platform/architecture markers to the core all extra and the integration SDK dependency, so Intel macOS no longer pulls Foundry Local through the standard install, and workspace installs also skip the native SDK. Updated the lockfile and installation docs.