Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Currently viewing: 
Foundry (classic) portal version - Switch to version for the new Foundry portal
A Foundry resource provides unified access to models, agents, and tools. This article explains which SDK and endpoint to use for your scenario.
The Foundry SDK is a thin-client SDK that exposes all of the Foundry project APIs through a single project endpoint. Higher-level SDKs build on it — for example, the Agent Framework foundry package depends on the Foundry SDK to access Foundry models, tools, and project configuration.
| SDK | What it's for | Endpoint |
|---|---|---|
| Foundry SDK | Thin-client SDK over all Foundry project APIs. Access to Foundry Models and platform tools (file search, code interpreter, web search, memory, SharePoint, WorkIQ, Fabric IQ, MCP). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| Agent Framework | Hosted agents and multi-agent systems build using code. The foundry package depends on the Foundry SDK for project access. Run in your own process. |
Responses API in the project endpoint, via FoundryChatClient. |
| OpenAI SDK | Full OpenAI API surface, including embeddings. Best latency and maximum OpenAI compatibility. | https://<resource-name>.openai.azure.com/openai/v1 |
| Anthropic SDK | Anthropic Claude models deployed in Foundry. | https://<resource-name>.services.ai.azure.com/anthropic |
| Foundry Tools SDKs | Prebuilt solutions (Vision, Speech, Content Safety, and more). | Tool-specific endpoints. |
Choose your SDK:
- Use Foundry SDK when building apps with agents, evaluations, or Foundry-specific features
- Use Agent Framework when building hosted agents or multi-agent systems in code using the Responses API
- Use OpenAI SDK when maximum OpenAI compatibility or lowest latency is required, when generating embeddings, or when using Foundry direct models via Chat Completions
- Use Anthropic SDK when working with Anthropic Claude models deployed in Foundry
- Use Foundry Tools SDKs when working with specific AI services (Vision, Speech, Language, etc.)
Note
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
-
An Azure account with an active subscription. If you don't have one, create a free Azure account, which includes a free trial subscription.
Have one of the following Azure RBAC roles to create and manage Foundry resources:
Foundry User (least-privilege role for development)
Important
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
Foundry Project Manager (for managing Foundry projects)
Contributor or Owner (for subscription-level permissions)
For details on each role's permissions, see Role-based access control for Microsoft Foundry.
Install the required language runtimes, global tools, and VS Code extensions as described in Prepare your development environment.
Important
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)
- Python:
- Language runtime installed:
- Node.js:
node --version(≥18)
- Node.js:
- Language runtime installed:
- .NET:
dotnet --version(≥6.0)
- .NET:
- Language runtime installed:
- Java:
java --version(≥11)
- Java:
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>
Note
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
Note
This article applies to a Foundry project. The code shown here doesn't work for a hub-based project. For more information, see Types of projects.
Note
SDK versions: This article covers installation of the 1.x SDK. Make sure the samples you follow match your installed package. Switch to the new Foundry portal documentation to view article for 2.x.
| SDK Version | Portal Version | Status | Python Package |
|---|---|---|---|
| 2.x | Foundry (new) | Stable | azure-ai-projects>=2.0.0 |
| 1.x | Foundry (classic) | Stable | azure-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 this command to install the 1.x packages for Foundry classic projects.
pip install openai azure-identity azure-ai-projects==1.0.0
| SDK Version | Portal Version | Status | Java Package |
|---|---|---|---|
| 2.0.0 | Foundry (new) | Stable | azure-ai-projectsazure-ai-agents |
| SDK Version | Portal Version | Status | JavaScript Package |
|---|---|---|---|
| 2.0.1 | Foundry (new) | Stable | @azure/ai-projects |
| 1.0.1 | Foundry classic | Stable | @azure/ai-projects |
| SDK Version | Portal Version | Status | .NET Package |
|---|---|---|---|
| 2.0.0-beta.1 (preview) | Foundry (new) | Preview | Azure.AI.ProjectsAzure.AI.Projects.OpenAI |
| 1.1.0 (GA) | Foundry classic | Stable | Azure.AI.Projects |
The Azure AI Projects client library for Java is a unified library that enables you to use multiple client libraries together by connecting to a single project endpoint.
Important
The Java azure-ai-projects package doesn't have a 1.x GA release. The code samples in the Java sections use the azure-ai-inference package directly, which is being deprecated and will be retired on May 30, 2026.
For the 2.x Projects SDK, switch to the new Foundry portal documentation.
Add these dependencies to your Maven pom.xml for Foundry classic projects.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-inference</artifactId>
<version>1.0.0-beta.6</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.2</version>
</dependency>
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 1.x JavaScript packages for Foundry classic projects.
npm install @azure/ai-projects@1.0.1 @azure/identity
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 these commands to add the 1.x Azure AI SDK packages for Foundry classic projects.
# Add 1.x Azure AI SDK packages
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects --version 1.1.0
dotnet add package Azure.AI.Agents.Persistent --version 1.1.0
dotnet add package Azure.AI.Inference
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
/openairoute.
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.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
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:
models = project_client.get_openai_client(api_version="2024-10-21")
chat_responses = models.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the size of France in square miles?"},
],
)
print(chat_responses.choices[0].message.content)
Create a project client:
package com.azure.ai.foundry.samples;
import com.azure.ai.inference.ChatCompletionsClient;
import com.azure.ai.inference.ChatCompletionsClientBuilder;
import com.azure.ai.inference.models.ChatCompletions;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.credential.TokenCredential;
import com.azure.core.exception.HttpResponseException;
import com.azure.core.util.logging.ClientLogger;
import com.azure.identity.DefaultAzureCredentialBuilder;
String prompt = "What best practices should I follow when asking an AI model to review Java code?";
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
.credential(credential)
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
ChatCompletions completions = client.complete(prompt);
String content = completions.getChoice().getMessage().getContent();
System.out.println("\nResponse from AI assistant:\n" + content);
Create a project client:
const endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deployment = "gpt-4o";
const project = new AIProjectClient(endpoint, new DefaultAzureCredential());
Create an OpenAI-compatible client from your project:
const client = await project.getAzureOpenAIClient({
// The API version should match the version of the Azure OpenAI resource
apiVersion: "2024-12-01-preview"
});
const chatCompletion = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(chatCompletion.choices[0].message.content);
Create a project client:
using System.ClientModel.Primitives;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.Identity;
using OpenAI.Chat;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
Create an OpenAI-compatible client from your project:
ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
if (!connection.TryGetLocatorAsUri(out Uri uri) || uri is null)
{
throw new InvalidOperationException("Invalid URI.");
}
uri = new Uri($"https://{uri.Host}");
const string modelDeploymentName = "gpt-4o";
AzureOpenAIClient azureOpenAIClient = new AzureOpenAIClient(uri, new DefaultAzureCredential());
ChatClient chatClient = azureOpenAIClient.GetChatClient(deploymentName: modelDeploymentName);
Console.WriteLine("Complete a chat");
ChatCompletion result = chatClient.CompleteChat("List all the rainbow colors");
Console.WriteLine(result.Content[0].Text);
What you can do with the Foundry SDK
- Access Foundry Models, including Azure OpenAI
- Use the Foundry Agent Service
- Run cloud evaluations
- Enable app tracing
- Fine-tune a model
- Get endpoints and keys for Foundry Tools, local orchestration, and more
Troubleshooting
Authentication errors
If you see DefaultAzureCredential failed to retrieve a token:
Verify Azure CLI is authenticated:
az account show az login # if not logged inCheck RBAC role assignment:
Confirm you have at least the Foundry User role on the Foundry project
Important
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
For managed identity in production:
- Ensure the managed identity has the appropriate role assigned
- See Configure managed identities
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 # .NETReinstall 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 Chat Completions 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://ai.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))
For more information, see Azure OpenAI supported programming languages. 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
Important
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.ai.openai.OpenAIClient;
import com.azure.ai.openai.OpenAIClientBuilder;
import com.azure.ai.openai.models.ChatChoice;
import com.azure.ai.openai.models.ChatCompletions;
import com.azure.ai.openai.models.ChatCompletionsOptions;
import com.azure.ai.openai.models.ChatRequestAssistantMessage;
import com.azure.ai.openai.models.ChatRequestMessage;
import com.azure.ai.openai.models.ChatRequestSystemMessage;
import com.azure.ai.openai.models.ChatRequestUserMessage;
import com.azure.ai.openai.models.ChatResponseMessage;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Configuration;
import java.util.ArrayList;
import java.util.List;
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
.credential(defaultCredential)
.endpoint("{endpoint}")
.buildClient();
List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant."));
chatMessages.add(new ChatRequestUserMessage("What is the speed of light?"));
ChatCompletions chatCompletions = client.getChatCompletions(deploymentName, new ChatCompletionsOptions(chatMessages));
System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
ChatResponseMessage message = choice.getMessage();
System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
System.out.println("Message:");
System.out.println(message.getContent());
For more information on using the OpenAI SDK, see Azure OpenAI supported programming languages.
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const deployment = "gpt-4o";
const endpoint = "https://<resource-name>.openai.azure.com";
const scope = "https://ai.azure.com/.default";
const apiVersion = "2024-04-01-preview";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const options = { azureADTokenProvider, deployment, apiVersion, endpoint };
const client = new AzureOpenAI(options);
const result = await client.chat.completions.create({
model: deployment,
messages: [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "What is the speed of light?" },
],
});
console.log(result.choices[0].message.content);
For more information on using the OpenAI SDK, see Azure OpenAI supported programming languages.
- 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 `ChatClient` for the Azure OpenAI v1 endpoint. ```csharp using System.ClientModel.Primitives; using Azure.Identity; using OpenAI; using OpenAI.Chat; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string modelDeploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ChatClient chatClient = openAIClient.GetChatClient(modelDeploymentName); ChatCompletion completion = await chatClient.CompleteChatAsync( [ new SystemChatMessage("You are a helpful assistant."), new UserChatMessage("How many feet are in a mile?") ]); Console.WriteLine(completion.Content[0].Text); #pragma warning restore OPENAI001
For more information on using the OpenAI SDK, see Azure OpenAI supported programming languages.
Agent Framework
Microsoft Agent Framework is an open-source SDK (Python and .NET) for building agents and multi-agent systems in code. It's the recommended path for Hosted agents (preview) on Microsoft Foundry.
Run your code as a Hosted agent
The main story for code-based agents in Foundry is Hosted agents (preview). Write your agent with Agent Framework, package it as a container image or zip of your source code, and let Foundry run it with a managed endpoint, automatic scaling on isolated Micro VMs, a dedicated Microsoft Entra agent identity, session-level state, and end-to-end observability.
Hosted agents are the recommended path when you want a Foundry-managed, network-addressable endpoint that other apps or agents can call. See Deploy your first Hosted agent.
Build agents in code outside Foundry with the Responses API
If you're hosting your agent outside of Foundry — in your own process or infrastructure — you can also use Agent Framework to call the Responses API in your project endpoint directly. Agent Framework connects through the FoundryChatClient provider, which targets:
{project_endpoint}/openai/v1/responses
Going through the project endpoint — instead of a resource-level OpenAI endpoint — gives your agent:
- Foundry models from the catalog (Azure OpenAI and Foundry direct models) through one API.
- Platform tools beyond the OpenAI tool set, including file search, code interpreter, memory, web search, MCP servers, SharePoint, WorkIQ, and Fabric IQ.
- Project-scoped data, On-Behalf-Of (OBO) tool authentication, and the project's tracing, content filters, and identity configuration.
This pattern is additive to Hosted agents, not an alternative — the same Agent Framework code can call the Responses API from your own process today and be packaged as a Hosted agent later when you want a Foundry-managed endpoint. See Quickstart: Build agents using the Responses API.
For a full comparison of agent types and hosting choices, see What is Microsoft Foundry Agent Service?.
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/
Note
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.
If your workloads use retiring Azure AI Language features—for example, sentiment analysis, key phrase extraction, summarization, entity linking, CLU, or CQA—plan to migrate to Microsoft Foundry alternatives. For new development, consider using the Foundry SDK or the OpenAI-compatible endpoint as described earlier in this article. See Migrate from Language Studio to Microsoft Foundry.
For Speech and Translation Foundry Tools, use the endpoints in the following tables. Replace placeholders with your resource information.
Speech Endpoints
| Foundry Tool | Endpoint |
|---|---|
| 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 Voice | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Translation Endpoints
| Foundry Tool | Endpoint |
|---|---|
| Text Translation | https://api.cognitive.microsofttranslator.com/ |
| Document Translation | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Language Endpoints
| Foundry Tool | Endpoint |
|---|---|
| Text analysis | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com |
Important
On March 20, 2027, Azure Language Studio will retire and migrate to Microsoft Foundry; all capabilities and future enhancements will be available in Microsoft Foundry.
On March 31, 2029, the following Azure Language capabilities will retire (end of support). Before that date, users should migrate existing workloads and onboard new projects to Microsoft Foundry models for enhanced natural language understanding and simplified application integration:
- Key Phrase Extraction
- Sentiment Analysis and Opinion Mining
- Custom Text Classification
- Conversational Language Understanding (CLU)
- Custom Question Answering (CQA)
- Orchestration Workflow
- Summarization (extractive and abstractive, for documents and conversations)
- Entity Linking
Core features with continued support: Language Detection, PII Detection, Text Analytics for Health, Prebuilt NER, and Custom NER.
For migration options, see Migrate from Language Studio to Microsoft Foundry.
