Where you work in Foundry
Microsoft Foundry is not a single screen. It is a set of places to work—portal pages, playgrounds, SDKs, and editor tools—where you create projects, deploy models, build agents, and later watch many agents across your organization. This concept maps those places so you know where to click or which tool to open.
Concept 1 introduced the two-level layout. A Foundry resource is the top-level account where admins set networking, security, and shared model deployments. A Foundry project is the workspace where your team builds: agents, uploaded files, and evaluations live there. Most everyday tasks happen inside a project; a few older features still apply to the whole resource. Switch projects with the project name dropdown in the upper left of the Microsoft Foundry portal.
Your subscription and region still matter. Which models you can deploy, which deployment options you see, and whether Agents or evaluations are offered can differ by Azure region, so check before you create resources. Storage, Key Vault, and Azure AI Search connect as separate Azure services with their own security rules.
Four ways to build and test
You can stay in the browser, write code that calls web APIs, scaffold from a terminal, or work inside Visual Studio Code. Teams mix these every day; none replaces the others.
| Surface | Best for | Typical starting point |
|---|---|---|
| Microsoft Foundry portal | Exploring models, configuring prompt agents, running evaluations, and managing resources without a local setup. | Agents playground to try a prompt agent. |
| Microsoft Foundry SDKs or REST API | Applications that call agents, automation, and release pipelines. SDKs ship for Python, C#, JavaScript, and Java. | Foundry SDK quickstart after you copy the project endpoint. |
| Azure Developer CLI (azd) extensions | Scaffolding, running, testing, and deploying agent projects from a command line. | Develop agents with azd documentation. |
| Visual Studio Code extension (Foundry Toolkit) | Day-to-day agent coding, debugging, and project navigation inside VS Code. | Install the Microsoft Foundry Toolkit for VS Code. |
Coding assistants such as GitHub Copilot can also work with Foundry through the Foundry Skill and, for tool access, the Foundry MCP Server. Use these after you understand the portal and how projects are organized.
| If you need to… | Start here |
|---|---|
| Compare prompts or models interactively before writing code | Model playground or Agents playground in the portal |
| Ship an agent inside your own app with version control | SDK or REST with the project endpoint from the welcome screen |
| Generate a hosted agent repo and deploy from the terminal | Azure Developer CLI (azd) |
| Debug agent code beside your repository | VS Code with the Foundry Toolkit, or Open in VS Code for the Web from a playground Code tab |
Inside the Microsoft Foundry portal
The portal is the website where you discover models, deploy them, try them in playgrounds, save agent versions, run evaluations, and manage who has access. When you deploy a model in the portal, you land in that model's playground for interactive testing.
Use the Manage toolbar button for the project and parent Foundry resource you already selected. From Manage you can review Project details (resource ID, endpoint, subscription, location), open Resource details in the Azure portal, add or remove users on the Users tab, attach connected resources, add sibling projects, and configure quota or an AI gateway for the resource. Manage applies to your current project; switch projects first if you need another one.
Select Operate on the upper-right toolbar to see agents, models, and tools across projects in your subscription: inventory, monitoring, compliance, and security signals. These fleet-wide views are available in the portal today. Features marked preview in Microsoft documentation follow supplemental preview terms and are not recommended for production workloads.
| Playground | Best for | What you can validate |
|---|---|---|
| Model playground | Prompt engineering, model comparison, parameter tuning | System prompts, tools such as web search or code interpreter, guardrails, and side-by-side model comparison (up to three models) |
| Agents playground | Multi-turn agent prototyping with tools and knowledge | Instructions, tools, knowledge sources, memory, tracing, and evaluation through AgentOps |
| Images playground | Image generation and editing flows | Text-to-image prompts, inpainting, and model comparison for image models such as gpt-image-1 |
| Video playground (preview) | Generative video workflows with models such as Azure OpenAI Sora-2 | Prompt iteration and grid comparison; generated videos are retained for 24 hours unless you download them |
Evaluations in the Agents playground are enabled by default for all Foundry projects and are included in consumption-based billing. To turn them off, select metrics in the upper right of the Agents playground and clear all evaluators.
Example: shop support assistant
Imagine an online shop called RiverMarket. You want a prompt agent that answers order-status questions, uses a friendly tone, and refuses to invent tracking numbers.
You would create a Foundry project for RiverMarket, deploy a chat model, and open the Agents playground. You write instructions that define how the agent should sound, which facts it may use, and that it must ask for an order ID when information is missing. You test a back-and-forth chat in the playground, turn on tracing to confirm behavior, then save a version once the answers look reliable.
When RiverMarket's web app needs the same agent, you copy the project endpoint from the welcome screen and follow the SDK quickstart: create or update the agent by name, open a conversation, and send customer messages through the Responses API. Merchandisers keep tuning instructions in the portal; the SDK carries the stable agent name into production code.
Your first hour: project to agent
These steps follow the agent development lifecycle and assume you have an Azure subscription. You need a Foundry project; if you do not yet have a Foundry resource, the portal creates one when you create the project. Pick a resource group and a location (region) for the new resources.
- Step 1, create a project. In the Microsoft Foundry portal, create a project. Choose an existing resource group or accept a new one, and select a location. A dedicated resource group makes it easier to delete the project and its Azure resources later.
- Step 2, deploy a model. Open the model catalog, choose a model, and deploy it—for example with Deploy and Default settings. Write down the deployment name because calls to the model use that name, not the catalog model name. Wait until deployment status shows Succeeded.
- Step 3, test in the model playground. After deployment the portal opens the model playground. Send a simple message and check the reply, latency, and token usage before you add tools.
- Step 4, create a prompt agent. Open the Agents playground (Build, then Agents, then Create agent). Name the agent, pick your deployed model, and write instructions that state the task, tone, and how to handle missing information.
- Step 5, test follow-up turns. Ask a question, then ask a related follow-up in the same chat. If the second answer uses context from the first, the session is keeping conversation history.
- Step 6, call the agent from code. Copy the project endpoint from the welcome screen. Follow the SDK quickstart to create or update the agent, sign in with Microsoft Entra (for example az login on your machine for local SDK runs), and send messages through a conversation.
Each time you save an agent definition from code or the portal, Foundry stores a new version that cannot be edited in place. You can compare settings, chat output, or saved definitions between versions and roll back, which matters before you publish an agent application later in the course.
You can try unsaved changes in the Agents playground, but that work disappears if you leave the portal. Save a version before you run full evaluations or depend on conversation history outside the playground.
Who can do what
Who can open which pages is set with Azure roles—named permission sets you assign on a Foundry resource, a project, or a single agent. Setup work such as creating deployments or projects is separate from everyday building inside a project (agents, evaluations, and file uploads).
| Role | Where it usually applies | What it allows |
|---|---|---|
| Foundry User | Foundry resource and project | Build and test agents inside a project—the usual least-privilege role for developers. |
| Reader (Azure built-in) | Foundry resource | View information about the resource without changing it. Some organizations also assign Foundry User on specific projects. |
| Foundry Project Manager | Foundry resource | Create and manage projects, build in them, and give teammates the Foundry User role. |
| Foundry Account Owner | Foundry resource | Manage the resource, deploy models, and create shared connections. Account owners cannot build inside projects until they also receive Foundry User. |
When you create a project through the portal, Foundry can automatically give Foundry User to your sign-in account and to the project's system identity if you are allowed to assign roles. Do not use the Azure AI Developer role for Foundry project work—it applies to Machine Learning workspaces and Foundry hubs, not Foundry projects. If a project is missing or evaluations fail to start, check role assignments before you change models or regions.
Common mistakes and what to do next
- Calling a model by its catalog name instead of the deployment name you chose during Deploy. Requests must use the deployment name.
- Selecting a model that is not available in your Foundry resource region. If a model is missing from the deployment list, check regional availability for that model.
- Skipping permission checks. Without Foundry User (and any Reader pairing your organization requires), you cannot build or evaluate in the project.
- Assuming playground use has no cost. Model inference, AgentOps evaluations, and other attached services bill through consumption-based pricing.
- Leaving the portal with unsaved agent changes. Save a version before you expect history, monitoring, or full evaluations to reflect your latest instructions.
- Trying to configure fully private deployments only in the portal UI. Some network-isolated scenarios require the SDK or CLI instead of the portal.
Concept 3 connects these places to capability families—models, agents, tools, observability, and governance—so you can see how portal pages and SDK calls fit one map. Open that concept when you are comfortable creating a project and a first agent.
Go deeper
- Client libraries and sign-in patterns for Python, C#, JavaScript, and Java: SDK overview
- Scaffold, run, test, and deploy hosted agent projects from the terminal: Develop agents with azd
- Install and use the Microsoft Foundry Toolkit inside VS Code: Install the toolkit
- Who can do what in Foundry and how to assign roles: Role-based access control for Foundry
Where each role starts
Hover over a card, or tab to it. On a touch screen, tap a card to open its bullets. Find the card that matches your job, then follow its starting link.
Full Stack Developer
Full Stack Developer
- Build and debug agents in VS Code
- Use the SDKs for Python, C#, JavaScript, and Java
- Deploy hosted agents with the Azure Developer CLI
Start here
Foundry SDK quickstart →
Data Engineer
Data Engineer
- Ground agents with Foundry IQ, and remote sources need no upfront indexing
- Search several sources in one request with multi-source selection
- Add knowledge and tools through Foundry Agent Service, and trace each run in Foundry
Start here
What is Foundry IQ? →
AI Engineer
AI Engineer
- Use built-in evaluations to measure quality
- Trace agent runs with OpenTelemetry-based tracing
- Benchmark, compare, and route models for each task
Start here
Run evaluations in Foundry →
Security and Governance Lead
Security and Governance Lead
- Assign Foundry roles with role-based access control
- Use Microsoft Entra identity for access
- Set guardrails and content filters
Start here
Role-based access control for Foundry →
Business Owner
Business Owner
- Estimate costs with the Azure pricing calculator
- Model inference and playground evaluations use consumption-based billing
- Check each service's pricing page before you build
Start here
Azure pricing calculator →