AI Agents with Azure Developer CLI

Chapter Navigation:

📚 Course Home: AZD For Beginners
📖 Current Chapter: Chapter 2 - AI-First Development
⬅️ Previous: Microsoft Foundry Integration
➡️ Next: AI Model Deployment
🚀 Advanced: Multi-Agent Solutions

Introduction

AI agents are autonomous programs that can perceive their environment, make decisions, and take actions to achieve specific goals. Unlike simple chatbots that respond to prompts, agents can:

Use tools - Call APIs, search databases, execute code
Plan and reason - Break complex tasks into steps
Learn from context - Maintain memory and adapt behavior
Collaborate - Work with other agents (multi-agent systems)

This guide shows you how to deploy AI agents to Azure using Azure Developer CLI (azd).

Validation note (2026-03-25): This guide was reviewed against azd 1.23.12 and azure.ai.agents 0.1.18-preview. The azd ai experience is still preview-driven, so check extension help if your installed flags differ.

Learning Goals

By completing this guide, you will:

Understand what AI agents are and how they differ from chatbots
Deploy pre-built AI agent templates using AZD
Configure Foundry Agents for custom agents
Implement basic agent patterns (tool use, RAG, multi-agent)
Monitor and debug deployed agents

Learning Outcomes

Upon completion, you will be able to:

Deploy AI agent applications to Azure with a single command
Configure agent tools and capabilities
Implement retrieval-augmented generation (RAG) with agents
Design multi-agent architectures for complex workflows
Troubleshoot common agent deployment issues

🤖 What Makes an Agent Different from a Chatbot?

Feature	Chatbot	AI Agent
Behavior	Responds to prompts	Takes autonomous actions
Tools	None	Can call APIs, search, execute code
Memory	Session-based only	Persistent memory across sessions
Planning	Single response	Multi-step reasoning
Collaboration	Single entity	Can work with other agents

Simple Analogy

Chatbot = A helpful person answering questions at an information desk
AI Agent = A personal assistant who can make calls, book appointments, and complete tasks for you

🚀 Quick Start: Deploy Your First Agent

Option 1: Foundry Agents Template (Recommended)

# Initialize the AI agents template
azd init --template get-started-with-ai-agents

# Deploy to Azure
azd up

What gets deployed:

✅ Foundry Agents
✅ Microsoft Foundry Models (gpt-4.1)
✅ Azure AI Search (for RAG)
✅ Azure Container Apps (web interface)
✅ Application Insights (monitoring)

Time: ~15-20 minutes Cost: ~$100-150/month (development)

Option 2: OpenAI Agent with Prompty

# Initialize the Prompty-based agent template
azd init --template agent-openai-python-prompty

# Deploy to Azure
azd up

What gets deployed:

✅ Azure Functions (serverless agent execution)
✅ Microsoft Foundry Models
✅ Prompty configuration files
✅ Sample agent implementation

Time: ~10-15 minutes Cost: ~$50-100/month (development)

Option 3: RAG Chat Agent

# Initialize RAG chat template
azd init --template azure-search-openai-demo

# Deploy to Azure
azd up

What gets deployed:

✅ Microsoft Foundry Models
✅ Azure AI Search with sample data
✅ Document processing pipeline
✅ Chat interface with citations

Time: ~15-25 minutes Cost: ~$80-150/month (development)

Option 4: AZD AI Agent Init (Manifest- or Template-Based Preview)

If you have an agent manifest file, you can use the azd ai command to scaffold a Foundry Agent Service project directly. Recent preview releases also added template-based initialization support, so the exact prompt flow may differ slightly depending on your installed extension version.

# Install the AI agents extension
azd extension install azure.ai.agents

# Optional: verify the installed preview version
azd extension show azure.ai.agents

# Initialize from an agent manifest
azd ai agent init -m agent-manifest.yaml

# Deploy to Azure
azd up

When to use azd ai agent init vs azd init --template:

Approach	Best For	How It Works
`azd init --template`	Starting from a working sample app	Clones a full template repo with code + infra
`azd ai agent init -m`	Building from your own agent manifest	Scaffolds project structure from your agent definition

Tip: Use azd init --template when learning (Options 1-3 above). Use azd ai agent init when building production agents with your own manifests. See AZD AI CLI Commands for full reference.

🏗️ Agent Architecture Patterns

Pattern 1: Single Agent with Tools

The simplest agent pattern - one agent that can use multiple tools.

graph TD
    UI[User Interface] --> Agent[AI Agent<br/>gpt-4.1]
    Agent --> Search[Search Tool]
    Agent --> Database[Database Tool]
    Agent --> API[API Tool]

Best for:

Customer support bots
Research assistants
Data analysis agents

AZD Template: azure-search-openai-demo

Pattern 2: RAG Agent (Retrieval-Augmented Generation)

An agent that retrieves relevant documents before generating responses.

graph TD
    Query[User Query] --> RAG[RAG Agent]
    RAG --> Vector[Vector Search]
    RAG --> LLM[LLM<br/>gpt-4.1]
    Vector -- Documents --> LLM
    LLM --> Response[Response with Citations]

Best for:

Enterprise knowledge bases
Document Q&A systems
Compliance and legal research

AZD Template: azure-search-openai-demo

Pattern 3: Multi-Agent System

Multiple specialized agents working together on complex tasks.

graph TD
    Orchestrator[Orchestrator Agent] --> Research[Research Agent<br/>gpt-4.1]
    Orchestrator --> Writer[Writer Agent<br/>gpt-4.1-mini]
    Orchestrator --> Reviewer[Reviewer Agent<br/>gpt-4.1]

Best for:

Complex content generation
Multi-step workflows
Tasks requiring different expertise

Learn More: Multi-Agent Coordination Patterns

⚙️ Configuring Agent Tools

Agents become powerful when they can use tools. Here's how to configure common tools:

Tool Configuration in Foundry Agents

# agent_config.py
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FunctionTool, CodeInterpreterTool

# Define custom tools
search_tool = FunctionTool(
    name="search_knowledge_base",
    description="Search the company knowledge base for relevant documents",
    parameters={
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query"
            }
        },
        "required": ["query"]
    }
)

# Create agent with tools
agent = project_client.agents.create_agent(
    model="gpt-4.1",
    name="Support Agent",
    instructions="You are a helpful support agent. Use the search tool to find relevant information.",
    tools=[search_tool, CodeInterpreterTool()]
)

Environment Configuration

# Set up agent-specific environment variables
azd env set AZURE_OPENAI_MODEL "gpt-4.1"
azd env set AGENT_INSTRUCTIONS "You are a helpful assistant..."
azd env set ENABLE_CODE_INTERPRETER "true"
azd env set ENABLE_FILE_SEARCH "true"

# Deploy with updated configuration
azd deploy

📊 Monitoring Agents

Application Insights Integration

All AZD agent templates include Application Insights for monitoring:

# Open monitoring dashboard
azd monitor --overview

# View live logs
azd monitor --logs

# View live metrics
azd monitor --live

Key Metrics to Track

Metric	Description	Target
Response Latency	Time to generate response	< 5 seconds
Token Usage	Tokens per request	Monitor for cost
Tool Call Success Rate	% of successful tool executions	> 95%
Error Rate	Failed agent requests	< 1%
User Satisfaction	Feedback scores	> 4.0/5.0

Custom Logging for Agents

import os
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

# Configure Azure Monitor with OpenTelemetry
configure_azure_monitor(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

tracer = trace.get_tracer(__name__)

def log_agent_interaction(user_query, agent_response, tools_used, latency_ms):
    with tracer.start_as_current_span("agent_interaction") as span:
        span.set_attributes({
            "user_query": user_query,
            "response_length": len(agent_response),
            "tools_used": tools_used,
            "latency_ms": latency_ms
        })

Note: Install the required packages: pip install azure-monitor-opentelemetry opentelemetry

💰 Cost Considerations

Estimated Monthly Costs by Pattern

Pattern	Dev Environment	Production
Single Agent	$50-100	$200-500
RAG Agent	$80-150	$300-800
Multi-Agent (2-3 agents)	$150-300	$500-1,500
Enterprise Multi-Agent	$300-500	$1,500-5,000+

Cost Optimization Tips

Use gpt-4.1-mini for simple tasks

azd env set AZURE_OPENAI_MODEL "gpt-4.1-mini"

Implement caching for repeated queries

from functools import lru_cache

@lru_cache(maxsize=1000)
def get_cached_response(query_hash):
    return agent.run(query_hash)

Set token limits per run

# Set max_completion_tokens when running the agent, not during creation
run = project_client.agents.create_run(
    thread_id=thread.id,
    agent_id=agent.id,
    max_completion_tokens=1000  # Limit response length
)

Scale to zero when not in use

# Container Apps automatically scale to zero
azd env set MIN_REPLICAS "0"

🔧 Troubleshooting Agents

Common Issues and Solutions

❌ Agent not responding to tool calls

# Check if tools are properly registered
azd show

# Verify OpenAI deployment
az cognitiveservices account deployment list \
  --name $AZURE_OPENAI_NAME \
  --resource-group $RG_NAME

# Check agent logs
azd monitor --logs

Common causes:

Tool function signature mismatch
Missing required permissions
API endpoint not accessible

❌ High latency in agent responses

# Check Application Insights for bottlenecks
azd monitor --live

# Consider using a faster model
azd env set AZURE_OPENAI_MODEL "gpt-4.1-mini"
azd deploy

Optimization tips:

Use streaming responses
Implement response caching
Reduce context window size

❌ Agent returning incorrect or hallucinated information

# Improve with better system prompts
instructions = """
You are a helpful assistant. IMPORTANT:
- Only answer based on provided context
- If you don't know, say "I don't know"
- Always cite your sources
- Never make up information
"""

# Add retrieval for grounding
agent = project_client.agents.create_agent(
    model="gpt-4.1",
    instructions=instructions,
    tools=[FileSearchTool()]  # Ground responses in documents
)

❌ Token limit exceeded errors

# Implement context window management
def truncate_context(messages, max_tokens=8000, model="gpt-4.1"):
    """Keep only recent messages within token limit."""
    import tiktoken
    encoding = tiktoken.encoding_for_model(model)
    total_tokens = 0
    truncated = []
    
    for msg in reversed(messages):
        msg_tokens = len(encoding.encode(msg.content))
        if total_tokens + msg_tokens > max_tokens:
            break
        truncated.insert(0, msg)
        total_tokens += msg_tokens
    
    return truncated

🎓 Hands-On Exercises

Exercise 1: Deploy a Basic Agent (20 minutes)

Goal: Deploy your first AI agent using AZD

# Step 1: Initialize template
azd init --template get-started-with-ai-agents

# Step 2: Login to Azure
azd auth login
# If you work across tenants, add --tenant-id <tenant-id>

# Step 3: Deploy
azd up

# Step 4: Test the agent
# Expected output after deployment:
#   Deployment Complete!
#   Endpoint: https://<app-name>.<region>.azurecontainerapps.io
# Open the URL shown in the output and try asking a question

# Step 5: View monitoring
azd monitor --overview

# Step 6: Clean up
azd down --force --purge

Success Criteria:

Agent responds to questions
Can access monitoring dashboard via azd monitor
Resources cleaned up successfully

Exercise 2: Add a Custom Tool (30 minutes)

Goal: Extend an agent with a custom tool

Deploy the agent template:

azd init --template get-started-with-ai-agents
azd up

Create a new tool function in your agent code:

def get_weather(location: str) -> str:
    """Get current weather for a location."""
    # API call to weather service
    return f"Weather in {location}: Sunny, 72°F"

from azure.ai.projects.models import FunctionTool

weather_tool = FunctionTool(
    name="get_weather",
    description="Get current weather for a location",
    parameters={
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
    }
)

agent = project_client.agents.create_agent(
    model="gpt-4.1",
    name="Weather Agent",
    tools=[weather_tool]
)

Redeploy and test:

azd deploy
# Ask: "What's the weather in Seattle?"
# Expected: Agent calls get_weather("Seattle") and returns weather info

Success Criteria:

Agent recognizes weather-related queries
Tool is called correctly
Response includes weather information

Exercise 3: Build a RAG Agent (45 minutes)

Goal: Create an agent that answers questions from your documents

# Step 1: Deploy RAG template
azd init --template azure-search-openai-demo
azd up

# Step 2: Upload your documents
# Place PDF/TXT files in the data/ directory, then run:
python scripts/prepdocs.py

# Step 3: Test with domain-specific questions
# Open the web app URL from the azd up output
# Ask questions about your uploaded documents
# Responses should include citation references like [doc.pdf]

Success Criteria:

Agent answers from uploaded documents
Responses include citations
No hallucination on out-of-scope questions

📚 Next Steps

Now that you understand AI agents, explore these advanced topics:

Topic	Description	Link
Multi-Agent Systems	Build systems with multiple collaborating agents	Retail Multi-Agent Example
Coordination Patterns	Learn orchestration and communication patterns	Coordination Patterns
Production Deployment	Enterprise-ready agent deployment	Production AI Practices
Agent Evaluation	Test and evaluate agent performance	AI Troubleshooting
AI Workshop Lab	Hands-on: Make your AI solution AZD-ready	AI Workshop Lab

📖 Additional Resources

Official Documentation

AZD Templates for Agents

Community Resources

Agent Skills for Your Editor

Microsoft Azure Agent Skills - Install reusable AI agent skills for Azure development in GitHub Copilot, Cursor, or any supported agent. Includes skills for Azure AI, Microsoft Foundry, deployment, and diagnostics:
```
npx skills add microsoft/github-copilot-for-azure
```

Navigation

Previous Lesson: Microsoft Foundry Integration
Next Lesson: AI Model Deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

AI Agents with Azure Developer CLI

Introduction

Learning Goals

Learning Outcomes

🤖 What Makes an Agent Different from a Chatbot?

Simple Analogy

🚀 Quick Start: Deploy Your First Agent

Option 1: Foundry Agents Template (Recommended)

Option 2: OpenAI Agent with Prompty

Option 3: RAG Chat Agent

Option 4: AZD AI Agent Init (Manifest- or Template-Based Preview)

🏗️ Agent Architecture Patterns

Pattern 1: Single Agent with Tools

Pattern 2: RAG Agent (Retrieval-Augmented Generation)

Pattern 3: Multi-Agent System

⚙️ Configuring Agent Tools

Tool Configuration in Foundry Agents

Environment Configuration

📊 Monitoring Agents

Application Insights Integration

Key Metrics to Track

Custom Logging for Agents

💰 Cost Considerations

Estimated Monthly Costs by Pattern

Cost Optimization Tips

🔧 Troubleshooting Agents

Common Issues and Solutions

🎓 Hands-On Exercises

Exercise 1: Deploy a Basic Agent (20 minutes)

Exercise 2: Add a Custom Tool (30 minutes)

Exercise 3: Build a RAG Agent (45 minutes)

📚 Next Steps

📖 Additional Resources

Official Documentation

AZD Templates for Agents

Community Resources

Agent Skills for Your Editor

FilesExpand file tree

agents.md

Latest commit

History

agents.md

File metadata and controls

AI Agents with Azure Developer CLI

Introduction

Learning Goals

Learning Outcomes

🤖 What Makes an Agent Different from a Chatbot?

Simple Analogy

🚀 Quick Start: Deploy Your First Agent

Option 1: Foundry Agents Template (Recommended)

Option 2: OpenAI Agent with Prompty

Option 3: RAG Chat Agent

Option 4: AZD AI Agent Init (Manifest- or Template-Based Preview)

🏗️ Agent Architecture Patterns

Pattern 1: Single Agent with Tools

Pattern 2: RAG Agent (Retrieval-Augmented Generation)

Pattern 3: Multi-Agent System

⚙️ Configuring Agent Tools

Tool Configuration in Foundry Agents

Environment Configuration

📊 Monitoring Agents

Application Insights Integration

Key Metrics to Track

Custom Logging for Agents

💰 Cost Considerations

Estimated Monthly Costs by Pattern

Cost Optimization Tips

🔧 Troubleshooting Agents

Common Issues and Solutions

🎓 Hands-On Exercises

Exercise 1: Deploy a Basic Agent (20 minutes)

Exercise 2: Add a Custom Tool (30 minutes)

Exercise 3: Build a RAG Agent (45 minutes)

📚 Next Steps

📖 Additional Resources

Official Documentation

AZD Templates for Agents

Community Resources

Agent Skills for Your Editor