Add Mastering Toolboxes in Microsoft Foundry recipe#52
Open
lindazqli wants to merge 21 commits into
Open
Conversation
End-to-end notebook covering every Foundry tool type, identity/auth, Tool Search, versioning, governance, and consuming a toolbox from Agent Framework, LangGraph, and the Copilot SDK. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
🔍 PreviewA live preview of this PR is available at: |
- Rewrite intro thesis to lead with the problem/pattern, not a product definition - Replace 8-item feature list with 4 action-verb learning objectives; map them in the conclusion - Reframe as a reference walkthrough with an explicit runnable core spine; tag catalog/reference sections - Add a Failure modes section (symptom / cause / fix) - Bump azure-ai-projects floor to >=2.2.0 (preview tool classes require it) Executed cell outputs still need to be captured against a live Foundry project. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
SDK 2.3.0 relocates project.beta.toolboxes to project.toolboxes and switches create_version to require the *ToolboxTool classes (Tool -> ToolboxTool), renaming ToolboxSearchPreviewTool. The notebook is written for the 2.2.0 API, so cap the floor-only range in requirements.txt and the inline %pip install. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
2.3.0 relocates the operation group from project.beta.toolboxes to project.toolboxes and switches create_version from the agent Tool classes to the dedicated *ToolboxTool family. Swap every tool class (WebSearchTool -> WebSearchToolboxTool, MCPTool -> MCPToolboxTool, ToolboxSearchPreviewTool -> ToolboxSearchPreviewToolboxTool, etc.), update the operation path, and pin requirements + inline %pip to >=2.3.0,<2.4.0. Helper types, field names, wire shapes, and api-version=v1 are unchanged between 2.2.0 and 2.3.0; all 26 imported model symbols verified present and every tool validated to construct and serialize against 2.3.0. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Executed the full notebook end-to-end against a live Foundry project on azure-ai-projects 2.3.0 and fixed every issue that surfaced: - Cell 38: drop invalid *: ToolConfig(pin=False) - the service rejects any explicit pin=False (toolbox_search_preview is always pinned). Omit a tool to leave it search-gated instead. - Cell 36 (declarative REST): give every tool a unique ame - the service requires all-but-one tool to carry an identifier (name/server_label). - Cell 48 (Microsoft Agent Framework): update to MAF 1.10 API (ChatAgent->Agent, AzureAIAgentClient->foundry.FoundryChatClient, still MCPStreamableHTTPTool). Authenticate the MCP initialize handshake via a pre-authenticated http_client (header_provider only injects on tool calls), and build FoundryChatClient from project_endpoint+credential (the project_client= path is incompatible with the 2.3.0 preview). - Cell 49 (LangGraph): pass project_endpoint+credential explicitly to AzureAIProjectToolbox and AzureAIChatCompletionsModel; add langchain-mcp-adapters (cell 2 pip + requirements.txt). All cells now carry real executed outputs (0 error cells), including live MAF and LangGraph agent responses over the toolbox MCP endpoint. Cleanup verified: no toolboxes left behind. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Work IQ runs as the signed-in user (delegated/OBO auth), so its oauth2 connection must be backed by a per-tenant Entra app registration with the WorkIQAgent.Ask delegated permission and admin consent. Replace the generic azd connection snippet with the authoritative step-by-step (app registration, OAuth field values, redirect URI, and the one-time tenant enablement) from the public Microsoft Learn docs, and note the runtime failures (TokenAudience is required for OBO / agent-card 404) that result when the app isn't configured. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Validated the Work IQ guidance against the primary Foundry how-to page. The WorkIQPreviewToolboxTool connects over Agent-to-Agent (A2A), not the 'Work IQ MCP' catalog surface: the connection is authType OAuth2 / category RemoteA2A targeting https://workiq.svc.cloud.microsoft/a2a/. Reframe the section around A2A+OBO (matching the runtime 'agent card 404' error), switch to Settings > Connections > New connection > Work IQ, add single-tenant + 'APIs my organization uses' registration specifics, VNet-not-supported prereq, and the ARM REST alternative. OAuth field table, scopes, redirect URI, and az ad sp create appId all verified verbatim against the docs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Corrected doc-contradicted service facts across the notebook after validating every prose claim against Microsoft Learn: - Connection categories: RemoteTool_Preview does not exist. MCP/Fabric IQ use RemoteTool; A2A/Work IQ use RemoteA2A; AI Search uses CognitiveSearch (cell 6, plus azd --kind remote-a2a). - Fabric IQ auth: requires delegated user auth (oauth2 / user-entra-token OBO); application-only project-managed-identity is not supported (cells 5, 27). - Web Search (Bing Custom Search) auth is api-key, not custom-keys (cells 5, 11). - OpenAPI auth table now includes anonymous (none) (cell 5). - Browser Automation: powered by Playwright Workspaces (not Azure Playwright Testing); connection kind PlaywrightWorkspace, auth api-key (cells 5, 29). - Skills are behavioral SKILL.md instructions only (no packaged tools); no default=True on skills.create - default promotion is a separate step (cells 31, 32). - Unnamed-tool rule is per built-in type, not one per toolbox (cells 8, 36, 55). - CONSENT_REQUIRED code aligned to documented -32006 (cells 5, 45). - user-entra-token relabeled 'managed user identity passthrough' (OBO), not 'Foundry managed identity passthrough' (cells 5, 17). - ImportError troubleshooting pinned to azure-ai-projects 2.3.0 (cell 55). SDK-introspection (azure-ai-projects 2.3.0) confirmed base_url, agent_card_path, MCPToolFilter(read_only), MCPToolRequireApproval, and create_version(metadata=) are real SDK params, so those claims were kept despite docs omitting them. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Rework the opening architecture section (cell 0 + the Mermaid diagram) to mirror the canonical model on the Foundry toolbox how-to page: - Replace the invented 'four pillars' (One endpoint / Identity / Tool Search / Governed) with the doc's tool-lifecycle framing: four pillars with Build and Consume available today, each described in the doc's own terms (select tools + configure auth centrally; connect any agent to one MCP-compatible endpoint). - Add the doc's managed-resource + versioning promise (reconfigure without code changes; promote a version to default and every consumer picks it up). - Diagram: label the endpoint 'MCP-compatible'; drop the APIM / Azure Policy callouts from the governed-by-default node (not part of the toolbox docs) in favor of the doc's runtime governance (identity, credential injection, token refresh, policy enforcement); trim the Consume surface to the three clients the notebook actually demonstrates (Microsoft Agent Framework, LangGraph, Copilot SDK). - Regenerate 01-toolbox-architecture.svg from the updated .mmd source. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Policy enforcement (section 8 + diagram): the customer-owned APIM runtime gateway governs *only MCP-server tools* - calls that route through your MCP server. Built-in / first-party tools (Web Search, Code Interpreter, File Search, Azure AI Search, ...) never traverse the gateway. Added a bypass branch to the diagram, scoped the RT subgraph label, and updated the table row, blockquote, and alt text (also noting the RAI guardrail screens every tool, unlike APIM). Auth & identity (section 3 + diagram): added a 'Two identities, better together' explanation of the hosted-agent story - the agent authenticates to the toolbox with its own agent managed identity (the trust boundary, Foundry user role), yet for oauth2 / user-entra-token connections it forwards the caller's end-user token so the downstream tool acts as the real user (OBO), with no OAuth wiring in agent code. Diagram now labels the two hops (agent->toolbox, toolbox->tool), adds a better-together callout, and fixes the user-entra-token label to 'managed user identity passthrough'. Regenerated 02-auth-identity.svg and 04-policy-enforcement.svg from source. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The previous revision showed built-in / first-party tools as a dead-end
('never traverse your gateway'), which wrongly implied they were ungoverned.
Built-in tools skip only the customer-owned APIM gateway (control point 2);
the RAI guardrail (control point 3) still screens every tool's inputs and
outputs at the toolbox layer. Route both MCP-server and built-in tools into
the guardrail in the diagram, relabel it 'Toolbox guardrail (all tools)', and
update the alt text and RAI table row so bypassing the gateway never reads as
bypassing content governance.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace the hand-drawn Mermaid architecture diagram with the exact toolbox-architecture.png published in the Foundry toolbox docs (Build / Consume pillars, consumed by LangGraph, Microsoft Agent Framework, GitHub Copilot, Claude Code, and Microsoft Copilot Studio, governed by default). Update cell 0's image reference and alt text to match the doc verbatim, and drop the now-unused 01-toolbox-architecture.mmd/.svg. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Drop the explicit 'built-in tools bypass the gateway' call-out from the policy-enforcement diagram and its prose. The diagram now states only what is governed: the runtime gateway governs MCP-server tools, and the toolbox guardrail governs all tools. Remove the enumerated built-in-tools bypass node and soften the alt text, RAI table row, and blockquote so they no longer frame governance in terms of what skips the gateway. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The Skills section only covered build-time references (ToolboxSkillReference in the skills= list). Explain that once attached, a skill is not a callable tool - it surfaces as an MCP Resource on the same toolbox endpoint (Skills-for-MCP SEP-2640): any MCP client calls resources/list to discover skills and resources/read to download each SKILL.md body, with no Foundry SDK. Add section 10b with a runnable, skip-guarded consume_skills() that reuses the existing raw MCP session to list and read skill resources over the consumer endpoint. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Tool search ranks the toolbox's own un-pinned tools (pinned/auto-pinned tools are already in tools/list), not a Foundry-wide catalog. Fix the wording in the 03-tool-search-flow diagram and cells 37/38/45. Add the discover/progressive- disclosure framing to the intro so the Consume pillar's dynamic discovery is tied to Tool Search. Point the Skills section and section 10b at the official 'Attach skills to a toolbox' doc and the MAF Skills-in-Toolbox sample. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Drop the 'four pillars, two available today' Build/Consume framing. Present the three pillars that are available now: (1) Build & curate, (2) Discover with Tool Search (progressive disclosure), and (3) Govern with an RAI guardrail plus a bring-your-own AI gateway for MCP - governed by default, with more governance controls to come. Make Discover a first-class pillar and align the 'By the end' outcomes to Build & curate / Discover / Govern / Consume. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace the official Build/Consume doc PNG with a custom Mermaid diagram that matches the three-pillar intro exactly: (1) Build & curate feeds the toolbox default version, which holds the curated tools plus (2) Discover with Tool Search and (3) Govern (RAI guardrail over all tools + BYO AI gateway for MCP, more to come); the toolbox is exposed through one MCP-compatible endpoint and consumed unchanged by Microsoft Agent Framework, LangGraph, and the Copilot SDK. Update cell 0's image reference and alt text accordingly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep the official left-to-right structure (Build & curate -> Toolbox -> Consume, governed by default) and add a single Discover with Tool Search box in the middle toolbox column. Govern stays as the toolbox's governed-by-default treatment rather than a separate box. Update cell 0 alt text to match. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ddle Recreate the public doc's layout as a custom diagram: a Toolboxes in Foundry title banner, a Consumed by row (LangGraph, Microsoft Agent Framework, GitHub Copilot, Claude Code, Microsoft Copilot Studio), a Tool lifecycle arrow over the pillars, and a Governed by default banner. Add a single Discover pillar (Tool Search) between Build and Consume. Update cell 0 alt text to match. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace the Mermaid render with a hand-authored SVG that mirrors the public doc's exact look: full-width rounded Toolboxes in Foundry title banner, a Consumed by chip row, a Tool lifecycle arrow, three green pillars with pink / blue / orange inner pills, and a full-width Governed by default banner with the same caption. The only addition is the Discover (Tool Search) pillar in the middle. Remove the now-unused .mmd source since the SVG is authored directly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mastering Toolboxes in Microsoft Foundry
Adds a new end-to-end recipe notebook modeled on the existing Foundry IQ recipe.
What it covers
what it is / how it works / supported parameters: Web Search, Code Interpreter (Files API upload + generated-file download), File Search (vector stores), MCP, Azure AI Search, OpenAPI, A2A, Work IQ, Fabric IQ, Browser Automation, SkillsNotes
azure-ai-projects2.2.0 SDK and verified Microsoft Learn docs