Microsoft Foundry SDKs and Endpoints
This article refers to the Microsoft Foundry (new) portal.
| SDK | What it’s for | Endpoint |
|---|---|---|
| Foundry SDK | Foundry-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 SDK | Latest 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 SDKs | Prebuilt solutions (Vision, Speech, Content Safety, and more). | Tool-specific endpoints (varies by service). |
| Agent Framework | Multi-agent orchestration in code. Cloud-agnostic. | Uses the project endpoint via the Foundry 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
- 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:
- Azure AI User (least-privilege role for development)
- Azure AI 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.
Before starting, make sure your development environment is ready.
This article focuses on scenario-specific steps like SDK installation, authentication, and running sample code.
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)
- Python:
Foundry SDK
The Foundry SDK connects to a single project endpoint that provides access to the most popular Foundry capabilities:If your organization uses a custom subdomain, replace
<resource-name> with <your-custom-subdomain> in the endpoint URL.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 Version | Portal Version | Status | Python Package |
|---|---|---|---|
| 2.x (preview) | Foundry (new) | Preview | azure-ai-projects>=2.0.0b1 --pre |
| 1.x (GA) | Foundry classic | Stable | azure-ai-projects==1.0.0 |
| SDK Version | Portal Version | Status | Java Package |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 | Foundry (new) | Preview | azure-ai-projectsazure-ai-agents |
| SDK Version | Portal Version | Status | JavaScript Package |
|---|---|---|---|
| 2.0.0-beta.4 (preview) | Foundry (new) | Preview | @azure/ai-projects 'prerelease' |
| 1.0.1 | Foundry classic | Stable | @azure/ai-projects |
| SDK Version | Portal Version | Status | .NET Package |
|---|---|---|---|
| 1.2.0-beta.5 (preview) | Foundry (new) | Preview | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (GA) | Foundry classic | Stable | Azure.AI.Projects |
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.
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.
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 seeDefaultAzureCredential failed to retrieve a token:
-
Verify Azure CLI is authenticated:
-
Check RBAC role assignment:
- Confirm you have at least the Azure AI User role on the Foundry project
- See Assign Azure roles
-
For managed identity in production:
- Ensure the managed identity has the appropriate role assigned
- See Configure managed identities
Endpoint configuration errors
If you seeConnection 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 withAttributeError or ModuleNotFoundError:
- Check SDK version:
- 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.
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.
/openai/v1 endpoint directly.
-
Install the OpenAI package:
Run this command to add the OpenAI client library to your .NET project.
OpenAI package.
This snippet configures DefaultAzureCredential, builds OpenAIClientOptions, and creates a ResponseClient for the Azure OpenAI v1 endpoint.
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.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/ |