Foundry Toolboxes and User Delegation: Auth-Free Agents That Act on Your Behalf

By Jeff | SMF Works | July 23, 2026

The moment the agent stops answering and starts acting

Most agent demos die the same way: the model is fine, the tools work in Postman, and then someone asks—whose identity is this call using?

An internal employee agent that can summarize mail, check calendar, and hit a private orders MCP server cannot run as a shared service principal if you care about Microsoft 365 permissions, sensitivity labels, or per-user audit. It has to act as the signed-in user. That means On-Behalf-Of (OBO) token exchange, per-user token isolation, consent, refresh, and retries—for every tool, in every agent.

On July 22, 2026, Linda and Maria on the Microsoft Foundry Blog published Building Agents that Act on Your Behalf with Toolboxes in Foundry. The post is short and sharp: put auth on the toolbox connection, not in agent code; let Foundry acquire, exchange, and refresh tokens server-side; expose one versioned MCP endpoint that any compatible harness can consume. Combined with the Microsoft Learn guide Create, test, and deploy a toolbox in Foundry and the Hosted Agents / Work IQ docs, that is enough surface for a full production deep dive.

This Clearinghouse article is the field guide: why DIY user delegation fails at scale, how Toolboxes collapse that surface, the auth matrix, endpoints, approvals, and a concrete hosted-agent build path.

Why DIY user delegation burns weeks

The July 22 post walks a realistic employee-agent scenario: private Entra-protected MCP for orders plus Microsoft’s managed Work IQ surface for Microsoft 365 context. Both require user delegation. Building that yourself usually means three infrastructure classes before domain logic:

Failure mode	What goes wrong in practice
Token isolation	Cache keys must partition by user and tenant. A wrong key silently leases User A’s downstream access to User B.
Consent and refresh	Every API has its own consent failure shape, refresh path, and retry semantics.
Duplication across agents	Each new tool adds scopes, exchange paths, headers, and brokers. Hundreds of tools × many agents becomes a second product.

That is an identity and tool lifecycle problem. Enterprises already own gateways, vaults, and policy engines. What was missing was a developer experience that packages those controls into something reusable, discoverable, and governed by default.

What a Foundry Toolbox is

Per Microsoft Learn, a toolbox is a curated, centrally managed set of tools exposed through a single MCP-compatible endpoint. Agents do not embed credentials. They connect to the endpoint; Foundry injects credentials, refreshes tokens, and enforces policy at runtime.

Build and Consume are available today:

Pillar	Status	What it enables
Build	Available	Select tools, configure authentication centrally, publish a reusable toolbox.
Consume	Available	Any MCP-compatible agent runtime, IDE, or custom client discovers and invokes tools through one endpoint.

Operational properties that matter in production:

Single stable consumer URL — agents keep one endpoint; tools behind it can change.
Versioning — create and test a new version, then promote it to default_version without redeploying agents.
Open consumption — Microsoft Agent Framework, LangGraph, Copilot SDK, hosted agents, and custom MCP clients share the contract.
Hosted-agent guidance — Learn’s Hosted Agents page is explicit: do not add tools directly on the hosted agent definition; use toolboxes via MCP clients.

Hosted agents bring your container, Entra agent identity, sandbox, and protocols (Responses, Invocations, A2A). Toolboxes bring the tool plane. Keep those planes separate.

Three steps: connection → toolbox version → agent

Step 1 — Put auth on the connection (never in agent code)

Auth type is chosen when the project connection is created—portal, azd, or REST. For end-user delegation, the Foundry Blog shows OAuth2 on a remote-tool connection:

azd ai connection create <name-of-connection> \
  --kind remote-tool --target <tool-endpoint> \
  --auth-type oauth2 \
  --authorization-url <auth-url> \
  --token-url <token-url> \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "<scope1> <scope2>"

The unified Foundry azd extension documents a broader --auth-type set, including none, custom-keys, api-key, oauth2, user-entra-token, project-managed-identity, and agentic-identity. Connections hold secrets; toolbox YAML/SDK references connections by name.

Step 2 — Build the toolbox once

The July 22 sample composes a private MCP tool and Work IQ behind one version:

version = project.toolboxes.create_version(
    name="employee-toolbox",
    description="Private orders MCP and Work IQ connected via user delegation auth",
    tools=[
        MCPToolboxTool(
            server_label="orders",
            server_url="https://orders-mcp.example.com/mcp",
            require_approval="never",
            project_connection_id="orders-mcp",
        ),
        WorkIQPreviewToolboxTool(
            name="work_iq",
            description="Reason over the caller's M365 mail, chats, meetings, docs.",
            project_connection_id="workiq-conn",
        ),
    ],
)

Learn’s Python path uses AIProjectClient and create_toolbox_version with typed tools (MCPTool, WebSearchTool, ToolboxSearchPreviewTool, and peers). Same idea: tools are declarations + connection IDs, not runtime secret loaders.

Step 3 — Consume from a hosted agent (auth-free agent code)

PROJECT_ENDPOINT = "<project-endpoint>"
CONSUMER_URL = f"{PROJECT_ENDPOINT}/toolboxes/employee-toolbox/mcp?api-version=v1"
toolbox = MCPStreamableHTTPTool(
    name="employee_toolbox",
    url=CONSUMER_URL,
)
agent = Agent(
    client=FoundryChatClient(project_endpoint=PROJECT_ENDPOINT, credential=credential),
    tools=[toolbox],
)

One user request can fan out to both the private MCP and Work IQ on the end user’s behalf. Adding a third tool is a new connection plus one toolbox line—the agent binary does not change.

Official samples walk Agent Framework and LangGraph consumption in one place:
https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox-user-identity

Auth matrix: whose identity reaches the tool?

The July 22 post’s table is the control surface every platform team should pin:

Auth type	Whose identity reaches the tool	Use it for
agentic-identity	The agent’s own Entra identity	Service-to-service with per-agent audit
project-managed-identity	The project’s managed identity	Service-to-service without user context
oauth2	The end user (delegation, consent-once)	Work IQ, GitHub, and other user-context tools
custom-keys	A stored API key/header	Key-based SaaS; agent never sees the secret
none	Anonymous	Public servers (for example Microsoft Learn MCP)

Hosted Agents docs reinforce the dual-mode story at the runtime boundary:

User-invoked / interactive — when a user token is present, the platform supports OAuth 2.0 OBO so downstream calls can use the user’s delegated permissions under tenant policy.
Autonomous / background — without a user token, the agent uses its dedicated Entra agent identity.

Toolboxes let you choose per tool which path applies, instead of forcing one identity model on the whole agent.

Work IQ specifics (preview)

Work IQ is the intelligence layer that grounds agents in real-time Microsoft 365 context (mail, meetings, files, chats) with semantic understanding, honoring M365 permissions. In Foundry it is typically reached via A2A as a peer agent; authentication uses OBO so requests run as the signed-in user. Learn notes that Bring your own Entra app (OBO) is the supported path for Work IQ connections, and that callers need appropriate Microsoft 365 Copilot licensing. Treat Work IQ as a delegation-class tool: put it behind oauth2 / user Entra token connections, not a shared app-only key.

Consumer endpoint vs developer endpoint

Learn documents two MCP URL patterns:

Endpoint role	Behavior	When to use
Consumer	Always serves `default_version`	Production agents; promote versions without redeploy
Developer / version-specific	Pins an explicit toolbox version	Pre-promotion testing and canaries

Tip from Learn: connect agents to the consumer endpoint in production. Reserve version-specific URLs for validation. The first version of a new toolbox is auto-promoted to default; later promotions are an explicit platform operation.

That pairs cleanly with Hosted Agents lifecycle: you can ship a new toolbox version, validate on a developer URL from a non-prod agent, then promote—without rebuilding containers.

Tool Search, skills, and the tool catalog problem

As toolboxes grow, stuffing every tool into the model context fails. Foundry’s Tool Search (toolbox_search_preview) supports intent-based routing: the agent discovers tools dynamically instead of loading the entire catalog every turn. Learn’s feature matrix marks Tool Search available across Python, REST, .NET, JavaScript, azd, and Foundry Toolkit.

Toolbox versions can also attach skill references (project skills as MCP resources), and can mix first-party tools: Web Search, Azure AI Search, Code Interpreter, File Search, OpenAPI, A2A, Fabric IQ, Browser Automation, and Work IQ (subject to region/model compatibility).

Practical rule: every tool gets a clear description; MCP tools use server_label namespacing ({server_label}.{tool_name}); unnamed duplicates of the same built-in type are rejected—name instances when you need more than one.

Governance at the boundary: approvals, RAI, gateways

Because Foundry sits on the tool call path, policy can live outside agent code.

`require_approval`

Toolbox MCP tools/list responses include _meta.tool_configuration.require_approval:

Value	Expected agent behavior
`"always"`	Confirm with the user before every invocation
`"never"`	Invoke freely

Critical detail from Learn: the MCP endpoint does not block tools/call for you. Enforcement is the agent runtime’s job. Production harnesses should build an approval map at startup from tools/list and constrain the loop (and system prompt) accordingly. That matches the Agent Framework harness model of standing approval policy—toolbox metadata is the catalog; the harness is the enforcer.

RAI guardrails

Apply a guardrail (RAI policy) to a toolbox version so inputs and outputs are screened at the tool boundary. The Foundry Blog calls out the high-value case: untrusted MCP content should not smuggle prompt-injection back into the agent unfiltered.

Bring-your-own gateway

Front MCP servers with a gateway (for example Azure API Management) for rate limits, logging, and network policy. That complements—not replaces—the Foundry AI Gateway control plane story for model traffic. Tools and models both need governed edges; Toolboxes are the tool edge.

RBAC triad

Learn’s prerequisites are the identity checklist:

Developer — Foundry User (create/manage toolbox versions).
Agent identity — Foundry User when a hosted agent calls tools at runtime.
End user — Foundry User when OAuth / UserEntraToken flows proxy that user.

Miss any leg and “it works in my tenant admin account” becomes “it fails for everyone else.”

Production build path

Foundry project in a supported region; check tool-type region/model compatibility.
Connections — oauth2 / user-entra-token for user-context tools; agentic- or project-managed-identity for service paths; custom-keys for SaaS. No secrets in agent images.
Toolbox v1 — descriptions, Tool Search if the catalog grows, require_approval on high-blast tools.
Validate on the developer MCP URL (tools/list, approval meta, one live call per auth class).
Hosted agent → consumer MCP URL via MCPStreamableHTTPTool (or equivalent). Prefer Responses for chat agents.
RBAC for developer, agent identity, and OAuth end users; RAI on the toolbox version; APIM in front of untrusted MCP.
Promote after canary; leave consumer URL and agent code unchanged.
Observe via Application Insights agents view + Azure Monitor; review Work IQ / third-party data-boundary and M365 Copilot license needs.

How this fits the July Foundry stack

Toolboxes are the tool plane next to the rest of the month’s surface:

Capability	Role next to Toolboxes
Hosted Agents	Runtime + agent identity; tools via toolbox MCP, not inline definition
Agent Framework harness (2026-07-22)	Loop, approvals, OTel—consume toolbox as MCP tools
AI Gateway control plane (2026-07-20)	Model TPM/routing via APIM; toolbox + APIM-fronted MCP for tools
Agent Optimizer (2026-07-18)	Closed-loop quality once tools are stable
Work IQ / Foundry IQ	M365 grounding and knowledge under governed tool patterns

If last week’s question was “how do we run the loop?”, this week’s is “how do we call enterprise tools as the right principal without rewriting every agent?” Toolboxes are Microsoft’s answer.

What to do this week

Pick one agent that needs user context (mail, calendar, or private Entra MCP).
Move tools into a toolbox with oauth2 / user-entra-token connections—agent code stays auth-free.
Point non-prod at the developer MCP URL; verify isolation with two test users.
Promote to consumer default only after approval maps and RAI are in place; add Tool Search before the catalog bloats the prompt.

Primary sources:

Bottom line

Production agents that act need identity discipline as much as model quality. Foundry Toolboxes move OAuth, OBO, token isolation, and consent onto a versioned MCP control plane, so hosted agents and open harnesses stay auth-free while still calling private MCP servers and Work IQ as the signed-in user. Build connections once, version the toolbox, enforce approvals and RAI at the boundary, and promote without redeploying agents.

That is how you scale from a working demo to an enterprise tool fabric—inside the Microsoft Foundry ecosystem, with identity you can audit.