.Net: [WIP] Add Foundry Toolbox Support to Hosted Agents

[rogerbarreto]

Summary

Adds Foundry Toolbox (MCP proxy) integration to AgentFrameworkResponseHandler in Microsoft.Agents.AI.Foundry, supporting both host-configured (eager, startup) and client-selectable (per-request, lazy) toolbox injection.

What this adds

Phase 1 — Host-configured toolboxes (eager)

• Eager initialization via IHostedService — MCP clients connect and discover tools at startup, gating the readiness probe (spec §3.1)
• Tool injection — discovered MCP tools are added to ChatOptions.Tools on every request
• OAuth consent interception — JSON-RPC error -32006 returned by the Foundry proxy is caught by a per-tool AIFunction wrapper, stored in AsyncLocal shared state, and propagated back to the handler which emits mcp_approval_request + incomplete SSE events
• Retry/backoff — FoundryToolboxBearerTokenHandler retries up to 3x with exponential backoff on 429/5xx (spec §7)
• Graceful degradation — when FOUNDRY_AGENT_TOOLSET_ENDPOINT is absent the container starts healthy with no tools (spec §2)

Phase 2 — Client-selectable toolboxes (per-request)

• HostedMcpToolboxAITool — new public (experimental) marker type subclassing HostedMcpServerTool. Rides the OpenAI Responses mcp wire format using a synthetic foundry-toolbox://<name>?version=<v> URI so toolbox selection survives client → server serialization without a new wire type.
• FoundryAITool.CreateHostedMcpToolbox(...) — factory overloads so consumers can attach a toolbox marker from (a) a plain name [+ version], (b) a ToolboxRecord (uses Name + DefaultVersion), or (c) a specific ToolboxVersion (uses Name + Version) retrieved from AIProjectClient.
• Per-request parsing & merge — handler parses marker tools from the incoming request, resolves them via FoundryToolboxService, and merges with any host-configured toolbox tools. Markers are deduped by name per request.
• Lazy toolbox open — toolboxes requested by the client that weren't pre-registered are opened on demand and cached (double-checked SemaphoreSlim). Cached toolboxes are reused across requests.
• StrictMode option (default true) — when a client-requested toolbox fails to resolve, the handler emits a failed response with a clear error. Set StrictMode = false to silently skip unresolvable toolboxes.

Files changed

New

• HostedMcpToolboxAITool.cs — marker tool, UriScheme = "foundry-toolbox", BuildAddress/TryParseToolboxAddress
• FoundryToolboxOptions.cs — toolbox name list, API version, StrictMode
• FoundryToolboxBearerTokenHandler.cs — DelegatingHandler: Bearer token, Foundry-Features header, 3x backoff
• McpConsentContext.cs — AsyncLocal per-request consent state
• ConsentAwareMcpClientAIFunction.cs — AIFunction wrapper catching -32006, cancels linked CTS to escape FunctionInvokingChatClient tool loop
• FoundryToolboxService.cs — IHostedService + IAsyncDisposable: eager MCP client per toolbox at startup, plus GetToolboxToolsAsync(name, version?, ct) for lazy open
• InputConverter.ReadMcpToolboxMarkers — parses MCPTool entries with the foundry-toolbox:// scheme
• Unit tests: HostedMcpToolboxAIToolTests, Hosting/FoundryToolboxServiceTests
• Hosted-Toolbox/ sample — minimal hosted agent using AddFoundryToolboxes

Modified

• AgentFrameworkResponseHandler.cs — per-request marker parse + merge, linked CTS consent path, mcp_approval_request emission, EmitFailed on strict-mode resolution failures
• FoundryAITool.cs — CreateHostedMcpToolbox(string, string?), CreateHostedMcpToolbox(ToolboxRecord), CreateHostedMcpToolbox(ToolboxVersion) factories
• ServiceCollectionExtensions.cs — AddFoundryToolboxes(params string[]) and AddFoundryToolboxes(configureOptions, params string[]) overloads
• Microsoft.Agents.AI.Foundry.csproj — ModelContextProtocol + Azure.Identity under .NETCoreApp condition

Usage

Host configured (eager at startup):

builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes("my-toolbox", "another-toolbox");

Client selected (per request) — discover via AIProjectClient:

// Discover a toolbox via the Foundry project
var project = new AIProjectClient(endpoint, credential);
ToolboxRecord toolbox = await project.GetAgentToolboxesClient().GetToolboxAsync("calendar-tools");

// Attach as a per-request tool (uses record.Name + record.DefaultVersion)
var response = await agent.RunAsync(
    "Book a meeting with the team next Tuesday.",
    new ChatClientAgentRunOptions
    {
        ChatOptions = new() { Tools = [FoundryAITool.CreateHostedMcpToolbox(toolbox)] }
    });

// Or pin a specific version
ToolboxVersion version = await project.GetAgentToolboxesClient().GetToolboxVersionAsync("calendar-tools", "v2");
var toolWithVersion = FoundryAITool.CreateHostedMcpToolbox(version);

// Or pass the name/version explicitly
var toolByName = FoundryAITool.CreateHostedMcpToolbox("calendar-tools", version: "v2");

Combined — host-configured toolboxes are always injected; client markers additionally lazy-open any toolbox the server hasn't pre-registered.

Environment variables

Variable	Required	Description
FOUNDRY_AGENT_TOOLSET_ENDPOINT	No (absent = healthy, no tools)	Foundry Toolsets proxy base URL
FOUNDRY_AGENT_TOOLSET_FEATURES	No	Feature flags sent via Foundry-Features header
FOUNDRY_AGENT_NAME	No	MCP client info name (default: hosted-agent)
FOUNDRY_AGENT_VERSION	No	MCP client info version (default: 1.0.0)

WIP — needs integration testing against a live Foundry Toolsets proxy.