How to Build an AI Agent in Microsoft Foundry: A Step-by-Step Guide

Agents are the defining Azure AI skill of 2026: not a model that answers a question, but a system that plans, calls tools, and completes a multi-step task. This tutorial shows you how to build an AI agent in Microsoft Foundry from an empty subscription to a working, tool-using agent, first in the portal, then in code. It is the hands-on companion to the theory we cover across the SkillTech Azure AI Certification track. If you want the conceptual grounding first, read our primer on agentic AI in Microsoft Azure and what Azure AI Foundry is.

What you will build

A math-tutor AI agent that uses the Code Interpreter tool to run Python, calculate and plot a graph on request. It is deliberately small — the point is to learn the four primitives that every Microsoft Foundry Agent Service project shares: the agent, the thread the run and the tools.

Prerequisites

You need an active Azure subscription (the free tier is enough to follow along), permission to create resources and Python 3.9+ if you want the code path. That is it,  no GPU, no prior deployment.

Step 1 — Create a Foundry project

Go to the Microsoft Foundry portal (ai.azure.com) and choose Create an agent. Give the project a name and accept the defaults. Foundry provisions three things for you in one action: a Foundry resource, a project, and a default model deployment (typically GPT-4o). This is the fastest way to get a working AI agent in Azure without wiring services by hand.

Step 2 — Configure the agent in the playground

When provisioning finishes you land in the Agent playground. Set the instructions, the agent's system prompt  to something precise:

You are a patient math tutor. When a user asks you to
calculate or visualise numbers, use the Code Interpreter
tool. Show the steps, then the final answer.

Clear, scoped instructions matter more than a clever model. Vague instructions are the number one reason a first agent behaves unpredictably.

Step 3 — Attach a tool

In the playground's tools panel, enable Code Interpreter. This gives the agent a sandboxed Python runtime it can call on its own when a task needs real computation. Other tools you will meet later include File Search (grounding on your documents), Function calling (your own APIs) and web grounding for current information.

Step 4 — Test in the portal

Type: "Draw a graph for a line with slope 4 and y-intercept 9." Watch the agent decide to invoke Code Interpreter, run the Python and return both the explanation and the plotted image. You have just observed the plan-act-respond loop that defines an agent. This portal test is the fastest way to prototype before you write a single line of code.

Step 5 — Recreate it in code (Python)

The portal is for prototyping; production agents live in code. Grab your project endpoint from the project Overview page, then:

pip install azure-ai-projects azure-identity
az login

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import CodeInterpreterTool

client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with client:
    tool = CodeInterpreterTool()
    agent = client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],   # e.g. gpt-4o
        name="math-tutor",
        instructions="You are a patient math tutor. Use Code Interpreter to calculate and plot.",
        tools=tool.definitions,
        tool_resources=tool.resources,
    )

    thread = client.agents.threads.create()
    client.agents.messages.create(
        thread_id=thread.id, role="user",
        content="Draw a graph for a line with slope 4 and y-intercept 9",
    )

    run = client.agents.runs.create_and_process(
        thread_id=thread.id, agent_id=agent.id,
    )
    print("Run status:", run.status)

    for m in client.agents.messages.list(thread_id=thread.id):
        print(m.role, ":", m.content)

Run it. The create_and_process call handles the full run lifecycle — queuing, tool execution and completion — so you get the finished conversation back in one call. That maps exactly to the agent/thread/run/tools model from the table above.

Cost and hygiene: agents, threads and model calls are billable. Delete test agents when done (client.agents.delete_agent(agent.id)) and set a budget alert in Azure Cost Management. Treat keys and endpoints as secrets,  use DefaultAzureCredential and Key Vault, never hard-coded strings.

Step 6 — Make it production-worthy

Three upgrades separate a demo from a real deployment: grounding (attach File Search or Azure AI Search so answers cite your data), observability (enable tracing to inspect each tool call) and evaluation (score responses for accuracy and safety before shipping). Microsoft's current Foundry Agent Service quickstart and Foundry documentation track the latest SDK names and the migration path as the platform evolves.

How this maps to certifications

Agent-building is now examined directly. The developer-focused AI-103 (Azure AI Apps and Agents Developer) and the dedicated AI Agent certification both assess these exact primitives, and our AI-103 study guide shows how to prepare. Doing the lab first makes the theory obvious.

Common first-agent mistakes to avoid

Four mistakes account for most stuck beginners.

1) Vague instructions - an agent told to "be helpful" will wander; scope it to one job. 

2) Over-tooling - attach only the tools the task needs, because every extra tool widens the space of things that can go wrong.

3) Ignoring cost - leaving test agents and threads alive quietly burns tokens; clean up after every session. 

4) Skipping evaluation — never promote an agent to users without checking its outputs for accuracy and safety on a fixed set of test prompts. 

Frequently asked questions

Do I need to know machine learning to build an agent?

No. You consume a hosted model; you do not train one. Solid Python and clear prompt design get you a long way.

Portal or SDK — which should I use?

Prototype in the playground, then move to the SDK for version control, testing, and deployment. They target the same underlying service.

Conclusion

Building an agent in Microsoft Foundry Portal shifts your mindset from "prompting a model" to "orchestrating a system." By mastering the four primitives - the agent, the thread, the run and the tools - you move past basic chatbots and start building AI that can independently plan, execute code and solve multi-step problems. The math-tutor agent is just the beginning. The exact same architecture scales up to enterprise agents that search secure corporate databases, call internal HR functions, or govern web research.

Ready to build production-grade AI?

If you want to turn this baseline knowledge into a recognized credential, the developer-focused AI-103 Certification is your next target. 

Start the AI-103 track today, and let's get your first production agent deployed.