Choosing an Endpoint, and Reading the First Error

What this slice covers

Microsoft Foundry exposes more than one endpoint, and more than one SDK can talk to it. This note covers the map — which SDK and which address suit which job — and then the diagnostic half: the three families of failure that account for nearly every broken first call, and how to tell them apart from the error text. Writing the first working chat client is covered separately; this note is about picking the right door and about what to do when it will not open.

The map

Think of four routes into a Foundry resource.

The Foundry SDK is a thin client over all of the project APIs, addressed through the project endpoint on services.ai.azure.com. Choose it when you are building applications with agents, evaluations, or anything Foundry-specific, and when you want the platform tools — file search, code interpreter, web search, memory, SharePoint, Work IQ, Fabric IQ, MCP.

The Agent Framework sits above it for hosted agents and multi-agent orchestration in C#/.NET and Python, working through the Responses API on the project endpoint. Its Foundry package depends on the Foundry SDK, so choosing it does not mean abandoning the model above.

The OpenAI SDK talks to the Azure OpenAI endpoint on openai.azure.com, on the v1 route. Choose it when you want the full OpenAI API surface, the best latency, and maximum compatibility with existing OpenAI clients — and note what you give up: this endpoint does not provide access to Foundry-specific features such as agents, evaluations, or Foundry-exclusive platform tools.

The Anthropic SDK reaches Claude models deployed in Foundry through a distinct anthropic path, using the Anthropic Messages API rather than the OpenAI-compatible surface. Separately, the Foundry Tools SDKs cover the prebuilt, non-generative capabilities on their own tool-specific endpoints.

The one routing rule people trip over

There is a specific asymmetry worth memorising: embeddings. Microsoft directs you to the OpenAI SDK endpoint for generating embeddings, because the project endpoint used by the Foundry SDK does not currently route embedding requests. If you have built your whole application on the project endpoint and then add a retrieval feature, this is where it stops working — and the error will not say the word "embeddings" in a helpful way.

One more structural fact constrains the map: a Foundry resource provides all of these endpoints, while an Azure OpenAI resource provides only the openai v1 endpoint. If a tutorial's project endpoint does not resolve for you, check which resource type you actually created before you check anything else.

Failure family one: authentication

The signature is a message saying the default credential failed to retrieve a token. This is almost never a code bug. Work through it in order: confirm the Azure CLI is signed in, since the local credential chain leans on it; confirm you hold at least the Foundry User role on the project; and in production, confirm the managed identity your app runs under has the appropriate assignment. A useful pre-flight is asking the CLI for an access token for the Foundry resource and printing only its expiry — success proves the credential chain works without exposing anything sensitive.

Remember the role rename here too. 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, and older documentation may still use the earlier names for the same permissions.

Failure family two: the endpoint

The signature is a connection refused or a 404. Check the endpoint's literal shape against the documented pattern — resource name, then the projects path, then the project name — and check that both names match what actually exists in your subscription. Custom subdomains substitute for the resource name. A 404 here means the address is wrong, not that the service is down; treat it as a spelling problem.

Failure family three: package versions

The signature is an attribute error or a missing module while running a sample that plainly should work. The cause is usually a generation mismatch: the 2.x SDKs correspond to the current Foundry portal, the 1.x SDKs to the classic portal, and code written for one does not run against the other. Print the installed version before you debug anything else.

On .NET there is an extra trap worth knowing by name. Do not install the preview Azure.AI.Projects.OpenAI package alongside the generally available Azure.AI.Extensions.OpenAI package: both define the same types in different namespaces, and the result is ambiguous reference errors at compile time. For agent scenarios, use the GA package only.

The habit to build

Before blaming your code, verify the environment: subscription and tenant, token acquisition, role assignment, endpoint format, runtime version, and that the model deployment reports a successful provisioning state. Five commands answer all of it, and they turn a mysterious failure into a specific one.