/translations/hu/03-agentic-design-patterns/code_samples/03-python-agent-framework.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "lesson-intro",
   "metadata": {},
   "source": [
    "# 03. Lecke - Ügynöki Tervezési Minták\n",
    "\n",
    "Ebben a leckében három alapvető tervezési mintát vizsgálunk meg az eredményes mesterséges intelligencia ügynökök létrehozásához:\n",
    "\n",
    "1. **Világos Ügynöki Utasítások** — Precíz, szerepet meghatározó promptok készítése, amelyek irányítják az ügynök viselkedését  \n",
    "2. **Strukturált Kimenet Pydantic Modellekkel** — Biztosítva, hogy az ügynökök kiszámítható, validált adatokat szolgáltassanak  \n",
    "3. **Egyszeres Felelősségű Ügynökök** — Olyan fókuszált ügynökök tervezése, amelyek mindegyike egy feladatot végez jól\n",
    "\n",
    "Minden mintát egy **utazási célpont ajánló** forgatókönyvre alkalmazunk, fokozatosan építve egy rendszert, amely képes javasolni célpontokat, ellenőrizni az elérhetőséget és kezelni a logisztikát.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "setup-header",
   "metadata": {},
   "source": [
    "## Beállítás\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "setup-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install agent-framework azure-ai-projects azure-identity pydantic python-dotenv --quiet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "imports",
   "metadata": {},
   "outputs": [],
   "source": [
    "import logging\n",
    "logging.getLogger(\"agent_framework.foundry\").setLevel(logging.ERROR)\n",
    "\n",
    "import os\n",
    "import asyncio\n",
    "import dotenv\n",
    "from typing import Annotated\n",
    "from pydantic import BaseModel\n",
    "from agent_framework import tool\n",
    "from agent_framework.foundry import FoundryChatClient\n",
    "from azure.identity import DefaultAzureCredential\n",
    "\n",
    "dotenv.load_dotenv(dotenv.find_dotenv())\n",
    "\n",
    "endpoint = os.getenv(\"AZURE_AI_PROJECT_ENDPOINT\")\n",
    "deployment_name = os.getenv(\"AZURE_AI_MODEL_DEPLOYMENT_NAME\")\n",
    "\n",
    "missing = [k for k, v in {\n",
    "    \"AZURE_AI_PROJECT_ENDPOINT\": endpoint,\n",
    "    \"AZURE_AI_MODEL_DEPLOYMENT_NAME\": deployment_name\n",
    "}.items() if not v]\n",
    "\n",
    "if missing:\n",
    "    raise ValueError(\n",
    "        f\"Missing required environment variables: {', '.join(missing)}. \"\n",
    "        \"Please set them as environment variables (e.g., in your .env file or shell environment).\"\n",
    "    )\n",
    "\n",
    "provider = FoundryChatClient(\n",
    "    project_endpoint=endpoint,\n",
    "    model=deployment_name,\n",
    "    credential=DefaultAzureCredential()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "pattern1-header",
   "metadata": {},
   "source": [
    "## Minta 1: Világos Ügynöki Utasítások\n",
    "\n",
    "A leghatásosabb minta egyben a legegyszerűbb is: világos, részletes utasítások írása az ügynök számára.\n",
    "\n",
    "A jó utasítások meghatározzák:\n",
    "- **Ki** az ügynök (személyiség és stílus)\n",
    "- **Mit** kell tennie (lépésről lépésre a feladatok)\n",
    "- **Hogyan** viselkedjen (korlátok és stílus)\n",
    "\n",
    "Az alábbiakban egy utazási concierge ügynököt hozunk létre explicit utasításokkal, amelyek alakítják minden általa adott választ.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "pattern1-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = provider.as_agent(\n",
    "    name=\"TravelConcierge\",\n",
    "    instructions=\"\"\"You are a luxury travel concierge named Alex. Your role is to:\n",
    "1. Understand the traveler's preferences (budget, climate, activities)\n",
    "2. Check destination availability before making recommendations\n",
    "3. Provide detailed, personalized travel suggestions\n",
    "4. Always mention visa requirements and best travel seasons\n",
    "Be warm, professional, and enthusiastic about travel.\"\"\",\n",
    ")\n",
    "\n",
    "response = await agent.run(\n",
    "    \"I'd love a week-long vacation somewhere with great food and history. Budget around $2500.\"\n",
    ")\n",
    "print(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "pattern2-header",
   "metadata": {},
   "source": [
    "## Minta 2: Strukturált kimenet Pydantic modellekkel\n",
    "\n",
    "A szabad formátumú szöveg hasznos a párbeszédhez, de a további rendszereknek strukturált adatokra van szükségük.\n",
    "A **Pydantic modellek** és egy **eszközfüggvény** párosításával képesek vagyunk:\n",
    "\n",
    "- Meghatározni a ügynök kimenetének pontos sémáját\n",
    "- Automatikusan érvényesíteni a válaszokat\n",
    "- Megbízhatóan integrálni az ügynök eredményeit az alkalmazáslogikába\n",
    "\n",
    "Bevezetünk egy eszközt is, amely visszaadja a célállomás adatait, így az ügynök valós adatokra alapozhatja a javaslatait.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "pattern2-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "class DestinationRecommendation(BaseModel):\n",
    "    destination: str\n",
    "    available: bool\n",
    "    best_season: str\n",
    "    highlights: list[str]\n",
    "    estimated_budget_usd: int\n",
    "\n",
    "\n",
    "class TravelRecommendations(BaseModel):\n",
    "    recommendations: list[DestinationRecommendation]\n",
    "    personalized_note: str\n",
    "\n",
    "\n",
    "@tool(approval_mode=\"never_require\")\n",
    "def get_destination_details(destination: Annotated[str, \"The destination to look up\"]) -> str:\n",
    "    \"\"\"Get details about a vacation destination.\"\"\"\n",
    "    details = {\n",
    "        \"Barcelona\": \"Available. Best: May-Jun. Beach, architecture, nightlife. ~$2000/week\",\n",
    "        \"Tokyo\": \"Available. Best: Mar-Apr. Culture, food, technology. ~$2500/week\",\n",
    "        \"Cape Town\": \"Not available. Best: Nov-Mar. Nature, wine, adventure. ~$1800/week\",\n",
    "    }\n",
    "    return details.get(destination, f\"{destination}: No information available.\")\n",
    "\n",
    "\n",
    "structured_agent = provider.as_agent(\n",
    "    name=\"StructuredTravelExpert\",\n",
    "    instructions=\"You are a travel expert. Recommend destinations based on traveler preferences. Use the get_destination_details tool.\",\n",
    "    tools=[get_destination_details],\n",
    ")\n",
    "\n",
    "response = await structured_agent.run(\n",
    "    \"Recommend 3 destinations for a culture-loving traveler with a $2500 budget\"\n",
    ")\n",
    "\n",
    "if response:\n",
    "    print(response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "pattern3-header",
   "metadata": {},
   "source": [
    "## Mintázat 3: Egyfelelősségű Ügynökök\n",
    "\n",
    "Az összetett feladatok előnyös, ha a munkát több, egyetlen felelősségre szakosodott ügynökre osztjuk:\n",
    "\n",
    "- Egy **Úticél Szakértő**, aki ismeri a helyszíneket és az elérhetőséget\n",
    "- Egy **Logisztikai Tervező**, aki kezeli a járatokat, a szállodákat és az útvonalakat\n",
    "\n",
    "Ez tükrözi a szoftvermérnöki elvet, a *felelősségek szétválasztását* — így minden ügynök könnyebben tesztelhető, karbantartható és fejleszthető önállóan.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "pattern3-code",
   "metadata": {},
   "outputs": [],
   "source": [
    "destination_agent = provider.as_agent(\n",
    "    name=\"DestinationExpert\",\n",
    "    tools=[get_destination_details],\n",
    "    instructions=\"\"\"You are a destination research specialist. Your only job is to:\n",
    "1. Evaluate destinations based on traveler preferences\n",
    "2. Check availability using the provided tool\n",
    "3. Return a short ranked list with pros/cons\n",
    "Do NOT discuss flights, hotels, or logistics — another agent handles that.\"\"\",\n",
    ")\n",
    "\n",
    "logistics_agent = provider.as_agent(\n",
    "    name=\"LogisticsPlanner\",\n",
    "    instructions=\"\"\"You are a travel logistics planner. Your only job is to:\n",
    "1. Create a day-by-day itinerary for the chosen destination\n",
    "2. Suggest flight and hotel options within the stated budget\n",
    "3. Note visa requirements and travel insurance recommendations\n",
    "Do NOT recommend destinations — another agent handles that.\"\"\",\n",
    ")\n",
    "\n",
    "# Step 1: Destination Expert picks the best options\n",
    "dest_response = await destination_agent.run(\n",
    "    \"I want a week of culture and food for under $2500. Where should I go?\"\n",
    ")\n",
    "print(\"=== Destination Expert ===\")\n",
    "print(dest_response)\n",
    "\n",
    "# Step 2: Logistics Planner builds the trip plan\n",
    "logistics_response = await logistics_agent.run(\n",
    "    f\"Plan a week-long trip based on this recommendation:\\n{dest_response}\"\n",
    ")\n",
    "print(\"\\n=== Logistics Planner ===\")\n",
    "print(logistics_response)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "summary",
   "metadata": {},
   "source": [
    "## Összefoglaló\n",
    "\n",
    "Ebben a leckében három ügynöki tervezési mintát alkalmaztunk egy utazási ajánló forgatókönyvben:\n",
    "\n",
    "| Minta | Fő gondolat | Előny |\n",
    "|---|---|---|\n",
    "| **Világos utasítások** | Határozzuk meg előre a személyiséget, felelősségeket és korlátokat | Következetes, márkára szabott ügynöki viselkedés |\n",
    "| **Strukturált kimenet** | Használjunk Pydantic modelleket válaszformátumként | Érvényesített, géppel olvasható eredmények |\n",
    "| **Egységes felelősség** | Adjunk minden ügynöknek egy jól fókuszált feladatot | Könnyebb tesztelni, karbantartani és összerakni |\n",
    "\n",
    "Ezek a minták természetesen kombinálhatók — az egységes felelősségű ügynökön belül világos utasításokat és strukturált kimenetet alkalmazva robusztus, éles környezetre kész rendszereket építhetünk.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n\n<!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**Jogi nyilatkozat**:\nEz a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered.\n<!-- CO-OP TRANSLATOR DISCLAIMER END -->\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}