Skip to main content

Microsoft Foundry SDKs and Endpoints

This article refers to the Microsoft Foundry (new) portal.
A Foundry resource provides unified access to models, agents, and tools. This article explains which SDK and endpoint to use for your scenario.
SDKWhat it’s forEndpoint
Foundry SDKFoundry-specific capabilities with OpenAI-compatible interfaces. Includes access to Foundry direct models through the Responses API (not Chat Completions).https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
OpenAI SDKLatest OpenAI SDK models and features with the full OpenAI API surface. Foundry direct models available through Chat Completions API (not Responses).https://<resource-name>.openai.azure.com/openai/v1
Foundry Tools SDKsPrebuilt solutions (Vision, Speech, Content Safety, and more).Tool-specific endpoints (varies by service).
Agent FrameworkMulti-agent orchestration in code. Cloud-agnostic.Uses the project endpoint via the Foundry SDK.
Choose your SDK:
  • Use Foundry SDK when building apps with agents, evaluations, or Foundry-specific features
  • Use OpenAI SDK when maximum OpenAI compatibility is required, or using Foundry direct models via Chat Completions
  • Use Foundry Tools SDKs when working with specific AI services (Vision, Speech, Language, etc.)
  • Use Agent Framework when building multi-agent systems in code (local orchestration)
Resource types: A Foundry resource provides all endpoints previously listed. An Azure OpenAI resource provides only the /openai/v1 endpoint.Authentication: Samples here use Microsoft Entra ID (DefaultAzureCredential). API keys work on /openai/v1. Pass the key as api_key instead of a token provider.

Prerequisites

Before starting, make sure your development environment is ready.
This article focuses on scenario-specific steps like SDK installation, authentication, and running sample code.

Verify prerequisites

Before proceeding, confirm:
  • Azure subscription is active: az account show
  • You have the required RBAC role: Check Azure portal → Foundry resource → Access control (IAM)
  • Language runtime installed:
    • Python: python --version (≥3.8)
    • Node.js: node --version (≥18)
    • .NET: dotnet --version (≥6.0)
    • Java: java --version (≥11)

Foundry SDK

The Foundry SDK connects to a single project endpoint that provides access to the most popular Foundry capabilities:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
If your organization uses a custom subdomain, replace <resource-name> with <your-custom-subdomain> in the endpoint URL.
This approach simplifies application configuration. Instead of managing multiple endpoints, you configure one.

Install the SDK

SDK versions: The 2.x preview SDK targets the new Foundry portal and API. The 1.x GA SDK targets Foundry classic. Make sure the samples you follow match your installed package.
SDK VersionPortal VersionStatusPython Package
2.x (preview)Foundry (new)Previewazure-ai-projects>=2.0.0b1 --pre
1.x (GA)Foundry classicStableazure-ai-projects==1.0.0
The Azure AI Projects client library for Python is a unified library that enables you to use multiple client libraries together by connecting to a single project endpoint. Run these commands to install the preview packages for Foundry projects.
pip install --pre azure-ai-projects
pip install azure-identity openai
SDK VersionPortal VersionStatusJava Package
1.0.0-beta.3
1.0.0-beta.1
Foundry (new)Previewazure-ai-projects
azure-ai-agents
SDK VersionPortal VersionStatusJavaScript Package
2.0.0-beta.4 (preview)Foundry (new)Preview@azure/ai-projects 'prerelease'
1.0.1Foundry classicStable@azure/ai-projects
SDK VersionPortal VersionStatus.NET Package
1.2.0-beta.5 (preview)Foundry (new)PreviewAzure.AI.Projects
Azure.AI.Projects.Openai
1.x (GA)Foundry classicStableAzure.AI.Projects
The Azure AI Projects client library for Java (preview) is a unified library that enables you to use multiple client libraries together by connecting to a single project endpoint.
Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
Add these packages to your installation for Foundry projects.
package com.azure.ai.agents;

import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
The Azure AI Projects client library for JavaScript is a unified library that enables you to use multiple client libraries together by connecting to a single project endpoint. Run this command to install the preview JavaScript packages for Foundry projects.
npm install @azure/ai-projects@beta @azure/identity dotenv
The Azure AI Projects client library for .NET is a unified library that enables you to use multiple client libraries together by connecting to a single project endpoint. Run this command to add the Azure.AI.Projects package to your .NET project.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity

Using the Foundry SDK

The SDK exposes two client types because Foundry and OpenAI have different API shapes:
  • Project client – Use for Foundry-native operations where OpenAI has no equivalent. Examples: listing connections, retrieving project properties, enabling tracing.
  • OpenAI-compatible client – Use for Foundry functionality that builds on OpenAI concepts. The Responses API, agents, evaluations, and fine-tuning all use OpenAI-style request/response patterns. This client also gives you access to Foundry direct models (non-Azure-OpenAI models hosted in Foundry). The project endpoint serves this traffic on the /openai route.
Most apps use both clients. Use the project client for setup and configuration, then use the OpenAI-compatible client for running agents, evaluations, and calling models (including Foundry direct models). Create a project client:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_client = AIProjectClient(
  endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
  credential=DefaultAzureCredential())
Create an OpenAI-compatible client from your project:
with project_client.get_openai_client() as openai_client:
    response = openai_client.responses.create(
        model="gpt-5.2",
        input="What is the size of France in square miles?",
    )
    print(f"Response output: {response.output_text}")
Expected output:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Create a project client:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;

String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";

ProjectsClient projectClient = new ProjectsClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint(endpoint)
    .buildClient();
Create and use an OpenAI-compatible client from your project:
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Create a project client:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
Create an OpenAI-compatible client from your project:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
    model: deploymentName,
    input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Create a project client:
using Azure.AI.Projects.OpenAI; 
using Azure.Identity;
using OpenAI.Responses;

string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";

AIProjectClient projectClient = new(
    endpoint: new Uri(endpoint), 
    tokenProvider: new DefaultAzureCredential());
Create an OpenAI-compatible client from your project:
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001

What you can do with the Foundry SDK

Troubleshooting

Authentication errors

If you see DefaultAzureCredential failed to retrieve a token:
  1. Verify Azure CLI is authenticated:
    az account show
    az login  # if not logged in
    
  2. Check RBAC role assignment:
    • Confirm you have at least the Azure AI User role on the Foundry project
    • See Assign Azure roles
  3. For managed identity in production:

Endpoint configuration errors

If you see Connection refused or 404 Not Found:
  • Verify resource and project names match your actual deployment
  • Check endpoint URL format: Should be https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
  • For custom subdomains: Replace <resource-name> with your custom subdomain

SDK version mismatches

If code samples fail with AttributeError or ModuleNotFoundError:
  • Check SDK version:
    pip show azure-ai-projects  # Python
    npm list @azure/ai-projects  # JavaScript
    dotnet list package  # .NET
    
  • Verify moniker alignment: 2.x SDK requires Foundry portal, 1.x SDK requires Foundry classic
  • Reinstall with correct version flags: See installation commands in each language section above

OpenAI SDK

Use the OpenAI SDK when you want the full OpenAI API surface and maximum client compatibility. This endpoint provides access to Azure OpenAI models and Foundry direct models (via Responses API). It doesn’t provide access to Foundry-specific features like agents and evaluations. The following snippet shows how to use the Azure OpenAI /openai/v1 endpoint directly.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://<resource-name>.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

response = client.responses.create(
    model="model_deployment_name",
    input= "What is the size of France in square miles?" 
)

print(response.model_dump_json(indent=2)) 
Expected output:
{
  "id": "resp_abc123",
  "object": "response",
  "created": 1234567890,
  "model": "gpt-5.2",
  "output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
For more information, see Azure OpenAI supported programming languages
Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
The following snippet shows how to use the Azure OpenAI /openai/v1 endpoint directly.
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;

import java.util.function.Supplier;

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
        tokenCredential, "https://cognitiveservices.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
        .baseUrl(endpoint)
        .credential(BearerTokenCredential.create(bearerTokenSupplier))
        .build();

ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
        .input("What is the speed of light?")
        .model(deploymentName) 
        .build();

Response response = openAIClient.responses().create(responseCreateParams);

System.out.println("Response output: " + response.getOutputText());
For more information on using the OpenAI SDK, see Azure OpenAI supported programming languages
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
        model: deploymentName,
        input: "What is the size of France in square miles?",
    });
console.log(`Response output: ${response.output_text}`);
For more information on using the OpenAI SDK, see Azure OpenAI supported programming languages
  1. Install the OpenAI package: Run this command to add the OpenAI client library to your .NET project.
    dotnet add package OpenAI
    
When it succeeds, the .NET CLI confirms that it installed the OpenAI package. This snippet configures DefaultAzureCredential, builds OpenAIClientOptions, and creates a ResponseClient for the Azure OpenAI v1 endpoint.
using Azure.Identity;
using Azure.Core;
using OpenAI;
using System;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

const string directModelEndpoint  = "https://<resource-name>.openai.azure.com/openai/v1/";
const string deploymentName = "gpt-5.2";    

BearerTokenPolicy tokenPolicy = new(
     new DefaultAzureCredential(),
     "https://cognitiveservices.azure.com/.default");
 
OpenAIResponseClient client = new(
     model: deploymentName,
     authenticationPolicy: tokenPolicy, // To use Entra 
  // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY 
     options: new OpenAIClientOptions()
     {
         Endpoint = new($"{directModelEndpoint}"),
     });
ResponseCreationOptions options = new ResponseCreationOptions
 {
     Temperature = (float)0.7,
 };
 
OpenAIResponse modelDirectResponse = client.CreateResponse(
      [
         ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"),
      ], options);
 
Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}");
#pragma warning restore OPENAI001
// The ResponseClient lets you interact with models and services in your project.
For more information on using the OpenAI SDK, see Azure OpenAI supported programming languages

Using the Agent Framework for local orchestration

Microsoft Agent Framework is an open-source SDK for building multi-agent systems in code (for example, .NET and Python) with a cloud-provider-agnostic interface. Use Agent Framework when you want to define and orchestrate agents locally. Pair it with the Foundry SDK when you want those agents to run against Foundry models or when you want Agent Framework to orchestrate agents hosted in Foundry. For more information, see the Microsoft Agent Framework overview.

Foundry Tools SDKs

Foundry Tools (formerly Azure AI Services) are prebuilt point solutions with dedicated SDKs. Use the following endpoints to work with Foundry Tools.

Which endpoint should you use?

Choose an endpoint based on your needs: Use the Azure AI Services endpoint to access Computer Vision, Content Safety, Document Intelligence, Language, Translation, and Token Foundry Tools. Foundry Tools endpoint: https://<your-resource-name>.cognitiveservices.azure.com/
Endpoints use either your resource name or a custom subdomain. If your organization set up a custom subdomain, replace your-resource-name with your-custom-subdomain in all endpoint examples.
For Speech and Translation Foundry Tools, use the endpoints in the following tables. Replace placeholders with your resource information.

Speech Endpoints

Foundry ToolEndpoint
Speech to Text (Standard)https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com
Text to Speech (Neural)https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com
Custom Voicehttps://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/

Translation Endpoints

Foundry ToolEndpoint
Text Translationhttps://api.cognitive.microsofttranslator.com/
Document Translationhttps://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/
The following sections include quickstart links for the Foundry Tools SDKs and reference information.

C# supported Foundry Tools

Foundry ToolDescriptionQuickstarts and reference documentation
Speech icon SpeechAdd speech to text, text to speech, translation, and speaker recognition capabilities to applications.• Speech to text quickstart

• Text to speech quickstart

• Speech translation quickstart

• Speech SDK for .NET

• Speech NuGet package (Speech CLI)
Language icon LanguageBuild applications with natural language understanding capabilities.• Custom question answering (CQA) quickstart

• Entity linking quickstart

• Language detection quickstart

• Key Phrase extraction quickstart

• Detecting named entities (NER) quickstart

• Detect Personally Identifiable Information (PII) quickstart

• Sentiment analysis and opinion mining quickstart

• Using text, document and conversation summarization quickstart

• Using Text Analytics for health quickstart

• Language SDK for .NET (text analysis)

• Language NuGet package (text analysis)

• Language SDK for .NET (Question Answering)

• Language NuGet package (question answering)
Translator icon TranslatorUse AI-powered translation technology to translate more than 100 in-use, at-risk, and endangered languages and dialects.• Translator SDK for .NET (text)

• Translator NuGet package (text)

• Translator SDK for .NET (batch)

• Translator NuGet package (batch)
Azure AI Search icon Azure AI SearchBring AI-powered cloud search to your mobile and web apps.• Use agentic retrieval quickstart

• Vector search quickstart

• Classic generative search (RAG) using grounding data quickstart

• Full-text search quickstart

• Semantic ranking quickstart

• Chat with Azure OpenAI models using your own data quickstart

• Azure AI Search SDK for .NET

• Azure AI Search NuGet package
Content Safety icon Content SafetyDetect harmful content in applications and services.• Analyze text content quickstart

• Use a text blocklist quickstart

• Analyze image content quickstart

• Content Safety SDK for .NET

• Content Safety NuGet package
Document Intelligence icon Document IntelligenceTurn documents into intelligent data-driven solutions.• Document Intelligence quickstart

• Document Intelligence SDK for .NET

• Document Intelligence NuGet package
Vision icon VisionAnalyze content in digital images and rich media assets.• Azure Vision in Foundry Tools v3.2 GA Read quickstart

• Image Analysis quickstart

• Use the Face service quickstart

• Vision SDK for .NET

• Vision NuGet package

Java supported Foundry Tools

Foundry ToolDescriptionQuickstarts and reference documentation
Speech icon SpeechAdd speech to text, text to speech, translation, and speaker recognition capabilities to applications.• Speech to text quickstart

• Text to speech quickstart

• Speech translation quickstart

• Speech SDK for Java

• Speech Maven package
Language icon LanguageBuild applications with natural language understanding capabilities.• Entity linking quickstart

• Language detection quickstart

• Key Phrase extraction quickstart

• Detecting named entities (NER) quickstart

• Detect Personally Identifiable Information (PII) quickstart

• Sentiment analysis and opinion mining quickstart

• Using text, document and conversation summarization quickstart

• Using Text Analytics for health quickstart

• Language SDK for Java (text analysis)

• Language Maven package
Translator icon TranslatorUse AI-powered translation technology to translate more than 100 in-use, at-risk, and endangered languages and dialects.• Translator SDK for Java (text)

• Translator Maven package (text)
Azure AI Search icon Azure AI SearchBring AI-powered cloud search to your mobile and web apps.• Use agentic retrieval quickstart

• Vector search quickstart

• Classic generative search (RAG) using grounding data quickstart

• Full-text search quickstart

• Semantic ranking quickstart

• Chat with Azure OpenAI models using your own data quickstart

• Azure AI Search SDK for Java

• Azure AI Search Maven package
Content Safety icon Content SafetyDetect harmful content in applications and services.• Analyze text content quickstart

• Use a text blocklist quickstart

• Analyze image content quickstart

• Content Safety SDK for Java

• Content Safety Maven package
Document Intelligence icon Document IntelligenceTurn documents into intelligent data-driven solutions.• Document Intelligence quickstart

• Document Intelligence SDK for Java

• Document Intelligence Maven package
Vision icon VisionAnalyze content in digital images and rich media assets.• Image Analysis quickstart

• Use the Face service quickstart

• Vision SDK for Java

• Vision Maven package

JavaScript supported Foundry Tools

Foundry ToolDescriptionQuickstarts and reference documentation
Speech icon SpeechAdd speech to text, text to speech, translation, and speaker recognition capabilities to applications.• Speech to text quickstart

• Text to speech quickstart

• Speech translation quickstart

• Speech SDK for JavaScript

• Speech npm package
Language icon LanguageBuild applications with natural language understanding capabilities.• Entity linking quickstart

• Language detection quickstart

• Key Phrase extraction quickstart

• Detecting named entities (NER) quickstart

• Detect Personally Identifiable Information (PII) quickstart

• Sentiment analysis and opinion mining quickstart

• Using text, document and conversation summarization quickstart

• Using Text Analytics for health quickstart

• Language SDK for JavaScript (text analysis)

• Language npm package
Translator icon TranslatorUse AI-powered translation technology to translate more than 100 in-use, at-risk, and endangered languages and dialects.• Translator SDK for JavaScript (text)

• Translator npm package (text)
Azure AI Search icon Azure AI SearchBring AI-powered cloud search to your mobile and web apps.• Use agentic retrieval quickstart

• Vector search quickstart

• Classic generative search (RAG) using grounding data quickstart

• Full-text search quickstart

• Semantic ranking quickstart

• Chat with Azure OpenAI models using your own data quickstart

• Azure AI Search SDK for JavaScript

• Azure AI Search npm package
Content Safety icon Content SafetyDetect harmful content in applications and services.• Analyze text content quickstart

• Use a text blocklist quickstart

• Analyze image content quickstart

• Content Safety npm package
Document Intelligence icon Document IntelligenceTurn documents into intelligent data-driven solutions.• Document Intelligence quickstart

• Document Intelligence SDK for JavaScript

• Document Intelligence npm package
Vision icon VisionAnalyze content in digital images and rich media assets.• Azure Vision in Foundry Tools v3.2 GA Read quickstart

• Image Analysis quickstart

• Use the Face service quickstart

• Vision SDK for JavaScript

• Vision npm package

Python supported Foundry Tools

Foundry ToolDescriptionQuickstarts and reference documentation
Speech icon SpeechAdd speech to text, text to speech, translation, and speaker recognition capabilities to applications.• Speech to text quickstart

• Text to speech quickstart

• Speech translation quickstart

• Speech SDK for Python

• Speech PyPi package
Language icon LanguageBuild applications with natural language understanding capabilities.• Custom question answering (CQA) quickstart

• Entity linking quickstart

• Language detection quickstart

• Key Phrase extraction quickstart

• Detect named entities (NER) quickstart

• Detect Personally Identifiable Information (PII) quickstart

• Sentiment analysis and opinion mining quickstart

• Using text, document and conversation summarization quickstart

• Using Text Analytics for health quickstart

• Language SDK for Python (text analysis)

• Language PyPi package (text analysis)

• Language SDK for Python (question answering)

• Language PyPi package (question answering)

• Language SDK for Python (language conversations)

• Language PyPi package (language conversations)
Translator icon TranslatorUse AI-powered translation technology to translate more than 100 in-use, at-risk, and endangered languages and dialects.• Translator SDK for Python (text)

• Translator PyPi package (text)

• Translator SDK for Python (batch)

• Translator PyPi package (batch)
Azure AI Search icon Azure AI SearchBring AI-powered cloud search to your mobile and web apps.• Connect to a search service quickstart

• Use agentic retrieval quickstart

• Vector search quickstart

• Classic generative search (RAG) using grounding data quickstart

• Full-text search quickstart

• Semantic ranking quickstart

• Chat with Azure OpenAI models using your own data quickstart

• Azure AI Search SDK for Python

• Azure AI Search PyPi package
Content Safety icon Content SafetyDetect harmful content in applications and services.• Analyze text content quickstart

• Use a text blocklist quickstart

• Analyze image content quickstart

• Content Safety SDK for Python

• Content Safety PyPi package
Document Intelligence icon Document IntelligenceTurn documents into intelligent data-driven solutions.• Document Intelligence quickstart

• Document Intelligence SDK for Python

• Document Intelligence PyPi package
Vision icon VisionAnalyze content in digital images and rich media assets.• Azure Vision in Foundry Tools v3.2 GA Read quickstart

• Image Analysis quickstart

• Use the Face service quickstart

• Vision SDK for Python

• Vision PyPi package