Building on Microsoft Foundry
Skill area 2 is 55–60% of AI-901, and objective 2.1 is where you prove you understand the Foundry platform. This guide covers the platform, deployments, prompts, and SDK. Agents have their own guide.
Foundry portal, resources, and projects
Microsoft Foundry is the platform for building, deploying, evaluating, observing, and securing AI apps and agents. It was previously called Azure AI Foundry; the exam and some docs may still use that name, but Microsoft Foundry is the current name. The Foundry portal is at ai.azure.com.
The hierarchy matters. A Foundry resource is the top-level Azure resource. A Foundry project lives inside that resource and is the unit of scoping for access, billing, endpoints, deployments, tools, and development work. When a question asks where you manage a solution, think project first.
Your code connects to the project endpoint, not just the Azure portal. The format is https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
| Inside a Foundry project | What it means for the exam |
|---|---|
| Model deployments | A deployed model endpoint with a deployment name your app passes in code. |
| Agents | Agent definitions and related runtime assets. This guide only locates them; the Agents guide covers details. |
| Playgrounds | Interactive testing surfaces for chat, prompts, models, and scenario experiments before code. |
| Evaluations | Tools for measuring outputs, comparing prompt changes, and checking quality before release. |
| Connections | References to other resources such as Azure AI Search, storage, or data sources. |
| Toolboxes | Reusable groups of tools that can be exposed to agents and apps through a managed endpoint. |
| Observability | Tracing, monitoring, and diagnostics for requests, tool calls, and app behavior. |
| RBAC | Project-scoped role assignments that control who can create, manage, and use assets. |
Foundry RBAC role names include Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager. You may still see older Azure AI role names in screenshots or older material, but AI-901 content should use the Foundry names.
Foundry (classic) is the older hub-based project model. It is deprecated, so mention it only as an older architecture you might see in existing environments. For new work and for this site, use the current Foundry resource and Foundry project model.
From Foundry Models to a callable deployment
The Foundry Models catalog is where you discover available model families and compare what they are designed to do. A model in the catalog is not automatically something your app can call. In the normal path, you choose a model, create a deployment in your project, and then call that deployment from code.
A deployment has its own deployment name. In SDK calls, model= takes that deployment name. It is a common mistake to pass the model family name when the deployment was named something else.
After deploying, test in the playground. The playground lets you try system messages, user prompts, parameters, and sample inputs before writing application code. This is also where you can quickly see whether the deployed model fits the task, whether the answer format is stable, and whether your prompt needs examples or source material.
| Step | What you do | Exam clue |
|---|---|---|
| Choose from Foundry Models | Select a model family based on task, modality, latency, capability, residency needs, and support requirements. | The question asks which model type or family is appropriate. |
| Deploy to the project | Create a deployment and give it a deployment name. | The app needs an endpoint it can call. |
| Configure filters and parameters | Set content filters and tune generation parameters such as system message and output length. | The question mentions safety controls or blocked input and output. |
| Test in the playground | Try prompts interactively before writing code. | The question asks how to validate a prompt or model behavior quickly. |
| Call from code | Use the project endpoint, credential, SDK client, and deployment name. | The question shows Python or asks what value goes in model=. |
Deployment options include serverless API, managed compute, and instant access. Serverless API is the normal preferred path; managed compute is for dedicated capacity that you size; instant access lets supported models be called by name without creating a deployment. For serverless deployments, Global Standard is the sensible default unless there is a specific residency, throughput, or batch-processing reason to choose something else. The Models guide covers the detail, so use models.html#deployment for the deeper comparison.
Content filters apply to a deployment. They evaluate prompts and generated output and can block or flag content based on configured severity thresholds and blocklists. On the exam, connect content filters with Azure AI Content Safety and responsible operation of generative AI, not with model selection alone.
Prompt engineering before heavier changes
Prompt engineering is how you shape model behavior through instructions, examples, and source material. It is the first lever because you can change it without redeploying infrastructure or changing model weights.
Prompt engineering is always the first lever because it costs nothing. Try clearer instructions, better format requirements, examples, and grounding material before moving to more complex approaches.
System message
The system message sets the role, constraints, tone, safety boundaries, and durable behavior. Put stable instructions here: who the assistant is, what it should never do, how it should handle missing information, and the output rules it must follow every time.
User prompt
The user prompt is the specific request for this turn. Put the task, source material, desired audience, length, format, and any one-time constraints here. A good user prompt is explicit about what success looks like.
Be specific about format, length, and audience. “Summarize this” is weak. “Write five bullet points for a nontechnical operations director; include risks and next actions; use only the source text” is much stronger. If you want JSON, a table, headings, citations, or a maximum length, say so directly.
Zero-shot, one-shot, and few-shot
| Technique | What you provide | Worked example |
|---|---|---|
| Zero-shot | Only instructions and the task. | “Classify this ticket as billing, access, hardware, or other. Return only the category.” |
| One-shot | One example of the desired input and output. | “Example: ‘I cannot reset my password’ → access. Now classify: ‘My invoice has the wrong tax rate.’” |
| Few-shot | Several examples that show the pattern. | “Password reset → access; cracked screen → hardware; refund request → billing. Now classify the new ticket.” |
Give the model source material in the prompt when the answer must come from your content. This is grounding at the prompt level. It reduces hallucination because the model has the relevant facts in front of it, and you can instruct it to say when the source does not contain the answer.
Weak prompt: Summarize this policy for employees.
This prompt does not specify audience, length, format, source boundaries, or what details matter.
Strong rewrite: You are helping new employees understand the travel policy. Using only the source text below, write a plain-English summary in six bullets. Include approval requirements, receipt rules, and reimbursement timing. If the source does not say something, write “Not stated in the source.”
The exam often asks what to adjust first when a model gives vague or inconsistent answers. The best first answer is usually to improve the prompt: add clearer instructions, specify the output format, provide examples, or include the relevant source content.
Foundry SDK basics
The Foundry SDK is the current SDK surface for projects. In Python, the package is azure-ai-projects version 2.x. Version 1.x belongs to Foundry (classic) and is API-incompatible with the current project model.
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
response = openai.responses.create(
model="support-chat-prod",
input="Write a three-bullet summary of the warranty note.",
)
print(response.output_text)The imports bring in the project client and the Azure identity credential. AIProjectClient connects your code to the Foundry project endpoint. DefaultAzureCredential uses keyless Microsoft Entra authentication, so local developers, managed identities, and hosted workloads can authenticate without hard-coding secrets.
project.get_openai_client() returns an OpenAI-compatible client scoped through the Foundry project. responses.create() sends a request to a deployed model. The model= value is the deployment name, such as support-chat-prod, not necessarily the model family name you selected in the catalog. response.output_text is the plain generated text.
| SDK | Package | Use when |
|---|---|---|
| Foundry SDK | azure-ai-projects 2.x | You are working with Foundry projects, project endpoints, model deployments, project-scoped clients, and current agent surfaces. |
| OpenAI SDK | OpenAI client package for your language | You need direct OpenAI-compatible calls. Embeddings must go through the OpenAI SDK endpoint at https://<resource>.openai.azure.com/openai/v1/. |
| Foundry Tools service SDKs | Service-specific Azure SDK packages | You are calling Azure Speech, Azure Language, Azure Document Intelligence, Content Understanding, or another purpose-built service directly. |
The two most common mistakes are passing a model family name instead of the deployment name, and using a missing or wrong project endpoint. If the endpoint does not include /api/projects/<project-name>, it is not the project endpoint shown in the current Foundry SDK pattern.
Traps candidates make with Foundry
Using old product names everywhere
Know that older docs may say Azure AI Foundry, but write and think Microsoft Foundry for current material. Foundry Tools, Foundry Models, Foundry resource, Foundry project, and Foundry SDK are the current terms.
Skipping the project level
A project is not cosmetic. It scopes access, billing, endpoints, deployments, tools, and observability. If a question asks where a deployment or playground lives, the answer is inside a Foundry project.
Confusing model and deployment
The catalog contains models. Your application usually calls a deployment. The deployment has the name used in code, even if it points to a familiar model family.
Overengineering prompt problems
If output is vague, too long, wrong format, or missing audience fit, improve the prompt first. Specify the role, output shape, examples, and source material before jumping to heavier solutions.
Forgetting content filters
Content filters attach to deployments and evaluate input and output. They are part of responsible AI operations for generative apps.
Using Foundry SDK 1.x examples
Foundry SDK 2.x is the current path. Version 1.x examples often reflect Foundry (classic) and can use API patterns that do not match current project endpoints.
The night-before cheat sheet
Hierarchy
Foundry resource is the top-level Azure resource.
Foundry project lives inside the resource and scopes access, billing, endpoints, deployments, tools, and observability.
Deployment is the callable instance of a model. Code passes the deployment name.
Project contents
Remember this list: model deployments, agents, playgrounds, evaluations, connections, toolboxes, observability, and RBAC. If the question asks where these are managed, answer within a Foundry project.
Deployment options
Serverless API: normal preferred path.
Managed compute: dedicated compute you size.
Instant access: call a supported model without creating a deployment.
Global Standard: sensible default unless a specific requirement points elsewhere.
Prompting ladder
Set a clear system message. Be specific about task, audience, length, and format. Add one-shot or few-shot examples when the pattern matters. Give the model source material when the answer must be grounded.
| SDK skeleton in five lines | Recall cue |
|---|---|
from azure.ai.projects import AIProjectClient | Use the Foundry SDK package. |
DefaultAzureCredential() | Keyless Entra authentication. |
AIProjectClient(endpoint="https://<resource>.services.ai.azure.com/api/projects/<project>", credential=...) | Use the project endpoint. |
project.get_openai_client() | Get the project-scoped OpenAI-compatible client. |
openai.responses.create(model="deployment-name", input="...") | model= is the deployment name. |