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

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "lesson-intro",
   "metadata": {},
   "source": [
    "# درس ۰۳ - الگوهای طراحی عامل محور\n",
    "\n",
    "در این درس، سه الگوی طراحی پایه برای ساخت عامل‌های هوش مصنوعی مؤثر را بررسی می‌کنیم:\n",
    "\n",
    "1. **دستورات واضح برای عامل** — ساخت درخواست‌های دقیق و تعریف‌کننده نقش که رفتار عامل را هدایت می‌کنند  \n",
    "2. **خروجی ساختاریافته با مدل‌های Pydantic** — اطمینان از اینکه عامل‌ها داده‌های پیش‌بینی‌پذیر و اعتبارسنجی‌شده بازمی‌گردانند  \n",
    "3. **عامل‌های با مسئولیت واحد** — طراحی عامل‌های متمرکز که هرکدام یک کار را به خوبی انجام می‌دهند\n",
    "\n",
    "ما هر الگو را روی سناریوی **توصیه‌گر مقصد سفر** اعمال خواهیم کرد و به‌صورت مرحله‌به‌مرحله سیستمی می‌سازیم که بتواند مقصدها را پیشنهاد دهد، دسترسی را بررسی کند و امور لجستیکی را مدیریت کند.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "setup-header",
   "metadata": {},
   "source": [
    "## راه‌اندازی\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": [
    "## الگو ۱: دستورالعمل‌های واضح برای نماینده\n",
    "\n",
    "تأثیرگذارترین الگو، ساده‌ترین آن نیز هست: نوشتن دستورالعمل‌های واضح و دقیق برای نماینده شما.\n",
    "\n",
    "دستورالعمل‌های خوب مشخص می‌کنند:\n",
    "- **چه کسی** نماینده است (شخصیت و لحن)\n",
    "- **چه کاری** باید انجام دهد (وظایف گام به گام)\n",
    "- **چگونه** باید رفتار کند (محدودیت‌ها و سبک)\n",
    "\n",
    "در زیر، یک نماینده متصدی سفر ایجاد می‌کنیم با دستورالعمل‌های صریح که هر پاسخی که تولید می‌کند را شکل می‌دهد.\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": [
    "## الگو ۲: خروجی ساختاریافته با مدل‌های Pydantic\n",
    "\n",
    "متن آزاد برای گفتگو کاربردی است، اما سیستم‌های پایین‌دستی به داده‌های ساختاریافته نیاز دارند.  \n",
    "با جفت‌کردن **مدل‌های Pydantic** با یک **تابع ابزار**، ما می‌توانیم:\n",
    "\n",
    "- یک طرحواره دقیق برای خروجی عامل تعریف کنیم  \n",
    "- پاسخ‌ها را به‌طور خودکار اعتبارسنجی کنیم  \n",
    "- نتایج عامل را به‌طور قابل اطمینان در منطق برنامه ادغام کنیم  \n",
    "\n",
    "ما همچنین ابزاری معرفی می‌کنیم که جزئیات مقصد را بازمی‌گرداند تا عامل توصیه‌های خود را بر داده‌های واقعی پایه‌گذاری کند.\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": [
    "## الگو ۳: نمایندگان مسئولیت تک\n",
    "\n",
    "وظایف پیچیده با تقسیم کار بین چند نماینده متمرکز که هرکدام یک مسئولیت دارند، بهتر انجام می‌شود:\n",
    "\n",
    "- یک **کارشناس مقصد** که درباره مکان‌ها و دسترسی‌ها اطلاع دارد\n",
    "- یک **برنامه‌ریز لجستیک** که پروازها، هتل‌ها و برنامه‌های سفر را مدیریت می‌کند\n",
    "\n",
    "این مشابه اصل مهندسی نرم‌افزار *تفکیک وظایف* است — هر نماینده به‌صورت مستقل آزمایش، نگهداری و بهبود می‌یابد.\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": [
    "## خلاصه\n",
    "\n",
    "در این درس سه الگوی طراحی عامل‌محور را در سناریوی توصیه‌گر سفر به کار بردیم:\n",
    "\n",
    "| الگو | ایده کلیدی | مزیت |\n",
    "|---|---|---|\n",
    "| **دستورالعمل‌های روشن** | تعریف پرسونای عامل، مسئولیت‌ها و محدودیت‌ها از ابتدا | رفتار عامل سازگار و مطابق با برند |\n",
    "| **خروجی ساختاریافته** | استفاده از مدل‌های Pydantic به عنوان قالب پاسخ | نتایج معتبر و قابل‌خواندن توسط ماشین |\n",
    "| **تک مسئولیتی** | اختصاص یک وظیفه متمرکز به هر عامل | آسان‌تر برای تست، نگهداری و ترکیب |\n",
    "\n",
    "این الگوها به صورت طبیعی ترکیب می‌شوند — می‌توانید دستورالعمل‌های روشن را با خروجی ساختاریافته در یک عامل با تک‌مسئولیتی ترکیب کنید تا سیستم‌هایی مقاوم و آماده تولید بسازید.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n\n<!-- CO-OP TRANSLATOR DISCLAIMER START -->\n**سلب مسئولیت**:\nاین سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم.\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
}