EBS Analysis: Get started with Microsoft Foundry SDKs and endpoints – Microsoft Foundry

## Navigating the Microsoft Foundry SDK Landscape: A Strategic Guide for Enterprise AI Development

### Executive Introduction

Enterprise teams adopting generative AI face a fundamental architectural decision: which SDK and endpoint strategy best aligns with their use case, compliance requirements, and operational model? Microsoft Foundry introduces a unified platform that abstracts away much of the traditional complexity around model access, agent orchestration, and tool integration. Yet this abstraction introduces its own decision surface—one that spans five distinct SDK paths, multiple endpoint shapes, and varying levels of OpenAI compatibility.

The research material reveals that Foundry is not a single client library but rather a layered ecosystem. At its foundation sits the Foundry SDK, a thin-client library exposing all Foundry project APIs through one canonical project endpoint. Higher-level frameworks like the Agent Framework build on this foundation, while specialized SDKs serve distinct workloads—Anthropic Claude models, Foundry Tools for vision and speech, and the OpenAI SDK for latency-sensitive or embedding-heavy scenarios.

For enterprise IT leaders, the stakes are high. Choosing the wrong SDK path can result in increased latency, limited access to platform tools, compliance gaps from improper authentication patterns, or technical debt from incompatible abstraction layers. This article provides a comprehensive, original analysis of the Foundry SDK and endpoint architecture, translating the technical reference material into actionable guidance for enterprise consulting contexts.

### Architecture and Capabilities: The Foundry Resource Model

At the architectural core, Microsoft Foundry introduces a critical distinction between resource types that fundamentally shapes endpoint availability. A Foundry resource provides unified access to all endpoints—OpenAI-compatible APIs, Anthropic endpoints, and Foundry Tools endpoints—under a single resource identity. This contrasts sharply with the legacy Azure OpenAI resource, which exposes only the `/openai/v1` endpoint. For enterprises consolidating multiple AI workloads under one governance boundary, the Foundry resource model offers significant operational simplification.

The project endpoint serves as the canonical entry point, formatted as `https://.services.ai.azure.com/api/projects/`. This single endpoint consolidates what previously required managing separate resource URLs, keys, and authentication contexts. Organizations using custom subdomains must replace “ with their custom subdomain, an important detail for enterprises with DNS management policies.

The SDK architecture deliberately exposes two client types because Foundry and OpenAI have fundamentally different API shapes:

– **Project Client**: Handles Foundry-native operations that have no OpenAI equivalent—listing connections, retrieving project properties, enabling tracing, and managing project-level configuration. These operations are administrative or setup-oriented and require Foundry-specific API surfaces.

– **OpenAI-Compatible Client**: Targets the Responses API served on the `/openai` route of the project endpoint. This client handles Foundry functionality built on OpenAI concepts—agents, evaluations, fine-tuning, and model inference. Critically, this endpoint provides access to Foundry Models sold by Azure, other catalog models, and platform tools including file search, code interpreter, web search, memory, SharePoint, WorkIQ, Fabric IQ, and MCP servers.

Most enterprise applications use both clients. The pattern is: use the project client for setup and configuration, then use the OpenAI-compatible client for runtime operations. This dual-client model reflects Foundry’s strategic positioning as both an AI platform and an AI application framework.

### How the Technology Works: SDK Selection by Scenario

The research material maps five distinct SDK paths to specific scenarios, and understanding these mappings is essential for enterprise architecture decisions.

**Foundry SDK**: This is the thin-client foundation exposing all Foundry project APIs. It is the correct choice when building applications that leverage Foundry-specific features—evaluations, data generation jobs, project-level tracing, or connections to external data sources. The Agent Framework’s `foundry` package depends on this SDK, meaning that any hosted agent or multi-agent system using Agent Framework implicitly relies on the Foundry SDK for model access, tool configuration, and project settings. Enterprises building comprehensive AI applications with Foundry-native features should treat this as their primary integration point.

**Agent Framework**: Recommended for hosted agents or multi-agent systems orchestrated in code. Available in C#/.NET and Python, it provides unified abstractions for building agents and coordinating multiple agents on complex tasks. The framework connects through the `FoundryChatClient` provider, which targets the Responses API in the project endpoint. This is the recommended orchestration layer for hosted agents in Foundry—agents packaged as container images or zip deployments, running on isolated Micro VMs with automatic scaling, dedicated Microsoft Entra agent identities, and session-level state.

**OpenAI SDK**: Appropriate when maximum OpenAI compatibility or lowest latency is required, when generating embeddings, or when using Models sold by Azure through Chat Completions. The OpenAI SDK targets the Azure OpenAI `/openai/v1` endpoint directly. A critical limitation: the project endpoint used by the Foundry SDK does not currently route embedding requests. Enterprises with heavy embedding workloads—semantic search, RAG pipelines, document similarity—should use the OpenAI SDK against the Azure OpenAI resource endpoint for these specific operations.

**Anthropic SDK**: For Anthropic Claude models deployed in Foundry. Claude models use a separate `/anthropic` endpoint appended to the resource URL, not the OpenAI-compatible endpoint. The Anthropic Messages API is distinct from the OpenAI Chat Completions API. Note that the Anthropic SDK does not provide native C# or Java clients—enterprises in those ecosystems must use the REST API with `HttpClient`.

**Foundry Tools SDKs**: For specific AI services—Computer Vision, Content Safety, Document Intelligence, Language, Translation, Speech, and Token services. These use the Azure AI Services endpoint at `https://.cognitiveservices.azure.com/`. Enterprises with existing Azure AI Services workloads need to plan migration paths, as Azure Language Studio retires on March 20, 2027, and specific Language capabilities (Sentiment Analysis, CLU, Summarization) retire on March 31, 2029.

### Implementation Considerations: Prerequisites and Environment Setup

Enterprise implementation requires careful attention to prerequisites that often become bottlenecks in production deployments.

**RBAC Role Model**: The Foundry RBAC role structure was recently renamed—Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager (previously Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager). Role IDs and core permissions remain unchanged, but enterprises in the middle of a rename rollout may see both naming conventions. The narrowest-scope principle applies:

– Foundry User: Day-to-day development on the Foundry project
– Foundry Project Manager: Managing an existing project and its connections
– Foundry Account Owner: Creating projects or managing account-level resources (assign on the target resource group only)

For privileged operations like creating Foundry resources, enterprises should activate resource-group assignments through Microsoft Entra Privileged Identity Management (PIM) just in time, then deactivate them. Day-to-day developers and runtime users should not carry elevated assignments.

**Language Runtime Requirements**: The SDK versions impose specific runtime constraints:
– Python 3.10 or later, with `openai>=3.0.0` and `azure-ai-projects>=2.3.0`
– Node.js 22 or later, with `@azure/ai-projects>=2.8.0`
– .NET 8 or later
– Java 17 or later

A critical JavaScript caveat: do not install `Azure.AI.Projects.OpenAI` (preview) alongside `Azure.AI.Extensions.OpenAI` (GA). Both packages define the same types in different namespaces, causing ambiguous reference errors. Use only `Azure.AI.Extensions.OpenAI` for agent scenarios.

**Credential Authentication**: Samples use Microsoft Entra ID via `DefaultAzureCredential`. API keys work only on the `/openai/v1` endpoint and must be passed as `api_key` instead of a token provider. For managed identity in production, ensure the managed identity has the appropriate Foundry role assigned. Enterprises should verify that their local credential can request a Foundry access token without displaying the token—using `az account show` and `az login` with an identity that has the required Foundry role.

### Security and Governance Implications

The Foundry architecture introduces several security considerations that enterprises must address:

**Authentication Pathways**: The dual authentication model—Microsoft Entra ID for Foundry endpoints and API keys for the OpenAI-compatible endpoint—creates a governance split. Enterprises should standardize on Entra ID for production workloads, as it provides role-based access control, conditional access policies, and audit logging. API keys, while simpler for development, lack fine-grained authorization and should be restricted to non-production environments or specific integration scenarios.

**Project-Scoped Access**: The project endpoint provides project-scoped data access, On-Behalf-Of (OBO) tool authentication, and project-level tracing and content filters. This scoping is a security feature—it means that agents running through the project endpoint inherit the project’s identity configuration, content filter settings, and data access boundaries. Enterprises should design their project structure to align with security boundaries: separate projects for different business units, compliance classifications, or environments.

**Custom Subdomain Implications**: Organizations using custom subdomains must replace “ with “ in all endpoint URLs. This affects not only connectivity but also certificate management, DNS configuration, and potentially private endpoint setups. Enterprises with strict network security policies should validate that custom subdomain configurations are consistent across all SDK integrations.

**Managed Identity for Production**: The research material explicitly recommends managed identity for production deployments. Enterprises should ensure that managed identities have the appropriate Foundry roles assigned at the project level, not just the resource level. This aligns with the principle of least privilege and enables audit trails that link specific operations to specific identities.

### Operational Implications: Long-Running Operations and Polling Patterns

A significant operational consideration in newer SDK versions is the shift to long-running operations. Operations such as evaluation job creation and data-generation job creation now return a poller instead of a direct result. This architectural change affects how enterprise applications handle asynchronous operations, error recovery, and status reporting.

Each SDK implements polling patterns differently:

– **Python SDK**: Pollers from `azure-ai-projects` follow Azure’s long-running operation conventions, with `wait()` methods and status properties that applications must check at appropriate intervals.
– **.NET SDK**: The `Azure.AI.Projects` library exposes poller types that integrate with .NET’s async patterns, but enterprises must ensure their application code handles cancellation and timeout scenarios.
– **Java SDK**: The `azure-ai-projects:2.3.0` and `azure-ai-agents:2.3.0` dependencies provide their own polling abstractions, which may differ in semantics from the Python and .NET implementations.

Enterprises should establish polling patterns in their shared libraries rather than letting each application implement its own retry logic. This is particularly important for batch evaluation workloads, where job completion times can vary significantly based on dataset size and model complexity.

### Common Pitfalls: Lessons from the Reference Implementation

The research material documents several failure modes that enterprises should anticipate:

**AttributeError or ModuleNotFoundError**: These typically indicate incorrect package versions or missing dependencies. Enterprises should verify installations with `pip show azure-ai-projects` (Python), `npm list @azure/ai-projects` (JavaScript), or `dotnet list package` (.NET). Reinstalling with correct version flags resolves most issues, but the version constraints are strict—Python requires `openai>=3.0.0` alongside `azure-ai-projects>=2.3.0`, and mixing preview and GA packages in JavaScript causes ambiguous reference errors.

**Connection Refused or 404 Not Found**: These usually stem from mismatched resource and project names or incorrect endpoint URL format. The endpoint must be `https://.services.ai.azure.com/api/projects/`, and for custom subdomains, “ must be replaced with the custom subdomain. Enterprises should validate that resource and project names match their actual deployment—case sensitivity and spelling errors are common in configuration files.

**DefaultAzureCredential Failures**: When `DefaultAzureCredential` fails to retrieve a token, the root cause is typically an unauthenticated Azure CLI session or missing RBAC role. Enterprises should verify Azure CLI authentication with `az account show` and `az login`, and confirm that the identity has at least the Foundry User role on the Foundry project. The RBAC rename may cause confusion if enterprises are still referencing previous role names in their access policies.

**Embedding Request Failures**: The project endpoint used by the Foundry SDK does not route embedding requests. Enterprises building RAG pipelines or semantic search must use the OpenAI SDK against the Azure OpenAI resource endpoint for embedding operations. This is a common discovery point—teams assume the Foundry endpoint handles all OpenAI-compatible operations, but embeddings are explicitly excluded.

### Why This Matters to Enterprise IT

The Foundry SDK and endpoint architecture represents a strategic shift in how enterprises access and orchestrate AI capabilities. The consolidation of multiple endpoints under a single project endpoint reduces operational complexity—fewer endpoints to monitor, fewer authentication mechanisms to manage, and fewer network configurations to maintain. For enterprises with security requirements around data residency, private endpoints, or custom DNS, the custom subdomain support and project-scoped access model provide necessary flexibility without sacrificing governance.

The layered SDK architecture—Foundry SDK as foundation, Agent Framework for orchestration, specialized SDKs for specific model providers—mirrors the complexity of modern enterprise AI stacks. Enterprises that invest in understanding this architecture early avoid costly refactoring when their use cases evolve from simple model inference to multi-agent orchestration, evaluation pipelines, and integrated tool ecosystems.

The migration timelines for Azure Language capabilities (March 2027 and March 2029) create urgency for enterprises with existing Language Studio workloads. Teams that begin migration now—before the retirement deadline—avoid the last-minute rush that typically results in rushed decisions, inadequate testing, and compliance gaps.

### EBS Consulting Perspective

From an enterprise consulting standpoint, the Foundry SDK landscape presents a classic abstraction dilemma. The platform offers tremendous consolidation benefits, but those benefits come with a decision surface that requires deliberate architectural governance.

Our consulting experience with enterprise AI adoption reveals three recurring patterns:

**Pattern 1: The “OpenAI First” Trap.** Enterprises that begin with the OpenAI SDK for its familiarity and latency advantages often discover later that they need Foundry-specific features—agents, evaluations, platform tools—and face integration challenges when trying to layer the Foundry SDK on top. We recommend starting with the Foundry SDK as the primary integration point, even for simple use cases, because it provides the full API surface and avoids the discovery problem.

**Pattern 2: The SDK Sprawl Problem.** Enterprises that adopt multiple SDKs without a clear governance model end up with inconsistent authentication patterns, duplicated configuration logic, and divergent error handling. Our recommendation is to establish a “primary SDK” for each major use case category—Foundry SDK for platform-integrated applications, OpenAI SDK for embedding-heavy workloads, Foundry Tools SDKs for specific AI services—and document the boundaries explicitly.

**Pattern 3: The RBAC Rename Confusion.** The ongoing rename of Foundry RBAC roles from Azure AI naming conventions creates access control gaps, particularly in enterprises with automated role assignment scripts or infrastructure-as-code templates that reference previous role names. We recommend auditing existing role assignments and updating automation before the rename completes, rather than discovering access failures during deployment.

The Agent Framework warrants particular attention. As the recommended orchestration layer for hosted agents, it represents the strategic direction of Microsoft’s agent platform. Enterprises building agent-based solutions should evaluate whether their orchestration needs can be met by Agent Framework’s unified abstractions, rather than combining multiple orchestration SDKs (AutoGen, Semantic Kernel) that solve similar coordination tasks with conflicting abstractions and dependencies.

### Practical Next Steps

Enterprises should take the following actions to operationalize the Foundry SDK architecture:

1. **Audit Current State**: Inventory existing Azure AI and Azure OpenAI resources, identify which SDKs and endpoints are currently in use, and map them to the Foundry SDK decision framework.

2. **Validate RBAC Roles**: Confirm that all identities requiring Foundry access have the correct renamed roles (Foundry User, Foundry Project Manager, Foundry Account Owner) and update any automation referencing previous role names.

3. **Establish SDK Governance**: Define which SDK applies to which use case category, document the boundaries, and create reference implementations for the most common patterns—chat completions, embeddings, agent orchestration, and tool integration.

4. **Plan Language Capability Migration**: For enterprises with Azure Language Studio workloads (Sentiment Analysis, CLU, Summarization), begin migration planning now to avoid the March 2027 and March 2029 deadlines.

5. **Pilot Hosted Agents**: Evaluate Agent Framework for agent-based solutions, starting with a single agent deployment to validate the hosted agent model—container packaging, Micro VM scaling, Entra agent identity, and session-level state management.

6. **Implement Monitoring**: Establish monitoring for the project endpoint, including authentication failures, latency patterns, and long-running operation status. The poller-based architecture for evaluations and data generation jobs requires specific observability patterns.

### Conclusion

The Microsoft Foundry SDK and endpoint architecture represents a significant consolidation of AI platform capabilities, but it demands deliberate architectural decisions from enterprise teams. The layered SDK model—Foundry SDK, Agent Framework, OpenAI SDK, Anthropic SDK, and Foundry Tools SDKs—maps to distinct use cases, and selecting the wrong path can create technical debt, latency penalties, or compliance gaps.

At EBS Consulting, we guide enterprises through these decisions by mapping their specific workloads to the appropriate SDK architecture, establishing governance patterns that prevent SDK sprawl, and implementing migration strategies for legacy Azure AI Services. The urgency is real—particularly for teams with Azure Language Studio dependencies facing the 2027 and 2029 retirement deadlines—but the consolidation benefits of Foundry, when approached strategically, can significantly simplify enterprise AI operations.

The next conversation should focus on your organization’s specific use cases: Are you building agents, generating embeddings, orchestrating multi-step workflows, or leveraging prebuilt AI services? Each scenario maps to a different SDK path, and the right architecture depends on your current capabilities, compliance requirements, and operational model. Let us help you navigate this landscape with a structured assessment of your AI portfolio and a migration roadmap that aligns with your business objectives.

EBS Consulting Advice

If your organization is evaluating Get started with Microsoft Foundry SDKs and endpoints – Microsoft Foundry, do not treat the technology decision in isolation. Start with the business outcome, current architecture, security and identity controls, operational constraints, migration dependencies and governance requirements. A practical assessment should identify the current-state gaps, prioritize the risks and define an implementation roadmap with measurable outcomes.

EBS can help assess the environment, develop the architecture and modernization roadmap, and translate the technical options into an actionable business plan. Relevant EBS services: Microsoft Azure consulting Modern Workplace.

Have a technology challenge? Email info@escapebusinesssolutions.com to describe your situation. We welcome questions, consulting discussions and requests for a proposal.