The quickstart for Microsoft Foundry Agent Service is written for Python. It hides the Azure plumbing inside scaffolding so dense that you can finish the tutorial without knowing which resources were actually created. If you build on .NET, you begin with a handicap: the samples point the wrong direction, package names shift without warning, and the recent rebrand from Azure AI Foundry to Microsoft Foundry has left two sets of documentation competing in search results.

I recently built my first agent in C#. The service works well once you strip away the noise and separate the essential steps from the preview-version confusion. Here is the map I wish I had on day one.

The Four Resources You Actually Need

You do not need a dozen Azure services to run a basic Prompt Agent. You need exactly four things, and the CLI makes them visible in a way the Python notebooks do not.

First, a Foundry resource with kind AIServices. This acts as the parent capacity for the models you will call. Second, a project inside that resource. The project is the scope where your agent definitions, conversation threads, and deployment settings live. Third, a deployed model. Without an active deployment, the agent has no endpoint to invoke. Fourth, a role assignment for your own identity so the SDK can authenticate against the project.

That is it. No Kubernetes cluster, no custom compute, no manually managed Redis cache for conversation history.

Prompt Agents Versus Hosted Agents

Foundry gives you two ways to run agents. Do not default to the more complex option.

Prompt Agents are the simpler path. You pick a model, write system instructions, and Foundry runs the agent for you. You do not manage compute, containers, or routing logic. This fits internal tools, helpdesk bots, and straightforward question-answering over documents.

Hosted Agents require you to write application code, package it as a container, and wire that into Foundry. You choose this route only when you need custom business logic that Foundry cannot express through prompts and built-in tools, such as calling an internal API with non-standard authentication.

This guide focuses on Prompt Agents because they are the fastest way to validate that your .NET setup is correct before you invest in Docker files and orchestration.

Setting Up from the Command Line

Using the CLI forces you to see each resource, which is exactly what the Python quickstart obscures. Create a resource group in East US 2. Region choice matters here. Foundry rolls out tool support unevenly, and East US 2 currently carries the broadest set. If you pick a region that lacks the code interpreter or file search tools, your agent creation call will fail with an opaque error about unsupported capabilities.

Create the Foundry resource with the --allow-project-management flag. Without that flag, the resource remains a standalone cognitive services endpoint and will not accept the project-scoped deployments that agents require. Then create the project, deploy your model, and assign yourself the Foundry User role.

Use the stable role GUID instead of the display name:

53ca6127-db72-4b80-b1b0-d745d6d5456d

Role names propagate through Azure Active Directory at different speeds depending on the tenant. One organization sees Foundry User in the portal today; another will not see it for days. The GUID points directly to the definition and will not fail during rollout. This single detail can save you an hour of debugging permission-denied errors that look like policy problems but are actually label-resolution problems.

Avoid the Wrong NuGet Package

Here is where .NET developers often get stuck. You will see references to Azure.AI.Projects.OpenAI in older snippets. That package is preview-only, and it overlaps with Azure.AI.Extensions.OpenAI. Both define extension methods and types in similar namespaces. If you install them side by side, your build breaks with ambiguous reference errors that