Registry /
llm-agents / agent-framework-foundry-local
Install & Compatibility
Where this runs
tested against v1.0.0b260521 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FoundryLocalClient
✓ from agent_framework.foundry import FoundryLocalClient
FoundryLocalClient is the primary class for connecting to the local Foundry service.
Agent
✓ from agent_framework import Agent
Used to create and manage the agent instance, typically configured with a FoundryLocalClient.
This quickstart demonstrates how to create and run a simple AI agent using FoundryLocalClient to connect to a locally hosted LLM via the Foundry Local runtime. Ensure the Foundry Local CLI is installed, the service is running (`foundry service start`), and the specified model (e.g., `phi-4-mini`) is available locally.
import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryLocalClient
async def main():
# Set the default local model (e.g., phi-4-mini, qwen2.5) as an environment variable or pass explicitly
# Ensure Foundry Local CLI is installed and 'foundry service start' has been run.
# Optionally, set: os.environ['FOUNDRY_LOCAL_MODEL'] = 'phi-4-mini'
client = FoundryLocalClient(model='phi-4-mini') # Requires 'phi-4-mini' model to be downloaded via Foundry Local CLI
agent = Agent(
client=client,
name='LocalAssistant',
instructions='You are a helpful local assistant that runs entirely on my machine.'
)
print("Local agent created. Asking a question...")
result = await agent.run("Tell me a fun fact about Python.")
print(f"Agent response: {result}")
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
breakingThe broader Microsoft Agent Framework (which `agent-framework-foundry-local` integrates with) underwent significant architectural changes in its 1.0.0 release. Specifically, the `Message` constructor's `text` parameter was removed in favor of `contents=[...]`, and provider designs shifted. Existing code relying on older patterns of the `agent-framework` with `FoundryLocalClient` may break and require migration.fixUpdate `agent-framework` to 1.0.0 or later and revise message construction to use `Message(contents=[...])`. Consult the official migration guide for Agent Framework 1.0.0.
affects: agent-framework < 1.0.0 (when migrating to >=1.0.0)
gotchaThis package requires the separate installation and active running of the Foundry Local CLI and its runtime components. `pip install` only installs the Python client library, not the local LLM server.fixBefore running Python code, install Foundry Local via `winget install Microsoft.FoundryLocal` (Windows) or `brew tap microsoft/foundrylocal && brew install foundrylocal` (macOS), then start the service with `foundry service start`.
affects: All versions
gotchaThe first time a model is used with Foundry Local, it needs to be downloaded, which can take a significant amount of time and consume considerable disk space depending on the model size.fixPlan for initial model download time. Use `foundry model list` to see available models and `foundry model run <model_name>` or `foundry model download <model_name>` to pre-download models if desired.
affects: All versions
gotchaFunction/tool calling and structured output capabilities of the agent are dependent on the specific local model chosen and its support within Foundry Local. Not all local models support these advanced features.fixConsult Foundry Local documentation for specific models' capabilities. The `FoundryLocalClient.manager` helper can be used to inspect the local catalog and supported features.
affects: All versions
gotchaFoundry Local is designed for on-device inference and local development. It is not intended for distributed, containerized, or multi-machine production deployments.fixFor production deployments requiring scalability and managed services, consider using `agent-framework-foundry` with Azure AI Foundry's hosted services rather than `agent-framework-foundry-local`.
affects: All versions
Upgrade
Version history
1.0.0b260521latest on PyPI · released May 22, 2026
Audit
Dependencies
agent-frameworkrequiredThis package is an integration for the Microsoft Agent Framework, which provides the core agent abstractions and runtime. FoundryLocalClient is typically paired with a standard Agent from the core framework.
Foundry Local CLI/runtimerequiredFoundry Local is a separate CLI tool and runtime that manages and serves local language models, providing an OpenAI-compatible API that agent-framework-foundry-local connects to.