{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f4cf9593",
   "metadata": {},
   "source": [
    "# Lesson 01 - Introduction to AI Agents\n",
    "\n",
    "Welcome to the first lesson in the **AI Agents for Beginners** course!\n",
    "\n",
    "An **AI agent** is a program that uses a large language model (LLM) as its reasoning engine and can take *actions* in the real world — calling APIs, querying databases, or running code — to accomplish a goal on behalf of a user.\n",
    "\n",
    "In this notebook you will build your first agent: a **Travel Agent** that recommends vacation destinations. Along the way you will learn how to:\n",
    "\n",
    "1. Connect to Azure AI Foundry Agent Service using the **Microsoft Agent Framework**.\n",
    "2. Give the agent a **tool** — a plain Python function it can call.\n",
    "3. Run the agent and inspect its response.\n",
    "4. Stream the agent's response token-by-token."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1e2c3d4",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "Before running this notebook, make sure you have:\n",
    "\n",
    "1. **An Azure AI Foundry project** with a deployed chat model (e.g. `gpt-4o-mini`).\n",
    "2. **Logged in with the Azure CLI** — run `az login` in your terminal.\n",
    "3. **Set the required environment variables:**\n",
    "   - `AZURE_AI_PROJECT_ENDPOINT` — your Azure AI Foundry project endpoint.\n",
    "   - `AZURE_AI_MODEL_DEPLOYMENT_NAME` — the name of your deployed model.\n",
    "\n",
    "The cell below installs the Python packages you need."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fda5fa0a",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install agent-framework azure-ai-projects azure-identity -q"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c0df8a52",
   "metadata": {},
   "outputs": [],
   "source": [
    "import logging\n",
    "logging.getLogger(\"agent_framework.azure\").setLevel(logging.ERROR)\n",
    "\n",
    "import os\n",
    "import asyncio\n",
    "from typing import Annotated\n",
    "\n",
    "from agent_framework import tool\n",
    "from agent_framework.azure import AzureAIProjectAgentProvider\n",
    "from azure.identity import AzureCliCredential\n",
    "\n",
    "provider = AzureAIProjectAgentProvider(credential=AzureCliCredential())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5f6a7b8",
   "metadata": {},
   "source": [
    "## Creating Your First Agent\n",
    "\n",
    "An agent needs two things:\n",
    "\n",
    "- **Instructions** that tell it *who it is* and *how to behave* (a system prompt).\n",
    "- **Tools** — Python functions decorated with `@tool` that the agent can call to retrieve information or perform actions.\n",
    "\n",
    "Below we define a simple tool that returns a list of popular vacation destinations. The agent will use this tool when a user asks for travel recommendations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6507f83",
   "metadata": {},
   "outputs": [],
   "source": [
    "@tool(approval_mode=\"never_require\")\n",
    "def get_destinations() -> list[str]:\n",
    "    \"\"\"Get a list of popular vacation destinations.\"\"\"\n",
    "    return [\n",
    "        \"Barcelona\",\n",
    "        \"Paris\",\n",
    "        \"Berlin\",\n",
    "        \"Tokyo\",\n",
    "        \"Sydney\",\n",
    "        \"New York City\",\n",
    "        \"Cairo\",\n",
    "        \"Cape Town\",\n",
    "        \"Rio de Janeiro\",\n",
    "        \"Bali\",\n",
    "    ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cf5a4800",
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = await provider.create_agent(\n",
    "    tools=[get_destinations],\n",
    "    name=\"TravelAgent\",\n",
    "    instructions=(\n",
    "        \"You are a helpful travel agent. Help users find their perfect vacation \"\n",
    "        \"destination based on their preferences. Use the get_destinations tool \"\n",
    "        \"to see available destinations.\"\n",
    "    ),\n",
    ")\n",
    "\n",
    "response = await agent.run(\n",
    "    \"I'm looking for a warm beach destination. What do you recommend?\"\n",
    ")\n",
    "print(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9e0f1a2",
   "metadata": {},
   "source": [
    "## Streaming Responses\n",
    "\n",
    "For a more interactive experience you can **stream** the agent's response. Instead of waiting for the full reply, the agent yields text chunks as they are generated. This is especially useful in chat interfaces where you want to display output in real time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "772e9481",
   "metadata": {},
   "outputs": [],
   "source": [
    "async for chunk in agent.run(\n",
    "    \"Tell me about Tokyo as a travel destination\", stream=True\n",
    "):\n",
    "    print(chunk, end=\"\", flush=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3b4c5d6",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this lesson you learned how to:\n",
    "\n",
    "- **Create a provider** that connects to Azure AI Foundry Agent Service via `AzureAIProjectAgentProvider`.\n",
    "- **Define a tool** using the `@tool` decorator so the agent can call your Python functions.\n",
    "- **Run the agent** with a user message and print its response.\n",
    "- **Stream responses** for real-time output.\n",
    "\n",
    "In the next lesson we will explore agentic frameworks in more depth and learn how to give agents more powerful tools and multi-step reasoning capabilities."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.12.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}