Microsoft Foundry tools integration

Integrate with Microsoft Foundry model tools using LangChain Python.

This page covers Microsoft Foundry project tools from langchain_azure_ai.tools. See also the tools provided as part of Microsoft Foundry Tools (formerly Azure AI Services).

Use these tools when you want agents to call capabilities in tools provided by Microsoft Foundry projects.

Overview

Tool	Description
AzureOpenAIModelImageGenTool	Generate images through an OpenAI-compatible /images/generations endpoint.
AzureOpenAITranscriptionsTool	Transcribe audio files to text through an OpenAI-compatible /audio/transcriptions endpoint.
CodeInterpreterTool	Run Python code server-side in a sandboxed container.
WebSearchTool	Search the internet for current information and sources.
FileSearchTool	Search vector stores for relevant document content.
ImageGenerationTool	Generate or edit images using GPT image models.
McpTool	Access external Model Context Protocol (MCP) servers.
AzureAIProjectToolbox	Load tools from an Azure AI Foundry Toolbox and use them via Model Context Protocol (MCP).

Setup

Install dependencies, create the resources used by the tools, and provide credentials.

Installation

Install the integration package:

pip

pip install -U "langchain-azure-ai[tools]"

uv add "langchain-azure-ai[tools]"

Credentials

Pass either DefaultAzureCredential() or an API-key string through the credential argument (except for AzureAIProjectToolbox which doesn’t support keys.)

Initialize credential

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

Using Microsoft Entra ID requires the role Azure AI User for the resources where the models are deployed.

Configure endpoints

The tools support two endpoint styles:

• An Azure AI Foundry project endpoint via project_endpoint or AZURE_AI_PROJECT_ENDPOINT (or FOUNDRY_PROJECT_ENDPOINT).
• A direct OpenAI-compatible endpoint via endpoint or OPENAI_BASE_URL, for example https://<resource>.services.ai.azure.com/openai/v1.

If both are available, prefer project_endpoint because it resolves the backing service endpoint automatically for Foundry-based workflows.

Configure endpoint

    export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.tools import AzureOpenAIModelImageGenTool

tool = AzureOpenAIModelImageGenTool(
    endpoint="https://<resource>.services.ai.azure.com/openai/v1",
    credential=DefaultAzureCredential(),
    model="my-gpt-image-1-deployment",
)

result = tool.invoke(
    {
        "prompt": "A futuristic cityscape at sunset with flying cars",
        "n": 1,
        "size": "1024x1024",
    }
)
print(result)

Tools

AzureOpenAIModelImageGenTool

AzureOpenAIModelImageGenTool (from langchain_azure_ai.tools) generates images using OpenAI-compatible image generation endpoints exposed by Microsoft Foundry Models or Azure OpenAI. You can use models including gpt-image-1.5 or MAI-Image-2.

Use this tool when you want explicit tool invocation for image generation in an agent flow. The tool calls the OpenAI client images.generate API and returns either base64 PNG output or saved file paths when output_directory is configured.

You must deploy an image generation model first, then pass the deployment name in model.

Configuration options

project_endpoint · str

The Foundry project where the image model is deployed. Using this parameter requires using Microsoft Entra ID.

endpoint · str

The OpenAI-compatible endpoint where the route /images/generations is present.

credential · str | TokenCredential

The credentials to use, either keys or token credentials.

prompt · str

Text prompt describing the image to generate.

n · int · default: "1"

Number of images to generate.

size · str | None · default: "1024x1024"

Output image size (for example 1024x1024, 1024x1792, or 1792x1024, model-dependent).

quality · str | None

Optional quality parameter passed to the image-generation model (for example hd, model-dependent).

style · str | None

Optional style parameter such as vivid or natural (model-dependent).

model · str

Required deployment name of the image generation model to use. Create this deployment in Microsoft Foundry before using the tool. Any OpenAI-compatible model can be used (for example, MAI-Image-2).

output_directory · str | None

If set, generated images are saved as PNG files and the tool returns saved file paths. If omitted, the tool returns base64 PNG data.

AzureOpenAITranscriptionsTool

AzureOpenAITranscriptionsTool (from langchain_azure_ai.tools) transcribes audio to text using OpenAI-compatible speech-to-text endpoints exposed by Microsoft Foundry Models or Azure OpenAI (such as Whisper).

Use this tool when you want to convert audio files or remote audio URLs into text transcriptions within an agent flow. The tool handles both local files and remote URLs automatically, supporting multiple audio formats (MP3, MP4, MPEG, MPGA, M4A, OGG, FLAC, WAV).

You must deploy a speech-to-text model first, then pass the deployment name in model.

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.tools import AzureOpenAITranscriptionsTool

tool = AzureOpenAITranscriptionsTool(
    endpoint="https://<resource>.services.ai.azure.com/openai/v1",
    credential=DefaultAzureCredential(),
    model="my-whisper-deployment",
)

result = tool.invoke(
    {
        "audio_path": "/path/to/audio.wav",
        "language": "en",
    }
)
print(result)

Configuration options

project_endpoint · str

The Foundry project where the speech-to-text model is deployed. Using this parameter requires using Microsoft Entra ID.

endpoint · str

The OpenAI-compatible endpoint where the route /audio/transcriptions is present.

credential · str | TokenCredential

The credentials to use, either keys or token credentials.

audio_path · str

Path to a local audio file or a URL pointing to an audio file.

language · str | None

Optional language code in ISO-639-1 format (e.g., "en", "es", "fr"). If not specified, the language will be auto-detected by the model.

model · str

Required deployment name of the speech-to-text model to use. Create this deployment in Microsoft Foundry before using the tool.

CodeInterpreterTool

CodeInterpreterTool allows the model to write and execute Python code within a sandboxed container and include the results in its response. This is useful for data analysis, mathematical computations, visualization, and general problem-solving.

Tools in namespace langchain_azure_ai.tools.builtin must be used with an OpenAI model deployed in a Microsoft Foundry project. They are resolved within the model’s inference request and are not available for models running outside Azure AI Foundry.

from langchain_azure_ai.tools.builtin import CodeInterpreterTool

tool = CodeInterpreterTool(
    memory_limit="4g",
)

model_with_code = model.bind_tools([tool])
response = model_with_code.invoke("Plot a sine wave using Python and explain it")
print(response)

Configuration options

file_ids · list[str] | None

Optional list of uploaded file IDs to make available inside the container for the code to process.

memory_limit · str | None

Memory limit for the container. Accepted values are "1g", "4g", "16g", and "64g".

network_policy · dict | None

Optional network access policy for the container.

WebSearchTool

WebSearchTool allows the model to search the internet for current information and sources related to its queries. This is useful for providing up-to-date information, research, fact-checking, and accessing real-time data.

Tools in namespace langchain_azure_ai.tools.builtin must be used with an OpenAI model deployed in a Microsoft Foundry project. They are resolved within the model’s inference request and are not available for models running outside Azure AI Foundry.

from langchain_azure_ai.tools.builtin import WebSearchTool

tool = WebSearchTool(
    search_context_size="high",
)

model_with_search = model.bind_tools([tool])
response = model_with_search.invoke(
    "What are the latest developments in quantum computing?"
)
print(response)

Configuration options

search_context_size · 'low' | 'medium' | 'high' | None

High-level guidance for the amount of context window space to use for the search results. Defaults to "medium".

user_location · dict | None

Approximate location of the user. Can include optional keys: city, country (ISO-3166 two-letter code), region, timezone (IANA), and type="approximate".

filters · dict | None

Search filters. Can include an optional allowed_domains list to restrict results to specific domains.

FileSearchTool

FileSearchTool searches for relevant content from uploaded vector stores. This is useful for retrieving information from large document collections, knowledge bases, and custom data sources that have been indexed in vector stores.

Tools in namespace langchain_azure_ai.tools.builtin must be used with an OpenAI model deployed in a Microsoft Foundry project. They are resolved within the model’s inference request and are not available for models running outside Azure AI Foundry.

from langchain_azure_ai.tools.builtin import FileSearchTool

tool = FileSearchTool(
    vector_store_ids=["vs_abc123", "vs_def456"],
    max_num_results=5,
)

model_with_search = model.bind_tools([tool])
response = model_with_search.invoke(
    "Find information about company policies on remote work"
)
print(response)

Configuration options

vector_store_ids · list[str] · required

IDs of the vector stores to search. At least one ID must be provided.

max_num_results · int | None

Maximum number of results to return (1-50). Defaults to a reasonable number.

filters · dict | None

Optional metadata filter to narrow results using comparison or compound filters.

ranking_options · dict | None

Ranking options. Can include optional keys ranker and score_threshold to control result ranking.

ImageGenerationTool

ImageGenerationTool allows the model to generate or edit images using GPT image models. This is useful for creating visuals, editing images, and generating artwork based on text descriptions. This tool must be used with an OpenAI model deployed in a Microsoft Foundry project. If you are using another model, use AzureOpenAIModelImageGenTool instead.

Tools in namespace langchain_azure_ai.tools.builtin must be used with an OpenAI model deployed in a Microsoft Foundry project. They are resolved within the model’s inference request and are not available for models running outside Azure AI Foundry.

from langchain_azure_ai.tools.builtin import ImageGenerationTool

tool = ImageGenerationTool(
    quality="high",
    size="1024x1024",
    model_deployment="my-gpt-image-1-deployment",
)

model_with_images = model.bind_tools([tool])
response = model_with_images.invoke(
    "Generate an image of a futuristic city with flying cars"
)
print(response)

Configuration options

model_deployment · str | None

Deployment name of the image generation model in Azure AI Foundry. When set, the tool automatically injects the x-ms-oai-image-generation-deployment HTTP request header.

model · 'gpt-image-1' | 'gpt-image-1-mini' | 'gpt-image-1.5' | None

Image generation model to use.

action · 'generate' | 'edit' | 'auto' | None

Whether to generate a new image or edit an existing one. Defaults to "auto".

quality · 'low' | 'medium' | 'high' | 'auto' | None

Image quality. Defaults to "auto".

size · '1024x1024' | '1024x1536' | '1536x1024' | 'auto' | None

Image size. Defaults to "auto".

output_format · 'png' | 'webp' | 'jpeg' | None

Output format. Defaults to "png".

background · 'transparent' | 'opaque' | 'auto' | None

Background type for image generation.

input_fidelity · str | None

How closely the output should match style and facial features of input images. One of "high" or "low".

input_image_mask · dict | None

Mask for inpainting operations.

moderation · 'auto' | 'low' | None

Moderation level. Defaults to "auto".

output_compression · int | None

Compression level (0-100, default 100).

partial_images · int | None

Number of partial images to stream (0-3).

McpTool

McpTool gives the model access to an external Model Context Protocol (MCP) server. This allows the model to call tools exposed by remote MCP servers within a single conversational turn, enabling integration with custom services and external systems.

Tools in namespace langchain_azure_ai.tools.builtin must be used with an OpenAI model deployed in a Microsoft Foundry project. They are resolved within the model’s inference request and are not available for models running outside Azure AI Foundry.

from langchain_azure_ai.tools.builtin import McpTool

tool = McpTool(
    server_label="my_mcp_server",
    server_url="https://my-mcp-server.example.com",
    allowed_tools=["tool_1", "tool_2"],
)

model_with_mcp = model.bind_tools([tool])
response = model_with_mcp.invoke(
    "Use the MCP server to retrieve user profile information"
)
print(response)

Configuration options

server_label · str · required

A label for this MCP server, used to identify it in tool calls.

server_url · str | None

The URL for the MCP server. Either server_url or connector_id must be provided.

connector_id · str | None

Identifier for a built-in service connector (e.g., "connector_gmail"). Either server_url or connector_id must be provided.

allowed_tools · list[str] | dict | None

List of tool names, or a tool filter dict, that the model is allowed to call on this server.

headers · dict[str, str] | None

Optional HTTP headers to send with every request to the MCP server (e.g., for authentication).

require_approval · 'always' | 'never' | dict | None

Whether tool calls require human approval before execution.

server_description · str | None

Optional description of the MCP server for the model.

authorization · str | None

OAuth access token for the MCP server.

Toolboxes

Setup

Install required dependencies:

pip

pip install -U "langchain-azure-ai[tools]" langchain-mcp-adapters httpx

uv add "langchain-azure-ai[tools]" langchain-mcp-adapters httpx

AzureAIProjectToolbox

AzureAIProjectToolbox (from langchain_azure_ai.tools) loads tools from an Azure AI Foundry Toolbox and makes them available via the Model Context Protocol (MCP).

Azure AI Foundry Toolbox is a managed multi-MCP server that aggregates multiple configured tools behind a single MCP endpoint. Use this when you want to dynamically load and use a collection of tools from your Azure AI Foundry project in an agent.

The toolbox automatically handles:

• Azure Identity Bearer-token authentication
• Graceful OAuth consent-error handling: returns a fallback tool with the consent URL instead of raising
• Automatic tool-schema sanitization for MCP servers that emit incomplete JSON schemas

Create a toolbox in your Microsoft Foundry project. For documentation see Toolbox in Foundry.

Configuration parameters

project_endpoint · str

Azure AI Foundry project endpoint, e.g., https://<resource>.services.ai.azure.com/api/projects/<project>. Falls back to AZURE_AI_PROJECT_ENDPOINT or FOUNDRY_PROJECT_ENDPOINT environment variables.

toolbox_name · str

Name of the toolbox as configured in Azure AI Foundry. This parameter is required.

api_version · str · default: "v1"

Toolbox API version appended to the MCP URL.

credential · str | TokenCredential

Azure credential for Bearer-token authentication. Accepts a string (static Bearer token) or any TokenCredential such as DefaultAzureCredential. Defaults to DefaultAzureCredential().

extra_headers · dict[str, str]

Additional HTTP headers to include in MCP requests. The Foundry-Features header is automatically added with the default value unless already present.

Basic usage

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.tools import AzureAIProjectToolbox
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage

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-mini", credential=DefaultAzureCredential())
    agent = create_agent(
        model=model,
        tools=tools,
    )

    result = await agent.ainvoke({
        "messages": [HumanMessage("What can you do with the available tools?")]
    })
    return result

Or use environment variables instead:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

Then instantiate without arguments (or just toolbox_name):

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
tools = await toolbox.get_tools()

Using async context manager

async with is supported for ergonomic compatibility:

async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
    tools = await toolbox.get_tools()

Integration with agents

The get_tools() method returns a list of BaseTool instances ready for use with any LangChain agent pattern:

Agent with AzureAIProjectToolbox

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.tools import AzureAIProjectToolbox
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

async def main():
    credential = DefaultAzureCredential()
    toolbox = AzureAIProjectToolbox(
        toolbox_name="my-toolbox",
        credential=credential,
    )

    tools = await toolbox.get_tools()

    model = init_chat_model("azure_ai:gpt-5-mini", credential=credential)
    agent = create_agent(
        model=model,
        tools=tools,
        system_prompt=(
            "You are a helpful assistant with access to a set of tools from "
            "Azure AI Foundry. Use them to help the user with their requests."
        ),
    )

    return agent

API reference

from langchain_azure_ai.tools import (
    AzureAIProjectToolbox,
    AzureOpenAIModelImageGenTool,
    AzureOpenAITranscriptionsTool,
)
from langchain_azure_ai.tools.builtin import (
    CodeInterpreterTool,
    FileSearchTool,
    ImageGenerationTool,
    McpTool,
    WebSearchTool,
)

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.