Azure-AI_Foundry

Module 6: AI Agents with Azure AI Agent Service

Learning Objectives

By the end of this module, you will be able to:

Explain what AI agents are and how they differ from chat completions
Create and manage agents using the Azure AI Agent Service
Equip agents with built-in and custom tools
Orchestrate multi-agent workflows with handoff patterns
Apply safety guardrails to agent systems

What Are AI Agents?

AI agents are autonomous systems that use a large language model (LLM) as their reasoning engine to plan, execute, and adapt actions toward a goal. Unlike a simple chat completion call — where you send a prompt and get a response — an agent can:

Maintain persistent context across a conversation (threads)
Invoke tools (code interpreter, file search, APIs, functions) to take real actions
Operate in a run loop where the model decides what to do next
Handle multi-step tasks without constant human instruction

📖 Official docs: Azure AI Agent Service overview

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                   Azure AI Foundry Project               │
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────┐   │
│  │  Agent    │    │  Thread  │    │   Tool Resources │   │
│  │          │    │          │    │                  │   │
│  │ - Model  │◄──►│ - Msgs   │    │ - Code Interp.   │   │
│  │ - Instrs │    │ - Context│    │ - File Search    │   │
│  │ - Tools  │    │          │    │ - Bing Search    │   │
│  └────┬─────┘    └────┬─────┘    │ - Functions      │   │
│       │               │          │ - Azure AI Search │   │
│       │               │          │ - OpenAPI         │   │
│       ▼               ▼          └────────┬─────────┘   │
│  ┌─────────────────────────────────────────┐            │
│  │                  Run                     │            │
│  │                                         │            │
│  │  1. Read thread messages                │            │
│  │  2. LLM decides next action             │            │
│  │  3. Call tools if needed                │            │
│  │  4. Append assistant message            │            │
│  │  5. Repeat or complete                  │            │
│  └─────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────┘

Agent vs Chat Completion — When to Use What

Feature	Chat Completions	AI Agents
State management	Stateless — you manage history	Stateful — threads persist automatically
Tool execution	You implement the tool loop	Agent service handles the loop
Multi-step reasoning	Manual orchestration	Autonomous run lifecycle
File handling	Manual upload/parsing	Built-in Code Interpreter & File Search
Cost model	Pay per token	Pay per token + tool execution
Latency	Single round-trip	Multiple round-trips (run loop)
Best for	Simple Q&A, structured output	Complex tasks, data analysis, research

Decision Guide

Use Chat Completions when you need:

Low-latency, single-turn responses
Full control over the conversation loop
Simple function calling with predictable flows

Use AI Agents when you need:

Multi-step task execution with tool use
Persistent conversation threads
File analysis, code execution, or web search
The model to decide which tools to call and when

Quick Start Example

"""Minimal agent example — create, run, read, cleanup."""
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import AgentThreadCreationOptions

# 1. Connect to your Azure AI Foundry project
client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

# 2. Create an agent
agent = client.agents.create_agent(
    model=os.environ.get("MODEL_DEPLOYMENT", "gpt-4o"),
    name="hello-agent",
    instructions="You are a helpful assistant that answers questions concisely.",
)
print(f"Agent created: {agent.id}")

# 3. Create a thread and add a user message
thread = client.agents.create_thread()
client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="What are three benefits of using AI agents over raw chat completions?",
)

# 4. Run the agent
run = client.agents.create_and_process_run(
    thread_id=thread.id,
    agent_id=agent.id,
)
print(f"Run status: {run.status}")

# 5. Read the response
messages = client.agents.list_messages(thread_id=thread.id)
for msg in reversed(messages.data):
    if msg.role == "assistant":
        print(f"Agent: {msg.content[0].text.value}")

# 6. Cleanup
client.agents.delete_agent(agent.id)
print("Agent deleted.")

Prerequisites

pip install azure-ai-projects azure-identity

Set the environment variable:

PROJECT_ENDPOINT=https://<your-hub>.services.ai.azure.com/api/projects/<project-name>

💡 Tip: Use create_and_process_run() for simple cases — it blocks until the run completes. For production, use create_run() + polling or streaming (covered in Lesson 1).

Module Roadmap

Lesson	Title	Topics
Lesson 1	Agent Fundamentals	Agent anatomy, threads, runs, lifecycle, streaming
Lesson 2	Agent Tools	Code Interpreter, File Search, Bing, Functions, OpenAPI
Lesson 3	Multi-Agent Orchestration	Handoff patterns, Semantic Kernel, AutoGen, safety
Knowledge Check	Knowledge Check	15 scenario-based review questions

Key Terminology

Term	Definition
Agent	A configured entity with a model, instructions, and tools
Thread	A conversation session that persists messages and context
Message	A single user or assistant turn within a thread
Run	An invocation of an agent on a thread — the execution lifecycle
Tool	A capability the agent can invoke (code interpreter, function, etc.)
Run Step	A granular record of what the agent did during a run

Additional Resources

Next → Lesson 1: Agent Fundamentals