Add azure-monitor-opentelemetry to dev deps

Fixes Samples & Markdown CI failure. The PR's new transitive dep on
azure-monitor-opentelemetry-exporter (via azure-ai-agentserver-core) makes
pyright resolve the azure.monitor.opentelemetry namespace, flipping the
check_md_code_blocks diagnostic for `configure_azure_monitor` from
reportMissingImports (filtered) to reportAttributeAccessIssue (not filtered).
Installing the umbrella azure-monitor-opentelemetry package in dev makes
pyright resolve the symbol correctly, matching the install guidance the
observability README already gives users.

.gitignore

@@ -203,6 +203,8 @@ temp*/
 
 # AI
 .claude/
+.omc/
+.omx/
 WARP.md
 **/memory-bank/
 **/projectBrief.md

docs/decisions/0025-foundry-toolbox-support.md

@@ -0,0 +1,454 @@
+---
+status: proposed
+contact: evmattso
+date: 2026-04-10
+deciders: evmattso
+---
+
+# Foundry Toolbox Support in FoundryChatClient
+
+## What is the goal of this feature?
+
+Enable Agent Framework users to consume Foundry **toolboxes** — named, versioned bundles of tool definitions stored server-side in an Azure AI Foundry project — directly from `FoundryChatClient`, without dropping to the raw `azure-ai-projects` SDK.
+
+A user who has configured a toolbox in the Foundry portal (or via the raw SDK) should be able to load it into an agent with a single call:
+
+```python
+toolbox = await client.get_toolbox("research_tools")
+agent = Agent(client=client, instructions="...", tools=toolbox)
+```
+
+**Success metric:** an agent can consume a toolbox with no manual handling of version-resolution logic on the user's side.
+
+## What is the problem being solved?
+
+`azure-ai-projects==2.1.0a20260409002` ships a new `BetaToolboxesOperations` surface, reachable as `AIProjectClient.beta.toolboxes` on the raw SDK client (and therefore as `FoundryChatClient.project_client.beta.toolboxes` through our wrapper), that lets teams:
+- Group related hosted tools (code interpreter, file search, MCP, web search, etc.) under a named toolbox
+- Version toolboxes immutably, so agents can pin to a specific configuration for production stability
+- Share toolboxes across multiple agents in a project
+
+However, consuming a toolbox from the framework today requires:
+1. Knowing the raw SDK accessor path (`client.project_client.beta.toolboxes`)
+2. Making two calls for the common case — `.get(name)` to find the default version, then `.get_version(name, version)` to actually retrieve tools
+3. Manually unpacking `toolbox.tools` before passing them to `Agent(tools=...)`
+
+None of this is hard, but it's the kind of boilerplate that should live in the client. Every other hosted tool in `FoundryChatClient` (code interpreter, file search, web search, image generation, MCP) already has a factory method (`get_code_interpreter_tool()`, etc.). Toolbox support should fit the same shape on the chat-client composition surface.
+
+## API Changes
+
+### One new method on the FoundryChatClient surface
+
+The public toolbox-consumption surface lands on:
+
+- `RawFoundryChatClient` (inherited by `FoundryChatClient`) in `_chat_client.py`
+
+The implementation delegates to shared helper functions in `_tools.py` so there is a single source of truth for the SDK calls.
+
+**Scope note:** `FoundryAgent` is intentionally not part of this design. `FoundryAgent` is the runtime surface for invoking an already-configured server-side Foundry agent; if that agent should use a toolbox, the toolbox/tools should already be configured on the Foundry side (UI or `azure-ai-projects` authoring flow) before MAF connects to it.
+
+**Scope note:** Authoring a server-side agent whose definition references a toolbox (via `PromptAgentDefinition(tools=toolbox.tools, ...)` + `client.agents.create_version(...)`) is deliberately outside MAF scope. That is an `azure-ai-projects` / service-resource authoring concern, not a future MAF feature. Users who need it should use the raw Azure SDK directly.
+
+```python
+async def get_toolbox(
+    self,
+    name: str,
+    *,
+    version: str | None = None,
+) -> ToolboxVersionObject:
+    """Fetch a Foundry toolbox by name.
+
+    If ``version`` is ``None``, resolves the toolbox's current default version
+    (two requests). If ``version`` is specified, fetches that version directly
+    (single request).
+
+    :param name: The name of the toolbox.
+    :param version: Optional immutable version identifier to pin to.
+    :return: A ``ToolboxVersionObject``. Pass its ``tools`` attribute to
+        ``Agent(tools=toolbox.tools)``.
+    :raises azure.core.exceptions.ResourceNotFoundError: If the toolbox or
+        version does not exist.
+    """
+
+```
+
+### Return types: raw SDK models, no custom wrappers
+
+Methods return the `azure.ai.projects.models` types directly:
+
+- `get_toolbox()` → `ToolboxVersionObject` (has `.name`, `.version`, `.tools`, `.id`, `.created_at`, `.description`, `.metadata`, `.policies`)
+
+No custom wrapper classes are defined. Returning the SDK types directly:
+- Eliminates maintenance overhead of keeping a custom wrapper aligned with SDK changes
+- Matches the existing convention — `get_code_interpreter_tool()` returns the raw `CodeInterpreterTool` SDK type
+- Means any new fields the SDK adds to these types flow through automatically
+
+`Agent(..., tools=...)` will accept the fetched toolbox object directly by flattening to `toolbox.tools` internally.
+
+### Design decisions
+
+**Instance methods, not `@staticmethod` factories.** Existing `get_code_interpreter_tool()` / `get_mcp_tool()` / etc. are `@staticmethod` because they're pure factories with no network I/O. Toolbox fetching requires the project client, so these new methods must be instance methods. This is a deliberate departure from the existing-factory pattern, justified by the async-with-I/O nature of the operation.
+
+**Raw SDK type passthrough (no custom wrappers).** There is only one toolbox type in the Foundry SDK and maintaining a shadow wrapper would create alignment risk as the SDK evolves. The raw `ToolboxVersionObject` and `ToolboxObject` carry all the fields users need. Individual tools inside `toolbox.tools` are the same `azure.ai.projects.models.Tool` subclasses returned by other factory methods.
+
+**Two-request default-version path.** When `version=None`, implementation calls `.get(name)` to find `default_version`, then `.get_version(name, default_version)` for the tools. Caching the default-version mapping was considered and rejected — default versions can change server-side via `update(default_version=...)`, and a stale cache would silently give callers the wrong tools. Two requests at agent setup is acceptable.
+
+**No discovery/listing surface in MAF.** Discovery is intentionally left to the raw `azure-ai-projects` client. MAF does not currently expose project-resource listing surfaces for many other Foundry resources (deployments, vector stores, agents, etc.), so the toolbox design stays narrowly focused on explicit retrieval by name/version.
+
+**Shared helpers in `_tools.py`.** The SDK-call helper function (`fetch_toolbox`) lives in a shared module so the chat-client surface stays thin and the request logic remains centralized.
+
+**`tools=toolbox` convenience, not a new wrapper type.** Although `get_toolbox()` returns the raw `ToolboxVersionObject`, Agent Framework can still support `tools=toolbox` / `tools=[toolbox]` by flattening the toolbox's `.tools` internally. That matches existing SDK ergonomics where some higher-level objects can be placed directly in `tools=` and unpacked underneath, without introducing a public `FoundryToolbox` wrapper.
+
+**Errors pass through unchanged.** `ResourceNotFoundError`, `HttpResponseError`, etc. from the SDK propagate as-is. No framework-specific exception hierarchy.
+
+## E2E Code Samples
+
+### Primary sample
+
+New file: `samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py`
+
+```python
+import asyncio
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+
+
+async def main() -> None:
+    client = FoundryChatClient(credential=AzureCliCredential())
+
+    toolbox = await client.get_toolbox("research_tools")
+    print(f"Loaded toolbox {toolbox.name}@{toolbox.version} ({len(toolbox.tools)} tools)")
+
+    agent = Agent(
+        client=client,
+        instructions="You are a research assistant.",
+        tools=toolbox,
+    )
+
+    result = await agent.run("What are the latest developments in quantum error correction?")
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Version pinning
+
+```python
+toolbox = await client.get_toolbox("research_tools", version="v3")
+```
+
+### Combining multiple toolboxes
+
+```python
+toolbox_a = await client.get_toolbox("research_tools")
+toolbox_b = await client.get_toolbox("some_other_tools", version="v3")
+
+agent = Agent(
+    client=client,
+    instructions="...",
+    tools=[toolbox_a, toolbox_b],
+)
+```
+
+### Combining toolbox tools with locally defined tools
+
+```python
+toolbox = await client.get_toolbox("research_tools")
+
+def get_internal_metrics(metric_name: str) -> dict:
+    """Custom tool that reads from an internal dashboard."""
+    ...
+
+agent = Agent(
+    client=client,
+    instructions="...",
+    tools=[get_internal_metrics, toolbox],
+)
+```
+
+### Selecting only some tools from a toolbox
+
+Developers will not always want to pass the entire toolbox through unchanged. A
+small helper in the Foundry package provides local post-fetch selection without
+changing the raw return type of `get_toolbox()`.
+
+```python
+from agent_framework.foundry import select_toolbox_tools
+
+toolbox = await client.get_toolbox("research_tools")
+
+selected_tools = select_toolbox_tools(
+    toolbox,
+    include_names=["githubmcp", "code_interpreter"],
+)
+
+agent = Agent(
+    client=client,
+    instructions="Use only the selected toolbox tools.",
+    tools=selected_tools,
+)
+```
+
+Supported filters:
+
+```python
+from agent_framework.foundry import FoundryHostedToolType, select_toolbox_tools
+
+selected_tools = select_toolbox_tools(
+    toolbox,
+    include_types=["mcp", "code_interpreter"],  # type: Collection[FoundryHostedToolType]
+    exclude_names=["internal_admin_tool"],
+)
+```
+
+Helper signature:
+
+```python
+type FoundryHostedToolType = Literal[
+    "code_interpreter",
+    "file_search",
+    "image_generation",
+    "mcp",
+    "web_search",
+] | str
+
+def select_toolbox_tools(
+    tools: ToolboxVersionObject | Sequence[Tool | dict[str, Any]],
+    *,
+    include_names: Collection[str] | None = None,
+    exclude_names: Collection[str] | None = None,
+    include_types: Collection[FoundryHostedToolType] | None = None,
+    exclude_types: Collection[FoundryHostedToolType] | None = None,
+    predicate: Callable[[Tool | dict[str, Any]], bool] | None = None,
+) -> list[Tool | dict[str, Any]]:
+    ...
+```
+
+Normalized name precedence for `include_names` / `exclude_names`:
+
+1. MCP `server_label`
+2. generic tool `name`
+3. fallback tool `type`
+
+This keeps `get_toolbox()` as a thin fetch API and makes selection an explicit,
+local post-processing step, while still allowing the ergonomic
+`select_toolbox_tools(toolbox, ...)` call shape.
+
+## Native vs MCP consumption of a Foundry toolbox
+
+A Foundry toolbox can be consumed two ways. This design adds new implementation work only for the first:
+
+1. **Native consumption (in scope).** Tools execute inside Foundry's agent runtime. `get_toolbox()` returns the `ToolboxVersionObject` whose `.tools` attribute carries typed tool configs that the runtime interprets server-side. This design is specifically for `FoundryChatClient`-backed local agent composition.
+
+2. **MCP consumption (already supported through existing MCP abstractions).** A Foundry toolbox can also be exposed as an MCP server. In that case, use the existing `MCPStreamableHTTPTool(name=..., url=...)` — it already handles this path with any chat client (Foundry, OpenAI, Anthropic, etc.). No new Foundry-specific API is needed for MCP-exposed toolboxes in this design.
+
+### MCPStreamableHTTPTool example for a Foundry toolbox endpoint
+
+If Foundry gives you an MCP endpoint for the toolbox (for example from the
+toolbox details UI / endpoint surface), the existing MCP client path is:
+
+```python
+from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework.openai import OpenAIChatClient
+
+toolbox_mcp = MCPStreamableHTTPTool(
+    name="research_tools",
+    url="https://<foundry-toolbox-mcp-endpoint>",
+)
+
+agent = Agent(
+    client=OpenAIChatClient(),
+    instructions="You are a research assistant.",
+    tools=[toolbox_mcp],
+)
+```
+
+This is a different integration shape than `get_toolbox(...).tools`:
+
+- `get_toolbox(...).tools` = **native Foundry hosted-tool configs** interpreted by the
+  Foundry runtime
+- `MCPStreamableHTTPTool(name=..., url=...)` = **live MCP server connection** to a
+  toolbox endpoint
+
+The design in this spec adds first-class support only for the native hosted-tool
+path. The MCP path is already served by the framework's existing MCP abstractions.
+
+These paths are not unified because they have fundamentally different execution models. Native toolbox tools are declarative configs the Foundry runtime executes; MCP consumption is a live wire protocol to a running server.
+
+**MCP authentication inside a toolbox** is handled server-side via `project_connection_id` on individual `MCPTool` entries (OAuth connection objects configured in the Foundry project). The client never holds bearer tokens. Consent flow handling (`CONSENT_REQUIRED` → user-visible consent URL) happens during `agent.run()`, not during toolbox fetching — see Non-goals.
+
+## Testing Strategy
+
+Unit tests in `packages/foundry/tests/test_toolbox.py` with mocked `project_client.beta.toolboxes`. A single opt-in live round-trip, `test_integration_get_toolbox_round_trip_against_real_project`, is marked `@pytest.mark.integration`; it is skipped by default and only runs when the required Foundry credentials are available.
+
+Coverage:
+
+- `get_toolbox(name, version="v3")` — explicit version, single request. Assert `.get` not called, `.get_version` awaited once, returns `ToolboxVersionObject`.
+- `get_toolbox(name)` — default-version resolution. Assert `.get` then `.get_version` called in order with correct args.
+- Error propagation — `ResourceNotFoundError` from `.get` propagates unchanged.
+- Tool passthrough — heterogeneous tool list (`CodeInterpreterTool`, `MCPTool(project_connection_id=...)`) passes through unchanged. Asserts `project_connection_id` survives.
+- Agent integration smoke — `tools=toolbox` / `tools=[toolbox]` flatten to the underlying toolbox tools.
+- Multiple toolbox composition smoke — `tools=[toolbox_a, toolbox_b]` flattens into a single agent tool list.
+- `get_toolbox_tool_name()` — selection-name precedence is MCP `server_label`, then `name`, then `type`.
+- `select_toolbox_tools(toolbox, include_names=...)` — selects by normalized tool names directly from a fetched toolbox object.
+- `select_toolbox_tools(toolbox, include_types=...)` — selects by tool types with `Literal`-guided IDE completion.
+- `select_toolbox_tools(..., exclude_names=..., predicate=...)` — supports exclusion + custom predicates.
+
+Deliberately **not** covered:
+- Runtime consent-flow handling for OAuth MCP tools (see Non-goals).
+- Toolbox discovery/listing (`list_toolboxes`, `list_toolbox_versions`) — deliberately left to the raw Azure SDK.
+- Full CRUD (`create_version`, `update`, `delete`) and server-side agent authoring — see Non-goals.
+
+Live Foundry API integration is exercised only through the opt-in `@pytest.mark.integration` round-trip noted above; it is not part of the default test run.
+
+## Framework dependency: `normalize_tools` flattening
+
+The core `normalize_tools` function in `packages/core/agent_framework/_tools.py` already supports flattening composite tool inputs. Toolbox support extends that behavior so a fetched `ToolboxVersionObject` is treated as a composite tool source and flattened to its `.tools`.
+
+That enables:
+
+- `tools=toolbox`
+- `tools=[toolbox]`
+- `tools=[local_tool, toolbox]`
+- `tools=[toolbox_a, toolbox_b]`
+
+while still keeping `select_toolbox_tools(toolbox.tools, ...)` available for partial selection before the final agent construction step.
+
+## Telemetry
+
+Telemetry for toolbox support has two separate goals:
+
+1. **Observe toolbox API access** — `get_toolbox()`
+2. **Observe toolbox usage during agent runs** — when users pass toolbox-derived tools into `Agent(..., tools=...)`
+
+### Request telemetry for toolbox API access
+
+When Agent Framework constructs the `AIProjectClient` internally for `FoundryChatClient`, it already sets:
+
+```python
+user_agent=AGENT_FRAMEWORK_USER_AGENT
+```
+
+That means toolbox API requests made through:
+
+- `project_client.beta.toolboxes.get(...)`
+- `project_client.beta.toolboxes.get_version(...)`
+
+carry the standard MAF user-agent marker and can be queried in backend request logs the same way as other Foundry SDK calls made through framework-owned clients.
+
+Important constraint: if the caller passes an already-constructed `project_client`, Agent Framework does **not** mutate it to inject the MAF user-agent. In that case, toolbox API request telemetry reflects whatever user-agent behavior that external client was configured with.
+
+### Runtime telemetry for toolbox usage on agent runs
+
+Tool-level telemetry already captures which hosted Foundry tools are available / invoked during agent execution. The remaining gap is **toolbox provenance**: once the user writes `tools=toolbox` (or otherwise flattens the toolbox into tool configs), the framework sees only raw tool configs and no longer knows which toolbox name/version supplied them.
+
+The design for closing the **client-side** observability gap is **internal provenance tracking**, not user-supplied metadata and not a new public wrapper type.
+
+#### Provenance model
+
+Note: this section is still under investigation.
+
+When `get_toolbox()` or `list_toolbox_versions()` returns a `ToolboxVersionObject`, Agent Framework will attach private provenance metadata to:
+
+- the returned toolbox object
+- each tool inside `toolbox.tools`
+
+Recommended shape (private, internal-only):
+
+```python
+tool._maf_toolbox_sources = [
+    {
+        "id": toolbox.id,
+        "name": toolbox.name,
+        "version": toolbox.version,
+    }
+]
+```
+
+Key properties of this approach:
+
+- **No new public API surface** — users still work with raw `ToolboxVersionObject` / `ToolboxObject`
+- **No user burden** — callers do not need to stamp metadata manually
+- **Provenance follows the tool objects** — works with:
+  - `tools=toolbox.tools`
+  - `tools=[toolbox_a.tools, toolbox_b.tools]`
+  - `tools=[*toolbox_a.tools, *toolbox_b.tools]`
+- **Private attributes are not serialized** into the actual request payload sent to the model/service, so this metadata does not leak into the tool definition body
+
+This is intentionally preferred over introducing a new public `FoundryToolbox` wrapper purely for telemetry, and preferred over a separate global provenance registry. The provenance lives on the existing tool objects so list-copying and chat-option merging naturally preserve it.
+
+#### Span enrichment
+
+When Agent / chat telemetry computes span attributes for a run, it should inspect the final tool list and aggregate the private toolbox provenance from any tool objects that carry it. The aggregated values are then emitted as attributes on the existing run/chat spans.
+
+Suggested custom attributes:
+
+- `agent_framework.foundry.toolbox.ids`
+- `agent_framework.foundry.toolbox.names`
+- `agent_framework.foundry.toolbox.versions`
+- or a single compact attribute such as `agent_framework.foundry.toolbox.sources=["research_tools@1","some_other_tools@3"]`
+
+The single compact `toolbox.sources` form is preferred for initial implementation because it is easy to query and easy to render from combined tool lists.
+
+#### Scope of telemetry changes
+
+This design does **not** require new spans. It enriches existing telemetry:
+
+- toolbox API access continues to rely on request logs + Azure SDK distributed tracing + MAF user-agent
+- agent/chat execution spans gain toolbox provenance attributes when toolbox-derived tools are present
+
+Implementation-wise, this design most likely touches:
+
+- `packages/foundry/agent_framework_foundry/_tools.py` — to stamp provenance on fetched toolbox objects / tools
+- `packages/core/agent_framework/observability.py` — to aggregate provenance into span attributes
+
+#### Important limitation: no server-side toolbox telemetry solution yet
+
+Private provenance attached to tool objects is only useful on the client side. It
+does **not** go over the wire to the Foundry service because those private fields
+are intentionally not serialized into the request payload.
+
+That means this design can support:
+
+- local OpenTelemetry / exporter spans emitted by Agent Framework
+- local attribution of a run to one or more fetched toolboxes
+
+but it does **not** solve:
+
+- server-side request-log attribution of a model/tool run back to a toolbox
+- backend/database queries that need the service itself to know "this tool came from toolbox X"
+
+At the moment, we do not have a satisfactory design for server-side toolbox
+telemetry. The service would require additional structured information on the
+request, and there is no accepted mechanism in this design yet for projecting
+toolbox provenance into a server-visible field/header/metadata shape.
+
+So the telemetry story in this spec is explicitly limited to **client-side
+toolbox telemetry**. Server-side toolbox attribution remains an open question and
+requires either:
+
+- new service/API support, or
+- a later framework design for emitting additional server-visible request metadata.
+
+#### Deliberate non-goals for telemetry
+
+- No requirement for users to pass explicit toolbox metadata in `default_options["metadata"]` or `run(..., options=...)`
+- No new public `FoundryToolbox` wrapper type just to preserve attribution
+- No attempted server-side attribution mechanism in this design (for example a custom request header or request metadata field) until there is a validated end-to-end contract for it
+
+## Non-goals / Future Work
+
+Explicitly out of scope for this design. Each is a separate design and PR when needed.
+
+1. **Create/update/delete toolboxes from code.** CRUD is rare in agent consumption flows. Users who need it drop to `client.project_client.beta.toolboxes.create_version(...)`, `.update(...)`, `.delete(...)` directly.
+
+2. **Server-side agent authoring from toolbox.** Creating a `PromptAgentDefinition(tools=toolbox.tools)` + `client.agents.create_version(...)` is a future feature covering agent authoring from code. The toolbox read API provides the building blocks; the authoring helpers are a separate design.
+
+3. **OAuth consent-flow runtime handling.** When a toolbox contains MCP tools with `project_connection_id` pointing to an OAuth connection, the runtime may return `CONSENT_REQUIRED` mid-run. This is a runtime concern separate from toolbox fetching.
+
+4. **Live integration tests.** This PR ships unit tests only.
+
+5. **Toolbox caching or refresh APIs.** Each `get_toolbox()` call hits the network. Users who want caching wrap the call themselves.

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative.Foundry/AzureAgentProvider.cs

@@ -4,6 +4,7 @@ using System;
 using System.ClientModel.Primitives;
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
+using System.Linq;
 using System.Net.Http;
 using System.Runtime.CompilerServices;
 using System.Text.Json.Nodes;
@@ -69,14 +70,7 @@ public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential proj
                 include: null,
                 cancellationToken).ConfigureAwait(false);
 
-        ChatMessage[] createdMessages = [.. newItems.AsChatMessages()];
-        if (createdMessages.Length != 1)
-        {
-            throw new InvalidOperationException(
-                $"Expected exactly one chat message from created conversation item in conversation '{conversationId}', but got {createdMessages.Length}.");
-        }
-
-        return createdMessages[0];
+        return newItems.AsChatMessages().Single();
 
         IEnumerable<ResponseItem> GetResponseItems()
         {
@@ -214,14 +208,7 @@ public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential proj
     {
         AgentResponseItem responseItem = await this.GetConversationClient().GetProjectConversationItemAsync(conversationId, messageId, include: null, cancellationToken).ConfigureAwait(false);
         ResponseItem[] items = [responseItem.AsResponseResultItem()];
-        ChatMessage[] messages = [.. items.AsChatMessages()];
-        if (messages.Length != 1)
-        {
-            throw new InvalidOperationException(
-                $"Expected exactly one chat message for message '{messageId}' in conversation '{conversationId}', but got {messages.Length}.");
-        }
-
-        return messages[0];
+        return items.AsChatMessages().Single();
     }
 
     /// <inheritdoc/>

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/InvokeAzureAgentExecutor.cs

@@ -49,11 +49,7 @@ internal sealed class InvokeAzureAgentExecutor(InvokeAzureAgent model, ResponseA
 
     public async ValueTask ResumeAsync(IWorkflowContext context, ExternalInputResponse response, CancellationToken cancellationToken)
     {
-        ChatMessage? lastMessage = response.Messages.LastOrDefault();
-        if (lastMessage is not null)
-        {
-            await context.SetLastMessageAsync(lastMessage).ConfigureAwait(false);
-        }
+        await context.SetLastMessageAsync(response.Messages.Last()).ConfigureAwait(false);
         await this.InvokeAgentAsync(context, response.Messages, cancellationToken).ConfigureAwait(false);
     }
 
@@ -89,19 +85,15 @@ internal sealed class InvokeAzureAgentExecutor(InvokeAzureAgent model, ResponseA
         await this.AssignAsync(this.AgentOutput?.Messages?.Path, agentResponse.Messages.ToTable(), context).ConfigureAwait(false);
 
         // Attempt to parse the last message as JSON and assign to the response object variable.
-        string? lastMessageText = agentResponse.Messages.LastOrDefault()?.Text;
-        if (!string.IsNullOrEmpty(lastMessageText))
+        try
         {
-            try
-            {
-                using JsonDocument jsonDocument = JsonDocument.Parse(lastMessageText);
-                Dictionary<string, object?> objectProperties = jsonDocument.ParseRecord(VariableType.RecordType);
-                await this.AssignAsync(this.AgentOutput?.ResponseObject?.Path, objectProperties.ToFormula(), context).ConfigureAwait(false);
-            }
-            catch (JsonException)
-            {
-                // Not valid json, skip assignment.
-            }
+            JsonDocument jsonDocument = JsonDocument.Parse(agentResponse.Messages.Last().Text);
+            Dictionary<string, object?> objectProperties = jsonDocument.ParseRecord(VariableType.RecordType);
+            await this.AssignAsync(this.AgentOutput?.ResponseObject?.Path, objectProperties.ToFormula(), context).ConfigureAwait(false);
+        }
+        catch
+        {
+            // Not valid json, skip assignment.
         }
 
         if (this.Model.Input?.ExternalLoop?.When is not null)

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/QuestionExecutor.cs

@@ -122,13 +122,10 @@ internal sealed class QuestionExecutor(Question model, ResponseAgentProvider age
                 string? workflowConversationId = context.GetWorkflowConversation();
                 if (workflowConversationId is not null)
                 {
-                    // Input message expected to be defined when values have been extracted, but guard defensively.
-                    ChatMessage? input = response.Messages.LastOrDefault();
-                    if (input is not null)
-                    {
-                        await agentProvider.CreateMessageAsync(workflowConversationId, input, cancellationToken).ConfigureAwait(false);
-                        await context.SetLastMessageAsync(input).ConfigureAwait(false);
-                    }
+                    // Input message always defined if values has been extracted.
+                    ChatMessage input = response.Messages.Last();
+                    await agentProvider.CreateMessageAsync(workflowConversationId, input, cancellationToken).ConfigureAwait(false);
+                    await context.SetLastMessageAsync(input).ConfigureAwait(false);
                 }
             }
 

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/RequestExternalInputExecutor.cs

@@ -45,11 +45,7 @@ internal sealed class RequestExternalInputExecutor(RequestExternalInput model, R
                 await agentProvider.CreateMessageAsync(workflowConversationId, inputMessage, cancellationToken).ConfigureAwait(false);
             }
         }
-        ChatMessage? lastMessage = response.Messages.LastOrDefault();
-        if (lastMessage is not null)
-        {
-            await context.SetLastMessageAsync(lastMessage).ConfigureAwait(false);
-        }
+        await context.SetLastMessageAsync(response.Messages.Last()).ConfigureAwait(false);
         await this.AssignAsync(this.Model.Variable?.Path, response.Messages.ToFormula(), context).ConfigureAwait(false);
 
         await context.RaiseCompletionEventAsync(this.Model, cancellationToken).ConfigureAwait(false);

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/RequestExternalInputExecutorTest.cs

@@ -85,29 +85,6 @@ public sealed class RequestExternalInputExecutorTest(ITestOutputHelper output) :
             expectMessagesCreated: true);
     }
 
-    [Fact]
-    public async Task CaptureResponseWithEmptyMessagesAsync()
-    {
-        await this.CaptureResponseTestAsync(
-            displayName: nameof(CaptureResponseWithEmptyMessagesAsync),
-            variableName: "TestVariable",
-            messageCount: 0);
-    }
-
-    [Fact]
-    public async Task CaptureResponseWithEmptyMessagesAndWorkflowConversationAsync()
-    {
-        // Arrange
-        this.State.Set(SystemScope.Names.ConversationId, FormulaValue.New("WorkflowConversationId"), VariableScopeNames.System);
-
-        // Act & Assert
-        await this.CaptureResponseTestAsync(
-            displayName: nameof(CaptureResponseWithEmptyMessagesAndWorkflowConversationAsync),
-            variableName: "TestVariable",
-            messageCount: 0,
-            expectMessagesCreated: false);
-    }
-
     private async Task ExecuteTestAsync(
         string displayName,
         string variableName)

python/.cspell.json

@@ -24,6 +24,7 @@
     ],
     "words": [
         "aeiou",
+        "agentserver",
         "agui",
         "aiplatform",
         "azuredocindex",

python/packages/core/agent_framework/_feature_stage.py

@@ -49,6 +49,7 @@ class ExperimentalFeature(str, Enum):
     EVALS = "EVALS"
     FILE_HISTORY = "FILE_HISTORY"
     SKILLS = "SKILLS"
+    TOOLBOXES = "TOOLBOXES"
 
 
 class ReleaseCandidateFeature(str, Enum):

python/packages/core/agent_framework/_telemetry.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 import logging
 import os
+from collections.abc import Generator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from typing import Any, Final
 
 from . import __version__ as version_info
@@ -26,6 +29,35 @@ USER_AGENT_KEY: Final[str] = "User-Agent"
 HTTP_USER_AGENT: Final[str] = "agent-framework-python"
 AGENT_FRAMEWORK_USER_AGENT = f"{HTTP_USER_AGENT}/{version_info}"  # type: ignore[has-type]
 
+_user_agent_prefixes: ContextVar[tuple[str, ...]] = ContextVar("_user_agent_prefixes", default=())
+
+
+@contextmanager
+def user_agent_prefix(prefix: str) -> Generator[None]:
+    """Context manager that adds a prefix to the user agent string for the current scope.
+
+    This is useful for upstream layers that want to identify themselves in telemetry
+    for the duration of a request without permanently mutating global state.
+
+    Args:
+        prefix: The prefix to add (e.g. "foundry-hosting").
+    """
+    current = _user_agent_prefixes.get()
+    token = _user_agent_prefixes.set((*current, prefix)) if prefix and prefix not in current else None
+    try:
+        yield
+    finally:
+        if token is not None:
+            _user_agent_prefixes.reset(token)
+
+
+def _get_user_agent() -> str:
+    """Return the full user agent string including any context-scoped prefixes."""
+    prefixes = _user_agent_prefixes.get()
+    if not prefixes:
+        return AGENT_FRAMEWORK_USER_AGENT
+    return f"{'/'.join(prefixes)}/{AGENT_FRAMEWORK_USER_AGENT}"
+
 
 def prepend_agent_framework_to_user_agent(headers: dict[str, Any] | None = None) -> dict[str, Any]:
     """Prepend "agent-framework" to the User-Agent in the headers.
@@ -57,12 +89,9 @@ def prepend_agent_framework_to_user_agent(headers: dict[str, Any] | None = None)
     """
     if not IS_TELEMETRY_ENABLED:
         return headers or {}
+    user_agent = _get_user_agent()
     if not headers:
-        return {USER_AGENT_KEY: AGENT_FRAMEWORK_USER_AGENT}
-    headers[USER_AGENT_KEY] = (
-        f"{AGENT_FRAMEWORK_USER_AGENT} {headers[USER_AGENT_KEY]}"
-        if USER_AGENT_KEY in headers
-        else AGENT_FRAMEWORK_USER_AGENT
-    )
+        return {USER_AGENT_KEY: user_agent}
+    headers[USER_AGENT_KEY] = f"{user_agent} {headers[USER_AGENT_KEY]}" if USER_AGENT_KEY in headers else user_agent
 
     return headers

python/packages/core/agent_framework/_tools.py

@@ -12,6 +12,7 @@ from collections.abc import (
     AsyncIterable,
     Awaitable,
     Callable,
+    Iterable,
     Mapping,
     Sequence,
 )
@@ -859,6 +860,15 @@ def normalize_tools(
     Returns:
         A normalized list where callable inputs are converted to ``FunctionTool``
         using :func:`tool`, and existing tool objects are passed through unchanged.
+
+    Tool-collection wrappers are flattened in two forms:
+
+    - non-tool, non-callable iterables
+    - mapping-like objects that expose a ``.tools`` collection (for example
+      ``ToolboxVersionObject`` from azure-ai-projects)
+
+    This lets callers write ``tools=[toolbox, my_func]`` and have the
+    toolbox's contents spread in alongside individual tools.
     """
     if not tools:
         return []
@@ -883,6 +893,24 @@ def normalize_tools(
         if callable(tool_item):  # type: ignore[reportUnknownArgumentType]
             normalized.append(tool(tool_item))
             continue
+        # Mapping-like tool collections (for example ToolboxVersionObject) are
+        # not flattened by the generic Iterable branch below because they are
+        # also Mapping instances. If they expose a ``tools`` collection, spread
+        # that collection into the normalized list.
+        collection_tools = getattr(tool_item, "tools", None)  # type: ignore[reportUnknownArgumentType]
+        if isinstance(collection_tools, Iterable) and not isinstance(
+            collection_tools, (str, bytes, bytearray, Mapping)
+        ):
+            normalized.extend(normalize_tools(list(collection_tools)))  # type: ignore[reportUnknownArgumentType]
+            continue
+        # Tool-collection wrapper (e.g. FoundryToolbox): a non-tool, non-callable
+        # iterable. Flatten its contents so ``tools=[toolbox, my_func]`` works.
+        # Strings, mappings, and Pydantic BaseModel are excluded — BaseModel
+        # instances iterate over (field, value) tuples, not tools, so they
+        # should pass through as leaf tool specs (handled below).
+        if isinstance(tool_item, Iterable) and not isinstance(tool_item, (str, bytes, bytearray, Mapping, BaseModel)):
+            normalized.extend(normalize_tools(list(tool_item)))  # type: ignore[reportUnknownArgumentType]
+            continue
         normalized.append(tool_item)  # type: ignore[reportUnknownArgumentType]
     return normalized
 

python/packages/core/agent_framework/foundry/__init__.py

@@ -20,6 +20,7 @@ _IMPORTS: dict[str, tuple[str, str]] = {
     "FoundryEmbeddingOptions": ("agent_framework_foundry", "agent-framework-foundry"),
     "FoundryEmbeddingSettings": ("agent_framework_foundry", "agent-framework-foundry"),
     "FoundryEvals": ("agent_framework_foundry", "agent-framework-foundry"),
+    "FoundryHostedToolType": ("agent_framework_foundry", "agent-framework-foundry"),
     "FoundryMemoryProvider": ("agent_framework_foundry", "agent-framework-foundry"),
     "FoundryLocalChatOptions": ("agent_framework_foundry_local", "agent-framework-foundry-local"),
     "FoundryLocalClient": ("agent_framework_foundry_local", "agent-framework-foundry-local"),
@@ -31,6 +32,9 @@ _IMPORTS: dict[str, tuple[str, str]] = {
     "RawFoundryEmbeddingClient": ("agent_framework_foundry", "agent-framework-foundry"),
     "evaluate_foundry_target": ("agent_framework_foundry", "agent-framework-foundry"),
     "evaluate_traces": ("agent_framework_foundry", "agent-framework-foundry"),
+    "get_toolbox_tool_name": ("agent_framework_foundry", "agent-framework-foundry"),
+    "get_toolbox_tool_type": ("agent_framework_foundry", "agent-framework-foundry"),
+    "select_toolbox_tools": ("agent_framework_foundry", "agent-framework-foundry"),
 }
 
 

python/packages/core/agent_framework/foundry/__init__.pyi

@@ -12,6 +12,7 @@ from agent_framework_foundry import (
     FoundryEmbeddingOptions,
     FoundryEmbeddingSettings,
     FoundryEvals,
+    FoundryHostedToolType,
     FoundryMemoryProvider,
     RawFoundryAgent,
     RawFoundryAgentChatClient,
@@ -19,6 +20,9 @@ from agent_framework_foundry import (
     RawFoundryEmbeddingClient,
     evaluate_foundry_target,
     evaluate_traces,
+    get_toolbox_tool_name,
+    get_toolbox_tool_type,
+    select_toolbox_tools,
 )
 from agent_framework_foundry_local import (
     FoundryLocalChatOptions,
@@ -35,6 +39,7 @@ __all__ = [
     "FoundryEmbeddingOptions",
     "FoundryEmbeddingSettings",
     "FoundryEvals",
+    "FoundryHostedToolType",
     "FoundryLocalChatOptions",
     "FoundryLocalClient",
     "FoundryLocalSettings",
@@ -46,4 +51,7 @@ __all__ = [
     "RawFoundryEmbeddingClient",
     "evaluate_foundry_target",
     "evaluate_traces",
+    "get_toolbox_tool_name",
+    "get_toolbox_tool_type",
+    "select_toolbox_tools",
 ]

python/packages/core/tests/core/test_telemetry.py

@@ -8,6 +8,7 @@ from agent_framework import (
     USER_AGENT_TELEMETRY_DISABLED_ENV_VAR,
     prepend_agent_framework_to_user_agent,
 )
+from agent_framework._telemetry import user_agent_prefix
 
 # region Test constants
 
@@ -96,3 +97,56 @@ def test_modifies_original_dict():
 
     assert result is headers  # Same object
     assert "User-Agent" in headers
+
+
+# region Test user_agent_prefix context manager
+
+
+def test_user_agent_prefix_adds_prefix():
+    """Test that the context manager adds a prefix within its scope."""
+    with user_agent_prefix("test-host"):
+        result = prepend_agent_framework_to_user_agent()
+        assert result["User-Agent"].startswith("test-host/")
+        assert AGENT_FRAMEWORK_USER_AGENT in result["User-Agent"]
+
+    # Prefix is removed after exiting the context
+    result = prepend_agent_framework_to_user_agent()
+    assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT
+
+
+def test_user_agent_prefix_ignores_duplicates():
+    """Test that duplicate prefixes are not added within nested scopes."""
+    with user_agent_prefix("test-host"), user_agent_prefix("test-host"):
+        result = prepend_agent_framework_to_user_agent()
+        assert result["User-Agent"].count("test-host") == 1
+
+
+def test_user_agent_prefix_ignores_empty():
+    """Test that empty strings are not added as prefixes."""
+    with user_agent_prefix(""):
+        result = prepend_agent_framework_to_user_agent()
+        assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT
+
+
+def test_user_agent_prefix_restores_on_exit():
+    """Test that prefixes are fully restored after the context manager exits."""
+    with user_agent_prefix("test-host"):
+        pass
+    result = prepend_agent_framework_to_user_agent()
+    assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT
+
+
+def test_user_agent_prefix_nesting():
+    """Test that nested context managers compose prefixes correctly."""
+    with user_agent_prefix("outer"):
+        with user_agent_prefix("inner"):
+            result = prepend_agent_framework_to_user_agent()
+            assert "outer" in result["User-Agent"]
+            assert "inner" in result["User-Agent"]
+        # Inner prefix removed
+        result = prepend_agent_framework_to_user_agent()
+        assert "outer" in result["User-Agent"]
+        assert "inner" not in result["User-Agent"]
+    # Both removed
+    result = prepend_agent_framework_to_user_agent()
+    assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT

python/packages/core/tests/core/test_tools.py

@@ -1144,3 +1144,160 @@ def test_parse_annotation_with_annotated_and_literal():
 
 
 # endregion
+
+
+# region normalize_tools flattening of tool-collection wrappers
+
+
+def _make_flatten_function_tool(name: str) -> FunctionTool:
+    """Build a FunctionTool for flattening tests."""
+
+    @tool(name=name, description=f"{name} tool")
+    def _impl(x: int) -> int:
+        return x
+
+    return _impl  # type: ignore[return-value]
+
+
+def test_normalize_tools_flattens_tool_collection_wrapper() -> None:
+    """A non-tool, non-callable iterable inside the tools list is flattened."""
+    from agent_framework._tools import normalize_tools
+
+    inner_a = _make_flatten_function_tool("inner_a")
+    inner_b = _make_flatten_function_tool("inner_b")
+
+    class ToolBundle:
+        """Minimal stand-in for a tool-collection wrapper like FoundryToolbox."""
+
+        def __init__(self, tools: list[FunctionTool]) -> None:
+            self._tools = tools
+
+        def __iter__(self):
+            return iter(self._tools)
+
+    bundle = ToolBundle([inner_a, inner_b])
+
+    normalized = normalize_tools([bundle])
+
+    assert len(normalized) == 2
+    assert normalized[0] is inner_a
+    assert normalized[1] is inner_b
+
+
+def test_normalize_tools_combines_bundle_with_individual_tools() -> None:
+    """The canonical ``tools=[bundle, my_func]`` call site spreads bundle + individual."""
+    from agent_framework._tools import normalize_tools
+
+    bundled = _make_flatten_function_tool("bundled")
+    standalone = _make_flatten_function_tool("standalone")
+
+    class ToolBundle:
+        def __init__(self, tools: list[FunctionTool]) -> None:
+            self._tools = tools
+
+        def __iter__(self):
+            return iter(self._tools)
+
+    normalized = normalize_tools([ToolBundle([bundled]), standalone])
+
+    assert len(normalized) == 2
+    assert normalized[0] is bundled
+    assert normalized[1] is standalone
+
+
+def test_normalize_tools_flattens_nested_bundles() -> None:
+    """Bundles inside bundles are flattened recursively via the recursive call."""
+    from agent_framework._tools import normalize_tools
+
+    inner = _make_flatten_function_tool("deep")
+
+    class ToolBundle:
+        def __init__(self, tools: list[Any]) -> None:
+            self._tools = tools
+
+        def __iter__(self):
+            return iter(self._tools)
+
+    nested = ToolBundle([ToolBundle([inner])])
+
+    normalized = normalize_tools([nested])
+
+    assert len(normalized) == 1
+    assert normalized[0] is inner
+
+
+def test_normalize_tools_bundle_only_form() -> None:
+    """Passing a bundle directly (no outer list) also flattens its contents.
+
+    ``tools=bundle`` — the outer wrap-in-list happens in the non-Sequence
+    branch, then the flattening logic kicks in on the inner pass.
+    """
+    from agent_framework._tools import normalize_tools
+
+    a = _make_flatten_function_tool("a")
+    b = _make_flatten_function_tool("b")
+
+    class ToolBundle:
+        def __init__(self, tools: list[FunctionTool]) -> None:
+            self._tools = tools
+
+        def __iter__(self):
+            return iter(self._tools)
+
+    normalized = normalize_tools(ToolBundle([a, b]))  # type: ignore[arg-type]
+
+    assert len(normalized) == 2
+    assert normalized[0] is a
+    assert normalized[1] is b
+
+
+def test_normalize_tools_does_not_flatten_known_tool_types() -> None:
+    """FunctionTool / dict / callable are detected before the flatten branch."""
+    from agent_framework._tools import normalize_tools
+
+    func_tool = _make_flatten_function_tool("ft")
+    dict_tool: dict[str, Any] = {"type": "code_interpreter", "container": {"type": "auto"}}
+
+    def plain_callable(x: int) -> int:
+        return x
+
+    normalized = normalize_tools([func_tool, dict_tool, plain_callable])
+
+    assert len(normalized) == 3
+    assert normalized[0] is func_tool
+    assert normalized[1] is dict_tool
+    # plain_callable was wrapped in a FunctionTool via the @tool helper
+    assert isinstance(normalized[2], FunctionTool)
+
+
+def test_normalize_tools_flattens_mapping_like_toolbox_with_tools_attr() -> None:
+    """Mapping-like toolbox objects with ``.tools`` should still flatten."""
+    from collections.abc import Mapping as MappingABC
+
+    from agent_framework._tools import normalize_tools
+
+    bundled = _make_flatten_function_tool("bundled")
+    standalone = _make_flatten_function_tool("standalone")
+
+    class ToolBundleMapping(MappingABC[str, Any]):
+        def __init__(self, tools: list[FunctionTool]) -> None:
+            self.tools = tools
+            self._data = {"name": "research_tools", "version": "v1", "tools": tools}
+
+        def __getitem__(self, key: str) -> Any:
+            return self._data[key]
+
+        def __iter__(self):
+            return iter(self._data)
+
+        def __len__(self) -> int:
+            return len(self._data)
+
+    normalized = normalize_tools([ToolBundleMapping([bundled]), standalone])
+
+    assert len(normalized) == 2
+    assert normalized[0] is bundled
+    assert normalized[1] is standalone
+
+
+# endregion

python/packages/foundry/README.md

@@ -1,3 +1,66 @@
 # Agent Framework Foundry
 
 This package contains the Microsoft Foundry integrations for Microsoft Agent Framework, including Foundry chat clients, preconfigured Foundry agents, Foundry embedding clients, and Foundry memory providers.
+
+## Toolboxes
+
+A *toolbox* is a named, versioned bundle of hosted tool configurations — code interpreter, file search, image generation, MCP, web search, and so on — stored inside a Microsoft Foundry project. Toolboxes let you manage tool configuration once and reuse it across agents.
+
+### Authoring a toolbox
+
+Toolboxes can be authored two ways:
+
+- **Foundry portal** — create and version toolboxes through the UI without touching code.
+- **Programmatically** — use the [`azure-ai-projects`](https://pypi.org/project/azure-ai-projects/) SDK to create, update, and version toolboxes from Python.
+
+> Toolbox authoring APIs (`ToolboxVersionObject`, `ToolboxObject`, `project_client.beta.toolboxes.*`) require `azure-ai-projects>=2.1.0`. Earlier versions can only consume toolboxes that already exist.
+
+### Using toolboxes with `FoundryAgent`
+
+For hosted `FoundryAgent`, the toolbox must already be attached to the agent in the Microsoft Foundry project. Once attached, the agent invokes its toolbox tools transparently — no client-side wiring required — and you interact with the agent the same way you would with any other tool-equipped Foundry agent.
+
+### Using toolboxes with `FoundryChatClient`
+
+There are two patterns for wiring a toolbox into a `FoundryChatClient`-backed agent.
+
+**1. Fetch, optionally filter, and pass the tools directly**
+
+Load the toolbox from the Microsoft Foundry project, optionally select a subset of its tools, and hand them to an `Agent` alongside any other tools you own:
+
+```python
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient, select_toolbox_tools
+
+client = FoundryChatClient(...)
+toolbox = await client.get_toolbox("my-toolbox", version="3")
+
+# Pass the whole toolbox:
+agent = Agent(client=client, tools=toolbox)
+
+# Or filter to a subset first:
+selected = select_toolbox_tools(toolbox, include_types=["code_interpreter", "mcp"])
+agent = Agent(client=client, tools=selected)
+```
+
+See [`foundry_chat_client_with_toolbox.py`](../../samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py) for a full example, including combining multiple toolboxes.
+
+**2. Connect to the toolbox's MCP endpoint with `MCPStreamableHTTPTool`**
+
+Each toolbox is reachable as an MCP server. Instead of fetching and fanning out its individual tool definitions, you can point a MAF `MCPStreamableHTTPTool` at the toolbox's MCP endpoint — the agent then discovers and calls its tools over MCP at runtime:
+
+```python
+from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework.foundry import FoundryChatClient
+
+async with Agent(
+    client=FoundryChatClient(...),
+    instructions="You are a helpful assistant. Use the toolbox tools when useful.",
+    tools=MCPStreamableHTTPTool(
+        name="my_toolbox",
+        description="Tools served by my Foundry toolbox",
+        url="https://<your-toolbox-mcp-endpoint>",
+    ),
+) as agent:
+    result = await agent.run("What tools are available?")
+    print(result.text)
+```

python/packages/foundry/agent_framework_foundry/__init__.py

@@ -16,6 +16,7 @@ from ._foundry_evals import (
     evaluate_traces,
 )
 from ._memory_provider import FoundryMemoryProvider
+from ._tools import FoundryHostedToolType, get_toolbox_tool_name, get_toolbox_tool_type, select_toolbox_tools
 
 try:
     __version__ = importlib.metadata.version(__name__)
@@ -30,6 +31,7 @@ __all__ = [
     "FoundryEmbeddingOptions",
     "FoundryEmbeddingSettings",
     "FoundryEvals",
+    "FoundryHostedToolType",
     "FoundryMemoryProvider",
     "RawFoundryAgent",
     "RawFoundryAgentChatClient",
@@ -38,4 +40,7 @@ __all__ = [
     "__version__",
     "evaluate_foundry_target",
     "evaluate_traces",
+    "get_toolbox_tool_name",
+    "get_toolbox_tool_type",
+    "select_toolbox_tools",
 ]

python/packages/foundry/agent_framework_foundry/_agent.py

@@ -34,6 +34,8 @@ from azure.ai.projects.aio import AIProjectClient
 from azure.core.credentials import TokenCredential
 from azure.core.credentials_async import AsyncTokenCredential
 
+from ._tools import sanitize_foundry_response_tool
+
 if sys.version_info >= (3, 13):
     from typing import TypeVar  # type: ignore # pragma: no cover
 else:
@@ -307,6 +309,20 @@ class RawFoundryAgentChatClient(  # type: ignore[misc]
         """Skip model check — model is configured on the Foundry agent."""
         pass
 
+    @override
+    def _prepare_tools_for_openai(
+        self,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None,
+    ) -> list[Any]:
+        """Prepare tools for Foundry agent Responses API calls.
+
+        Mirrors ``RawFoundryChatClient`` sanitization so toolbox-fetched MCP
+        tools with extra read-model fields continue to work through the agent
+        surface.
+        """
+        response_tools = super()._prepare_tools_for_openai(tools)
+        return [sanitize_foundry_response_tool(tool_item) for tool_item in response_tools]
+
     def _prepare_messages_for_azure_ai(self, messages: Sequence[Message]) -> tuple[list[Message], str | None]:
         """Extract system/developer messages as instructions for Azure AI.
 

python/packages/foundry/agent_framework_foundry/_chat_client.py

@@ -16,6 +16,7 @@ from agent_framework import (
     load_settings,
 )
 from agent_framework._compaction import CompactionStrategy, TokenizerProtocol
+from agent_framework._feature_stage import ExperimentalFeature, experimental
 from agent_framework.observability import ChatTelemetryLayer
 from agent_framework_openai._chat_client import OpenAIChatOptions, RawOpenAIChatClient
 from azure.ai.projects.aio import AIProjectClient
@@ -32,6 +33,8 @@ from azure.ai.projects.models import MCPTool as FoundryMCPTool
 from azure.core.credentials import TokenCredential
 from azure.core.credentials_async import AsyncTokenCredential
 
+from ._tools import fetch_toolbox, sanitize_foundry_response_tool
+
 if sys.version_info >= (3, 13):
     from typing import TypeVar  # type: ignore # pragma: no cover
 else:
@@ -46,7 +49,8 @@ else:
     from typing_extensions import TypedDict  # type: ignore # pragma: no cover
 
 if TYPE_CHECKING:
-    from agent_framework import ChatAndFunctionMiddlewareTypes
+    from agent_framework import ChatAndFunctionMiddlewareTypes, ToolTypes
+    from azure.ai.projects.models import ToolboxVersionObject
 
 logger: logging.Logger = logging.getLogger("agent_framework.foundry")
 
@@ -218,6 +222,21 @@ class RawFoundryChatClient(  # type: ignore[misc]
                 raise ValueError("model must be a non-empty string")
             options["model"] = self.model
 
+    @override
+    def _prepare_tools_for_openai(
+        self,
+        tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None,
+    ) -> list[Any]:
+        """Prepare tools for Foundry Responses API calls.
+
+        Foundry toolbox reads can surface MCP tool objects with extra fields
+        (for example ``name``) that are accepted by the toolbox API but rejected
+        by the Responses API. Sanitize those hosted-tool payloads before sending
+        them downstream.
+        """
+        response_tools = super()._prepare_tools_for_openai(tools)
+        return [sanitize_foundry_response_tool(tool_item) for tool_item in response_tools]
+
     async def configure_azure_monitor(
         self,
         enable_sensitive_data: bool = False,
@@ -460,6 +479,37 @@ class RawFoundryChatClient(  # type: ignore[misc]
 
     # endregion
 
+    # region Toolbox methods (instance methods — these hit the network)
+
+    @experimental(feature_id=ExperimentalFeature.TOOLBOXES)
+    async def get_toolbox(
+        self,
+        name: str,
+        *,
+        version: str | None = None,
+    ) -> ToolboxVersionObject:
+        """Fetch a Foundry toolbox by name.
+
+        If ``version`` is omitted, resolves the toolbox's current default version
+        (two requests). If ``version`` is specified, fetches that version directly
+        (single request).
+
+        Args:
+            name: The name of the toolbox.
+
+        Keyword Args:
+            version: Optional immutable version identifier to pin to.
+
+        Returns:
+            A ``ToolboxVersionObject``. Pass its ``tools`` attribute to
+            ``Agent(tools=toolbox.tools)``.
+
+        Raises:
+            azure.core.exceptions.ResourceNotFoundError: If the toolbox or
+                the requested version does not exist.
+        """
+        return await fetch_toolbox(self.project_client, name, version)
+
 
 class FoundryChatClient(  # type: ignore[misc]
     FunctionInvocationLayer[FoundryChatOptionsT],

python/packages/foundry/agent_framework_foundry/_tools.py

@@ -0,0 +1,166 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Shared tool helpers for Foundry chat clients.
+
+Includes:
+
+* *Toolbox* helpers — a *toolbox* is a named, versioned bundle of tool
+  definitions stored in an Azure AI Foundry project.
+* Responses-API payload sanitization for Foundry hosted tools.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast
+
+from agent_framework._feature_stage import ExperimentalFeature, experimental
+from azure.ai.projects.models import MCPTool as FoundryMCPTool
+
+if TYPE_CHECKING:
+    from azure.ai.projects.aio import AIProjectClient
+    from azure.ai.projects.models import Tool, ToolboxVersionObject
+
+FoundryHostedToolType: TypeAlias = (
+    Literal[
+        "code_interpreter",
+        "file_search",
+        "image_generation",
+        "mcp",
+        "web_search",
+    ]
+    | str
+)
+ToolboxToolSelectionInput: TypeAlias = "ToolboxVersionObject | Sequence[Tool | dict[str, Any]]"
+
+
+@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
+async def fetch_toolbox(
+    project_client: AIProjectClient,
+    name: str,
+    version: str | None = None,
+) -> ToolboxVersionObject:
+    """Fetch a toolbox version via an ``AIProjectClient``.
+
+    If ``version`` is omitted, resolves the toolbox's current default
+    version (two requests: one to ``.get(name)`` for the default version
+    pointer, one to ``.get_version(name, version)`` for the tools). If
+    ``version`` is specified, fetches that version directly (single request).
+    """
+    if version is None:
+        handle = await project_client.beta.toolboxes.get(name)
+        version = handle.default_version
+    return await project_client.beta.toolboxes.get_version(name, version)
+
+
+@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
+def get_toolbox_tool_name(tool: Tool | dict[str, Any]) -> str | None:
+    """Return the best-effort display/selection name for a toolbox tool.
+
+    Selection precedence:
+    1. MCP ``server_label``
+    2. Generic tool ``name``
+    3. Tool ``type``
+    """
+    if isinstance(tool, dict):
+        if server_label := tool.get("server_label"):
+            return str(server_label)
+        if name := tool.get("name"):
+            return str(name)
+        if tool_type := tool.get("type"):
+            return str(tool_type)
+        return None
+
+    if server_label := getattr(tool, "server_label", None):
+        return str(server_label)
+    if name := getattr(tool, "name", None):
+        return str(name)
+    if tool_type := getattr(tool, "type", None):
+        return str(tool_type)
+    return None
+
+
+@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
+def get_toolbox_tool_type(tool: Tool | dict[str, Any]) -> str | None:
+    """Return the raw tool ``type`` if present."""
+    tool_type = tool.get("type") if isinstance(tool, dict) else getattr(tool, "type", None)
+    return str(tool_type) if tool_type is not None else None
+
+
+@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
+def select_toolbox_tools(
+    tools: ToolboxToolSelectionInput,
+    *,
+    include_names: Collection[str] | None = None,
+    exclude_names: Collection[str] | None = None,
+    include_types: Collection[FoundryHostedToolType] | None = None,
+    exclude_types: Collection[FoundryHostedToolType] | None = None,
+    predicate: Callable[[Tool | dict[str, Any]], bool] | None = None,
+) -> list[Tool | dict[str, Any]]:
+    """Filter toolbox tools by normalized name, raw type, and/or predicate.
+
+    Normalized name precedence:
+    1. ``server_label`` for MCP tools
+    2. ``name``
+    3. ``type``
+    """
+    tool_items: Sequence[Tool | dict[str, Any]] = (
+        tools if isinstance(tools, Sequence) else cast("Sequence[Tool | dict[str, Any]]", tools.tools)
+    )
+    include_name_set = {str(item) for item in include_names} if include_names is not None else None
+    exclude_name_set = {str(item) for item in exclude_names} if exclude_names is not None else None
+    include_type_set = {str(item) for item in include_types} if include_types is not None else None
+    exclude_type_set = {str(item) for item in exclude_types} if exclude_types is not None else None
+
+    selected: list[Tool | dict[str, Any]] = []
+    for tool in tool_items:
+        tool_name = get_toolbox_tool_name(tool)
+        tool_type = get_toolbox_tool_type(tool)
+
+        if include_name_set is not None and tool_name not in include_name_set:
+            continue
+        if exclude_name_set is not None and tool_name in exclude_name_set:
+            continue
+        if include_type_set is not None and tool_type not in include_type_set:
+            continue
+        if exclude_type_set is not None and tool_type in exclude_type_set:
+            continue
+        if predicate is not None and not predicate(tool):
+            continue
+
+        selected.append(tool)
+
+    return selected
+
+
+@experimental(feature_id=ExperimentalFeature.TOOLBOXES)
+def sanitize_foundry_response_tool(tool_item: Any) -> Any:
+    """Return a Responses-API-safe tool payload for Foundry hosted tools.
+
+    Azure AI Projects toolbox reads can currently return hosted tool objects with
+    extra read-model decoration fields such as top-level ``name`` and
+    ``description``. Azure AI Foundry rejects at least ``name`` on Responses API
+    requests with:
+
+    ``Unknown parameter: 'tools[0].name'``.
+
+    We defensively strip these decoration fields for non-function hosted tools so
+    the round-trip
+    ``toolbox.tools -> Agent(..., tools=...) -> run()`` works, while the Azure
+    SDK/service behavior is corrected upstream.
+    """
+    if isinstance(tool_item, FoundryMCPTool):
+        sanitized: dict[str, Any] = dict(cast("Mapping[str, Any]", tool_item))
+        sanitized.pop("name", None)
+        sanitized.pop("description", None)
+        return sanitized
+
+    if isinstance(tool_item, Mapping):
+        mapping = cast("Mapping[str, Any]", tool_item)
+        if "type" in mapping and mapping.get("type") not in {"function", "custom"}:
+            sanitized = dict(mapping)
+            sanitized.pop("name", None)
+            sanitized.pop("description", None)
+            return sanitized
+
+    return cast(Any, tool_item)

python/packages/foundry/pyproject.toml

@@ -26,7 +26,7 @@ dependencies = [
     "agent-framework-core>=1.0.1,<2",
     "agent-framework-openai>=1.0.1,<2",
     "azure-ai-inference>=1.0.0b9,<1.0.0b10",
-    "azure-ai-projects>=2.0.0,<3.0",
+    "azure-ai-projects>=2.1.0,<3.0",
 ]
 
 [tool.uv]

python/packages/foundry/tests/foundry/test_foundry_chat_client.py

@@ -15,6 +15,7 @@ from agent_framework import ChatResponse, Content, Message, SupportsChatGetRespo
 from agent_framework._telemetry import AGENT_FRAMEWORK_USER_AGENT
 from agent_framework.exceptions import ChatClientException, ChatClientInvalidRequestException
 from agent_framework_openai import OpenAIContentFilterException
+from azure.ai.projects.models import MCPTool as FoundryMCPTool
 from azure.core.exceptions import ResourceNotFoundError
 from azure.identity import AzureCliCredential
 from openai import BadRequestError
@@ -608,6 +609,82 @@ def test_get_mcp_tool_with_project_connection_id() -> None:
     assert tool_config["server_label"] == "Docs_MCP"
 
 
+def test_prepare_tools_for_openai_strips_extraneous_name_from_foundry_mcp_tool() -> None:
+    """Toolbox-returned MCP tools may carry ``name``; Foundry Responses rejects it."""
+    project_client = MagicMock()
+    project_client.get_openai_client.return_value = _make_mock_openai_client()
+    client = FoundryChatClient(project_client=project_client, model="test-model")
+
+    tool = FoundryMCPTool(
+        server_label="githubmcp",
+        server_url="https://api.githubcopilot.com/mcp",
+    )
+    tool["project_connection_id"] = "githubmcp"
+    tool["name"] = "githubmcp"
+
+    response_tools = client._prepare_tools_for_openai([tool])
+
+    assert len(response_tools) == 1
+    prepared = response_tools[0]
+    assert prepared["type"] == "mcp"
+    assert prepared["server_label"] == "githubmcp"
+    assert prepared["project_connection_id"] == "githubmcp"
+    assert "name" not in prepared
+
+
+def test_prepare_tools_for_openai_strips_read_model_fields_from_toolbox_code_interpreter() -> None:
+    """Toolbox-returned code interpreter tools may carry read-model-only name/description."""
+    project_client = MagicMock()
+    project_client.get_openai_client.return_value = _make_mock_openai_client()
+    client = FoundryChatClient(project_client=project_client, model="test-model")
+
+    tool = {
+        "type": "code_interpreter",
+        "name": "code_interpreter_t6bbtm",
+        "description": "Toolbox read model description",
+        "container": {"file_ids": [], "type": "auto"},
+    }
+
+    response_tools = client._prepare_tools_for_openai([tool])
+
+    assert len(response_tools) == 1
+    prepared = response_tools[0]
+    assert prepared["type"] == "code_interpreter"
+    assert prepared["container"] == {"file_ids": [], "type": "auto"}
+    assert "name" not in prepared
+    assert "description" not in prepared
+
+
+def test_prepare_tools_for_openai_strips_name_from_non_function_hosted_tool_dicts() -> None:
+    """All non-function hosted tool payloads should drop top-level read-model names."""
+    project_client = MagicMock()
+    project_client.get_openai_client.return_value = _make_mock_openai_client()
+    client = FoundryChatClient(project_client=project_client, model="test-model")
+
+    response_tools = client._prepare_tools_for_openai([
+        {
+            "type": "file_search",
+            "name": "file_search_tool_123",
+            "description": "toolbox decoration",
+            "vector_store_ids": ["vs_123"],
+        },
+        {
+            "type": "web_search",
+            "name": "web_search_tool_456",
+            "description": "toolbox decoration",
+        },
+    ])
+
+    assert len(response_tools) == 2
+    assert response_tools[0]["type"] == "file_search"
+    assert response_tools[0]["vector_store_ids"] == ["vs_123"]
+    assert "name" not in response_tools[0]
+    assert "description" not in response_tools[0]
+    assert response_tools[1]["type"] == "web_search"
+    assert "name" not in response_tools[1]
+    assert "description" not in response_tools[1]
+
+
 @pytest.mark.flaky
 @pytest.mark.integration
 @skip_if_foundry_integration_tests_disabled

python/packages/foundry/tests/test_toolbox.py

@@ -0,0 +1,435 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Unit tests for toolbox helpers on FoundryChatClient.
+
+Return types are the raw azure-ai-projects SDK models (ToolboxVersionObject,
+ToolboxObject) — no custom wrapper. Tests verify the chat-client get path and
+tool-selection ergonomics.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import os
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+try:
+    from azure.ai.projects.models import (
+        AutoCodeInterpreterToolParam,
+        CodeInterpreterTool,
+        Tool,
+        ToolboxObject,
+        ToolboxVersionObject,
+    )
+except ImportError:
+    pytest.skip(
+        "Toolbox types require azure-ai-projects>=2.1.0 (unreleased).",
+        allow_module_level=True,
+    )
+
+from azure.core.exceptions import ResourceNotFoundError
+from azure.identity import AzureCliCredential
+
+# --------------------------------------------------------------------------- #
+# Helpers                                                                     #
+# --------------------------------------------------------------------------- #
+
+
+class _AsyncIter:
+    """Minimal async-iterable for mocking ``AsyncItemPaged`` in tests."""
+
+    def __init__(self, items: list[Any]) -> None:
+        self._items = items
+
+    def __aiter__(self) -> _AsyncIter:
+        self._iter = iter(self._items)
+        return self
+
+    async def __anext__(self) -> Any:
+        try:
+            return next(self._iter)
+        except StopIteration:
+            raise StopAsyncIteration from None
+
+
+def _make_code_interpreter() -> CodeInterpreterTool:
+    return CodeInterpreterTool(container=AutoCodeInterpreterToolParam())
+
+
+def _make_version_object(
+    *,
+    name: str = "research_tools",
+    version: str = "v1",
+    tools: list[Tool] | None = None,
+    description: str | None = None,
+) -> ToolboxVersionObject:
+    return ToolboxVersionObject(
+        id=f"tbv_{name}_{version}",
+        name=name,
+        version=version,
+        metadata={},
+        created_at=dt.datetime(2026, 4, 10, tzinfo=dt.timezone.utc),
+        tools=tools if tools is not None else [_make_code_interpreter()],
+        description=description,
+    )
+
+
+def _make_mock_foundry_client(*, project_client: MagicMock) -> Any:
+    """Build a FoundryChatClient wired to a mock project_client."""
+    from agent_framework_foundry import FoundryChatClient
+
+    project_client.get_openai_client = MagicMock(return_value=MagicMock())
+    return FoundryChatClient(project_client=project_client, model="test-model")
+
+
+# --------------------------------------------------------------------------- #
+# get_toolbox — explicit version path                                         #
+# --------------------------------------------------------------------------- #
+
+
+async def test_get_toolbox_with_explicit_version_makes_single_request() -> None:
+    project_client = MagicMock()
+    version_obj = _make_version_object(name="research_tools", version="v3")
+    project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
+    project_client.beta.toolboxes.get = AsyncMock(
+        side_effect=AssertionError("get() must not be called when version is explicit")
+    )
+
+    client = _make_mock_foundry_client(project_client=project_client)
+
+    toolbox = await client.get_toolbox("research_tools", version="v3")
+
+    assert isinstance(toolbox, ToolboxVersionObject)
+    assert toolbox.name == "research_tools"
+    assert toolbox.version == "v3"
+    project_client.beta.toolboxes.get_version.assert_awaited_once_with("research_tools", "v3")
+    project_client.beta.toolboxes.get.assert_not_called()
+
+
+# --------------------------------------------------------------------------- #
+# get_toolbox — default-version path + error + passthrough + smoke            #
+# --------------------------------------------------------------------------- #
+
+
+async def test_get_toolbox_default_version_resolves_then_fetches() -> None:
+    project_client = MagicMock()
+    handle = ToolboxObject(id="tb_1", name="research_tools", default_version="v5")
+    version_obj = _make_version_object(name="research_tools", version="v5")
+
+    project_client.beta.toolboxes.get = AsyncMock(return_value=handle)
+    project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
+
+    client = _make_mock_foundry_client(project_client=project_client)
+
+    toolbox = await client.get_toolbox("research_tools")
+
+    assert toolbox.version == "v5"
+    project_client.beta.toolboxes.get.assert_awaited_once_with("research_tools")
+    project_client.beta.toolboxes.get_version.assert_awaited_once_with("research_tools", "v5")
+
+
+async def test_get_toolbox_propagates_resource_not_found() -> None:
+    project_client = MagicMock()
+    project_client.beta.toolboxes.get = AsyncMock(side_effect=ResourceNotFoundError("no such toolbox"))
+
+    client = _make_mock_foundry_client(project_client=project_client)
+
+    with pytest.raises(ResourceNotFoundError):
+        await client.get_toolbox("missing_toolbox")
+
+
+async def test_get_toolbox_tool_passthrough_preserves_heterogeneous_types() -> None:
+    """Ensure all Tool subclasses pass through unchanged — critical for MCP tools
+    with project_connection_id, which must reach the runtime untouched."""
+    from azure.ai.projects.models import MCPTool as FoundryMCPTool
+
+    mcp_tool = FoundryMCPTool(
+        server_label="github_oauth",
+        server_url="https://api.githubcopilot.com/mcp",
+    )
+    mcp_tool["project_connection_id"] = "conn_abc"
+
+    project_client = MagicMock()
+    version_obj = _make_version_object(
+        name="mixed",
+        version="v1",
+        tools=[_make_code_interpreter(), mcp_tool],
+    )
+    project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
+
+    client = _make_mock_foundry_client(project_client=project_client)
+
+    toolbox = await client.get_toolbox("mixed", version="v1")
+
+    assert len(toolbox.tools) == 2
+    assert isinstance(toolbox.tools[0], CodeInterpreterTool)
+    assert isinstance(toolbox.tools[1], FoundryMCPTool)
+    assert toolbox.tools[1]["project_connection_id"] == "conn_abc"
+
+
+async def test_toolbox_tools_can_be_passed_to_agent() -> None:
+    """Integration smoke: toolbox.tools can be passed directly to Agent(tools=...) ."""
+    from agent_framework import Agent
+
+    project_client = MagicMock()
+    version_obj = _make_version_object(name="research_tools", version="v1", tools=[_make_code_interpreter()])
+    project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
+
+    client = _make_mock_foundry_client(project_client=project_client)
+
+    toolbox = await client.get_toolbox("research_tools", version="v1")
+
+    agent = Agent(
+        client=client,
+        instructions="You are a test agent.",
+        tools=toolbox.tools,
+    )
+
+    agent_tools = agent.default_options["tools"]
+    assert len(agent_tools) == 1
+    assert agent_tools[0]["type"] == "code_interpreter"
+
+
+async def test_multiple_toolbox_tool_lists_can_be_combined_in_agent() -> None:
+    """Nested toolbox ``.tools`` lists flatten into one tool list on Agent construction."""
+    from agent_framework import Agent
+
+    project_client = MagicMock()
+    project_client.get_openai_client = MagicMock(return_value=MagicMock())
+    client = _make_mock_foundry_client(project_client=project_client)
+
+    toolbox_a = _make_version_object(name="research_tools", version="v1", tools=[_make_code_interpreter()])
+    toolbox_b = _make_version_object(name="some_other_tools", version="v3", tools=[_make_code_interpreter()])
+
+    agent = Agent(
+        client=client,
+        instructions="You are a test agent.",
+        tools=[toolbox_a.tools, toolbox_b.tools],
+    )
+
+    agent_tools = agent.default_options["tools"]
+    assert len(agent_tools) == 2
+    assert agent_tools[0]["type"] == "code_interpreter"
+    assert agent_tools[1]["type"] == "code_interpreter"
+
+
+# --------------------------------------------------------------------------- #
+# toolbox tool selection helpers                                              #
+# --------------------------------------------------------------------------- #
+
+
+def test_get_toolbox_tool_name_prefers_server_label_then_name_then_type() -> None:
+    from azure.ai.projects.models import MCPTool as FoundryMCPTool
+
+    from agent_framework_foundry import get_toolbox_tool_name
+
+    mcp_tool = FoundryMCPTool(
+        server_label="githubmcp",
+        server_url="https://api.githubcopilot.com/mcp",
+    )
+    assert get_toolbox_tool_name(mcp_tool) == "githubmcp"
+
+    named_tool = {"type": "code_interpreter", "name": "ci_tool"}
+    assert get_toolbox_tool_name(named_tool) == "ci_tool"
+
+    unnamed_tool = {"type": "web_search"}
+    assert get_toolbox_tool_name(unnamed_tool) == "web_search"
+
+
+def test_select_toolbox_tools_filters_by_names() -> None:
+    from azure.ai.projects.models import MCPTool as FoundryMCPTool
+
+    from agent_framework_foundry import select_toolbox_tools
+
+    tools: list[Tool | dict[str, Any]] = [
+        FoundryMCPTool(server_label="githubmcp", server_url="https://api.githubcopilot.com/mcp"),
+        {"type": "code_interpreter", "name": "python_runner"},
+        {"type": "web_search"},
+    ]
+
+    selected = select_toolbox_tools(tools, include_names=["githubmcp", "python_runner"])
+
+    assert len(selected) == 2
+    assert selected[0] is tools[0]
+    assert selected[1] is tools[1]
+
+
+def test_select_toolbox_tools_filters_by_typed_tool_types() -> None:
+    from agent_framework_foundry import select_toolbox_tools
+
+    tools: list[Tool | dict[str, Any]] = [
+        {"type": "mcp", "server_label": "githubmcp"},
+        {"type": "code_interpreter", "name": "python_runner"},
+        {"type": "web_search"},
+    ]
+
+    selected = select_toolbox_tools(tools, include_types=["mcp", "code_interpreter"])
+
+    assert len(selected) == 2
+    assert selected[0]["type"] == "mcp"
+    assert selected[1]["type"] == "code_interpreter"
+
+
+def test_select_toolbox_tools_accepts_toolbox_object_directly() -> None:
+    from agent_framework_foundry import select_toolbox_tools
+
+    toolbox = _make_version_object(
+        name="research_tools",
+        version="v1",
+        tools=[
+            {"type": "mcp", "server_label": "githubmcp"},  # type: ignore[list-item]
+            {"type": "code_interpreter", "name": "python_runner"},  # type: ignore[list-item]
+            {"type": "web_search"},  # type: ignore[list-item]
+        ],
+    )
+
+    selected = select_toolbox_tools(toolbox, include_types=["mcp", "code_interpreter"])
+
+    assert len(selected) == 2
+    assert selected[0]["type"] == "mcp"
+    assert selected[1]["type"] == "code_interpreter"
+
+
+async def test_fetched_toolbox_can_be_combined_with_function_tool() -> None:
+    from agent_framework import Agent, FunctionTool, tool
+
+    project_client = MagicMock()
+    version_obj = _make_version_object(name="research_tools", version="v1", tools=[_make_code_interpreter()])
+    project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
+
+    client = _make_mock_foundry_client(project_client=project_client)
+    toolbox = await client.get_toolbox("research_tools", version="v1")
+
+    @tool(name="local_lookup", description="A local helper tool")
+    def local_lookup(query: str) -> str:
+        return query
+
+    agent = Agent(
+        client=client,
+        instructions="You are a test agent.",
+        tools=[toolbox, local_lookup],
+    )
+
+    agent_tools = agent.default_options["tools"]
+    assert len(agent_tools) == 2
+    assert agent_tools[0]["type"] == "code_interpreter"
+    assert isinstance(agent_tools[1], FunctionTool)
+    assert agent_tools[1].name == "local_lookup"
+
+
+def test_select_toolbox_tools_supports_excludes_and_predicate() -> None:
+    from agent_framework_foundry import select_toolbox_tools
+
+    tools: list[Tool | dict[str, Any]] = [
+        {"type": "mcp", "server_label": "githubmcp"},
+        {"type": "mcp", "server_label": "learnmcp"},
+        {"type": "web_search"},
+    ]
+
+    selected = select_toolbox_tools(
+        tools,
+        exclude_names=["learnmcp"],
+        predicate=lambda tool: tool.get("type") == "mcp",  # type: ignore[union-attr]
+    )
+
+    assert len(selected) == 1
+    assert selected[0]["server_label"] == "githubmcp"
+
+
+async def test_selected_toolbox_subset_can_be_combined_with_function_tool() -> None:
+    from agent_framework import Agent, FunctionTool, tool
+
+    from agent_framework_foundry import select_toolbox_tools
+
+    project_client = MagicMock()
+    version_obj = _make_version_object(
+        name="research_tools",
+        version="v1",
+        tools=[
+            {"type": "mcp", "server_label": "githubmcp"},  # type: ignore[list-item]
+            {"type": "code_interpreter", "name": "python_runner"},  # type: ignore[list-item]
+            {"type": "web_search"},  # type: ignore[list-item]
+        ],
+    )
+    project_client.beta.toolboxes.get_version = AsyncMock(return_value=version_obj)
+
+    client = _make_mock_foundry_client(project_client=project_client)
+    toolbox = await client.get_toolbox("research_tools", version="v1")
+    selected_tools = select_toolbox_tools(toolbox, include_types=["mcp", "code_interpreter"])
+
+    @tool(name="local_lookup", description="A local helper tool")
+    def local_lookup(query: str) -> str:
+        return query
+
+    agent = Agent(
+        client=client,
+        instructions="You are a test agent.",
+        tools=[selected_tools, local_lookup],
+    )
+
+    agent_tools = agent.default_options["tools"]
+    assert len(agent_tools) == 3
+    assert agent_tools[0]["type"] == "mcp"
+    assert agent_tools[1]["type"] == "code_interpreter"
+    assert isinstance(agent_tools[2], FunctionTool)
+    assert agent_tools[2].name == "local_lookup"
+
+
+# --------------------------------------------------------------------------- #
+# Integration                                                                 #
+# --------------------------------------------------------------------------- #
+
+
+skip_if_foundry_integration_tests_disabled = pytest.mark.skipif(
+    os.getenv("FOUNDRY_PROJECT_ENDPOINT", "") in ("", "https://test-project.services.ai.azure.com/")
+    or os.getenv("FOUNDRY_MODEL", "") == "",
+    reason="No real FOUNDRY_PROJECT_ENDPOINT or FOUNDRY_MODEL provided; skipping integration tests.",
+)
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_foundry_integration_tests_disabled
+async def test_integration_get_toolbox_round_trip_against_real_project() -> None:
+    """Create a toolbox via the raw SDK, fetch via FoundryChatClient, then delete.
+
+    Self-contained to avoid depending on toolboxes that may be cleaned up
+    externally. Exercises both the default-version resolution path
+    (``get`` + ``get_version``) and the explicit-version path.
+    """
+    from uuid import uuid4
+
+    from agent_framework import Agent
+
+    from agent_framework_foundry import FoundryChatClient
+
+    client = FoundryChatClient(credential=AzureCliCredential())
+    project_client = client.project_client
+
+    toolbox_name = f"af-int-toolbox-{uuid4().hex[:12]}"
+    created = await project_client.beta.toolboxes.create_version(
+        name=toolbox_name,
+        tools=[CodeInterpreterTool()],
+        description=f"{toolbox_name} integration test",
+    )
+    assert isinstance(created, ToolboxVersionObject)
+    try:
+        toolbox_default = await client.get_toolbox(toolbox_name)
+        assert toolbox_default.name == toolbox_name
+        assert toolbox_default.tools, "Default-version fetch returned no tools"
+
+        toolbox_pinned = await client.get_toolbox(toolbox_name, version=created.version)
+        assert toolbox_pinned.version == created.version
+        assert toolbox_pinned.tools
+
+        agent = Agent(
+            client=client,
+            instructions="You are a test agent.",
+            tools=toolbox_pinned.tools,
+        )
+        assert len(agent.default_options["tools"]) == len(toolbox_pinned.tools)
+    finally:
+        await project_client.beta.toolboxes.delete(toolbox_name)

python/packages/foundry_hosting/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/foundry_hosting/README.md

@@ -0,0 +1,3 @@
+# Foundry Hosting
+
+This package provides the integration of Agent Framework agents and workflows with the Foundry Agent Server, which can be hosted on Foundry infrastructure.

python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._invocations import InvocationsHostServer
+from ._responses import ResponsesHostServer
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["InvocationsHostServer", "ResponsesHostServer"]

python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations.py

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from agent_framework import AgentSession, BaseAgent, SupportsAgentRun
+from agent_framework._telemetry import user_agent_prefix
+from azure.ai.agentserver.invocations import InvocationAgentServerHost
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response, StreamingResponse
+from typing_extensions import Any, AsyncGenerator
+
+
+class InvocationsHostServer(InvocationAgentServerHost):
+    """An invocations server host for an agent."""
+
+    USER_AGENT_PREFIX = "foundry-hosting"
+
+    def __init__(
+        self,
+        agent: BaseAgent,
+        *,
+        openapi_spec: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize an InvocationsHostServer.
+
+        Args:
+            agent: The agent to handle responses for.
+            openapi_spec: The OpenAPI specification for the server.
+            **kwargs: Additional keyword arguments.
+
+        This host will expect the request to be a JSON body with a "message" field.
+        The response from the host will be a JSON object with a "response" field containing
+        the agent's response and a "session_id" field containing the session ID.
+        """
+        super().__init__(openapi_spec=openapi_spec, **kwargs)
+
+        if not isinstance(agent, SupportsAgentRun):
+            raise TypeError("Agent must support the SupportsAgentRun interface")
+
+        self._agent = agent
+        self._sessions: dict[str, AgentSession] = {}
+        self.invoke_handler(self._handle_invoke)  # pyright: ignore[reportUnknownMemberType]
+
+    async def _handle_invoke(self, request: Request) -> Response:
+        """Invoke the agent with the given request."""
+        with user_agent_prefix(self.USER_AGENT_PREFIX):
+            return await self._handle_invoke_inner(request)
+
+    async def _handle_invoke_inner(self, request: Request) -> Response:
+        """Core invoke handler logic."""
+        data = await request.json()
+        session_id: str = request.state.session_id
+
+        stream = data.get("stream", False)
+        user_message = data.get("message", None)
+        if user_message is None:
+            error = "Missing 'message' in request"
+            if stream:
+                return StreamingResponse(content=error, status_code=400)
+            return Response(content=error, status_code=400)
+
+        session = self._sessions.setdefault(session_id, AgentSession(session_id=session_id))
+
+        if stream:
+
+            async def stream_response() -> AsyncGenerator[str]:
+                async for update in self._agent.run(user_message, session=session, stream=True):
+                    if update.text:
+                        yield update.text
+
+            return StreamingResponse(
+                stream_response(),
+                media_type="text/event-stream",
+                headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+            )
+
+        response = await self._agent.run([user_message], session=session, stream=stream)
+        return JSONResponse({
+            "response": response.text,
+            "session_id": session_id,
+        })

python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py

@@ -0,0 +1,983 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from collections.abc import AsyncIterable, AsyncIterator, Generator, Mapping, Sequence
+from typing import cast
+
+from agent_framework import (
+    ChatOptions,
+    Content,
+    ContextProvider,
+    FileCheckpointStorage,
+    HistoryProvider,
+    Message,
+    RawAgent,
+    SupportsAgentRun,
+    WorkflowAgent,
+)
+from agent_framework._telemetry import user_agent_prefix
+from azure.ai.agentserver.responses import (
+    ResponseContext,
+    ResponseEventStream,
+    ResponseProviderProtocol,
+    ResponsesServerOptions,
+)
+from azure.ai.agentserver.responses.hosting import ResponsesAgentServerHost
+from azure.ai.agentserver.responses.models import (
+    ComputerScreenshotContent,
+    CreateResponse,
+    FunctionCallOutputItemParam,
+    FunctionShellAction,
+    FunctionShellCallOutputContent,
+    FunctionShellCallOutputExitOutcome,
+    LocalEnvironmentResource,
+    MessageContent,
+    MessageContentInputFileContent,
+    MessageContentInputImageContent,
+    MessageContentInputTextContent,
+    MessageContentOutputTextContent,
+    MessageContentReasoningTextContent,
+    MessageContentRefusalContent,
+    OAuthConsentRequestOutputItem,
+    OutputItem,
+    OutputItemApplyPatchToolCall,
+    OutputItemApplyPatchToolCallOutput,
+    OutputItemCodeInterpreterToolCall,
+    OutputItemComputerToolCall,
+    OutputItemComputerToolCallOutputResource,
+    OutputItemCustomToolCall,
+    OutputItemCustomToolCallOutput,
+    OutputItemFileSearchToolCall,
+    OutputItemFunctionShellCall,
+    OutputItemFunctionShellCallOutput,
+    OutputItemFunctionToolCall,
+    OutputItemImageGenToolCall,
+    OutputItemLocalShellToolCall,
+    OutputItemLocalShellToolCallOutput,
+    OutputItemMcpApprovalRequest,
+    OutputItemMcpApprovalResponseResource,
+    OutputItemMcpToolCall,
+    OutputItemMessage,
+    OutputItemOutputMessage,
+    OutputItemReasoningItem,
+    OutputItemWebSearchToolCall,
+    OutputMessageContent,
+    OutputMessageContentOutputTextContent,
+    OutputMessageContentRefusalContent,
+    ResponseStreamEvent,
+    StructuredOutputsOutputItem,
+    SummaryTextContent,
+    TextContent,
+)
+from azure.ai.agentserver.responses.streaming._builders import (
+    OutputItemFunctionCallBuilder,
+    OutputItemMcpCallBuilder,
+    OutputItemMessageBuilder,
+    OutputItemReasoningItemBuilder,
+    ReasoningSummaryPartBuilder,
+    TextContentBuilder,
+)
+from typing_extensions import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ResponsesHostServer(ResponsesAgentServerHost):
+    """A responses server host for an agent."""
+
+    USER_AGENT_PREFIX = "foundry-hosting"
+    # TODO(@taochen): Allow a different checkpoint storage that stores checkpoints externally
+    CHECKPOINT_STORAGE_PATH = "/.checkpoints"
+
+    def __init__(
+        self,
+        agent: SupportsAgentRun,
+        *,
+        prefix: str = "",
+        options: ResponsesServerOptions | None = None,
+        store: ResponseProviderProtocol | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a ResponsesHostServer.
+
+        Args:
+            agent: The agent to handle responses for.
+            prefix: The URL prefix for the server.
+            options: Optional server options.
+            store: Optional response store.
+            **kwargs: Additional keyword arguments.
+
+        Note:
+            1. The agent must not have a history provider with `load_messages=True`,
+               because history is managed by the hosting infrastructure.
+            2. The agent must not have any context providers that maintain context
+               in memory, because the hosting environment may get deactivated between
+               requests, and any in-memory context would be lost.
+        """
+        super().__init__(prefix=prefix, options=options, store=store, **kwargs)
+
+        for provider in getattr(agent, "context_providers", []):
+            if isinstance(provider, HistoryProvider) and provider.load_messages:
+                raise RuntimeError(
+                    "There shouldn't be a history provider with `load_messages=True` already present. "
+                    "History is managed by the hosting infrastructure."
+                )
+            provider = cast(ContextProvider, provider)
+            logger.warning(
+                "Context provider %s is present. If it maintains context in memory, "
+                "the context may be lost between requests. Use with caution.",
+                provider.source_id,
+            )
+
+        self._is_workflow_agent = False
+        self._checkpoint_storage_path = None
+        if isinstance(agent, WorkflowAgent):
+            if agent.workflow._runner_context.has_checkpointing():  # pyright: ignore[reportPrivateUsage]
+                raise RuntimeError(
+                    "There should not be a checkpoint storage already present in the workflow agent. "
+                    "The hosting infrastructure will manage checkpoints instead."
+                )
+            self._checkpoint_storage_path = (
+                self.CHECKPOINT_STORAGE_PATH
+                if self.config.is_hosted
+                else os.path.join(os.getcwd(), self.CHECKPOINT_STORAGE_PATH.lstrip("/"))
+            )
+            self._is_workflow_agent = True
+
+        self._agent = agent
+        self.response_handler(self._handler)  # pyright: ignore[reportUnknownMemberType]
+
+    @staticmethod
+    def _is_streaming_request(request: CreateResponse) -> bool:
+        """Check if the request is a streaming request."""
+        return request.stream is not None and request.stream is True
+
+    async def _handler(
+        self,
+        request: CreateResponse,
+        context: ResponseContext,
+        cancellation_signal: asyncio.Event,
+    ) -> AsyncIterable[ResponseStreamEvent | dict[str, Any]]:
+        """Handle the creation of a response."""
+        with user_agent_prefix(self.USER_AGENT_PREFIX):
+            async for event in self._handle_inner(request, context, cancellation_signal):
+                yield event
+
+    async def _handle_inner(
+        self,
+        request: CreateResponse,
+        context: ResponseContext,
+        cancellation_signal: asyncio.Event,
+    ) -> AsyncIterable[ResponseStreamEvent | dict[str, Any]]:
+        """Core handler logic."""
+        if self._is_workflow_agent:
+            # Workflow agents are handled differently because they require checkpoint restoration
+            async for event in self._handle_workflow_agent(request, context, cancellation_signal):
+                yield event
+            return
+
+        input_text = await context.get_input_text()
+        history = await context.get_history()
+        messages: list[str | Content | Message] = [*_to_messages(history), input_text]
+
+        chat_options, are_options_set = _to_chat_options(request)
+
+        is_streaming_request = self._is_streaming_request(request)
+        response_event_stream = ResponseEventStream(response_id=context.response_id, model=request.model)
+
+        yield response_event_stream.emit_created()
+        yield response_event_stream.emit_in_progress()
+
+        if not is_streaming_request:
+            # Run the agent in non-streaming mode
+            if isinstance(self._agent, RawAgent):
+                raw_agent = cast("RawAgent[Any]", self._agent)  # type: ignore[redundant-cast]  # pyright: ignore[reportUnknownMemberType]
+                response = await raw_agent.run(messages, stream=False, options=chat_options)
+            else:
+                if are_options_set:
+                    logger.warning("Agent doesn't support runtime options. They will be ignored.")
+                response = await self._agent.run(messages, stream=False)
+
+            for message in response.messages:
+                for content in message.contents:
+                    async for item in _to_outputs(response_event_stream, content):
+                        yield item
+
+            yield response_event_stream.emit_completed()
+            return
+
+        # Run the agent in streaming mode
+        if isinstance(self._agent, RawAgent):
+            raw_agent = cast("RawAgent[Any]", self._agent)  # type: ignore[redundant-cast]  # pyright: ignore[reportUnknownMemberType]
+            response_stream = raw_agent.run(messages, stream=True, options=chat_options)
+        else:
+            if are_options_set:
+                logger.warning("Agent doesn't support runtime options. They will be ignored.")
+            response_stream = self._agent.run(messages, stream=True)
+
+        # Track the current active output item builder for streaming;
+        # lazily created on matching content, closed when a different type arrives.
+        tracker = _OutputItemTracker(response_event_stream)
+
+        async for update in response_stream:
+            for content in update.contents:
+                for event in tracker.handle(content):
+                    yield event
+                if tracker.needs_async:
+                    async for item in _to_outputs(response_event_stream, content):
+                        yield item
+                    tracker.needs_async = False
+
+        # Close any remaining active builder
+        for event in tracker.close():
+            yield event
+
+        yield response_event_stream.emit_completed()
+
+    async def _handle_workflow_agent(
+        self,
+        request: CreateResponse,
+        context: ResponseContext,
+        cancellation_signal: asyncio.Event,
+    ) -> AsyncIterable[ResponseStreamEvent | dict[str, Any]]:
+        """Handle the creation of a response for a workflow agent.
+
+        Why this is required:
+        The sandbox may be deactivated after some period of inactivity, and only data managed
+        by the hosting infrastructure or files will be preserved upon deactivation.
+        """
+        input_text = await context.get_input_text()
+        is_streaming_request = self._is_streaming_request(request)
+
+        _, are_options_set = _to_chat_options(request)
+        if are_options_set:
+            logger.warning("Workflow agent doesn't support runtime options. They will be ignored.")
+
+        if request.previous_response_id is not None and context.conversation_id is not None:
+            raise RuntimeError("Previous response ID cannot be used in conjunction with conversation ID.")
+        context_id = request.previous_response_id or context.conversation_id
+
+        # The following should never happen due to the checks above.
+        # This is for type safety and defensive programming.
+        if self._checkpoint_storage_path is None:
+            raise RuntimeError("Checkpoint storage path is not configured for workflow agent.")
+        if not isinstance(self._agent, WorkflowAgent):
+            raise RuntimeError("Agent is not a workflow agent.")
+
+        # Restore from the latest checkpoint if available, otherwise start with an empty history
+        if context_id is not None:
+            checkpoint_storage = FileCheckpointStorage(os.path.join(self._checkpoint_storage_path, context_id))
+            latest_checkpoint = await checkpoint_storage.get_latest(workflow_name=self._agent.workflow.name)
+            if latest_checkpoint is not None:
+                if not is_streaming_request:
+                    _ = await self._agent.run(
+                        stream=False,
+                        checkpoint_id=latest_checkpoint.checkpoint_id,
+                        checkpoint_storage=checkpoint_storage,
+                    )
+                else:
+                    # Consume the streaming or the invocation will result in a no-op
+                    async for _ in self._agent.run(
+                        stream=True,
+                        checkpoint_id=latest_checkpoint.checkpoint_id,
+                        checkpoint_storage=checkpoint_storage,
+                    ):
+                        pass
+
+        # Now run the agent with the latest input
+        response_event_stream = ResponseEventStream(response_id=context.response_id, model=request.model)
+
+        # Create a new checkpoint storage for this response based on the following rules:
+        # - If no previous response ID or conversation ID is provided, create a new checkpoint storage for this response
+        # - If a previous response ID is provided, create a new checkpoint storage for this response
+        # - If a conversation ID is provided, reuse the existing checkpoint storage for the conversation
+        context_id = context.conversation_id or context.response_id
+        checkpoint_storage = FileCheckpointStorage(os.path.join(self._checkpoint_storage_path, context_id))
+
+        yield response_event_stream.emit_created()
+        yield response_event_stream.emit_in_progress()
+
+        if not is_streaming_request:
+            # Run the agent in non-streaming mode
+            response = await self._agent.run(input_text, stream=False, checkpoint_storage=checkpoint_storage)
+
+            for message in response.messages:
+                for content in message.contents:
+                    async for item in _to_outputs(response_event_stream, content):
+                        yield item
+
+            await self._delete_not_latest_checkpoints(checkpoint_storage, self._agent.workflow.name)
+            yield response_event_stream.emit_completed()
+            return
+
+        # Run the agent in streaming mode
+        response_stream = self._agent.run(input_text, stream=True, checkpoint_storage=checkpoint_storage)
+
+        # Track the current active output item builder for streaming;
+        # lazily created on matching content, closed when a different type arrives.
+        tracker = _OutputItemTracker(response_event_stream)
+
+        async for update in response_stream:
+            for content in update.contents:
+                for event in tracker.handle(content):
+                    yield event
+                if tracker.needs_async:
+                    async for item in _to_outputs(response_event_stream, content):
+                        yield item
+                    tracker.needs_async = False
+
+        # Close any remaining active builder
+        for event in tracker.close():
+            yield event
+
+        await self._delete_not_latest_checkpoints(checkpoint_storage, self._agent.workflow.name)
+        yield response_event_stream.emit_completed()
+        return
+
+    @staticmethod
+    async def _delete_not_latest_checkpoints(checkpoint_storage: FileCheckpointStorage, workflow_name: str) -> None:
+        """Delete all checkpoints except the latest one.
+
+        We only need the last checkpoint for each invocation.
+        """
+        latest_checkpoint = await checkpoint_storage.get_latest(workflow_name=workflow_name)
+        if latest_checkpoint is not None:
+            all_checkpoints = await checkpoint_storage.list_checkpoints(workflow_name=workflow_name)
+            for checkpoint in all_checkpoints:
+                if checkpoint.checkpoint_id != latest_checkpoint.checkpoint_id:
+                    await checkpoint_storage.delete(checkpoint.checkpoint_id)
+
+
+# region Active Builder State
+
+
+class _OutputItemTracker:
+    """Tracks the current active output item builder during streaming.
+
+    Handles lazy creation, delta emission, and closing of streaming builders
+    for text messages, reasoning, function calls, and MCP calls.
+    """
+
+    _DELTA_TYPES = frozenset({"text", "text_reasoning", "function_call", "mcp_server_tool_call"})
+
+    def __init__(self, stream: ResponseEventStream) -> None:
+        self._stream = stream
+        self._active_type: str | None = None
+        self._active_id: str | None = None
+        # Accumulated delta text for the current active builder
+        self._accumulated: list[str] = []
+        # Builder state — only one is active at a time
+        self._message_item: OutputItemMessageBuilder | None = None
+        self._text_content: TextContentBuilder | None = None
+        self._reasoning_item: OutputItemReasoningItemBuilder | None = None
+        self._summary_part: ReasoningSummaryPartBuilder | None = None
+        self._fc_builder: OutputItemFunctionCallBuilder | None = None
+        self._mcp_builder: OutputItemMcpCallBuilder | None = None
+        self.needs_async = False
+
+    def handle(self, content: Content) -> Generator[ResponseStreamEvent]:
+        """Process a content item, yielding sync events.
+
+        Sets ``needs_async = True`` if the caller must also drain an
+        async ``_to_outputs`` call for this content.
+        """
+        if content.type == "text" and content.text is not None:
+            if self._active_type != "text":
+                yield from self._close()
+                yield from self._open_message()
+            self._accumulated.append(content.text)
+            if self._text_content is not None:
+                yield self._text_content.emit_delta(content.text)
+
+        elif content.type == "text_reasoning" and content.text is not None:
+            if self._active_type != "text_reasoning":
+                yield from self._close()
+                yield from self._open_reasoning()
+            self._accumulated.append(content.text)
+            if self._summary_part is not None:
+                yield self._summary_part.emit_text_delta(content.text)
+
+        elif content.type == "function_call" and content.call_id is not None:
+            if self._active_type != "function_call" or self._active_id != content.call_id:
+                yield from self._close()
+                yield from self._open_function_call(content)
+            args_str = _arguments_to_str(content.arguments)
+            self._accumulated.append(args_str)
+            if self._fc_builder is not None:
+                yield self._fc_builder.emit_arguments_delta(args_str)
+
+        elif content.type == "mcp_server_tool_call" and content.tool_name:
+            key = f"{content.server_name or 'default'}::{content.tool_name}"
+            if self._active_type != "mcp_server_tool_call" or self._active_id != key:
+                yield from self._close()
+                yield from self._open_mcp_call(content)
+            args_str = _arguments_to_str(content.arguments)
+            self._accumulated.append(args_str)
+            if self._mcp_builder is not None:
+                yield self._mcp_builder.emit_arguments_delta(args_str)
+
+        else:
+            yield from self._close()
+            self.needs_async = True
+
+    def close(self) -> Generator[ResponseStreamEvent]:
+        """Close any remaining active builder."""
+        yield from self._close()
+
+    # -- Private open/close helpers --
+
+    def _open_message(self) -> Generator[ResponseStreamEvent]:
+        self._message_item = self._stream.add_output_item_message()
+        self._text_content = self._message_item.add_text_content()
+        self._active_type = "text"
+        self._active_id = None
+        yield self._message_item.emit_added()
+        yield self._text_content.emit_added()
+
+    def _open_reasoning(self) -> Generator[ResponseStreamEvent]:
+        self._reasoning_item = self._stream.add_output_item_reasoning_item()
+        self._summary_part = self._reasoning_item.add_summary_part()
+        self._active_type = "text_reasoning"
+        self._active_id = None
+        yield self._reasoning_item.emit_added()
+        yield self._summary_part.emit_added()
+
+    def _open_function_call(self, content: Content) -> Generator[ResponseStreamEvent]:
+        self._fc_builder = self._stream.add_output_item_function_call(
+            name=content.name or "",
+            call_id=content.call_id or "",
+        )
+        self._active_type = "function_call"
+        self._active_id = content.call_id
+        yield self._fc_builder.emit_added()
+
+    def _open_mcp_call(self, content: Content) -> Generator[ResponseStreamEvent]:
+        self._mcp_builder = self._stream.add_output_item_mcp_call(
+            server_label=content.server_name or "default",
+            name=content.tool_name or "",
+        )
+        self._active_type = "mcp_server_tool_call"
+        self._active_id = f"{content.server_name or 'default'}::{content.tool_name}"
+        yield self._mcp_builder.emit_added()
+
+    def _close(self) -> Generator[ResponseStreamEvent]:
+        accumulated = "".join(self._accumulated)
+
+        if self._active_type == "text" and self._text_content and self._message_item:
+            yield self._text_content.emit_text_done(accumulated)
+            yield self._text_content.emit_done()
+            yield self._message_item.emit_done()
+            self._text_content = None
+            self._message_item = None
+
+        elif self._active_type == "text_reasoning" and self._summary_part and self._reasoning_item:
+            yield self._summary_part.emit_text_done(accumulated)
+            yield self._summary_part.emit_done()
+            yield self._reasoning_item.emit_done()
+            self._summary_part = None
+            self._reasoning_item = None
+
+        elif self._active_type == "function_call" and self._fc_builder:
+            yield self._fc_builder.emit_arguments_done(accumulated)
+            yield self._fc_builder.emit_done()
+            self._fc_builder = None
+
+        elif self._active_type == "mcp_server_tool_call" and self._mcp_builder:
+            yield self._mcp_builder.emit_arguments_done(accumulated)
+            yield self._mcp_builder.emit_completed()
+            yield self._mcp_builder.emit_done()
+            self._mcp_builder = None
+
+        self._active_type = None
+        self._active_id = None
+        self._accumulated.clear()
+
+
+# endregion
+
+
+# region Option Conversion
+
+
+def _to_chat_options(request: CreateResponse) -> tuple[ChatOptions, bool]:
+    """Converts a CreateResponse request to ChatOptions.
+
+    Args:
+        request (CreateResponse): The request to convert.
+
+    Returns:
+        ChatOptions: The converted ChatOptions.
+        bool: Whether any options were set.
+
+    """
+    chat_options = ChatOptions()
+    are_options_set = False
+
+    if request.temperature is not None:
+        chat_options["temperature"] = request.temperature
+        are_options_set = True
+    if request.top_p is not None:
+        chat_options["top_p"] = request.top_p
+        are_options_set = True
+    if request.max_output_tokens is not None:
+        chat_options["max_tokens"] = request.max_output_tokens
+        are_options_set = True
+    if request.parallel_tool_calls is not None:
+        chat_options["allow_multiple_tool_calls"] = request.parallel_tool_calls
+        are_options_set = True
+
+    return chat_options, are_options_set
+
+
+# endregion
+
+
+# region Input Message Conversion
+
+
+def _to_messages(history: Sequence[OutputItem]) -> list[Message]:
+    """Converts a sequence of OutputItem objects to a list of Message objects.
+
+    Args:
+        history (Sequence[OutputItem]): The sequence of OutputItem objects to convert.
+
+    Returns:
+        list[Message]: The list of Message objects.
+    """
+    messages: list[Message] = []
+    for item in history:
+        messages.append(_to_message(item))
+    return messages
+
+
+def _to_message(item: OutputItem) -> Message:
+    """Converts an OutputItem to a Message.
+
+    Args:
+        item (OutputItem): The OutputItem to convert.
+
+    Returns:
+        Message: The converted Message.
+
+    Raises:
+        ValueError: If the OutputItem type is not supported.
+    """
+    if item.type == "output_message":
+        output_msg = cast(OutputItemOutputMessage, item)
+        return Message(
+            role=output_msg.role, contents=[_convert_output_message_content(part) for part in output_msg.content]
+        )
+
+    if item.type == "message":
+        msg = cast(OutputItemMessage, item)
+        return Message(role=msg.role, contents=[_convert_message_content(part) for part in msg.content])
+
+    if item.type == "function_call":
+        fc = cast(OutputItemFunctionToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[Content.from_function_call(fc.call_id, fc.name, arguments=fc.arguments)],
+        )
+
+    if item.type == "function_call_output":
+        fco = cast(FunctionCallOutputItemParam, item)
+        output = fco.output if isinstance(fco.output, str) else str(fco.output)
+        return Message(
+            role="tool",
+            contents=[Content.from_function_result(fco.call_id, result=output)],
+        )
+
+    if item.type == "reasoning":
+        reasoning = cast(OutputItemReasoningItem, item)
+        contents: list[Content] = []
+        if reasoning.summary:
+            for summary in reasoning.summary:
+                contents.append(Content.from_text(summary.text))
+        return Message(role="assistant", contents=contents)
+
+    if item.type == "mcp_call":
+        mcp = cast(OutputItemMcpToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[
+                Content.from_mcp_server_tool_call(
+                    mcp.id,
+                    mcp.name,
+                    server_name=mcp.server_label,
+                    arguments=mcp.arguments,
+                )
+            ],
+        )
+
+    if item.type == "mcp_approval_request":
+        mcp_req = cast(OutputItemMcpApprovalRequest, item)
+        mcp_call_content = Content.from_mcp_server_tool_call(
+            mcp_req.id,
+            mcp_req.name,
+            server_name=mcp_req.server_label,
+            arguments=mcp_req.arguments,
+        )
+        return Message(
+            role="assistant",
+            contents=[Content.from_function_approval_request(mcp_req.id, mcp_call_content)],
+        )
+
+    if item.type == "mcp_approval_response":
+        mcp_resp = cast(OutputItemMcpApprovalResponseResource, item)
+        # Build a placeholder function_call Content since the original call details are not available
+        placeholder_content = Content.from_function_call(mcp_resp.approval_request_id, "mcp_approval")
+        return Message(
+            role="user",
+            contents=[Content.from_function_approval_response(mcp_resp.approve, mcp_resp.id, placeholder_content)],
+        )
+
+    if item.type == "code_interpreter_call":
+        ci = cast(OutputItemCodeInterpreterToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[Content.from_code_interpreter_tool_call(call_id=ci.id)],
+        )
+
+    if item.type == "image_generation_call":
+        ig = cast(OutputItemImageGenToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[Content.from_image_generation_tool_call(image_id=ig.id)],
+        )
+
+    if item.type == "shell_call":
+        sc = cast(OutputItemFunctionShellCall, item)
+        return Message(
+            role="assistant",
+            contents=[
+                Content.from_shell_tool_call(
+                    call_id=sc.call_id,
+                    commands=sc.action.commands,
+                    status=str(sc.status),
+                )
+            ],
+        )
+
+    if item.type == "shell_call_output":
+        sco = cast(OutputItemFunctionShellCallOutput, item)
+        outputs = [
+            Content.from_shell_command_output(
+                stdout=out.stdout or "",
+                stderr=out.stderr or "",
+                exit_code=getattr(out.outcome, "exit_code", None) if hasattr(out, "outcome") else None,
+            )
+            for out in (sco.output or [])
+        ]
+        return Message(
+            role="tool",
+            contents=[
+                Content.from_shell_tool_result(
+                    call_id=sco.call_id,
+                    outputs=outputs,
+                    max_output_length=sco.max_output_length,
+                )
+            ],
+        )
+
+    if item.type == "local_shell_call":
+        lsc = cast(OutputItemLocalShellToolCall, item)
+        commands = lsc.action.command if hasattr(lsc.action, "command") and lsc.action.command else []
+        return Message(
+            role="assistant",
+            contents=[
+                Content.from_shell_tool_call(
+                    call_id=lsc.call_id,
+                    commands=commands,
+                    status=str(lsc.status),
+                )
+            ],
+        )
+
+    if item.type == "local_shell_call_output":
+        lsco = cast(OutputItemLocalShellToolCallOutput, item)
+        return Message(
+            role="tool",
+            contents=[
+                Content.from_shell_tool_result(
+                    call_id=lsco.id,
+                    outputs=[Content.from_shell_command_output(stdout=lsco.output)],
+                )
+            ],
+        )
+
+    if item.type == "file_search_call":
+        fs = cast(OutputItemFileSearchToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[
+                Content.from_function_call(
+                    fs.id,
+                    "file_search",
+                    arguments=json.dumps({"queries": fs.queries}),
+                )
+            ],
+        )
+
+    if item.type == "web_search_call":
+        ws = cast(OutputItemWebSearchToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[Content.from_function_call(ws.id, "web_search")],
+        )
+
+    if item.type == "computer_call":
+        cc = cast(OutputItemComputerToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[
+                Content.from_function_call(
+                    cc.call_id,
+                    "computer_use",
+                    arguments=str(cc.action),
+                )
+            ],
+        )
+
+    if item.type == "computer_call_output":
+        cco = cast(OutputItemComputerToolCallOutputResource, item)
+        return Message(
+            role="tool",
+            contents=[Content.from_function_result(cco.call_id, result=str(cco.output))],
+        )
+
+    if item.type == "custom_tool_call":
+        ct = cast(OutputItemCustomToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[Content.from_function_call(ct.call_id, ct.name, arguments=ct.input)],
+        )
+
+    if item.type == "custom_tool_call_output":
+        cto = cast(OutputItemCustomToolCallOutput, item)
+        output = cto.output if isinstance(cto.output, str) else str(cto.output)
+        return Message(
+            role="tool",
+            contents=[Content.from_function_result(cto.call_id, result=output)],
+        )
+
+    if item.type == "apply_patch_call":
+        ap = cast(OutputItemApplyPatchToolCall, item)
+        return Message(
+            role="assistant",
+            contents=[
+                Content.from_function_call(
+                    ap.call_id,
+                    "apply_patch",
+                    arguments=str(ap.operation),
+                )
+            ],
+        )
+
+    if item.type == "apply_patch_call_output":
+        apo = cast(OutputItemApplyPatchToolCallOutput, item)
+        return Message(
+            role="tool",
+            contents=[Content.from_function_result(apo.call_id, result=apo.output or "")],
+        )
+
+    if item.type == "oauth_consent_request":
+        oauth = cast(OAuthConsentRequestOutputItem, item)
+        return Message(
+            role="assistant",
+            contents=[Content.from_oauth_consent_request(oauth.consent_link)],
+        )
+
+    if item.type == "structured_outputs":
+        so = cast(StructuredOutputsOutputItem, item)
+        text = json.dumps(so.output) if not isinstance(so.output, str) else so.output
+        return Message(role="assistant", contents=[Content.from_text(text)])
+
+    raise ValueError(f"Unsupported OutputItem type: {item.type}")
+
+
+def _convert_output_message_content(content: OutputMessageContent) -> Content:
+    """Converts an OutputMessageContent to a Content object.
+
+    Args:
+        content (OutputMessageContent): The OutputMessageContent to convert.
+
+    Returns:
+        Content: The converted Content object.
+
+    Raises:
+        ValueError: If the OutputMessageContent type is not supported.
+    """
+    if content.type == "output_text":
+        text_content = cast(OutputMessageContentOutputTextContent, content)
+        return Content.from_text(text_content.text)
+    if content.type == "refusal":
+        refusal_content = cast(OutputMessageContentRefusalContent, content)
+        return Content.from_text(refusal_content.refusal)
+
+    raise ValueError(f"Unsupported OutputMessageContent type: {content.type}")
+
+
+def _convert_message_content(content: MessageContent) -> Content:
+    """Converts a MessageContent to a Content object.
+
+    Args:
+        content (MessageContent): The MessageContent to convert.
+
+    Returns:
+        Content: The converted Content object.
+
+    Raises:
+        ValueError: If the MessageContent type is not supported.
+    """
+    if content.type == "input_text":
+        input_text = cast(MessageContentInputTextContent, content)
+        return Content.from_text(input_text.text)
+    if content.type == "output_text":
+        output_text = cast(MessageContentOutputTextContent, content)
+        return Content.from_text(output_text.text)
+    if content.type == "text":
+        text = cast(TextContent, content)
+        return Content.from_text(text.text)
+    if content.type == "summary_text":
+        summary = cast(SummaryTextContent, content)
+        return Content.from_text(summary.text)
+    if content.type == "refusal":
+        refusal = cast(MessageContentRefusalContent, content)
+        return Content.from_text(refusal.refusal)
+    if content.type == "reasoning_text":
+        reasoning = cast(MessageContentReasoningTextContent, content)
+        return Content.from_text_reasoning(text=reasoning.text)
+    if content.type == "input_image":
+        image = cast(MessageContentInputImageContent, content)
+        if image.image_url:
+            return Content.from_uri(image.image_url)
+        if image.file_id:
+            return Content.from_hosted_file(image.file_id)
+    if content.type == "input_file":
+        file = cast(MessageContentInputFileContent, content)
+        if file.file_url:
+            return Content.from_uri(file.file_url)
+        if file.file_id:
+            return Content.from_hosted_file(file.file_id, name=file.filename)
+    if content.type == "computer_screenshot":
+        screenshot = cast(ComputerScreenshotContent, content)
+        return Content.from_uri(screenshot.image_url)
+
+    raise ValueError(f"Unsupported MessageContent type: {content.type}")
+
+
+# endregion
+
+# region Output Item Conversion
+
+
+def _arguments_to_str(arguments: str | Mapping[str, Any] | None) -> str:
+    """Convert arguments to a JSON string.
+
+    Args:
+        arguments: The arguments to convert, can be a string, mapping, or None.
+
+    Returns:
+        The arguments as a JSON string.
+    """
+    if arguments is None:
+        return ""
+    if isinstance(arguments, str):
+        return arguments
+    return json.dumps(arguments)
+
+
+async def _to_outputs(stream: ResponseEventStream, content: Content) -> AsyncIterator[ResponseStreamEvent]:
+    """Converts a Content object to an async sequence of ResponseStreamEvent objects.
+
+    Args:
+        stream: The ResponseEventStream to use for building events.
+        content: The Content to convert.
+
+    Yields:
+        ResponseStreamEvent: The converted event objects.
+
+    Raises:
+        ValueError: If the Content type is not supported.
+    """
+    if content.type == "text" and content.text is not None:
+        async for event in stream.aoutput_item_message(content.text):
+            yield event
+    elif content.type == "text_reasoning" and content.text is not None:
+        async for event in stream.aoutput_item_reasoning_item(content.text):
+            yield event
+    elif content.type == "function_call":
+        async for event in stream.aoutput_item_function_call(
+            content.name,  # type: ignore[arg-type]
+            content.call_id,  # type: ignore[arg-type]
+            _arguments_to_str(content.arguments),
+        ):
+            yield event
+    elif content.type == "function_result":
+        async for event in stream.aoutput_item_function_call_output(
+            content.call_id,  # type: ignore[arg-type]
+            str(content.result or ""),
+        ):
+            yield event
+    elif content.type == "image_generation_tool_result" and content.outputs is not None:
+        async for event in stream.aoutput_item_image_gen_call(str(content.outputs)):
+            yield event
+    elif content.type == "mcp_server_tool_call":
+        mcp_call = stream.add_output_item_mcp_call(
+            server_label=content.server_name or "default",
+            name=content.tool_name or "",
+        )
+        yield mcp_call.emit_added()
+        async for event in mcp_call.aarguments(_arguments_to_str(content.arguments)):
+            yield event
+        yield mcp_call.emit_completed()
+        yield mcp_call.emit_done()
+    elif content.type == "mcp_server_tool_result":
+        output = (
+            content.output
+            if isinstance(content.output, str)
+            else str(content.output)
+            if content.output is not None
+            else ""
+        )
+        async for event in stream.aoutput_item_custom_tool_call_output(content.call_id or "", output):
+            yield event
+    elif content.type == "shell_tool_call":
+        action = FunctionShellAction(commands=content.commands or [], timeout_ms=0, max_output_length=0)
+        async for event in stream.aoutput_item_function_shell_call(
+            content.call_id or "",
+            action,
+            LocalEnvironmentResource(),
+            status=content.status or "completed",
+        ):
+            yield event
+    elif content.type == "shell_tool_result":
+        output_items: list[FunctionShellCallOutputContent] = []
+        if content.outputs:
+            for out in content.outputs:
+                exit_code = getattr(out, "exit_code", None)
+                output_items.append(
+                    FunctionShellCallOutputContent(
+                        stdout=getattr(out, "stdout", "") or "",
+                        stderr=getattr(out, "stderr", "") or "",
+                        outcome=FunctionShellCallOutputExitOutcome(exit_code=exit_code if exit_code is not None else 0),
+                    )
+                )
+        async for event in stream.aoutput_item_function_shell_call_output(
+            content.call_id or "",
+            output_items,
+            status=content.status or "completed",
+            max_output_length=content.max_output_length,
+        ):
+            yield event
+    else:
+        # Log a warning for unsupported content types instead of raising an error to avoid breaking the response stream.
+        logger.warning(f"Content type '{content.type}' is not supported yet. This is usually safe to ignore.")
+
+
+# endregion

python/packages/foundry_hosting/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "agent-framework-foundry-hosting"
+description = "Foundry Hosting integration for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0a260420"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core>=1.0.0,<2",
+    "azure-ai-agentserver-core==2.0.0b2",
+    "azure-ai-agentserver-responses==1.0.0b4",
+    "azure-ai-agentserver-invocations==1.0.0b2",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+markers = [
+    "integration: marks tests as integration tests that require external services",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["agent_framework_foundry_hosting"]
+exclude = ['tests']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_foundry_hosting"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.mypy]
+help = "Run MyPy for this package."
+cmd = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_foundry_hosting"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_foundry_hosting --cov-report=term-missing:skip-covered tests'
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/foundry_hosting/tests/test_responses.py

@@ -0,0 +1,917 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""HTTP round-trip tests for ResponsesHostServer.
+
+These tests exercise the full HTTP pipeline using httpx.AsyncClient with
+ASGITransport — no real server process is started. Requests go through
+the Starlette routing stack, the Responses API middleware, and arrive at
+the registered _handle_create handler.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from unittest.mock import AsyncMock, MagicMock
+
+import httpx
+import pytest
+from agent_framework import (
+    AgentResponse,
+    AgentResponseUpdate,
+    Content,
+    HistoryProvider,
+    Message,
+    RawAgent,
+    ResponseStream,
+)
+from azure.ai.agentserver.responses import InMemoryResponseProvider
+from typing_extensions import Any
+
+from agent_framework_foundry_hosting import ResponsesHostServer
+from agent_framework_foundry_hosting._responses import _to_message  # pyright: ignore[reportPrivateUsage]
+
+# region Helpers
+
+
+def _make_agent(
+    *,
+    response: AgentResponse | None = None,
+    stream_updates: list[AgentResponseUpdate] | None = None,
+) -> MagicMock:
+    """Create a mock agent implementing SupportsAgentRun."""
+    agent = MagicMock(spec=RawAgent)
+    agent.id = "test-agent"
+    agent.name = "Test Agent"
+    agent.description = "A mock agent for testing"
+    agent.context_providers = []
+
+    if response is not None:
+
+        async def run_non_streaming(*args: Any, **kwargs: Any) -> AgentResponse:
+            return response
+
+        agent.run = AsyncMock(side_effect=run_non_streaming)
+
+    if stream_updates is not None:
+
+        async def _stream_gen() -> AsyncIterator[AgentResponseUpdate]:
+            for update in stream_updates:
+                yield update
+
+        def run_streaming(*args: Any, **kwargs: Any) -> Any:
+            if kwargs.get("stream"):
+                return ResponseStream(_stream_gen())  # type: ignore
+            raise NotImplementedError("Only streaming is configured on this mock")
+
+        agent.run = MagicMock(side_effect=run_streaming)
+
+    return agent
+
+
+def _make_server(agent: MagicMock, **kwargs: Any) -> ResponsesHostServer:
+    """Create a ResponsesHostServer with an in-memory store."""
+    return ResponsesHostServer(agent, store=InMemoryResponseProvider(), **kwargs)
+
+
+async def _post(
+    server: ResponsesHostServer,
+    *,
+    input_text: str = "Hello",
+    model: str = "test-model",
+    stream: bool = False,
+    temperature: float | None = None,
+    top_p: float | None = None,
+    max_output_tokens: int | None = None,
+    parallel_tool_calls: bool | None = None,
+) -> httpx.Response:
+    """Send a POST /responses request through the ASGI transport."""
+    payload: dict[str, Any] = {"model": model, "input": input_text, "stream": stream}
+    if temperature is not None:
+        payload["temperature"] = temperature
+    if top_p is not None:
+        payload["top_p"] = top_p
+    if max_output_tokens is not None:
+        payload["max_output_tokens"] = max_output_tokens
+    if parallel_tool_calls is not None:
+        payload["parallel_tool_calls"] = parallel_tool_calls
+
+    transport = httpx.ASGITransport(app=server)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        return await client.post("/responses", json=payload)
+
+
+def _parse_sse_events(body: str) -> list[dict[str, Any]]:
+    """Parse SSE text into a list of event dicts with 'event' and 'data' keys."""
+    events: list[dict[str, Any]] = []
+    current_event: str | None = None
+    current_data_lines: list[str] = []
+
+    for line in body.split("\n"):
+        if line.startswith("event: "):
+            current_event = line[len("event: ") :]
+        elif line.startswith("data: "):
+            current_data_lines.append(line[len("data: ") :])
+        elif line.strip() == "" and current_event is not None:
+            data_str = "\n".join(current_data_lines)
+            try:
+                data = json.loads(data_str)
+            except json.JSONDecodeError:
+                data = data_str
+            events.append({"event": current_event, "data": data})
+            current_event = None
+            current_data_lines = []
+
+    return events
+
+
+def _sse_event_types(events: list[dict[str, Any]]) -> list[str]:
+    """Extract event type strings from parsed SSE events."""
+    return [e["event"] for e in events]
+
+
+# endregion
+
+
+# region Initialization
+
+
+class TestResponsesHostServerInit:
+    def test_init_basic(self) -> None:
+        agent = _make_agent(
+            response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("hi")])])
+        )
+        server = _make_server(agent)
+        assert server is not None
+
+    def test_init_rejects_history_provider_with_load_messages(self) -> None:
+        hp = HistoryProvider(source_id="test", load_messages=True)
+        agent = _make_agent(
+            response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("hi")])])
+        )
+        agent.context_providers = [hp]
+        with pytest.raises(RuntimeError, match="history provider"):
+            ResponsesHostServer(agent)
+
+
+# endregion
+
+
+# region Health Check
+
+
+class TestHealthCheck:
+    async def test_readiness(self) -> None:
+        agent = _make_agent(
+            response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("hi")])])
+        )
+        server = _make_server(agent)
+        transport = httpx.ASGITransport(app=server)
+        async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+            resp = await client.get("/readiness")
+        assert resp.status_code == 200
+
+
+# endregion
+
+
+# region Non-streaming
+
+
+class TestNonStreaming:
+    async def test_basic_text_response(self) -> None:
+        agent = _make_agent(
+            response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("Hello!")])])
+        )
+        server = _make_server(agent)
+        resp = await _post(server, input_text="Hi", stream=False)
+
+        assert resp.status_code == 200
+        assert "application/json" in resp.headers["content-type"]
+
+        body = resp.json()
+        assert body["object"] == "response"
+        assert body["status"] == "completed"
+        assert len(body["output"]) > 0
+
+        # Find the message output item with our text
+        text_found = False
+        for item in body["output"]:
+            assert item["type"] == "message"
+            for part in item.get("content", []):
+                if part.get("type") == "output_text" and part.get("text") == "Hello!":
+                    text_found = True
+        assert text_found, f"Expected 'Hello!' in output, got: {body['output']}"
+
+    async def test_function_call_and_result(self) -> None:
+        agent = _make_agent(
+            response=AgentResponse(
+                messages=[
+                    Message(
+                        role="assistant",
+                        contents=[Content.from_function_call("call_1", "get_weather", arguments='{"loc": "NYC"}')],
+                    ),
+                    Message(role="tool", contents=[Content.from_function_result("call_1", result="sunny")]),
+                    Message(role="assistant", contents=[Content.from_text("The weather is sunny!")]),
+                ]
+            )
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=False)
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["status"] == "completed"
+
+        types = [item["type"] for item in body["output"]]
+        assert "function_call" in types
+        assert "function_call_output" in types
+        assert "message" in types
+
+    async def test_reasoning_content(self) -> None:
+        agent = _make_agent(
+            response=AgentResponse(
+                messages=[
+                    Message(
+                        role="assistant",
+                        contents=[
+                            Content.from_text_reasoning(text="Let me think..."),
+                            Content.from_text("The answer is 42"),
+                        ],
+                    ),
+                ]
+            )
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=False)
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["status"] == "completed"
+
+        types = [item["type"] for item in body["output"]]
+        assert "reasoning" in types
+        assert "message" in types
+
+    async def test_empty_response(self) -> None:
+        agent = _make_agent(response=AgentResponse(messages=[]))
+        server = _make_server(agent)
+        resp = await _post(server, stream=False)
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["status"] == "completed"
+
+    async def test_chat_options_forwarded(self) -> None:
+        agent = _make_agent(
+            response=AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])])
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=False, temperature=0.5, top_p=0.9, max_output_tokens=1024)
+
+        assert resp.status_code == 200
+        agent.run.assert_awaited_once()
+        call_kwargs = agent.run.call_args.kwargs
+        assert call_kwargs["stream"] is False
+        options = call_kwargs["options"]
+        assert options["temperature"] == 0.5
+        assert options["top_p"] == 0.9
+        assert options["max_tokens"] == 1024
+
+
+# endregion
+
+
+# region Streaming
+
+
+class TestStreaming:
+    async def test_basic_text_streaming(self) -> None:
+        agent = _make_agent(
+            stream_updates=[
+                AgentResponseUpdate(contents=[Content.from_text("Hello ")], role="assistant"),
+                AgentResponseUpdate(contents=[Content.from_text("world!")], role="assistant"),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        assert "text/event-stream" in resp.headers["content-type"]
+
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert types[0] == "response.created"
+        assert types[1] == "response.in_progress"
+        assert types[-1] == "response.completed"
+        assert "response.output_text.delta" in types
+        assert types.count("response.output_text.delta") == 2
+        assert "response.output_text.done" in types
+
+        # Verify the accumulated text in the done event
+        done_events = [e for e in events if e["event"] == "response.output_text.done"]
+        assert len(done_events) == 1
+        assert done_events[0]["data"]["text"] == "Hello world!"
+
+    async def test_function_call_streaming(self) -> None:
+        agent = _make_agent(
+            stream_updates=[
+                AgentResponseUpdate(
+                    contents=[Content.from_function_call("call_1", "search", arguments='{"q":')],
+                    role="assistant",
+                ),
+                AgentResponseUpdate(
+                    contents=[Content.from_function_call("call_1", "search", arguments=' "hello"}')],
+                    role="assistant",
+                ),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert types[0] == "response.created"
+        assert types[-1] == "response.completed"
+        assert types.count("response.function_call_arguments.delta") == 2
+        assert "response.function_call_arguments.done" in types
+
+        # Verify accumulated arguments
+        args_done = [e for e in events if e["event"] == "response.function_call_arguments.done"]
+        assert len(args_done) == 1
+        assert args_done[0]["data"]["arguments"] == '{"q": "hello"}'
+
+    async def test_alternating_text_and_function_call(self) -> None:
+        agent = _make_agent(
+            stream_updates=[
+                # Text deltas
+                AgentResponseUpdate(contents=[Content.from_text("Let me ")], role="assistant"),
+                AgentResponseUpdate(contents=[Content.from_text("search...")], role="assistant"),
+                # Function call argument deltas
+                AgentResponseUpdate(
+                    contents=[Content.from_function_call("call_1", "search", arguments='{"q":')],
+                    role="assistant",
+                ),
+                AgentResponseUpdate(
+                    contents=[Content.from_function_call("call_1", "search", arguments=' "x"}')],
+                    role="assistant",
+                ),
+                # More text deltas
+                AgentResponseUpdate(contents=[Content.from_text("Found ")], role="assistant"),
+                AgentResponseUpdate(contents=[Content.from_text("it!")], role="assistant"),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert types[0] == "response.created"
+        assert types[-1] == "response.completed"
+
+        # 4 text deltas + 2 function call argument deltas
+        assert types.count("response.output_text.delta") == 4
+        assert types.count("response.function_call_arguments.delta") == 2
+
+        # 3 distinct output items (text, fc, text)
+        assert types.count("response.output_item.added") == 3
+        assert types.count("response.output_item.done") == 3
+
+        # Verify accumulated content
+        text_done = [e for e in events if e["event"] == "response.output_text.done"]
+        assert len(text_done) == 2
+        assert text_done[0]["data"]["text"] == "Let me search..."
+        assert text_done[1]["data"]["text"] == "Found it!"
+
+        args_done = [e for e in events if e["event"] == "response.function_call_arguments.done"]
+        assert len(args_done) == 1
+        assert args_done[0]["data"]["arguments"] == '{"q": "x"}'
+
+    async def test_reasoning_then_text_streaming(self) -> None:
+        agent = _make_agent(
+            stream_updates=[
+                # Reasoning deltas
+                AgentResponseUpdate(contents=[Content.from_text_reasoning(text="Let me ")], role="assistant"),
+                AgentResponseUpdate(contents=[Content.from_text_reasoning(text="think...")], role="assistant"),
+                # Text deltas
+                AgentResponseUpdate(contents=[Content.from_text("The answer ")], role="assistant"),
+                AgentResponseUpdate(contents=[Content.from_text("is 42")], role="assistant"),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert types[0] == "response.created"
+        assert types[-1] == "response.completed"
+        # Reasoning + text = 2 output items
+        assert types.count("response.output_item.added") == 2
+        assert types.count("response.output_item.done") == 2
+        assert types.count("response.output_text.delta") == 2
+
+        # Verify accumulated text
+        text_done = [e for e in events if e["event"] == "response.output_text.done"]
+        assert len(text_done) == 1
+        assert text_done[0]["data"]["text"] == "The answer is 42"
+
+    async def test_empty_streaming(self) -> None:
+        agent = _make_agent(stream_updates=[])
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert types == ["response.created", "response.in_progress", "response.completed"]
+
+    async def test_mixed_contents_in_single_update(self) -> None:
+        """Text and function call in one update switches builder mid-update."""
+        agent = _make_agent(
+            stream_updates=[
+                AgentResponseUpdate(
+                    contents=[
+                        Content.from_text("Let me search"),
+                        Content.from_function_call("call_1", "search", arguments='{"q": "test"}'),
+                    ],
+                    role="assistant",
+                ),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert "response.output_text.delta" in types
+        assert "response.output_text.done" in types
+        assert "response.function_call_arguments.delta" in types
+        assert "response.function_call_arguments.done" in types
+
+    async def test_different_function_call_ids_produce_separate_items(self) -> None:
+        agent = _make_agent(
+            stream_updates=[
+                AgentResponseUpdate(
+                    contents=[Content.from_function_call("call_1", "func_a", arguments='{"x":1}')],
+                    role="assistant",
+                ),
+                AgentResponseUpdate(
+                    contents=[Content.from_function_call("call_2", "func_b", arguments='{"y":2}')],
+                    role="assistant",
+                ),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        # Two separate function call items
+        assert types.count("response.output_item.added") == 2
+        assert types.count("response.function_call_arguments.done") == 2
+
+    async def test_mcp_tool_call_streaming(self) -> None:
+        agent = _make_agent(
+            stream_updates=[
+                AgentResponseUpdate(
+                    contents=[
+                        Content(
+                            type="mcp_server_tool_call",
+                            server_name="my_server",
+                            tool_name="search",
+                            arguments='{"query":',
+                        )
+                    ],
+                    role="assistant",
+                ),
+                AgentResponseUpdate(
+                    contents=[
+                        Content(
+                            type="mcp_server_tool_call",
+                            server_name="my_server",
+                            tool_name="search",
+                            arguments=' "test"}',
+                        )
+                    ],
+                    role="assistant",
+                ),
+            ]
+        )
+        server = _make_server(agent)
+        resp = await _post(server, stream=True)
+
+        assert resp.status_code == 200
+        events = _parse_sse_events(resp.text)
+        types = _sse_event_types(events)
+
+        assert types[0] == "response.created"
+        assert types[-1] == "response.completed"
+        assert "response.output_item.added" in types
+        assert "response.output_item.done" in types
+
+
+# endregion
+
+
+# region _to_message conversion
+
+
+class TestToMessage:
+    """Tests for _to_message covering all supported OutputItem types."""
+
+    def test_output_message(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemOutputMessage, OutputMessageContentOutputTextContent
+
+        item = OutputItemOutputMessage({
+            "type": "output_message",
+            "role": "assistant",
+            "content": [OutputMessageContentOutputTextContent({"type": "output_text", "text": "hello"})],
+            "status": "completed",
+            "id": "msg-1",
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert len(msg.contents) == 1
+        assert msg.contents[0].type == "text"
+        assert msg.contents[0].text == "hello"
+
+    def test_message(self) -> None:
+        from azure.ai.agentserver.responses.models import MessageContentInputTextContent, OutputItemMessage
+
+        item = OutputItemMessage({
+            "type": "message",
+            "role": "user",
+            "content": [MessageContentInputTextContent({"type": "input_text", "text": "hi"})],
+        })
+        msg = _to_message(item)
+        assert msg.role == "user"
+        assert len(msg.contents) == 1
+        assert msg.contents[0].text == "hi"
+
+    def test_function_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemFunctionToolCall
+
+        item = OutputItemFunctionToolCall({
+            "type": "function_call",
+            "call_id": "call_1",
+            "name": "get_weather",
+            "arguments": '{"city": "NYC"}',
+            "status": "completed",
+            "id": "fc-1",
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_call"
+        assert msg.contents[0].call_id == "call_1"
+        assert msg.contents[0].name == "get_weather"
+
+    def test_function_call_output(self) -> None:
+        from azure.ai.agentserver.responses.models import FunctionCallOutputItemParam
+
+        item = FunctionCallOutputItemParam({"type": "function_call_output", "call_id": "call_1", "output": "sunny"})
+        msg = _to_message(item)  # type: ignore[arg-type]
+        assert msg.role == "tool"
+        assert msg.contents[0].type == "function_result"
+        assert msg.contents[0].call_id == "call_1"
+        assert msg.contents[0].result == "sunny"
+
+    def test_reasoning(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemReasoningItem, SummaryTextContent
+
+        item = OutputItemReasoningItem({
+            "type": "reasoning",
+            "id": "r-1",
+            "summary": [SummaryTextContent({"type": "summary_text", "text": "thinking hard"})],
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert len(msg.contents) == 1
+        assert msg.contents[0].text == "thinking hard"
+
+    def test_reasoning_no_summary(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemReasoningItem
+
+        item = OutputItemReasoningItem({"type": "reasoning", "id": "r-2"})
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents == []
+
+    def test_mcp_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemMcpToolCall
+
+        item = OutputItemMcpToolCall({
+            "type": "mcp_call",
+            "id": "mcp-1",
+            "server_label": "my_server",
+            "name": "search",
+            "arguments": '{"q": "test"}',
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "mcp_server_tool_call"
+        assert msg.contents[0].server_name == "my_server"
+        assert msg.contents[0].tool_name == "search"
+
+    def test_mcp_approval_request(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemMcpApprovalRequest
+
+        item = OutputItemMcpApprovalRequest({
+            "type": "mcp_approval_request",
+            "id": "apr-1",
+            "server_label": "srv",
+            "name": "dangerous_tool",
+            "arguments": "{}",
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_approval_request"
+
+    def test_mcp_approval_response(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemMcpApprovalResponseResource
+
+        item = OutputItemMcpApprovalResponseResource({
+            "type": "mcp_approval_response",
+            "id": "resp-1",
+            "approval_request_id": "apr-1",
+            "approve": True,
+        })
+        msg = _to_message(item)
+        assert msg.role == "user"
+        assert msg.contents[0].type == "function_approval_response"
+        assert msg.contents[0].approved is True
+
+    def test_code_interpreter_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemCodeInterpreterToolCall
+
+        item = OutputItemCodeInterpreterToolCall({
+            "type": "code_interpreter_call",
+            "id": "ci-1",
+            "status": "completed",
+            "container_id": "c-1",
+            "code": "print('hi')",
+            "outputs": [],
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "code_interpreter_tool_call"
+
+    def test_image_generation_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemImageGenToolCall
+
+        item = OutputItemImageGenToolCall({"type": "image_generation_call", "id": "ig-1", "status": "completed"})
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "image_generation_tool_call"
+
+    def test_shell_call(self) -> None:
+        from azure.ai.agentserver.responses.models import (
+            FunctionShellAction,
+            FunctionShellCallEnvironment,
+            OutputItemFunctionShellCall,
+        )
+
+        item = OutputItemFunctionShellCall({
+            "type": "shell_call",
+            "id": "sc-1",
+            "call_id": "call_sc",
+            "action": FunctionShellAction({"commands": ["ls", "-la"], "timeout_ms": 5000, "max_output_length": 1024}),
+            "status": "completed",
+            "environment": FunctionShellCallEnvironment({"type": "local"}),
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "shell_tool_call"
+        assert msg.contents[0].commands == ["ls", "-la"]
+        assert msg.contents[0].call_id == "call_sc"
+
+    def test_shell_call_output(self) -> None:
+        from azure.ai.agentserver.responses.models import (
+            FunctionShellCallOutputContent,
+            FunctionShellCallOutputExitOutcome,
+            OutputItemFunctionShellCallOutput,
+        )
+
+        item = OutputItemFunctionShellCallOutput({
+            "type": "shell_call_output",
+            "id": "sco-1",
+            "call_id": "call_sc",
+            "status": "completed",
+            "output": [
+                FunctionShellCallOutputContent({
+                    "stdout": "file.txt",
+                    "stderr": "",
+                    "outcome": FunctionShellCallOutputExitOutcome({"exit_code": 0}),
+                })
+            ],
+            "max_output_length": 1024,
+        })
+        msg = _to_message(item)
+        assert msg.role == "tool"
+        assert msg.contents[0].type == "shell_tool_result"
+        assert msg.contents[0].call_id == "call_sc"
+
+    def test_local_shell_call(self) -> None:
+        from azure.ai.agentserver.responses.models import LocalShellExecAction, OutputItemLocalShellToolCall
+
+        item = OutputItemLocalShellToolCall({
+            "type": "local_shell_call",
+            "id": "lsc-1",
+            "call_id": "call_lsc",
+            "action": LocalShellExecAction({"type": "exec", "command": ["echo", "hello"], "env": {}}),
+            "status": "completed",
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "shell_tool_call"
+        assert msg.contents[0].commands == ["echo", "hello"]
+
+    def test_local_shell_call_output(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemLocalShellToolCallOutput
+
+        item = OutputItemLocalShellToolCallOutput({
+            "type": "local_shell_call_output",
+            "id": "lsco-1",
+            "output": "hello\n",
+        })
+        msg = _to_message(item)
+        assert msg.role == "tool"
+        assert msg.contents[0].type == "shell_tool_result"
+
+    def test_file_search_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemFileSearchToolCall
+
+        item = OutputItemFileSearchToolCall({
+            "type": "file_search_call",
+            "id": "fs-1",
+            "status": "completed",
+            "queries": ["what is AI"],
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_call"
+        assert msg.contents[0].name == "file_search"
+        assert '"what is AI"' in (msg.contents[0].arguments or "")
+
+    def test_web_search_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemWebSearchToolCall, WebSearchActionSearch
+
+        item = OutputItemWebSearchToolCall({
+            "type": "web_search_call",
+            "id": "ws-1",
+            "status": "completed",
+            "action": WebSearchActionSearch({"type": "search", "query": "test"}),
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_call"
+        assert msg.contents[0].name == "web_search"
+
+    def test_computer_call(self) -> None:
+        from azure.ai.agentserver.responses.models import ComputerAction, OutputItemComputerToolCall
+
+        item = OutputItemComputerToolCall({
+            "type": "computer_call",
+            "id": "cc-1",
+            "call_id": "call_cc",
+            "action": ComputerAction({"type": "click"}),
+            "pending_safety_checks": [],
+            "status": "completed",
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_call"
+        assert msg.contents[0].name == "computer_use"
+
+    def test_computer_call_output(self) -> None:
+        from azure.ai.agentserver.responses.models import (
+            ComputerScreenshotImage,
+            OutputItemComputerToolCallOutputResource,
+        )
+
+        item = OutputItemComputerToolCallOutputResource({
+            "type": "computer_call_output",
+            "call_id": "call_cc",
+            "output": ComputerScreenshotImage({
+                "type": "computer_screenshot",
+                "image_url": "data:image/png;base64,abc",
+            }),
+        })
+        msg = _to_message(item)
+        assert msg.role == "tool"
+        assert msg.contents[0].type == "function_result"
+        assert msg.contents[0].call_id == "call_cc"
+
+    def test_custom_tool_call(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemCustomToolCall
+
+        item = OutputItemCustomToolCall({
+            "type": "custom_tool_call",
+            "call_id": "call_ct",
+            "name": "my_tool",
+            "input": '{"key": "value"}',
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_call"
+        assert msg.contents[0].name == "my_tool"
+        assert msg.contents[0].arguments == '{"key": "value"}'
+
+    def test_custom_tool_call_output(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemCustomToolCallOutput
+
+        item = OutputItemCustomToolCallOutput({
+            "type": "custom_tool_call_output",
+            "call_id": "call_ct",
+            "output": "result text",
+        })
+        msg = _to_message(item)
+        assert msg.role == "tool"
+        assert msg.contents[0].type == "function_result"
+        assert msg.contents[0].result == "result text"
+
+    def test_apply_patch_call(self) -> None:
+        from azure.ai.agentserver.responses.models import ApplyPatchUpdateFileOperation, OutputItemApplyPatchToolCall
+
+        item = OutputItemApplyPatchToolCall({
+            "type": "apply_patch_call",
+            "id": "ap-1",
+            "call_id": "call_ap",
+            "status": "completed",
+            "operation": ApplyPatchUpdateFileOperation({
+                "type": "update_file",
+                "path": "file.py",
+                "diff": "+ new line",
+            }),
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "function_call"
+        assert msg.contents[0].name == "apply_patch"
+
+    def test_apply_patch_call_output(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItemApplyPatchToolCallOutput
+
+        item = OutputItemApplyPatchToolCallOutput({
+            "type": "apply_patch_call_output",
+            "id": "apo-1",
+            "call_id": "call_ap",
+            "status": "completed",
+            "output": "patch applied",
+        })
+        msg = _to_message(item)
+        assert msg.role == "tool"
+        assert msg.contents[0].type == "function_result"
+        assert msg.contents[0].result == "patch applied"
+
+    def test_oauth_consent_request(self) -> None:
+        from azure.ai.agentserver.responses.models import OAuthConsentRequestOutputItem
+
+        item = OAuthConsentRequestOutputItem({
+            "type": "oauth_consent_request",
+            "id": "oauth-1",
+            "consent_link": "https://example.com/consent",
+            "server_label": "my_server",
+        })
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "oauth_consent_request"
+        assert msg.contents[0].consent_link == "https://example.com/consent"
+
+    def test_structured_outputs_dict(self) -> None:
+        from azure.ai.agentserver.responses.models import StructuredOutputsOutputItem
+
+        item = StructuredOutputsOutputItem({"type": "structured_outputs", "id": "so-1", "output": {"answer": 42}})
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].type == "text"
+        assert json.loads(msg.contents[0].text or "") == {"answer": 42}
+
+    def test_structured_outputs_string(self) -> None:
+        from azure.ai.agentserver.responses.models import StructuredOutputsOutputItem
+
+        item = StructuredOutputsOutputItem({"type": "structured_outputs", "id": "so-2", "output": "plain text"})
+        msg = _to_message(item)
+        assert msg.role == "assistant"
+        assert msg.contents[0].text == "plain text"
+
+    def test_unsupported_type_raises(self) -> None:
+        from azure.ai.agentserver.responses.models import OutputItem
+
+        item = OutputItem({"type": "some_unknown_type"})
+        with pytest.raises(ValueError, match="Unsupported OutputItem type: some_unknown_type"):
+            _to_message(item)
+
+
+# endregion

python/pyproject.toml

@@ -41,6 +41,7 @@ dev = [
     "pyright==1.1.408",
     "mcp[ws]==1.27.0",
     "opentelemetry-sdk==1.40.0",
+    "azure-monitor-opentelemetry==1.8.7",
     #tasks
     "poethepoet==0.42.1",
     "rich>=13.7.1,<15.0.0",
@@ -79,6 +80,7 @@ agent-framework-declarative = { workspace = true }
 agent-framework-devui = { workspace = true }
 agent-framework-durabletask = { workspace = true }
 agent-framework-foundry = { workspace = true }
+agent-framework-foundry-hosting = { workspace = true }
 agent-framework-foundry-local = { workspace = true }
 agent-framework-gemini = { workspace = true }
 agent-framework-github-copilot = { workspace = true }

python/samples/02-agents/context_providers/README.md

@@ -7,6 +7,7 @@ These samples demonstrate how to use context providers to enrich agent conversat
 | File / Folder | Description |
 |---------------|-------------|
 | [`simple_context_provider.py`](simple_context_provider.py) | Implement a custom context provider by extending `ContextProvider` to extract and inject structured user information across turns. |
+| [`foundry_toolbox_context_provider.py`](foundry_toolbox_context_provider.py) | Compose a Microsoft Foundry toolbox with a `ContextProvider` that caches the toolbox once and picks a subset of its tools per-turn via `select_toolbox_tools`, driven by keywords in the latest user message. |
 | [`azure_ai_foundry_memory.py`](azure_ai_foundry_memory.py) | Use `FoundryMemoryProvider` to add semantic memory — automatically retrieves, searches, and stores memories via Azure AI Foundry. |
 | [`azure_ai_search/`](azure_ai_search/) | Retrieval Augmented Generation (RAG) with Azure AI Search in semantic and agentic modes. See its own [README](azure_ai_search/README.md). |
 | [`mem0/`](mem0/) | Memory-powered context using the Mem0 integration (open-source and managed). See its own [README](mem0/README.md). |
@@ -19,6 +20,12 @@ These samples demonstrate how to use context providers to enrich agent conversat
 - `FOUNDRY_MODEL`: Model deployment name
 - Azure CLI authentication (`az login`)
 
+**For `foundry_toolbox_context_provider.py`:**
+- `FOUNDRY_PROJECT_ENDPOINT`: Your Microsoft Foundry project endpoint
+- `FOUNDRY_MODEL`: Model deployment name
+- A toolbox already configured in that project; set `TOOLBOX_NAME` / `TOOLBOX_VERSION` at the top of the sample
+- Azure CLI authentication (`az login`)
+
 **For `azure_ai_foundry_memory.py`:**
 - `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
 - `FOUNDRY_MODEL`: Chat/responses model deployment name

python/samples/02-agents/context_providers/foundry_toolbox_context_provider.py

@@ -0,0 +1,207 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Any
+
+from agent_framework import Agent, AgentSession, ContextProvider, Message, SessionContext
+from agent_framework.foundry import (
+    FoundryChatClient,
+    get_toolbox_tool_name,
+    get_toolbox_tool_type,
+    select_toolbox_tools,
+)
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import BaseModel
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Toolbox + Context Provider Example
+
+This sample composes a Foundry toolbox with a ContextProvider so the agent's
+tool list is chosen dynamically per-turn. It uses the chat client itself as a lightweight "tool router": the
+latest user message plus a short menu of toolbox tools is sent to the model
+with a Pydantic ``response_format``, and the returned tool names drive
+``select_toolbox_tools``. The toolbox is fetched once and cached on the
+provider's state dict; subsequent turns reuse the cache.
+
+Prerequisites:
+- A Microsoft Foundry project
+- A toolbox already configured in that project (set TOOLBOX_NAME below)
+- FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL environment variables set
+- Azure CLI authentication (`az login`)
+"""
+
+# Replace with your own Foundry toolbox name and version.
+TOOLBOX_NAME = "research_toolbox"
+# Set to None to resolve the toolbox's current default version at fetch time.
+TOOLBOX_VERSION: str | None = None
+
+# Generic queries that exercise the router without assuming any specific tool
+# types are configured. The first is introspective, the second forces a
+# non-empty pick for whichever tools the toolbox actually contains, and the
+# third should route to nothing.
+QUERIES: list[str] = [
+    "Introduce yourself and briefly describe the tools you can use to help me.",
+    "Pick the tool you think is most useful and demonstrate it with a short example.",
+    "Say hi in one short sentence - no tools needed.",
+]
+
+
+def create_sample_toolbox(name: str) -> str:
+    """Create (or replace) a toolbox version in the Foundry project.
+
+    Toolboxes are normally configured in the Foundry portal or a deployment
+    script, not the application itself. This helper exists so the sample can
+    be run end-to-end without first setting a toolbox up by hand — delete any
+    existing toolbox under ``name``, then create a fresh version containing a
+    single MCP tool. Returns the created version identifier.
+    """
+    from azure.ai.projects import AIProjectClient
+    from azure.ai.projects.models import MCPTool, Tool
+    from azure.core.exceptions import ResourceNotFoundError
+
+    with (
+        AzureCliCredential() as credential,
+        AIProjectClient(credential=credential, endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"]) as project_client,
+    ):
+        try:
+            project_client.beta.toolboxes.delete(name)
+            print(f"Toolbox `{name}` deleted")
+        except ResourceNotFoundError:
+            pass
+
+        tools: list[Tool] = [
+            MCPTool(
+                server_label="api_specs",
+                server_url="https://gitmcp.io/Azure/azure-rest-api-specs",
+                require_approval="never",
+            )
+        ]
+
+        created = project_client.beta.toolboxes.create_version(
+            name=name,
+            description="Toolbox version with MCP require_approval set to 'never'.",
+            tools=tools,
+        )
+        print(f"Created toolbox {created.name}@{created.version} ({len(created.tools)} tool(s))")
+        return created.version
+
+
+class ToolSelection(BaseModel):
+    """Structured output for the per-turn tool router."""
+
+    tool_names: list[str]
+
+
+ROUTER_INSTRUCTIONS = (
+    "You are a tool router. Given the user's latest message and a menu of "
+    "available tools (one per line, formatted as 'NAME - TYPE'), return the "
+    "NAMES of the tools that would plausibly help answer the message. Return "
+    "an empty list if no tool is needed."
+)
+
+
+class DynamicToolboxProvider(ContextProvider):
+    """Fetches a Foundry toolbox once and lets the model pick tools per-turn."""
+
+    DEFAULT_SOURCE_ID = "foundry_toolbox"
+
+    def __init__(
+        self,
+        source_id: str = DEFAULT_SOURCE_ID,
+        *,
+        client: FoundryChatClient,
+        toolbox_name: str,
+        toolbox_version: str | None = None,
+    ) -> None:
+        super().__init__(source_id)
+        self._client = client
+        self._toolbox_name = toolbox_name
+        self._toolbox_version = toolbox_version
+
+    async def before_run(
+        self,
+        *,
+        agent: Any,
+        session: AgentSession | None,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Cache the toolbox on first call, then let the model pick tools per-turn."""
+        toolbox = state.get("toolbox")
+        if toolbox is None:
+            toolbox = await self._client.get_toolbox(self._toolbox_name, version=self._toolbox_version)
+            state["toolbox"] = toolbox
+            print(f"[{self.source_id}] Loaded toolbox {toolbox.name}@{toolbox.version} ({len(toolbox.tools)} tool(s))")
+
+        user_messages = [m for m in context.get_messages(include_input=True) if getattr(m, "role", None) == "user"]
+        if not user_messages:
+            context.extend_tools(self.source_id, list(toolbox.tools))
+            return
+
+        picks = await self._route_tools(user_messages[-1].text, toolbox.tools)
+        if picks:
+            tools = select_toolbox_tools(toolbox, include_names=picks)
+            print(f"[{self.source_id}] Router picked {sorted(picks)} - surfacing {len(tools)} tool(s)")
+        else:
+            tools = list(toolbox.tools)
+            print(f"[{self.source_id}] Router picked nothing - surfacing all {len(tools)} tool(s)")
+        context.extend_tools(self.source_id, tools)
+
+    async def _route_tools(self, user_text: str, tools: Any) -> list[str]:
+        """Ask the model which toolbox tools to surface for this turn."""
+        menu = "\n".join(f"- {get_toolbox_tool_name(t)} - {get_toolbox_tool_type(t)}" for t in tools)
+        prompt = (
+            f"User message:\n{user_text}\n\n"
+            f"Available tools:\n{menu}\n\n"
+            "Return the names of tools that should be surfaced for this turn."
+        )
+        response = await self._client.get_response(
+            messages=[Message("user", [prompt])],
+            options={
+                "instructions": ROUTER_INSTRUCTIONS,
+                "response_format": ToolSelection,
+            },
+        )
+        selection: ToolSelection = response.value  # type: ignore
+        return selection.tool_names
+
+
+async def main() -> None:
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=AzureCliCredential(),
+    )
+
+    # Comment out if the toolbox already exists in your Foundry project.
+    create_sample_toolbox(TOOLBOX_NAME)
+
+    toolbox_provider = DynamicToolboxProvider(
+        client=client,
+        toolbox_name=TOOLBOX_NAME,
+        toolbox_version=TOOLBOX_VERSION,
+    )
+
+    async with Agent(
+        client=client,
+        instructions=(
+            "You are a helpful assistant. Use the tools available to you on each "
+            "turn to answer the user. If no tools are relevant, reply directly."
+        ),
+        context_providers=[toolbox_provider],
+    ) as agent:
+        session = agent.create_session()
+
+        for query in QUERIES:
+            print(f"\nUser: {query}")
+            result = await agent.run(query, session=session)
+            print(f"Assistant: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/02-agents/observability/README.md

@@ -347,28 +347,29 @@ setup_observability(
 ```
 
 **After (Current):**
+
 ```python
-# For Microsoft Foundry projects
 from agent_framework.foundry import FoundryChatClient
-from azure.identity import AzureCliCredential
-
-client = FoundryChatClient(
-    project_endpoint="https://your-project.services.ai.azure.com",
-    model="gpt-4o",
-    credential=AzureCliCredential(),
-)
-await client.configure_azure_monitor(enable_live_metrics=True)
-
-# For non-Azure AI projects
-from azure.monitor.opentelemetry import configure_azure_monitor
 from agent_framework.observability import create_resource, enable_instrumentation
+from azure.identity import AzureCliCredential
+from azure.monitor.opentelemetry import configure_azure_monitor
 
-configure_azure_monitor(
-    connection_string="InstrumentationKey=...",
-    resource=create_resource(),
-    enable_live_metrics=True,
-)
-enable_instrumentation()
+async def main():
+    # For Microsoft Foundry projects
+    client = FoundryChatClient(
+        project_endpoint="https://your-project.services.ai.azure.com",
+        model="gpt-4o",
+        credential=AzureCliCredential(),
+    )
+    await client.configure_azure_monitor(enable_live_metrics=True)
+
+    # For non-Azure AI projects
+    configure_azure_monitor(
+        connection_string="InstrumentationKey=...",
+        resource=create_resource(),
+        enable_live_metrics=True,
+    )
+    enable_instrumentation()
 ```
 
 ### Console Output

python/samples/02-agents/providers/foundry/README.md

@@ -26,6 +26,8 @@ This folder contains Azure AI Foundry and Foundry Local samples for Agent Framew
 | [`foundry_chat_client_with_hosted_mcp.py`](foundry_chat_client_with_hosted_mcp.py) | Foundry Chat Client with hosted MCP |
 | [`foundry_chat_client_with_local_mcp.py`](foundry_chat_client_with_local_mcp.py) | Foundry Chat Client with local MCP |
 | [`foundry_chat_client_with_session.py`](foundry_chat_client_with_session.py) | Foundry Chat Client with session management |
+| [`foundry_chat_client_with_toolbox.py`](foundry_chat_client_with_toolbox.py) | Foundry Chat Client with Foundry toolbox loading and multi-toolbox composition |
+| [`foundry_chat_client_with_toolbox_mcp.py`](foundry_chat_client_with_toolbox_mcp.py) | Foundry Chat Client connected to a toolbox via its MCP endpoint using `MCPStreamableHTTPTool` |
 
 ## FoundryLocalClient Samples
 

python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py

@@ -0,0 +1,174 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient, select_toolbox_tools
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Chat Client with Toolbox Example
+
+This sample demonstrates loading a named, versioned Foundry toolbox into an
+Agent via ``FoundryChatClient.get_toolbox()``. A toolbox is a server-side
+bundle of tool configurations (code interpreter, file search, MCP, web search,
+etc.) configured in the Foundry portal or via the raw SDK.
+
+Prerequisites:
+- A Microsoft Foundry project
+- A toolbox already configured in that project (set TOOLBOX_NAME below)
+- FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL environment variables set
+"""
+
+# Replace with your own Foundry toolbox name and version.
+TOOLBOX_NAME = "research_toolbox"
+TOOLBOX_VERSION = "1"
+# Used only by combine_toolboxes() — swap in a second toolbox you own.
+SECOND_TOOLBOX_NAME = "analysis_toolbox"
+SECOND_TOOLBOX_VERSION = "1"
+
+# Replace with any question that exercises the tools configured in your toolbox.
+QUERY = "Introduce yourself and briefly describe the tools you can use to help me."
+
+
+def create_sample_toolbox(name: str) -> str:
+    """Create (or replace) a toolbox version in the Foundry project.
+
+    Toolboxes are normally configured in the Foundry portal or a deployment
+    script, not the application itself. This helper exists so the samples can
+    be run end-to-end without first setting a toolbox up by hand — delete any
+    existing toolbox under ``name``, then create a fresh version containing a
+    single MCP tool. Returns the created version identifier.
+    """
+    from azure.ai.projects import AIProjectClient
+    from azure.ai.projects.models import MCPTool, Tool
+    from azure.core.exceptions import ResourceNotFoundError
+
+    with (
+        AzureCliCredential() as credential,
+        AIProjectClient(credential=credential, endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"]) as project_client,
+    ):
+        try:
+            project_client.beta.toolboxes.delete(name)
+            print(f"Toolbox `{name}` deleted")
+        except ResourceNotFoundError:
+            pass
+
+        tools: list[Tool] = [
+            MCPTool(
+                server_label="api_specs",
+                server_url="https://gitmcp.io/Azure/azure-rest-api-specs",
+                require_approval="never",
+            )
+        ]
+
+        created = project_client.beta.toolboxes.create_version(
+            name=name,
+            description="Toolbox version with MCP require_approval set to 'never'.",
+            tools=tools,
+        )
+        print(f"Created toolbox {created.name}@{created.version} ({len(created.tools)} tool(s))")
+        return created.version
+
+
+async def main() -> None:
+    """Example showing how to use a single Foundry toolbox with FoundryChatClient."""
+    print("=== Foundry Chat Client with Toolbox Example ===")
+
+    # For authentication, run `az login` in your terminal or replace
+    # AzureCliCredential with your preferred authentication option.
+    client = FoundryChatClient(
+        credential=AzureCliCredential(),
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+    )
+
+    # Comment out if the toolbox already exists in your Foundry project.
+    create_sample_toolbox(TOOLBOX_NAME)
+
+    # Omit ``version`` to resolve the toolbox's current default version at runtime.
+    toolbox = await client.get_toolbox(TOOLBOX_NAME)
+    print(f"Loaded toolbox {toolbox.name}@{toolbox.version} ({len(toolbox.tools)} tool(s))")
+
+    agent = Agent(
+        client=client,
+        instructions="You are a research assistant. Use the available tools to answer questions.",
+        tools=toolbox,
+    )
+
+    print(f"User: {QUERY}")
+    result = await agent.run(QUERY)
+    print(f"Result: {result}\n")
+
+
+async def combine_toolboxes() -> None:
+    """Alternative flow: combine the tools from multiple Foundry toolboxes."""
+    client = FoundryChatClient(
+        credential=AzureCliCredential(),
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+    )
+
+    # Comment out if the toolboxes already exist in your Foundry project.
+    create_sample_toolbox(TOOLBOX_NAME)
+    create_sample_toolbox(SECOND_TOOLBOX_NAME)
+
+    toolbox_a = await client.get_toolbox(TOOLBOX_NAME, version=TOOLBOX_VERSION)
+    toolbox_b = await client.get_toolbox(SECOND_TOOLBOX_NAME, version=SECOND_TOOLBOX_VERSION)
+    print(
+        "Loaded toolboxes: "
+        f"{toolbox_a.name}@{toolbox_a.version} ({len(toolbox_a.tools)} tool(s)), "
+        f"{toolbox_b.name}@{toolbox_b.version} ({len(toolbox_b.tools)} tool(s))"
+    )
+
+    agent = Agent(
+        client=client,
+        instructions="You are a research assistant. Use all available tools to answer questions.",
+        tools=[toolbox_a, toolbox_b],
+    )
+
+    print(f"User: {QUERY}")
+    result = await agent.run(QUERY)
+    print(f"Combined-toolbox result: {result}\n")
+
+
+async def select_tools_from_toolbox() -> None:
+    """Alternative flow: keep only a subset of toolbox tools before agent creation."""
+    client = FoundryChatClient(
+        credential=AzureCliCredential(),
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+    )
+
+    # Comment out if the toolbox already exists in your Foundry project.
+    create_sample_toolbox(TOOLBOX_NAME)
+
+    toolbox = await client.get_toolbox(TOOLBOX_NAME, version=TOOLBOX_VERSION)
+    print(f"Loaded toolbox {toolbox.name}@{toolbox.version} ({len(toolbox.tools)} tool(s))")
+
+    selected_tools = select_toolbox_tools(
+        toolbox,
+        include_types=["code_interpreter", "mcp"],
+    )
+    print(f"Selected {len(selected_tools)} toolbox tools for the agent")
+
+    agent = Agent(
+        client=client,
+        instructions="You are a research assistant. Use only the selected toolbox tools.",
+        tools=selected_tools,
+    )
+
+    print(f"User: {QUERY}")
+    result = await agent.run(QUERY)
+    print(f"Selected-toolbox result: {result}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+    # asyncio.run(combine_toolboxes())
+    # asyncio.run(select_tools_from_toolbox())

python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox_mcp.py

@@ -0,0 +1,118 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from collections.abc import Callable
+from typing import Any
+
+from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework.foundry import FoundryChatClient
+from azure.core.credentials import TokenCredential
+from azure.identity import AzureCliCredential, DefaultAzureCredential, get_bearer_token_provider
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Foundry Toolbox via MAF ``MCPStreamableHTTPTool``
+
+Instead of fetching the toolbox and fanning out individual tool specs, point
+MAF's ``MCPStreamableHTTPTool`` at the toolbox's MCP endpoint. The agent
+discovers and calls the toolbox's tools over MCP at runtime.
+
+Prerequisites:
+- A Microsoft Foundry project with a toolbox configured
+- FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL environment variables set
+- FOUNDRY_TOOLBOX_ENDPOINT: the toolbox's MCP endpoint URL, e.g.
+  ``https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1``
+- Azure CLI authentication (``az login``)
+"""
+
+# Must match the ``<name>`` segment of FOUNDRY_TOOLBOX_ENDPOINT.
+TOOLBOX_NAME = "research_toolbox"
+
+
+def create_sample_toolbox(name: str) -> str:
+    """Create (or replace) a toolbox version in the Foundry project.
+
+    Toolboxes are normally configured in the Foundry portal or a deployment
+    script, not the application itself. This helper exists so the sample can
+    be run end-to-end without first setting a toolbox up by hand — delete any
+    existing toolbox under ``name``, then create a fresh version containing a
+    single MCP tool. Returns the created version identifier.
+    """
+    from azure.ai.projects import AIProjectClient
+    from azure.ai.projects.models import MCPTool, Tool
+    from azure.core.exceptions import ResourceNotFoundError
+
+    with (
+        AzureCliCredential() as credential,
+        AIProjectClient(credential=credential, endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"]) as project_client,
+    ):
+        try:
+            project_client.beta.toolboxes.delete(name)
+            print(f"Toolbox `{name}` deleted")
+        except ResourceNotFoundError:
+            pass
+
+        tools: list[Tool] = [
+            MCPTool(
+                server_label="api_specs",
+                server_url="https://gitmcp.io/Azure/azure-rest-api-specs",
+                require_approval="never",
+            )
+        ]
+
+        created = project_client.beta.toolboxes.create_version(
+            name=name,
+            description="Toolbox version with MCP require_approval set to 'never'.",
+            tools=tools,
+        )
+        print(f"Created toolbox {created.name}@{created.version} ({len(created.tools)} tool(s))")
+        return created.version
+
+
+def make_toolbox_header_provider(credential: TokenCredential) -> Callable[[dict[str, Any]], dict[str, str]]:
+    """Build a header_provider that injects a fresh Azure AI bearer token on every MCP request."""
+    get_token = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
+
+    def provide(_kwargs: dict[str, Any]) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {get_token()}",
+        }
+
+    return provide
+
+
+async def main() -> None:
+    credential = DefaultAzureCredential()
+
+    # Comment out if the toolbox already exists in your Foundry project.
+    create_sample_toolbox(TOOLBOX_NAME)
+
+    toolbox_tool = MCPStreamableHTTPTool(
+        name="foundry_toolbox",
+        description="Tools exposed by the configured Foundry toolbox",
+        url=os.environ["FOUNDRY_TOOLBOX_ENDPOINT"],
+        header_provider=make_toolbox_header_provider(credential),
+        load_prompts=False,
+    )
+
+    async with Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=credential,
+        ),
+        instructions="You are a helpful assistant. Use the available toolbox tools to answer the user.",
+        tools=toolbox_tool,
+    ) as agent:
+        query = "What tools do you have access to?"
+        print(f"User: {query}")
+        result = await agent.run(query)
+        print(f"Assistant: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/04-hosting/foundry-hosted-agents/README.md

@@ -0,0 +1,56 @@
+# Foundry Hosted Agents Samples
+
+This directory contains samples that demonstrate how to use the Agent Framework to host agents on Foundry with different capabilities and configurations. Each sample includes a README with instructions on how to set up, run, and interact with the agent.
+
+Read more about Foundry Hosted Agents [here](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents).
+
+## Environment setup
+
+1. Navigate to the sample directory you want to run. For example:
+
+   ```bash
+   python -m venv .venv
+
+   # Windows
+   .venv\Scripts\Activate
+
+   # macOS/Linux
+   source .venv/bin/activate
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Create a `.env` file with your Foundry configuration following the `env.example` file in the sample.
+
+4. Make sure you are logged in with the Azure CLI:
+
+   ```bash
+   az login
+   ```
+
+## Deploying to a Docker container
+
+Navigate to the sample directory and build the Docker image:
+
+```bash
+docker build -t hosted-agent-sample .
+```
+
+Run the container, passing in the required environment variables:
+
+```bash
+docker run -p 8088:8088 \
+  -e FOUNDRY_PROJECT_ENDPOINT=<your-endpoint> \
+  -e MODEL_DEPLOYMENT_NAME=<your-model> \
+  hosted-agent-sample
+```
+
+The server will be available at `http://localhost:8088`. You can send requests using the same `curl` command shown above.
+
+## Deploying to Foundry
+
+Follow this [guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent?tabs=bash#configure-your-agent) to deploy your agent to Foundry.

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/.env.example

@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT="..."
+MODEL_DEPLOYMENT_NAME="..."

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/README.md

@@ -0,0 +1,44 @@
+# Basic example of hosting an agent with the `invocations` API
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+### Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations -i -H "Content-Type: application/json" -d '{"message": "Hi"}'
+```
+
+The server will respond with a JSON object containing the response text. The `-i` flag in the `curl` command includes the HTTP response headers in the output, which includes the session ID that can be used for multi-turn conversations. Here is an example of the response:
+
+```bash
+HTTP/1.1 200
+content-length: 34
+content-type: application/json
+x-agent-invocation-id: ec04d020-a0e7-441e-ae83-db75635a9f83
+x-agent-session-id: 9370b9d4-cd13-4436-a57f-03b843ac0e17
+x-platform-server: azure-ai-agentserver-core/2.0.0a20260410006 (python/3.12)
+date: Fri, 17 Apr 2026 23:46:44 GMT
+server: hypercorn-h11
+
+{"response":"Hi! How can I help?"}
+```
+
+### Multi-turn conversation
+
+To have a multi-turn conversation with the agent, take the session ID from the response headers of the previous request and include it in URL parameters for the next request. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations?agent_session_id=9370b9d4-cd13-4436-a57f-03b843ac0e17 -i -H "Content-Type: application/json" -d '{"message": "How are you?"}'
+```

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/agent.manifest.yaml

@@ -0,0 +1,23 @@
+name: agent-framework-agent-basic-invocations
+description: >
+  A basic Agent Framework agent hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Invocations Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-basic-invocations
+  kind: hosted
+  protocols:
+    - protocol: invocations
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: agent-framework-agent-basic-invocations
+protocols:
+  - protocol: invocations
+    version: 1.0.0
+resources:
+  cpu: '0.25'
+  memory: '0.5Gi'

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/main.py

@@ -0,0 +1,36 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from agent_framework_foundry_hosting import InvocationsHostServer
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+def main():
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    agent = Agent(
+        client=client,
+        instructions="You are a friendly assistant. Keep your answers brief.",
+        # History will be managed by the hosting infrastructure, thus there
+        # is no need to store history by the service. Learn more at:
+        # https://developers.openai.com/api/reference/resources/responses/methods/create
+        default_options={"store": False},
+    )
+
+    server = InvocationsHostServer(agent)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

python/samples/04-hosting/foundry-hosted-agents/invocations/01_basic/requirements.txt

@@ -0,0 +1,2 @@
+agent-framework
+agent-framework-foundry-hosting

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/.env.example

@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT="..."
+MODEL_DEPLOYMENT_NAME="..."

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/README.md

@@ -0,0 +1,46 @@
+# Basic example of hosting an agent with the `invocations` API
+
+This is the same as the [01_basic](../01_basic/README.md) example, but demonstrates the "break glass" scenario where you can create your own `invoke_handler` to handle specific types of invocations. This is useful when you want to override the default behavior for certain requests or add custom processing logic.
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+### Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations -i -H "Content-Type: application/json" -d '{"message": "Hi"}'
+```
+
+The server will respond with a JSON object containing the response text. The `-i` flag in the `curl` command includes the HTTP response headers in the output, which includes the session ID that can be used for multi-turn conversations. Here is an example of the response:
+
+```bash
+HTTP/1.1 200
+content-length: 34
+content-type: application/json
+x-agent-invocation-id: ec04d020-a0e7-441e-ae83-db75635a9f83
+x-agent-session-id: 9370b9d4-cd13-4436-a57f-03b843ac0e17
+x-platform-server: azure-ai-agentserver-core/2.0.0a20260410006 (python/3.12)
+date: Fri, 17 Apr 2026 23:46:44 GMT
+server: hypercorn-h11
+
+{"response":"Hi! How can I help?"}
+```
+
+### Multi-turn conversation
+
+To have a multi-turn conversation with the agent, take the session ID from the response headers of the previous request and include it in URL parameters for the next request. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations?agent_session_id=9370b9d4-cd13-4436-a57f-03b843ac0e17 -i -H "Content-Type: application/json" -d '{"message": "How are you?"}'
+```

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/agent.manifest.yaml

@@ -0,0 +1,23 @@
+name: agent-framework-agent-basic-invocations
+description: >
+  A basic Agent Framework agent hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Invocations Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-basic-invocations
+  kind: hosted
+  protocols:
+    - protocol: invocations
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/agent.yaml

@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: agent-framework-agent-basic-invocations
+protocols:
+  - protocol: invocations
+    version: 1.0.0
+resources:
+  cpu: '0.25'
+  memory: '0.5Gi'

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/main.py

@@ -0,0 +1,74 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+from collections.abc import AsyncGenerator
+
+from agent_framework import Agent, AgentSession
+from agent_framework.foundry import FoundryChatClient
+from azure.ai.agentserver.invocations import InvocationAgentServerHost
+from azure.identity import DefaultAzureCredential
+from dotenv import load_dotenv
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response, StreamingResponse
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+# In-memory session store — keyed by session ID.
+# WARNING: This is lost on restart. Use durable storage in production.
+_sessions: dict[str, AgentSession] = {}
+
+# Create the agent
+client = FoundryChatClient(
+    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+    model=os.environ["MODEL_DEPLOYMENT_NAME"],
+    credential=DefaultAzureCredential(),
+)
+
+agent = Agent(
+    client=client,
+    instructions="You are a friendly assistant. Keep your answers brief.",
+    # History will be managed by the hosting infrastructure, thus there
+    # is no need to store history by the service. Learn more at:
+    # https://developers.openai.com/api/reference/resources/responses/methods/create
+    default_options={"store": False},
+)
+
+app = InvocationAgentServerHost()
+
+
+@app.invoke_handler
+async def handle_invoke(request: Request):
+    """Handle streaming multi-turn chat with Azure OpenAI via SSE."""
+    data = await request.json()
+    session_id = request.state.session_id
+
+    stream = data.get("stream", False)
+    user_message = data.get("message", None)
+    if user_message is None:
+        error = "Missing 'message' in request"
+        if stream:
+            return StreamingResponse(content=error, status_code=400)
+        return Response(content=error, status_code=400)
+
+    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))
+
+    if stream:
+
+        async def stream_response() -> AsyncGenerator[str]:
+            async for update in agent.run(user_message, session=session, stream=True):
+                yield update.text
+
+        return StreamingResponse(
+            stream_response(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+        )
+
+    response = await agent.run([user_message], session=session, stream=stream)
+    return JSONResponse({"response": response.text})
+
+
+if __name__ == "__main__":
+    app.run()

python/samples/04-hosting/foundry-hosted-agents/invocations/02_break_glass/requirements.txt

@@ -0,0 +1,2 @@
+agent-framework
+azure-ai-agentserver-invocations

python/samples/04-hosting/foundry-hosted-agents/invocations/README.md

@@ -0,0 +1,8 @@
+# Hosting agents with Foundry Hosting and the `invocations` API
+
+This folder contains a list of samples that show how to host agents using the `invocations` API and deploy them to Foundry Hosting.
+
+| Sample | Description |
+| --- | --- |
+| [01_basic](./01_basic) | A basic example of hosting an agent with the `invocations` API and carrying on a multi-turn conversation. |
+| [02_break_glass](./02_break_glass) | An example of hosting an agent with the `invocations` API and a "break glass" scenario where you can create your own `invoke_handler` to handle specific types of invocations. |

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/.env.example

@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT="..."
+MODEL_DEPLOYMENT_NAME="..."

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/README.md

@@ -0,0 +1,31 @@
+# Basic example of hosting an agent with the `responses` API
+
+This agent only contains an instruction (personal). It's the most basic agent with an LLM and no tools.
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+## Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "input" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Hi"}'
+```
+
+## Multi-turn conversation
+
+To have a multi-turn conversation with the agent, include the previous response id in the request body. For example:
+
+```bash
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How are you?", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}'
+```

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.manifest.yaml

@@ -0,0 +1,23 @@
+name: agent-framework-agent-basic
+description: >
+  A basic Agent Framework agent hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-basic
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.yaml

@@ -0,0 +1,8 @@
+kind: hosted
+name: agent-framework-agent-basic
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/main.py

@@ -0,0 +1,36 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
+from agent_framework_foundry_hosting import ResponsesHostServer
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+def main():
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    agent = Agent(
+        client=client,
+        instructions="You are a friendly assistant. Keep your answers brief.",
+        # History will be managed by the hosting infrastructure, thus there
+        # is no need to store history by the service. Learn more at:
+        # https://developers.openai.com/api/reference/resources/responses/methods/create
+        default_options={"store": False},
+    )
+
+    server = ResponsesHostServer(agent)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/requirements.txt

@@ -0,0 +1,2 @@
+agent-framework
+agent-framework-foundry-hosting

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/.env.example

@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT="..."
+MODEL_DEPLOYMENT_NAME="..."

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/Dockerfile

@@ -1,11 +1,11 @@
-FROM python:3.14-slim
+FROM python:3.12-slim
 
 WORKDIR /app
 
-COPY ./ .
+COPY . user_agent/
+WORKDIR /app/user_agent
 
-RUN pip install --upgrade pip && \
-    if [ -f requirements.txt ]; then \
+RUN if [ -f requirements.txt ]; then \
         pip install -r requirements.txt; \
     else \
         echo "No requirements.txt found"; \
@@ -13,4 +13,4 @@ RUN pip install --upgrade pip && \
 
 EXPOSE 8088
 
-CMD ["python", "main.py"]
+CMD ["python", "main.py"]

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/README.md

@@ -0,0 +1,27 @@
+# Basic example of hosting an agent with the `responses` API and local tools
+
+This agent is equipped with a function tool and a local shell tool.
+
+> We recommend deploying this sample on a local container or to Foundry Hosting because the agent has access to a local shell tool, which can run arbitrary commands on the machine.
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+## Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "input" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What is the weather in Seattle?"}'
+
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "List the files in the current directory."}'
+```

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/agent.manifest.yaml

@@ -0,0 +1,23 @@
+name: agent-framework-agent-with-local-tools
+description: >
+  An Agent Framework agent with local tools hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-with-local-tools
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/agent.yaml

@@ -0,0 +1,8 @@
+kind: hosted
+name: agent-framework-agent-with-local-tools
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/main.py

@@ -0,0 +1,74 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+import subprocess
+from random import randint
+
+from agent_framework import Agent, tool
+from agent_framework.foundry import FoundryChatClient
+from agent_framework_foundry_hosting import ResponsesHostServer
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import Field
+from typing import Annotated
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+@tool(approval_mode="never_require")
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+@tool(approval_mode="always_require")
+def run_bash(command: str) -> str:
+    """Execute a shell command locally and return stdout, stderr, and exit code."""
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        parts: list[str] = []
+        if result.stdout:
+            parts.append(result.stdout)
+        if result.stderr:
+            parts.append(f"stderr: {result.stderr}")
+        parts.append(f"exit_code: {result.returncode}")
+        return "\n".join(parts)
+    except subprocess.TimeoutExpired:
+        return "Command timed out after 30 seconds"
+    except Exception as e:
+        return f"Error executing command: {e}"
+
+
+def main():
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    agent = Agent(
+        client=client,
+        instructions="You are a friendly assistant. Keep your answers brief.",
+        tools=[get_weather, run_bash],
+        # History will be managed by the hosting infrastructure, thus there
+        # is no need to store history by the service. Learn more at:
+        # https://developers.openai.com/api/reference/resources/responses/methods/create
+        default_options={"store": False},
+    )
+
+    server = ResponsesHostServer(agent)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

python/samples/04-hosting/foundry-hosted-agents/responses/02_local_tools/requirements.txt

@@ -0,0 +1,2 @@
+agent-framework
+agent-framework-foundry-hosting

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/.env.example

@@ -0,0 +1,4 @@
+FOUNDRY_PROJECT_ENDPOINT="..."
+MODEL_DEPLOYMENT_NAME="..."
+TOOLBOX_NAME="..."
+GITHUB_PAT="..."

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/Dockerfile

@@ -1,11 +1,11 @@
-FROM python:3.14-slim
+FROM python:3.12-slim
 
 WORKDIR /app
 
-COPY ./ .
+COPY . user_agent/
+WORKDIR /app/user_agent
 
-RUN pip install --upgrade pip && \
-    if [ -f requirements.txt ]; then \
+RUN if [ -f requirements.txt ]; then \
         pip install -r requirements.txt; \
     else \
         echo "No requirements.txt found"; \
@@ -13,4 +13,4 @@ RUN pip install --upgrade pip && \
 
 EXPOSE 8088
 
-CMD ["python", "main.py"]
+CMD ["python", "main.py"]

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/README.md

@@ -0,0 +1,25 @@
+# Basic example of hosting an agent with the `responses` API and a remote MCP
+
+This agent is equipped with a GitHub MCP server and a Foundry Toolbox, which are both remote MCPs.
+
+> Note that there are other ways to interact with Foundry toolboxes. Using it as a MCP is just one of the options.
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+## Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "input" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "List all the repositories I own on GitHub."}'
+```

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/agent.manifest.yaml

@@ -0,0 +1,27 @@
+name: agent-framework-agent-with-remote-mcp-tools
+description: >
+  An Agent Framework agent with remote MCP tools hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-with-remote-mcp-tools
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+    - name: GITHUB_PAT
+      value: ${GITHUB_PAT}
+    - name: TOOLBOX_NAME
+      value: ${TOOLBOX_NAME}
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/agent.yaml

@@ -0,0 +1,8 @@
+kind: hosted
+name: agent-framework-agent-with-remote-mcp-tools
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/main.py

@@ -0,0 +1,76 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+
+import httpx
+from agent_framework import Agent, MCPStreamableHTTPTool
+from agent_framework.foundry import FoundryChatClient
+from agent_framework_foundry_hosting import ResponsesHostServer
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+class ToolboxAuth(httpx.Auth):
+    """httpx Auth that injects a fresh bearer token on every request."""
+
+    def auth_flow(self, request: httpx.Request):
+        credential = AzureCliCredential()
+        token = credential.get_token("https://ai.azure.com/.default").token
+        request.headers["Authorization"] = f"Bearer {token}"
+        yield request
+
+
+def main():
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    # Foundry Toolbox as a MCP tool
+    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+    toolbox_name = os.environ["TOOLBOX_NAME"]
+    toolbox_endpoint = f"{project_endpoint.rstrip('/')}/toolboxes/{toolbox_name}/mcp?api-version=v1"
+    http_client = httpx.AsyncClient(auth=ToolboxAuth(), headers={"Foundry-Features": "Toolboxes=V1Preview"})
+    foundry_mcp_tool = MCPStreamableHTTPTool(
+        name="toolbox",
+        url=toolbox_endpoint,
+        http_client=http_client,
+        load_prompts=False,
+    )
+
+    # GitHub MCP server
+    github_pat = os.environ["GITHUB_PAT"]
+    if not github_pat:
+        raise ValueError(
+            "GITHUB_PAT environment variable must be set. Create a token at https://github.com/settings/tokens"
+        )
+
+    github_mcp_tool = client.get_mcp_tool(
+        name="GitHub",
+        url="https://api.githubcopilot.com/mcp/",
+        headers={
+            "Authorization": f"Bearer {github_pat}",
+        },
+        approval_mode="never_require",
+    )
+
+    agent = Agent(
+        client=client,
+        instructions="You are a friendly assistant. Keep your answers brief.",
+        tools=[foundry_mcp_tool, github_mcp_tool],
+        # History will be managed by the hosting infrastructure, thus there
+        # is no need to store history by the service. Learn more at:
+        # https://developers.openai.com/api/reference/resources/responses/methods/create
+        default_options={"store": False},
+    )
+
+    server = ResponsesHostServer(agent)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

python/samples/04-hosting/foundry-hosted-agents/responses/03_remote_mcp/requirements.txt

@@ -0,0 +1,2 @@
+agent-framework
+agent-framework-foundry-hosting

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/.env.example

@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT="..."
+MODEL_DEPLOYMENT_NAME="..."

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY . user_agent/
+WORKDIR /app/user_agent
+
+RUN if [ -f requirements.txt ]; then \
+        pip install -r requirements.txt; \
+    else \
+        echo "No requirements.txt found"; \
+    fi
+
+EXPOSE 8088
+
+CMD ["python", "main.py"]

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/README.md

@@ -0,0 +1,23 @@
+# Basic example of hosting an agent with the `responses` API and a workflow
+
+This sample demonstrates how to host a workflow using the `responses` API.
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+## Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "input" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Create a slogan for a new electric SUV that is affordable and fun to drive."}'
+```

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/agent.manifest.yaml

@@ -0,0 +1,23 @@
+name: agent-framework-workflows
+description: >
+  An Agent Framework workflow hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Responses Protocol
+    - Streaming
+template:
+  name: agent-framework-workflows
+  kind: hosted
+  protocols:
+    - protocol: responses
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/agent.yaml

@@ -0,0 +1,8 @@
+kind: hosted
+name: agent-framework-workflows
+protocols:
+  - protocol: responses
+    version: 1.0.0
+resources:
+  cpu: "0.25"
+  memory: 0.5Gi

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/main.py

@@ -0,0 +1,70 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+
+from agent_framework import Agent, AgentExecutor, WorkflowBuilder
+from agent_framework.foundry import FoundryChatClient
+from agent_framework_foundry_hosting import ResponsesHostServer
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+def main():
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    writer_agent = Agent(
+        client=client,
+        instructions=("You are an excellent slogan writer. You create new slogans based on the given topic."),
+        name="writer",
+    )
+
+    legal_agent = Agent(
+        client=client,
+        instructions=(
+            "You are an excellent legal reviewer. "
+            "Make necessary corrections to the slogan so that it is legally compliant."
+        ),
+        name="legal_reviewer",
+    )
+
+    format_agent = Agent(
+        client=client,
+        instructions=(
+            "You are an excellent content formatter. "
+            "You take the slogan and format it in a cool retro style when printing to a terminal."
+        ),
+        name="formatter",
+    )
+
+    # Set the context mode to `last_agent` so that each agent only sees the output of the
+    # previous agent instead of the full conversation history
+    writer_executor = AgentExecutor(writer_agent, context_mode="last_agent")
+    legal_executor = AgentExecutor(legal_agent, context_mode="last_agent")
+    format_executor = AgentExecutor(format_agent, context_mode="last_agent")
+
+    workflow_agent = (
+        WorkflowBuilder(
+            start_executor=writer_executor,
+            # Limiting the output to only the final formatted result.
+            # If this is not set, all intermediate results will be included in the output.
+            output_executors=[format_executor],
+        )
+        .add_edge(writer_executor, legal_executor)
+        .add_edge(legal_executor, format_executor)
+        .build()
+        .as_agent()
+    )
+
+    server = ResponsesHostServer(workflow_agent)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

python/samples/04-hosting/foundry-hosted-agents/responses/04_workflows/requirements.txt

@@ -0,0 +1,2 @@
+agent-framework
+agent-framework-foundry-hosting

python/samples/04-hosting/foundry-hosted-agents/responses/README.md

@@ -0,0 +1,11 @@
+# Hosting agents with Foundry Hosting and the `responses` API
+
+This folder contains a list of samples that show how to host agents using the `responses` API and deploy them to Foundry Hosting.
+
+| Sample | Description |
+| --- | --- |
+| [01_basic](./01_basic) | A basic example of hosting an agent with the `responses` API and carrying on a multi-turn conversation. |
+| [02_local_tools](./02_local_tools) | An example of hosting an agent with the `responses` API and local tools including a function tool and a local shell tool. |
+| [03_remote_mcp](./03_remote_mcp) | An example of hosting an agent with the `responses` API and remote MCPs, including a GitHub MCP server and a Foundry Toolbox. |
+| [04_workflows](./04_workflows) | An example of hosting a workflow with the `responses` API. |
+| [using_deployed_agent.py](./using_deployed_agent.py) | An example of how to use the deployed agent in Agent Framework. |

python/samples/04-hosting/foundry-hosted-agents/responses/using_deployed_agent.py

@@ -0,0 +1,50 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import Agent, AgentResponse, AgentResponseUpdate, ResponseStream
+from agent_framework.openai import OpenAIChatClient
+from typing_extensions import Any
+
+"""
+This script demonstrates how to talk to a deployed agent using the OpenAIChatClient.
+
+Depending on where you have deployed your agent (local or Foundry Hosting), you may
+need to change the base_url when initializing the OpenAIChatClient.
+"""
+
+
+async def print_streaming_response(streaming_response: ResponseStream[AgentResponseUpdate, AgentResponse[Any]]) -> None:
+    async for chunk in streaming_response:
+        if chunk.text:
+            print(chunk.text, end="", flush=True)
+
+
+async def main() -> None:
+    agent = Agent(client=OpenAIChatClient(base_url="http://localhost:8088"))
+    session = agent.create_session()
+
+    # First turn
+    query = "Hi!"
+    print(f"User: {query}")
+    print("Agent: ", end="", flush=True)
+    streaming_response = agent.run(query, session=session, stream=True)
+    await print_streaming_response(streaming_response)
+
+    # Second turn
+    query = "Your name is Javis. What can you do?"
+    print(f"\nUser: {query}")
+    print("Agent: ", end="", flush=True)
+    streaming_response = agent.run(query, session=session, stream=True)
+    await print_streaming_response(streaming_response)
+
+    # Third turn
+    query = "What is your name?"
+    print(f"\nUser: {query}")
+    print("Agent: ", end="", flush=True)
+    streaming_response = agent.run(query, session=session, stream=True)
+    await print_streaming_response(streaming_response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/05-end-to-end/hosted_agents/README.md

@@ -1,145 +0,0 @@
-# Hosted Agent Samples
-
-These samples demonstrate how to build and host AI agents in Python using the [Azure AI AgentServer SDK](https://pypi.org/project/azure-ai-agentserver-agentframework/) together with Microsoft Agent Framework. Each sample runs locally as a hosted agent and includes `Dockerfile` and `agent.yaml` assets for deployment to Microsoft Foundry.
-
-## Samples
-
-| Sample                                                                        | Description                                                                                           |
-| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| [`agent_with_hosted_mcp`](./agent_with_hosted_mcp/)                           | Hosted MCP tool that connects to Microsoft Learn via `https://learn.microsoft.com/api/mcp`            |
-| [`agent_with_text_search_rag`](./agent_with_text_search_rag/)                 | Retrieval-augmented generation using a custom `ContextProvider` with Contoso Outdoors sample data |
-| [`agents_in_workflow`](./agents_in_workflow/)                                 | Concurrent workflow that combines researcher, marketer, and legal specialist agents                   |
-| [`agent_with_local_tools`](./agent_with_local_tools/)                         | Local Python tool execution for Seattle hotel search                                                  |
-| [`writer_reviewer_agents_in_workflow`](./writer_reviewer_agents_in_workflow/) | Writer/Reviewer workflow using `FoundryChatClient`                                                    |
-
-## Common Prerequisites
-
-Before running any sample, ensure you have:
-
-1. Python 3.10 or later
-2. [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed
-3. An Azure OpenAI resource or a Microsoft Foundry project with a chat model deployment
-
-### Authenticate with Azure CLI
-
-All samples rely on Azure credentials. For local development, the simplest approach is Azure CLI authentication:
-
-```powershell
-az login
-az account show
-```
-
-## Running a Sample
-
-Each sample folder contains its own `requirements.txt`. Run commands from the specific sample directory you want to try.
-
-### Recommended: `uv`
-
-The sample dependencies include preview packages, so allow prerelease installs:
-
-```powershell
-cd <sample-directory>
-uv venv .venv
-uv pip install --prerelease=allow -r requirements.txt
-uv run main.py
-```
-
-### Alternative: `venv`
-
-Windows PowerShell:
-
-```powershell
-cd <sample-directory>
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-pip install -r requirements.txt
-python main.py
-```
-
-macOS/Linux:
-
-```bash
-cd <sample-directory>
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python main.py
-```
-
-Each sample starts a hosted agent locally on `http://localhost:8088/`.
-
-## Environment Variable Setup
-
-You can either export variables in your shell or create a local `.env` file in the sample directory.
-
-Example `.env` for Azure OpenAI samples:
-
-```dotenv
-AZURE_OPENAI_ENDPOINT=https://<your-openai-resource>.openai.azure.com/
-AZURE_OPENAI_MODEL=gpt-4.1
-```
-
-Example `.env` for Foundry project samples:
-
-```dotenv
-FOUNDRY_PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
-FOUNDRY_MODEL=gpt-4.1
-```
-
-## Interacting with the Agent
-
-After starting a sample, send requests to the Responses endpoint.
-
-PowerShell:
-
-```powershell
-$body = @{
-		input = "Your question here"
-		stream = $false
-} | ConvertTo-Json
-
-Invoke-RestMethod -Uri "http://localhost:8088/responses" -Method Post -Body $body -ContentType "application/json"
-```
-
-curl:
-
-```bash
-curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
-	-d '{"input":"Your question here","stream":false}'
-```
-
-Example prompts by sample:
-
-| Sample                               | Example input                                                                |
-| ------------------------------------ | ---------------------------------------------------------------------------- |
-| `agent_with_hosted_mcp`              | `What does Microsoft Learn say about managed identities in Azure?`           |
-| `agent_with_text_search_rag`         | `What is Contoso Outdoors' return policy for refunds?`                       |
-| `agents_in_workflow`                 | `Create a launch strategy for a budget-friendly electric SUV.`               |
-| `agent_with_local_tools`             | `Find me Seattle hotels from 2025-03-15 to 2025-03-18 under $200 per night.` |
-| `writer_reviewer_agents_in_workflow` | `Write a slogan for a new affordable electric SUV.`                          |
-
-## Deploying to Microsoft Foundry
-
-Each sample includes a `Dockerfile` and `agent.yaml` for deployment. For deployment steps, follow the hosted agents guidance in Microsoft Foundry:
-
-- [Hosted agents overview](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents)
-- [Create a hosted agent with CLI](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?tabs=cli#create-a-hosted-agent)
-- [Create a hosted agent in Visual Studio Code](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/vs-code-agents-workflow-pro-code?tabs=windows-powershell&pivots=python)
-
-## Troubleshooting
-
-### Missing Azure credentials
-
-If startup fails with authentication errors, run `az login` and verify the selected subscription with `az account show`.
-
-### Preview package install issues
-
-These samples depend on preview packages such as `azure-ai-agentserver-agentframework`. Use `uv pip install --prerelease=allow -r requirements.txt` or `pip install -r requirements.txt`.
-
-### ARM64 container images fail after deployment
-
-If you build images locally on ARM64 hardware such as Apple Silicon, build for `linux/amd64`:
-
-```bash
-docker build --platform=linux/amd64 -t image .
-```

python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/agent.yaml

@@ -1,30 +0,0 @@
-# Unique identifier/name for this agent
-name: agent-with-hosted-mcp
-# Brief description of what this agent does
-description: >
-  An AI agent that uses Azure OpenAI with a Hosted Model Context Protocol (MCP) server.
-  The agent answers questions by searching Microsoft Learn documentation using MCP tools.
-metadata:
-  # Categorization tags for organizing and discovering agents
-  authors:
-    - Microsoft Agent Framework Team
-  tags:
-    - Azure AI AgentServer
-    - Microsoft Agent Framework
-    - Model Context Protocol
-    - MCP
-template:
-  name: agent-with-hosted-mcp
-  # The type of agent - "hosted" for HOBO, "container" for COBO
-  kind: hosted
-  protocols:
-    - protocol: responses
-  environment_variables:
-    - name: AZURE_OPENAI_ENDPOINT
-      value: ${AZURE_OPENAI_ENDPOINT}
-    - name: AZURE_OPENAI_MODEL
-      value: "{{chat}}"
-resources:
-  - kind: model
-    id: gpt-4o-mini
-    name: chat

python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/main.py

@@ -1,34 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-from agent_framework import Agent
-from agent_framework.foundry import FoundryChatClient
-from azure.ai.agentserver.agentframework import from_agent_framework  # pyright: ignore[reportUnknownVariableType]
-from azure.identity import AzureCliCredential
-from dotenv import load_dotenv
-
-# Load environment variables from .env file
-load_dotenv()
-
-
-def main():
-    client = FoundryChatClient(credential=AzureCliCredential())
-
-    # Create MCP tool configuration as dict
-    mcp_tool = client.get_mcp_tool(
-        name="Microsoft_Learn_MCP",
-        url="https://learn.microsoft.com/api/mcp",
-    )
-
-    # Create an Agent using the Azure OpenAI Chat Client with a MCP Tool that connects to Microsoft Learn MCP
-    agent = Agent(
-        client=client,
-        name="DocsAgent",
-        instructions="You are a helpful assistant that can help with microsoft documentation questions.",
-        tools=[mcp_tool],
-    )
-    # Run the agent as a hosted agent
-    from_agent_framework(agent).run()
-
-
-if __name__ == "__main__":
-    main()

python/samples/05-end-to-end/hosted_agents/agent_with_hosted_mcp/requirements.txt

@@ -1,2 +0,0 @@
-azure-ai-agentserver-agentframework==1.0.0b16
-agent-framework

python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/.dockerignore

@@ -1,66 +0,0 @@
-# Virtual environments
-.venv/
-venv/
-env/
-.python-version
-
-# Environment files with secrets
-.env
-.env.*
-*.local
-
-# Python build artifacts
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Testing
-.tox/
-.nox/
-.coverage
-.coverage.*
-htmlcov/
-.pytest_cache/
-.mypy_cache/
-
-# IDE and OS files
-.DS_Store
-.idea/
-.vscode/
-*.swp
-*.swo
-*~
-
-# Foundry config
-.foundry/
-build-source-*/
-
-# Git
-.git/
-.gitignore
-
-# Docker
-.dockerignore
-
-# Documentation
-docs/
-*.md
-!README.md
-LICENSE

python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/.env.sample

@@ -1,3 +0,0 @@
-# IMPORTANT: Never commit .env to version control - add it to .gitignore
-FOUNDRY_PROJECT_ENDPOINT=
-FOUNDRY_MODEL=

python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/README.md

@@ -1,162 +0,0 @@
-**IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
-
-Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
-
-Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
-
-Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
-
-# What this sample demonstrates
-
-This sample demonstrates a **key advantage of code-based hosted agents**:
-
-- **Local Python tool execution** - Run custom Python functions as agent tools
-
-Code-based agents can execute **any Python code** you write. This sample includes a Seattle Hotel Agent with a `get_available_hotels` tool that searches for available hotels based on check-in/check-out dates and budget preferences.
-
-The agent is hosted using the [Azure AI AgentServer SDK](https://pypi.org/project/azure-ai-agentserver-agentframework/) and can be deployed to Microsoft Foundry using the Azure Developer CLI.
-
-## How It Works
-
-### Local Tools Integration
-
-In [main.py](main.py), the agent uses a local Python function (`get_available_hotels`) that simulates a hotel availability API. This demonstrates how code-based agents can execute custom server-side logic that prompt agents cannot access.
-
-The tool accepts:
-
-- **check_in_date** - Check-in date in YYYY-MM-DD format
-- **check_out_date** - Check-out date in YYYY-MM-DD format
-- **max_price** - Maximum price per night in USD (optional, defaults to $500)
-
-### Agent Hosting
-
-The agent is hosted using the [Azure AI AgentServer SDK](https://pypi.org/project/azure-ai-agentserver-agentframework/),
-which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
-
-### Agent Deployment
-
-The hosted agent can be deployed to Microsoft Foundry using the Azure Developer CLI [ai agent](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli#create-a-hosted-agent) extension.
-
-## Running the Agent Locally
-
-### Prerequisites
-
-Before running this sample, ensure you have:
-
-1. **Microsoft Foundry Project**
-   - Project created in [Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-foundry?view=foundry#microsoft-foundry-portals)
-   - Chat model deployed (e.g., `gpt-4o` or `gpt-4.1`)
-   - Note your project endpoint URL and model deployment name
-
-2. **Azure CLI**
-   - Installed and authenticated
-   - Run `az login` and verify with `az account show`
-
-3. **Python 3.10 or higher**
-   - Verify your version: `python --version`
-
-### Environment Variables
-
-Set the following environment variables (matching `agent.yaml`):
-
-- `FOUNDRY_PROJECT_ENDPOINT` - Your Microsoft Foundry project endpoint URL (required)
-- `FOUNDRY_MODEL` - The deployment name for your chat model (defaults to `gpt-4.1-mini`)
-
-This sample loads environment variables from a local `.env` file if present.
-
-Create a `.env` file in this directory with the following content:
-
-```
-FOUNDRY_PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
-FOUNDRY_MODEL=gpt-4.1-mini
-```
-
-Or set them via PowerShell:
-
-```powershell
-# Replace with your actual values
-$env:FOUNDRY_PROJECT_ENDPOINT="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
-$env:FOUNDRY_MODEL="gpt-4.1-mini"
-```
-
-### Running the Sample
-
-**Recommended (`uv`):**
-
-We recommend using [uv](https://docs.astral.sh/uv/) to create and manage the virtual environment for this sample.
-
-```bash
-uv venv .venv
-uv pip install --prerelease=allow -r requirements.txt
-uv run main.py
-```
-
-The sample depends on preview packages, so `--prerelease=allow` is required when installing with `uv`.
-
-**Alternative (`venv`):**
-
-If you do not have `uv` installed, you can use Python's built-in `venv` module instead:
-
-**Windows (PowerShell):**
-
-```powershell
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-pip install -r requirements.txt
-python main.py
-```
-
-**macOS/Linux:**
-
-```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python main.py
-```
-
-This will start the hosted agent locally on `http://localhost:8088/`.
-
-### Interacting with the Agent
-
-**PowerShell (Windows):**
-
-```powershell
-$body = @{
-   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under $200 per night"
-    stream = $false
-} | ConvertTo-Json
-
-Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"
-```
-
-**Bash/curl (Linux/macOS):**
-
-```bash
-curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
-   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'
-```
-
-The agent will use the `get_available_hotels` tool to search for available hotels matching your criteria.
-
-### Deploying the Agent to Microsoft Foundry
-
-To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry&tabs=cli
-
-## Troubleshooting
-
-### Images built on Apple Silicon or other ARM64 machines do not work on our service
-
-We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
-
-If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
-
-**Fix for local builds**
-
-Use this command to build the image locally:
-
-```shell
-docker build --platform=linux/amd64 -t image .
-```
-
-This forces the image to be built for the required `amd64` architecture.

python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/agent.yaml

@@ -1,27 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
-
-kind: hosted
-name: agent-with-local-tools
-# Brief description of what this agent does
-description: >
-  A travel assistant agent that helps users find hotels in Seattle.
-  Demonstrates local Python tool execution - a key advantage of code-based
-  hosted agents over prompt agents.
-metadata:
-  # Categorization tags for organizing and discovering agents
-  authors:
-    - Microsoft
-  tags:
-    - Azure AI AgentServer
-    - Microsoft Agent Framework
-    - Local Tools
-    - Travel Assistant
-    - Hotel Search
-protocols:
-  - protocol: responses
-    version: v1
-environment_variables:
-  - name: FOUNDRY_PROJECT_ENDPOINT
-    value: ${FOUNDRY_PROJECT_ENDPOINT}
-  - name: FOUNDRY_MODEL
-    value: ${FOUNDRY_MODEL}

python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/main.py

@@ -1,144 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-"""
-Seattle Hotel Agent - A simple agent with a tool to find hotels in Seattle.
-Uses Microsoft Agent Framework with Azure AI Foundry.
-Ready for deployment to Foundry Hosted Agent service.
-"""
-
-import asyncio
-import os
-from datetime import datetime
-from typing import Annotated
-
-from agent_framework import Agent
-from agent_framework.foundry import FoundryChatClient
-from azure.ai.agentserver.agentframework import from_agent_framework
-from azure.identity.aio import AzureCliCredential, ManagedIdentityCredential
-
-# Configure these for your Foundry project
-# Read the explicit variables present in the .env file
-FOUNDRY_PROJECT_ENDPOINT = os.getenv("FOUNDRY_PROJECT_ENDPOINT")  # e.g., "https://<project>.services.ai.azure.com"
-FOUNDRY_MODEL = os.getenv("FOUNDRY_MODEL", "gpt-4.1-mini")  # Your model deployment name e.g., "gpt-4.1-mini"
-
-
-# Simulated hotel data for Seattle
-SEATTLE_HOTELS = [
-    {
-        "name": "Contoso Suites",
-        "price_per_night": 189,
-        "rating": 4.5,
-        "location": "Downtown",
-    },
-    {
-        "name": "Fabrikam Residences",
-        "price_per_night": 159,
-        "rating": 4.2,
-        "location": "Pike Place Market",
-    },
-    {
-        "name": "Alpine Ski House",
-        "price_per_night": 249,
-        "rating": 4.7,
-        "location": "Seattle Center",
-    },
-    {
-        "name": "Margie's Travel Lodge",
-        "price_per_night": 219,
-        "rating": 4.4,
-        "location": "Waterfront",
-    },
-    {
-        "name": "Northwind Inn",
-        "price_per_night": 139,
-        "rating": 4.0,
-        "location": "Capitol Hill",
-    },
-    {
-        "name": "Relecloud Hotel",
-        "price_per_night": 99,
-        "rating": 3.8,
-        "location": "University District",
-    },
-]
-
-
-def get_available_hotels(
-    check_in_date: Annotated[str, "Check-in date in YYYY-MM-DD format"],
-    check_out_date: Annotated[str, "Check-out date in YYYY-MM-DD format"],
-    max_price: Annotated[int, "Maximum price per night in USD (optional)"] = 500,
-) -> str:
-    """
-    Get available hotels in Seattle for the specified dates.
-    This simulates a call to a fake hotel availability API.
-    """
-    try:
-        # Parse dates
-        check_in = datetime.strptime(check_in_date, "%Y-%m-%d")
-        check_out = datetime.strptime(check_out_date, "%Y-%m-%d")
-
-        # Validate dates
-        if check_out <= check_in:
-            return "Error: Check-out date must be after check-in date."
-
-        nights = (check_out - check_in).days
-
-        # Filter hotels by price
-        available_hotels = [hotel for hotel in SEATTLE_HOTELS if hotel["price_per_night"] <= max_price]
-
-        if not available_hotels:
-            return f"No hotels found in Seattle within your budget of ${max_price}/night."
-
-        # Build response
-        result = f"Available hotels in Seattle from {check_in_date} to {check_out_date} ({nights} nights):\n\n"
-
-        for hotel in available_hotels:
-            total_cost = hotel["price_per_night"] * nights
-            result += f"**{hotel['name']}**\n"
-            result += f"   Location: {hotel['location']}\n"
-            result += f"   Rating: {hotel['rating']}/5\n"
-            result += f"   ${hotel['price_per_night']}/night (Total: ${total_cost})\n\n"
-
-        return result
-
-    except ValueError as e:
-        return f"Error parsing dates. Please use YYYY-MM-DD format. Details: {str(e)}"
-
-
-def get_credential():
-    """Will use Managed Identity when running in Azure, otherwise falls back to Azure CLI Credential."""
-    return ManagedIdentityCredential() if os.getenv("MSI_ENDPOINT") else AzureCliCredential()
-
-
-async def main():
-    """Main function to run the agent as a web server."""
-    async with get_credential() as credential:
-        client = FoundryChatClient(
-            project_endpoint=FOUNDRY_PROJECT_ENDPOINT,
-            model=FOUNDRY_MODEL,
-            credential=credential,
-        )
-        agent = Agent(
-            client=client,
-            name="SeattleHotelAgent",
-            instructions="""You are a helpful travel assistant specializing in finding hotels in Seattle, Washington.
-
-When a user asks about hotels in Seattle:
-1. Ask for their check-in and check-out dates if not provided
-2. Ask about their budget preferences if not mentioned
-3. Use the get_available_hotels tool to find available options
-4. Present the results in a friendly, informative way
-5. Offer to help with additional questions about the hotels or Seattle
-
-Be conversational and helpful. If users ask about things outside of Seattle hotels,
-politely let them know you specialize in Seattle hotel recommendations.""",
-            tools=[get_available_hotels],
-        )
-
-        print("Seattle Hotel Agent Server running on http://localhost:8088")
-        server = from_agent_framework(agent)
-        await server.run_async()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

python/samples/05-end-to-end/hosted_agents/agent_with_local_tools/requirements.txt

@@ -1,2 +0,0 @@
-azure-ai-agentserver-agentframework==1.0.0b16
-agent-framework-foundry

python/samples/05-end-to-end/hosted_agents/agent_with_text_search_rag/agent.yaml

@@ -1,33 +0,0 @@
-# Unique identifier/name for this agent
-name: agent-with-text-search-rag
-# Brief description of what this agent does
-description: >
-  An AI agent that uses a ContextProvider for retrieval augmented generation (RAG) capabilities.
-  The agent runs searches against an external knowledge base before each model invocation and
-  injects the results into the model context. It can answer questions about Contoso Outdoors
-  policies and products, including return policies, refunds, shipping options, and product care
-  instructions such as tent maintenance.
-metadata:
-  # Categorization tags for organizing and discovering agents
-  authors:
-    - Microsoft Agent Framework Team
-  tags:
-    - Azure AI AgentServer
-    - Microsoft Agent Framework
-    - Retrieval-Augmented Generation
-    - RAG
-template:
-  name: agent-with-text-search-rag
-  # The type of agent - "hosted" for HOBO, "container" for COBO
-  kind: hosted
-  protocols:
-    - protocol: responses
-  environment_variables:
-    - name: AZURE_OPENAI_ENDPOINT
-      value: ${AZURE_OPENAI_ENDPOINT}
-    - name: AZURE_OPENAI_MODEL
-      value: "{{chat}}"
-resources:
-  - kind: model
-    id: gpt-4o-mini
-    name: chat