Tao Chen
d74d26c917
* Show more authentication methods in Foundry Toolbox MCP * Remove hardcoded toolbox version num * Add Foundry MCP OAuth consent handling * Use message instead of the dedicated item type * Go back to using OAuthConsentRequestOutputItem * WIP: sample testing * Update error code * Address review on Foundry Toolbox MCP samples Reviewed feedback addressed: - Drop the branch-pinned `git+https://...@feature/...` entries from `04_foundry_toolbox/requirements.txt`; restore the simple comment + `mcp` runtime dep. The git pins were only useful while iterating on the PR and shouldn't ship. (eavanvalkenburg) - Fix the `/toolsets/` typo in both `04_foundry_toolbox/README.md` and `06_files/README.md`. Verified empirically against the research_toolbox in the test workspace: the toolbox MCP gateway lives at `/toolboxes/{name}/mcp?api-version=v1` and requires the `Foundry-Features: Toolboxes=V1Preview` header. `/toolsets/{name}/mcp` returns 403 with `preview_feature_required: Toolsets=V1Preview` (a different opt-in feature). - Wrap `httpx.AsyncClient(...)` in `async with ... as http_client:` in both samples so the connection pool is cleaned up. (Copilot reviewer) - Make the `TOOLBOX_NAME` env var consistent in both samples. Previously the tool name silently fell back to `"toolbox"` when `TOOLBOX_NAME` was unset, but `resolve_toolbox_endpoint()` still required `TOOLBOX_NAME` and would raise `KeyError`. The samples now resolve the endpoint once and derive the tool name from the resolved URL when `TOOLBOX_NAME` isn't set, so the local tool name always matches the upstream toolbox identity regardless of which env var the user set. (Copilot reviewer) - Rename `_responses.is_consent_error` to `consent_url_from_error`: the helper returns `str | None` (the consent URL), not a bool, so the new name matches behavior. Update the test class accordingly. (eavanvalkenburg) - Tighten `_handle_inner_agent`'s lazy-entry catch from `Exception` to `AgentFrameworkException`, the type the MCP layer actually wraps consent errors in via `MCPStreamableHTTPTool.__aenter__` → `ToolExecutionException(inner_exception=mcp_error)`. Network failures, cancellations, and other non-framework exceptions now propagate normally instead of being briefly caught and re-raised. The test helper `_make_consent_error` is updated to use `ToolExecutionException` so it matches the real-world wrapping. (eavanvalkenburg) - Clarify the `github_pat` description in `agent.manifest.yaml` to note it's only needed when the PAT-based connection (`github-mcp-pat-conn`) is chosen; users selecting the OAuth2 connection (`github-mcp-oauth-conn`) can leave it empty. (Copilot reviewer) Validation: ran both samples end-to-end against a real Foundry toolbox (`research_toolbox`) -- the samples connect successfully and the agent lists the toolbox's MCP tools (`api_specs___fetch_azure_rest_api_docs`, etc.). `uv run poe test -P foundry_hosting` passes (119 tests), pyright + mypy clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: fix broken Foundry samples link in 04_foundry_toolbox README The previous URL pointed to an old location of the toolbox supported-scenarios doc; the doc moved to /samples/python/hosted-agents/SUPPORTED_TOOLBOX_SCENARIOS.md and the old /samples/python/toolbox/azd path now 404s. Caught by the markdown-link-check CI step. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
What this sample demonstrates
An Agent Framework agent that uses Foundry Toolbox for tool discovery and hosted using the Responses protocol. Foundry Toolbox is a managed tool registry in Microsoft Foundry that lets you define tools centrally and share them across agents.
Creating a Foundry Toolbox
You can create a Foundry Toolbox by code. Refer to this sample for an example: Foundry Toolbox CRUD Sample.
You can also create a Foundry Toolbox in the Foundry portal. Read more about it in the Foundry toolbox documentation.
If you set up a project with this sample and provision the resources using
azd provision, a Foundry Toolbox will be created with the specified tools inagent.manifest.yaml.
Authentication Methods
You can connect to MCP servers in Foundry Toolbox that use different authentication methods. This sample demonstrates the following authentication methods:
- No authentication: The tool does not require any authentication. The agent can invoke the tool without providing any credentials. Sample MCP server:
https://gitmcp.io/Azure/azure-rest-api-specs - Key-based authentication: The tool requires a key to authenticate. Sample MCP server:
https://api.githubcopilot.com/mcp(GitHub MCP server) with a Personal Access Token (PAT) for authentication. - OAuth2 authentication (managed): The tool requires OAuth2 to authenticate. Sample MCP server:
https://api.githubcopilot.com/mcp(GitHub MCP server) with OAuth2 for authentication. - Agent identity authentication: The tool requires an agent identity token to authenticate. Sample MCP server:
https://{foundry-resource-name}.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview(Azure Language MCP server) with agent identity for authentication. - Entra Pass-through authentication: The tool requires an Entra pass-through token to authenticate. Sample MCP server: Microsoft Outlook MCP server with Entra pass-through for authentication.
Definitions of these authentication methods can be found in the agent.manifest.yaml file in this sample.
There are also Non-MCP tools in the toolbox that support different authentication methods. Learn more at the Foundry sample repository.
How It Works
Model Integration
The agent uses FoundryChatClient from the Agent Framework to create an OpenAI-compatible Responses client. It connects to the toolbox's MCP endpoint via MCPStreamableHTTPTool, which discovers and invokes the toolbox's tools over MCP at runtime. The endpoint URL is provided through the FOUNDRY_TOOLBOX_ENDPOINT environment variable.
See main.py for the full implementation.
Agent Hosting
The agent is hosted using the Agent Framework with the ResponsesHostServer, which provisions a REST API endpoint compatible with the OpenAI Responses protocol.
Running the Agent Host
Follow the instructions in the Running the Agent Host Locally section of the README in the parent directory to run the agent host.
An extra environment variable must be set to point to the toolbox MCP endpoint. You can provide it in one of two ways:
Option A – Set FOUNDRY_TOOLBOX_ENDPOINT directly (recommended for local development):
export FOUNDRY_TOOLBOX_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"
Or in PowerShell:
$env:FOUNDRY_TOOLBOX_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"
Option B – Set TOOLBOX_NAME (used automatically by the Foundry hosting scaffolding after azd provision):
The agent derives the endpoint at runtime as:
{FOUNDRY_PROJECT_ENDPOINT}/toolboxes/{TOOLBOX_NAME}/mcp?api-version=v1
When deployed via azd provision, the scaffolding injects TOOLBOX_NAME=agent-tools and FOUNDRY_PROJECT_ENDPOINT automatically from the provisioned resources declared in agent.manifest.yaml.
Interacting with the agent
Depending on how you run the agent host, you can invoke the agent using
curl(Invoke-WebRequestin PowerShell) orazd. Please refer to the parent README for more details. Use this README for sample queries you can send to the agent.
Send a POST request to the server with a JSON body containing an "input" field to interact with the agent. For example:
curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "What tools do you have?"}'
Deploying the Agent to Foundry
To host the agent on Foundry, follow the instructions in the Deploying the Agent to Foundry section of the README in the parent directory.