Load tools from an Azure AI Foundry Toolbox and use them via MCP.
Azure AI Foundry Toolbox is a managed multi-MCP server that aggregates
multiple configured tools behind a single MCP endpoint. This class wraps
MultiServerMCPClient (from langchain-mcp-adapters) and adds:
get_bearer_token_provider.Foundry-Features header injection required by the Foundry MCP gateway.properties on object types).handle_tool_error = True on every tool so tool-call failures are
returned as tool messages rather than propagating ToolException.Each get_tools() call is stateless — it opens a fresh MCP session,
loads tools, and returns, mirroring MultiServerMCPClient.get_tools().
async with is supported as a convenience but does not change behavior.
Primary usage::
from azure.identity import DefaultAzureCredential
from langchain.chat_models import init_chat_model
from langchain.agents import create_agent
from langchain.messages import HumanMessage
from langchain_azure_ai.tools import AzureAIProjectToolbox
async def main():
toolbox = AzureAIProjectToolbox(
project_endpoint=(
"https://<resource>.services.ai.azure.com/api/projects/<project>"
),
toolbox_name="my-toolbox",
)
tools = await toolbox.get_tools()
model = init_chat_model("azure_ai:gpt-5.4")
agent = create_agent(
model=model.bind_tools(tools),
tools=tools
)
return await agent.ainvoke({"messages": [HumanMessage("What can you do?")]})
You can also rely on environment variables for configuration instead of passing constructor arguments::
# Set in the environment / agent.manifest.yaml:
# FOUNDRY_PROJECT_ENDPOINT=https://<resource>.../api/projects/<project>
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
tools = await toolbox.get_tools()
async with is also accepted (same behavior, returns self)::
async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
tools = await toolbox.get_tools()
Toolbox skills are exposed as MCP resources (URIs of the form
skill://{name}) and can be loaded as LangChain Blob objects with
get_resources / aget_resources::
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
skill_blobs = toolbox.get_resources(scheme="skills")
for blob in skill_blobs:
backend.write(
path=f"skills/{blob.source}/SKILL.md",
content=blob.as_string(),
encoding="utf-8",
)
For deepagents users, get_skills / aget_skills removes that
boilerplate by returning a ready-to-use files mapping for
create_deep_agent::
from deepagents import create_deep_agent
from deepagents.backends import StateBackend
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
skill_files = toolbox.get_skills()
agent = create_deep_agent(
model="azure_ai:gpt-5.2",
backend=StateBackend(),
skills=["/skills/"],
)
agent.invoke({"messages": [...], "files": skill_files})
| Name | Type | Description |
|---|---|---|
project_endpoint* | unknown | |
toolbox_name* | unknown | |
api_version* | unknown | |
credential* | unknown | |
extra_headers* | unknown |
Note:
Requires langchain-mcp-adapters and httpx::
pip install langchain-mcp-adapters httpx
Azure AI Foundry project endpoint, e.g.
https://<resource>.services.ai.azure.com/api/projects/<project>.
Falls back to the AZURE_AI_PROJECT_ENDPOINT or
FOUNDRY_PROJECT_ENDPOINT environment variables.
Name of the toolbox as configured in Azure AI Foundry. This parameter is required.
Toolbox API version appended to the MCP URL.
Defaults to "v1".
Azure credential used to obtain Bearer tokens. Accepts a
plain string (static Bearer token), any TokenCredential such as
DefaultAzureCredential or ManagedIdentityCredential.
Defaults to DefaultAzureCredential().
Additional HTTP headers to include in MCP requests. The
Foundry-Features header is automatically added with the default
value unless already present in extra_headers. Defaults to {}.
Azure AI Foundry project endpoint URL.
Name of the toolbox as configured in Azure AI Foundry.
Toolbox API version string appended to the MCP URL.
Azure credential for Bearer-token authentication.
Additional HTTP headers to include in MCP requests.
Compute the full MCP endpoint URL from project_endpoint + toolbox_name.
Fetch tools from the Azure AI Foundry Toolbox.
Opens a fresh MCP session, loads all tools exposed by the toolbox,
applies post-processing, and returns them. Each call is stateless,
matching MultiServerMCPClient.get_tools() behavior.
Return names of toolbox tools that require runtime approval.
This inspects the toolbox tools/list metadata and returns tool names
whose _meta.tool_configuration.require_approval value is "always".
This capability is independent from OAuth consent handling.
Async alias for get_tools().
Provided for consistency with the LangChain async naming convention.
Fetch resources exposed by the Azure AI Foundry Toolbox.
Toolbox skills are surfaced as MCP resources with URIs of the form
skill://{name}. This opens a fresh MCP session, lists the available
resources, optionally filters them by URI scheme, reads their
contents, and returns them as LangChain Blob objects.
Each returned Blob carries the resource name in its source
property (derived from the URI, e.g. skill://my-skill becomes
"my-skill") and its raw URI under metadata["uri"].
Fetch resources exposed by the Azure AI Foundry Toolbox.
Synchronous wrapper around :meth:aget_resources. See that method for
full details on scheme filtering and the returned Blob objects.
Load toolbox skills as a deepagents-ready file mapping.
This is an opinionated convenience built on top of
:meth:aget_resources. It fetches the toolbox skills (MCP resources
with skill:// URIs) and returns a mapping of virtual file paths to
deepagents FileData objects, laid out under base_path in the
directory structure that create_deep_agent expects::
{f"{base_path}{skill_name}/SKILL.md": <FileData>, ...}
How the files reach the agent depends on the backend:
backend as None and pass the
returned mapping as the files payload on invoke. State writes
go through the LangGraph runtime, so the backend cannot be seeded
standalone.backend. The skills are written into it via
aupload_files and the same mapping is also returned.Seeding a StateBackend (default)::
from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from langchain_azure_ai.tools import AzureAIProjectToolbox
toolbox = AzureAIProjectToolbox(toolbox_name="my-tools")
skill_files = await toolbox.aget_skills()
agent = create_deep_agent(
model="azure_ai:gpt-5.2",
backend=StateBackend(),
skills=[base_path],
)
await agent.ainvoke(
{"messages": [...], "files": skill_files}
)
Seeding any other backend (e.g. FilesystemBackend)::
from deepagents.backends import FilesystemBackend
backend = FilesystemBackend(root_dir="./my-project")
toolbox = AzureAIProjectToolbox(toolbox_name="my-tools")
await toolbox.aget_skills(backend=backend)
agent = create_deep_agent(
model="azure_ai:gpt-5.2",
backend=backend,
skills=["/skills/"],
)
Load toolbox skills as a deepagents-ready file mapping.
Synchronous wrapper around :meth:aget_skills. See that method for full
details on base_path, backend, and the returned mapping.