How to Build Your First Agent in Azure AI Foundry (AI-103 Hands-On Guide, 2026)

Last updated: July 2026. Written and fact-checked by the Examinotion editorial team against Microsoft Learn, the official AI-103 skills outline, and the Microsoft Foundry documentation.

TL;DR You build your first agent in Azure AI Foundry, now officially renamed Microsoft Foundry, by creating a project, deploying a chat model, then defining a prompt agent with instructions and tools, either in the portal or with the Python SDK. This tutorial walks both paths and maps each step to the AI-103 exam.

Azure AI Foundry is where the AI-103 exam expects you to build. AI-103, the Microsoft Certified: Azure AI Apps and Agents Developer Associate certification, is a hands-on developer exam, and its single largest domain is building generative and agentic solutions on Foundry [2]. This guide takes you through your first agent end to end, so the platform stops being an abstract exam objective and becomes something you have actually used.

One naming point before we start, because it trips up almost every 2026 tutorial. Microsoft has renamed Azure AI Foundry to Microsoft Foundry, and the current documentation lives under the foundry path on Microsoft Learn [1]. The exam skills outline and most search results still say "Azure AI Foundry", so this guide uses that familiar name in the heading while using Microsoft's current terminology in the steps. When you see "Microsoft Foundry" in the portal, it is the same product.

What is Azure AI Foundry (now Microsoft Foundry)?

Azure AI Foundry, now called Microsoft Foundry, is Microsoft's unified platform for building, deploying, and operating AI applications and agents. Microsoft describes it as "a unified Azure platform-as-a-service offering for enterprise AI operations, model builders, and application development" that brings agents, models, and tools together with built-in tracing, monitoring, and evaluation [1].

The rename is not cosmetic, and understanding the moving parts saves you real confusion in the exam and in the portal. Four pieces matter for this tutorial.

• The Foundry portal is the web experience at ai.azure.com where you manage projects, deploy models, and build agents [1]. A "New Foundry" toggle in the portal banner switches between the current experience and the older "Foundry classic" view, so screenshots from 2024 and 2025 may not match what you see.
• A project is your isolated workspace. Agents are created inside a specific project, and data is isolated between projects [5]. It is the unit of sharing and access control.
• The Foundry Agent Service is the managed runtime for agents. Microsoft defines an agent as "an AI application that uses a model from the Foundry model catalog to reason about user requests and take autonomous actions to fulfill them" [4].
• The Foundry SDK is the code path. The current package is Azure AI Projects version 2, installed as azure-ai-projects>=2.0.0, and it is deliberately incompatible with the older 1.x SDK used by classic hub-based projects [6].

Foundry also gives you access to a very large model catalogue, more than 1,900 models from Microsoft, OpenAI, Anthropic, Mistral, Meta, and others, all deployable under one project [1]. For your first agent you only need one chat model.

Why Azure AI Foundry matters for the AI-103 exam

Azure AI Foundry is the centre of the AI-103 exam, not a side topic. The official skills outline, measured as of 16 April 2026, lists Implement generative AI and agentic solutions at 30 to 35 percent, the single largest domain, and it names Foundry explicitly in the tasks "Build generative applications by using Foundry" and "Build agents by using Foundry" [2].

AI-103 is a pro-code exam aimed at people who already write software. Microsoft's audience profile states that the candidate "builds, manages, and deploys agents and AI solutions that take advantage of Microsoft Foundry" and should "have experience developing apps by using Python" [2][3]. That is why this tutorial leads with the Python SDK: the exam assumes you can read and write it.

This exam replaces the retired AI-102. Microsoft's AI-102 certification page now carries the banner "This certification and the renewal assessment are retired" [12], and AI-103 is the successor path for the Azure AI engineer role. If you are moving across from AI-102, our guide to the AI-102 retirement and AI-103 successor path explains what changed and what carries over.

Azure AI Foundry versus Copilot Studio: which tool does AI-103 test?

Azure AI Foundry and Copilot Studio are different tools for different builders, and AI-103 tests Foundry. Microsoft positions Copilot Studio as the low-code, managed environment for business makers and IT teams, and Foundry as the pro-code platform for professional developers who need fine-grained control and integration into their own applications and cloud infrastructure [1][9]. The two are designed to work together, not to compete, but they map to different certifications.

If your goal is a low-code agent instead, our walkthrough on building custom agents in Copilot Studio for AB-730 and the multi-agent Copilot Studio guide for AB-620 cover that side. For AI-103, stay in Foundry.

Before you start: prerequisites and cost

You need three things before building your first agent in Azure AI Foundry: an Azure subscription, the right role assignments, and awareness of what you will be billed. None of this is difficult, but the exam tests whether you understand the setup, so it is worth getting right.

An Azure subscription. You can create one for free, and new accounts receive a general Azure free credit to explore with [5]. Microsoft does not offer a dedicated free tier for production inference. As Microsoft puts it, "The platform is free to use and explore. Pricing occurs at the deployment level" [1]. Browsing the portal and the playground costs nothing, but every real model call bills pay-as-you-go from the first token.

The right roles. Foundry uses role-based access control, and the roles were recently renamed. You need Foundry Account Owner at subscription scope to create the account and project, and Foundry User to create and edit agents [5]. Microsoft notes that "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" [5], so older guides that reference the Azure AI names describe the same permissions.

Region and quota awareness. The Agent Service only works in regions that support the underlying Responses API, and not every tool works in every region [10]. Model quota is the most common early blocker: if a deployment fails with an "insufficient quota" message, you usually need to pick a different region or request more capacity [5]. Some newer models also require separate eligibility approval before you can deploy them [10].

How to build your first agent in Azure AI Foundry: the portal path

The fastest way to build your first agent in Azure AI Foundry is the portal, which provisions everything for you in a few minutes. Microsoft frames agent creation as a two-step process: set up the environment, then create and configure the agent [5]. The portal collapses most of the first step into a single guided flow.

1. Open the Foundry portal at ai.azure.com and sign in with an account that holds the Foundry Account Owner role. If you see a "New Foundry" toggle, make sure you are on the current experience so these steps match [1].
2. Choose Create an agent from the getting-started flow. Enter a project name, or use the advanced options to customise the resource, region, and model. The default setup, which Microsoft calls Basic, uses Microsoft-managed storage and is the quickest way to a working agent [5].
3. Wait for provisioning. This creates a Foundry account, a project as a child resource, and a default chat model deployment. Provisioning typically takes five to ten minutes [5].
4. Open the agent playground once provisioning completes. Go to Build, then Agents, then Create agent, and give the agent a name.
5. Write the agent instructions. Start simple, for example "You are a helpful assistant that answers general questions" [6]. Instructions are the system prompt that shapes how the agent behaves.
6. Test in the playground. Type a message and confirm the agent responds. You now have a working prompt agent, an agent defined entirely by configuration with no application code to manage [4].

That is a complete first agent. A model deployment, the thing your agent points at, is a named instance of a catalogue model with a specific version, SKU, and region [5]. Your agent references the deployment by name, which is why quota and region belong to the deployment rather than the agent.

How to build the same agent with the Foundry SDK (Python)

The Foundry SDK builds the same agent in code, which is exactly what AI-103 expects you to be able to do. Install the current package with pip install azure-ai-projects>=2.0.0, sign in with az login so DefaultAzureCredential can authenticate, then create the agent against your project endpoint [6].

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,          # copy from your project's Overview page
    credential=DefaultAzureCredential(),
)

agent = project.agents.create_version(
    agent_name="my-first-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",                # use whichever chat model is current in your region
        instructions="You are a helpful assistant that answers general questions",
    ),
)

Pin your code to the version 2 SDK and its current vocabulary. The new SDK talks about conversations, items, responses, and agent versions, replacing the older threads, messages, runs, and assistants from the classic Assistants API [1]. Model names move quickly, so treat gpt-4.1 as a placeholder and deploy whatever chat model is current and available in your region rather than hardcoding a name that will age [6]. Equivalent samples exist for C#, TypeScript, Java, and REST if Python is not your language, though Python is the one the exam assumes [3][6].

To hold a multi-turn conversation, you create a conversation and then send responses that reference your agent, rather than calling the model directly. Keeping the agent as the unit you invoke, instead of the raw model, is a habit the exam rewards, because it is how tools and tracing attach cleanly later.

Giving your agent tools and grounding

Tools are what turn a chatbot into an agent, and Azure AI Foundry ships a catalogue of them. On its own, your agent only knows what the base model was trained on. Tools let it search the web, read your documents, run code, and call your own functions. Microsoft groups them into knowledge tools, which ground the agent in data, and action tools, which let it do things [7].

The generally available tools you should know for AI-103 are:

• Web Search, the recommended default for grounding an agent in the open web, with no separate resource required [7].
• Grounding with Bing Search and Bing Custom Search, which add domain restriction and more parameters but require a separate Bing resource [7].
• File Search, which runs vector search over documents you upload, so the agent can answer from your own content [7].
• Azure AI Search, which grounds the agent against an existing search index [7].
• Code Interpreter, a sandboxed Python environment for calculation and data work [7].
• Function calling, where the agent decides to call a function you define and your application runs it [7].

Several other tools, including image generation, browser automation, Microsoft Fabric, SharePoint, and agent-to-agent calling, are in preview as of mid-2026 [7]. For exam preparation and for a reliable first build, stay on the generally available tools above and treat preview features as things to be aware of rather than to depend on. One practical caveat from the documentation: web grounding tools act as public endpoints and do not respect a private network or VPN, which matters if you later build in a network-secured environment [7].

Testing, tracing, and evaluating your agent

Testing and observability separate a demo agent from one you would trust in production, and AI-103 covers both. After you build the agent, Microsoft's own lifecycle runs create, test in the playground, trace, evaluate, optimise, publish, and monitor [4]. The middle steps are where most candidates are weakest.

Tracing records what your agent actually did: its inputs and outputs, every tool call, token consumption, and latency. Tracing is generally available for prompt and hosted agents, and Foundry uses OpenTelemetry conventions with traces stored in Azure Monitor Application Insights [8]. That storage is billed separately, so enabling tracing adds a small cost you should expect [8].

Evaluation measures quality rather than just watching behaviour. Foundry provides built-in evaluators so you can score responses for groundedness, relevance, and safety instead of judging by eye. Being able to explain the difference between tracing, which is observability, and evaluation, which is measurement, is the kind of distinction AI-103 questions like to test. For a fuller view of how these fit the exam, our complete AI-103 study guide sets the tutorial in context.

How this maps to the AI-103 skills you will be tested on

Everything you just built maps directly onto the AI-103 skills outline, which is the point of doing it by hand. The exam is not asking you to memorise screenshots, it is asking whether you can build and reason about agents on Foundry. Here is how the tutorial lines up with the measured skills [2].

The one domain this tutorial does not cover is the classic model work, computer vision, text analysis, and information extraction, which together make up around 30 to 45 percent of the exam [2]. Build the agent first, because it anchors the largest single domain, then round out the rest with structured revision and practice questions.

Common mistakes to avoid

Most first-agent problems come from stale guidance, not from difficult concepts. Because Foundry changed names and versions in 2026, the internet is full of instructions that no longer match the product. Watch for these.

• Following a classic-portal tutorial. If a guide references hubs, the Assistants API, or the Azure AI names, it predates the current Foundry and will not match your portal [1]. Check the date and the toggle.
• Mixing SDK versions. The version 2 azure-ai-projects SDK is incompatible with the 1.x SDK [6]. Installing the wrong one produces import errors that look mysterious until you check the version.
• Ignoring quota and region. Deployments fail when a model has no quota in your chosen region, and some models need eligibility approval [5][10]. Read the error message; it usually names the fix.
• Depending on preview tools. Preview features can change without notice [7]. Keep your first build, and your exam answers, on generally available capabilities.
• Treating the model as the agent. Invoke the agent, not the raw model, so tools, tracing, and versioning attach correctly [4][6].

If you would like a full picture of exam-day logistics rather than the build itself, our guide on how to pass the AI-103 exam covers scoring, timing, and preparation strategy.

Frequently Asked Questions

Is Azure AI Foundry the same as Microsoft Foundry?

Yes. Microsoft renamed Azure AI Foundry to Microsoft Foundry in 2026, and the current documentation uses the new name [1]. The product, portal at ai.azure.com, and capabilities are the same. Older tutorials, search results, and the AI-103 skills outline still say Azure AI Foundry, so you will see both names for the same platform.

Do I need to write code to build an agent in Azure AI Foundry?

No. You can build a prompt agent entirely in the Foundry portal by naming it, writing instructions, and testing in the playground, with no application code at all [4]. The Python SDK path exists for developers who want automation, version control, or CI/CD, and AI-103 expects you to be comfortable with both the portal and the SDK [2][6].

Is Azure AI Foundry free to use for the AI-103 exam prep?

Exploring the Foundry portal and playground is free, but any real model or agent call is billed pay-as-you-go from the first token, because "pricing occurs at the deployment level" [1]. New Azure accounts get a general free credit to experiment with [5]. Enabling tracing adds a separate Application Insights cost you should expect [8].

Should I learn Copilot Studio or Azure AI Foundry for AI-103?

Azure AI Foundry. The AI-103 skills outline and audience profile are built around Python and Foundry pro-code development, and Copilot Studio does not appear in the published outline [2][3]. Copilot Studio is the low-code tool tested by exams like AB-620 and AB-730, so learn it for those, but focus on Foundry for AI-103.

Can I use Microsoft Learn during the AI-103 exam?

Yes. Microsoft grants Microsoft Learn access during associate and expert role-based exams, and AI-103 is an associate role-based exam [3][11]. Access to Learn is not available on Fundamentals or GitHub exams [11]. The exam timer keeps running while you search, so treat Learn as a safety net, not a substitute for preparation.

What tools can a Foundry agent use to answer from real data?

A Foundry agent can ground its answers using Web Search or Grounding with Bing for the open web, File Search or Azure AI Search for your own documents and indexes, and Code Interpreter for computation [7]. It can also call your own functions through function calling, letting the agent trigger actions your application executes [7].

Conclusion

Building your first agent in Azure AI Foundry turns the largest AI-103 domain from theory into muscle memory. You have deployed a model, created a prompt agent in the portal and in Python, given it tools, and seen how tracing and evaluation fit around it, which is exactly the work the exam measures [2]. Do it once by hand and the skills outline reads very differently.

The best next step is to repeat this build with your own documents in File Search, then move on to structured revision. Start your preparation with Examinotion's AI-103 practice course, and if you are aiming higher at the architecture level, the AB-100 Agentic AI Architect track builds on the same Foundry foundations. You can compare the full range on the Microsoft AI exams hub.

Sources

1. What is Microsoft Foundry? — Microsoft Learn, accessed 2026-07-06
2. Study guide for Exam AI-103: Developing AI Apps and Agents on Azure — Microsoft Learn, skills measured as of 16 April 2026, accessed 2026-07-06
3. Microsoft Certified: Azure AI Apps and Agents Developer Associate — Microsoft Learn, accessed 2026-07-06
4. What is Microsoft Foundry Agent Service? — Microsoft Learn, accessed 2026-07-06
5. Set up your environment for Foundry Agent Service — Microsoft Learn, accessed 2026-07-06
6. Quickstart: Get started with the Microsoft Foundry SDK — Microsoft Learn, accessed 2026-07-06
7. Agent tools overview for Microsoft Foundry Agent Service — Microsoft Learn, accessed 2026-07-06
8. Agent tracing in Microsoft Foundry — Microsoft Learn, accessed 2026-07-06
9. Choose how to build with Microsoft Foundry — Microsoft Learn, accessed 2026-07-06
10. Quotas and limits for Microsoft Foundry Agent Service — Microsoft Learn, accessed 2026-07-06
11. Exam duration and exam experience — Microsoft Learn, accessed 2026-07-06
12. Microsoft Certified: Azure AI Engineer Associate (AI-102, retired) — Microsoft Learn, accessed 2026-07-06