Azure AI Foundry Tutorials - Build Agent with Azure AI Foundry SDK

In previous tutorial we had created an agent using Azure AI Foundry. In this tutorial we will be creating a simple azure ai agent using azure ai foundry sdk. We will be making use of the same azure ai foundry project we had created in previous tutorial.

Azure AI Agents - Table of Contents

Azure AI Foundry Hello World Example Azure AI Foundry - Azure AI Agent Hello World Example Azure AI Foundry - Foundry vs Hub Based Projects Azure AI Foundry - Build Agent with Azure AI Foundry SDK Azure AI Foundry - Bing Web Search Agent

Chat Completions API

When Azure OpenAI was first introduced, nearly everything revolved around one powerful API: the Chat Completions API. This API enabled developers to build back-and-forth conversational experiences by sending messages to a GPT model and receiving responses. However, it soon became clear that a basic chat interface alone was not enough to deliver real business value or strong ROI.

Assistants API and early agent patterns

As expectations grew, the industry moved toward agent-like systems-AI that could reason, use tools, retrieve files, execute code, and perform tasks autonomously. This led to the introduction of the Assistants API, which was the precursor to today's Azure AI Agent Service and Azure AI Foundry SDK. The Assistants API introduced important concepts such as:

Tool calling and function execution
File search and retrieval
Code interpreter capabilities

However, it had significant limitations:

Tightly coupled to OpenAI GPT models only
The API structure was complex and verbose
Even simple agent workflows required large, messy codebases
Extending agents with enterprise systems was cumbersome

In short, while powerful, the Assistants API was hard to use, hard to scale, and hard to maintain.

Azure AI Agent Service + Foundry SDK

Azure has taken those learnings and delivered a much more mature, enterprise-ready solution through the Azure AI Agent Service and Azure AI Foundry SDK. The Azure AI Foundry SDK:

Fully abstracts the complexity of the Assistants API
Supports multiple model providers, not just OpenAI
Lets you build agents using the model of your choice
Integrates seamlessly with enterprise data sources like SharePoint and Microsoft Fabric
Supports OpenAPI tools, Azure Functions, Azure Logic Apps, and more
Provides built-in evaluation, debugging, safety, and monitoring tools

Implementation

Do remember, that azure foundry sdk there are many changes regularly. So do take reference of the documentation - Azure Python SDK Documentation
Let us create a new Python project for our AI agent.

Agent SDK Output

Step 1: Create a project directory and navigate to it

mkdir azure-agent-sdk
cd azure-agent-sdk

Step 2: Create a virtual environment

# On Windows
python -m venv venv
.\venv\Scripts\Activate.ps1

Step 3: Install required packages

pip install azure-ai-agents==1.1.0
pip install azure-identity==1.20.0
pip install python-dotenv==1.0.1

These are the core packages we need:

azure-ai-agents - The main SDK for working with Azure AI agents
azure-identity - For authentication with Azure
python-dotenv - To load environment variables from .env file

Step 4: Create a requirements.txt file for future reference

azure-ai-agents==1.1.0
azure-core==1.32.0
azure-identity==1.20.0
python-dotenv==1.0.1

Configuration - Setting Up Environment Variables

We need to configure two important pieces of information: the Azure AI endpoint and the model deployment name. Create a .env file in your project directory:

MODEL_DEPLOYMENT_NAME="gpt-4o"
AZURE_AI_ENDPOINT="https://new-foundry-ai-project--resource.services.ai.azure.com/api/projects/new-foundry-ai-project-1"

Authentication with Azure

The Azure AI Foundry SDK uses Azure authentication to connect to your project. There are two common ways to authenticate:

Option 1: Using Azure CLI (Recommended for Development)

This is the simplest method for local development. Just make sure you are logged in with Azure CLI:

# Login to Azure
az login

# Verify you are logged in
az account show

# Set the correct subscription if you have multiple
az account set --subscription "your-subscription-id"

Then in your Python code, use DefaultAzureCredential which will automatically use your Azure CLI credentials:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential(
    exclude_environment_credential=True  # Skip env variables, use Azure CLI
)

Creating Your First Agent with SDK

Now let us write the Python code to create an agent. Create a file called agent.py:

import os
import time
from azure.ai.agents import AgentsClient
from azure.ai.agents.models import ListSortOrder
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Get configuration from environment variables
endpoint = os.getenv("AZURE_AI_ENDPOINT")
model_deployment = os.getenv("MODEL_DEPLOYMENT_NAME")

# Create the AgentsClient with authentication
agents_client = AgentsClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(exclude_environment_credential=True)
)

print("Connected to Azure AI Foundry")

# Create an agent
agent = agents_client.create_agent(
    model=model_deployment,
    name="my-agent",
    instructions="You are a helpful agent"
)

print(f"Created agent: {agent.id}")

# Create a thread (conversation)
thread = agents_client.threads.create()
print(f"Created thread: {thread.id}")

# Send a message to the agent
message = agents_client.messages.create(
    thread_id=thread.id,
    role="user",
    content="Hello, tell me a joke"
)
print(f"Created message: {message.id}")

# Run the agent to process the message
run = agents_client.runs.create(
    thread_id=thread.id,
    agent_id=agent.id
)

print(f"Started run: {run.id}")

# Poll until the run completes
while run.status in ["queued", "in_progress", "requires_action"]:
    time.sleep(1)
    run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
    print(f"Run status: {run.status}")

print(f"Run completed with status: {run.status}")

# Get all messages from the thread
messages = agents_client.messages.list(
    thread_id=thread.id,
    order=ListSortOrder.ASCENDING
)

# Print the conversation
print("\n=== Conversation ===")
for msg in messages:
    if msg.text_messages:
        last_text = msg.text_messages[-1]
        print(f"{msg.role}: {last_text.text.value}")

Running the Code

Make sure you are in your virtual environment and run:

python agent.py

You should see output similar to:

(venv) PS E:\agents\1> python .\azure-agent-sdk\agent.py
Connected to Azure AI Foundry
Created agent: asst_YyjFxFfXcIWcGIva4e0reYYv
Created thread: thread_FEpl5IyR34ngv8wmaG1aRYne
Created message: msg_9SW9Vam1OV88b2vwFxRwI3be
Started run: run_TsmIjou23c1sdFB3vPnlToyd
Run status: RunStatus.COMPLETED
Run completed with status: RunStatus.COMPLETED

=== Conversation ===
MessageRole.USER: Hello, tell me a joke
MessageRole.AGENT: Sure! Here's a light one:

Why don't skeletons fight each other?

Because they don't have the guts!

Download Source Code

Download it -
Build Agent with Azure AI Foundry SDK

Search Tutorials