/translations/fa/12-context-engineering/code_samples/12-chat_summarization.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# درس ۱۲ - کاهش تاریخچه چت با استفاده از دفترچه یادداشت Agent\n",
    "\n",
    "این دفترچه یادداشت نشان می‌دهد چگونه می‌توان با استفاده از چارچوب Agent مایکروسافت، مدیریت زمینه را در گفتگوهای طولانی انجام داد. با افزایش طول گفتگوها، تعداد توکن‌ها افزایش می‌یابد — که در نهایت از پنجره زمینه مدل فراتر می‌رود. ما این مشکل را با **الگوی خلاصه‌سازی زمینه** و **دفترچه یادداشت agent** برای حافظه ماندگار حل می‌کنیم.\n",
    "\n",
    "## آنچه یاد خواهید گرفت:\n",
    "۱. **چرا مدیریت زمینه اهمیت دارد**: درک محدودیت‌های توکن و پنجره‌های زمینه  \n",
    "۲. **عامل‌های آگاه به زمینه**: ساخت عامل‌هایی که زمینه گفتگوهای خود را مدیریت می‌کنند  \n",
    "۳. **الگوی خلاصه‌سازی زمینه**: استفاده از ابزارها برای فشرده‌سازی تاریخچه گفتگو  \n",
    "۴. **دفترچه یادداشت Agent**: حافظه ماندگاری که پس از کاهش زمینه باقی می‌ماند  \n",
    "\n",
    "## پیش‌نیازها:\n",
    "- راه‌اندازی Azure OpenAI با تنظیم متغیرهای محیطی  \n",
    "- درک مفاهیم پایه agent از درس‌های قبلی\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## راه‌اندازی\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install agent-framework azure-ai-projects azure-identity --quiet"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import asyncio\n",
    "from datetime import datetime\n",
    "from pathlib import Path\n",
    "\n",
    "from dotenv import load_dotenv\n",
    "\n",
    "from agent_framework import tool\n",
    "from agent_framework.azure import AzureAIProjectAgentProvider\n",
    "from azure.identity import AzureCliCredential"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load environment variables and create Azure AI Foundry provider\n",
    "load_dotenv()\n",
    "\n",
    "provider = AzureAIProjectAgentProvider(credential=AzureCliCredential())\n",
    "\n",
    "print(\"✅ Azure AI Foundry provider configured\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## چرا مدیریت زمینه مهم است\n",
    "\n",
    "هر مدل زبان بزرگ (LLM) دارای یک **پنجره زمینه‌ای** محدود است — حداکثر تعداد توکن‌هایی که می‌تواند در یک درخواست پردازش کند. با پیشرفت یک مکالمه چند مرحله‌ای:\n",
    "\n",
    "- **تعداد توکن‌ها به صورت خطی افزایش می‌یابد** با هر پیام کاربر و پاسخ دستیار.\n",
    "- **توکن‌های پرامپت هزینه را تسلط می‌دهند** زیرا کل تاریخچه در هر مرحله مجدداً ارسال می‌شود.\n",
    "- در نهایت مکالمه **از پنجره زمینه‌ای فراتر می‌رود** و مدل یا برش می‌دهد یا خطا می‌دهد.\n",
    "\n",
    "### استراتژی‌های مدیریت زمینه\n",
    "\n",
    "| استراتژی | چگونه کار می‌کند | معاوضه |\n",
    "|---|---|---|\n",
    "| **برش** | پیام‌های قدیمی‌تر را حذف می‌کند | زمینه اولیه از دست می‌رود |\n",
    "| **خلاصه‌سازی** | پیام‌های قدیمی‌تر را به یک خلاصه تبدیل می‌کند | برخی جزئیات از دست می‌روند، اما نکات کلیدی حفظ می‌شود |\n",
    "| **دفترچه یادداشت / حافظه خارجی** | حقایق کلیدی را خارج از مکالمه ذخیره می‌کند | نیاز به فراخوانی ابزار دارد، اما در برابر هر کاهش مقاوم است |\n",
    "\n",
    "در این دفترچه ما **خلاصه‌سازی** را با یک **ابزار دفترچه یادداشت** ترکیب می‌کنیم تا عامل بتواند پیوستگی را حفظ کند حتی زمانی که تاریخچه مکالمه خلاصه می‌شود.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ایجاد یک عامل آگاه به زمینه\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "agent = await provider.create_agent(\n",
    "    name=\"ContextAwareAgent\",\n",
    "    instructions=\"\"\"You are a helpful travel planning assistant with excellent memory management.\n",
    "When conversations get long:\n",
    "1. Summarize previous context into key points\n",
    "2. Track user preferences mentioned earlier\n",
    "3. Reference previous decisions without repeating full details\n",
    "Always maintain continuity while being concise.\"\"\",\n",
    ")\n",
    "\n",
    "print(\"🤖 Context-aware travel planning agent created\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## شبیه‌سازی یک مکالمه طولانی\n",
    "\n",
    "بیایید یک مکالمه چندمرحله‌ای را مرور کنیم تا ببینیم چگونه زمینه جمع می‌شود. نماینده باید جزئیات کلیدی (ترجیحات، بودجه، تاریخ‌های سفر) را در طول گفتگو حفظ کند و پیوستگی را نشان دهد.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = agent.create_session()\n",
    "\n",
    "# Turn 1 - Initial preferences\n",
    "response = await agent.run(\"I'm planning a trip to Japan. I love sushi, temples, and photography.\", session=session)\n",
    "print(f\"Turn 1: {response}\\n\")\n",
    "\n",
    "# Turn 2 - More details\n",
    "response = await agent.run(\"My budget is $3000 and I'll be traveling solo for 10 days in April.\", session=session)\n",
    "print(f\"Turn 2: {response}\\n\")\n",
    "\n",
    "# Turn 3 - Test context retention\n",
    "response = await agent.run(\"Based on everything I've told you so far, what's the one thing you'd recommend I not miss?\", session=session)\n",
    "print(f\"Turn 3: {response}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "توجه کنید که چگونه عامل زمینه را از نوبت‌های قبلی حفظ می‌کند — او درباره ژاپن، سوشی، معابد، عکاسی، بودجه ۳۰۰۰ دلاری، سفر انفرادی و بازه زمانی آوریل مطلع است. در یک مکالمه کوتاه این روش خوب عمل می‌کند، اما هر چه مکالمه طولانی‌تر شود، ارسال مجدد کل تاریخچه هزینه‌بر خواهد بود.\n",
    "\n",
    "بیایید مکالمه را با نوبت‌های بیشتر ادامه دهیم تا تجمع زمینه را ببینیم:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Turn 4 - Expand the conversation\n",
    "response = await agent.run(\"What about accommodation? I prefer traditional Japanese inns.\", session=session)\n",
    "print(f\"Turn 4: {response}\\n\")\n",
    "\n",
    "# Turn 5 - Change of plans\n",
    "response = await agent.run(\"Actually, I've changed my mind about the dates. I'll go in October instead for the autumn colors.\", session=session)\n",
    "print(f\"Turn 5: {response}\\n\")\n",
    "\n",
    "# Turn 6 - Test retention after change\n",
    "response = await agent.run(\"Summarize my complete travel plan so far — destination, budget, duration, interests, accommodation, and timing.\", session=session)\n",
    "print(f\"Turn 6: {response}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## الگوی خلاصه‌سازی متن زمینه\n",
    "\n",
    "با گسترش گفتگو، می‌توانیم از **ابزار خلاصه‌سازی** برای جمع‌وجور کردن متن تجمع‌یافته به فرمتی فشرده استفاده کنیم. عامل این ابزار را فراخوانی می‌کند تا ترجیحات کلیدی را ثبت کند تا حتی اگر پیام‌های قدیمی‌تر حذف شوند، اطلاعات حیاتی حفظ شود.\n",
    "\n",
    "این الگو ساختار اصلی برای کاهش پیشرفته‌تر تاریخچه است:\n",
    "1. عامل نکات کلیدی از گفتگو را شناسایی می‌کند\n",
    "2. ابزار خلاصه‌سازی را فراخوانی می‌کند تا آن‌ها را ذخیره کند\n",
    "3. پیام‌های قدیمی‌تر به‌طور ایمن حذف می‌شوند چون خلاصه آنچه اهمیت دارد را در بر می‌گیرد\n",
    "\n",
    "در ادامه ما ابزاری به نام `summarize_preferences` تعریف می‌کنیم که عامل می‌تواند آن را برای ثبت خلاصه‌ای فشرده از آنچه یاد گرفته است، فراخوانی کند.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@tool(approval_mode=\"never_require\")\n",
    "def summarize_preferences(conversation_notes: str) -> str:\n",
    "    \"\"\"Summarize accumulated user preferences into a compact format.\"\"\"\n",
    "    return f\"[SUMMARY] User preferences recorded: {conversation_notes}\"\n",
    "\n",
    "\n",
    "# Create an enhanced agent with the summarization tool\n",
    "summarizing_agent = await provider.create_agent(\n",
    "    name=\"SummarizingTravelAgent\",\n",
    "    instructions=\"\"\"You are a helpful travel planning assistant that actively manages conversation context.\n",
    "\n",
    "CONTEXT MANAGEMENT RULES:\n",
    "1. After gathering several user preferences, call summarize_preferences() to record a compact summary\n",
    "2. When the user asks you to recall details, reference your recorded summaries\n",
    "3. Keep responses concise — avoid restating the entire history\n",
    "\n",
    "PLANNING PROCESS:\n",
    "1. Gather user preferences (destination, budget, dates, interests)\n",
    "2. Summarize preferences using the tool\n",
    "3. Create recommendations based on the summary\n",
    "4. Update the summary when preferences change\"\"\",\n",
    "    tools=[summarize_preferences],\n",
    ")\n",
    "\n",
    "print(\"🤖 Summarizing travel agent created with context tools\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Demonstrate the summarization pattern\n",
    "summary_session = summarizing_agent.create_session()\n",
    "\n",
    "# Provide a batch of preferences\n",
    "response = await summarizing_agent.run(\n",
    "    \"I want to visit Greece. I love seafood, history, and island hopping. \"\n",
    "    \"Budget is $4000 for two weeks. Traveling with my partner in June. \"\n",
    "    \"Please record these preferences using your summarization tool.\",\n",
    "    session=summary_session,\n",
    ")\n",
    "print(f\"Agent: {response}\\n\")\n",
    "\n",
    "# Ask the agent to use the recorded context\n",
    "response = await summarizing_agent.run(\n",
    "    \"Now, based on what you've recorded, suggest the top 3 islands we should visit.\",\n",
    "    session=summary_session,\n",
    ")\n",
    "print(f\"Agent: {response}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## خلاصه\n",
    "\n",
    "در این درس یاد گرفتید چگونه در مکالمات طولانی‌مدت عامل‌ها، مدیریت زمینه را با استفاده از چارچوب عامل مایکروسافت انجام دهید:\n",
    "\n",
    "### مفاهیم کلیدی\n",
    "- **پنجره‌های زمینه محدود هستند** — هر توکن در تاریخچه مکالمه هزینه‌بر است و به محدودیت افزوده می‌شود.\n",
    "- **ابزارهای خلاصه‌سازی** به عامل این امکان را می‌دهند که زمینه انباشته‌شده را در قالب خلاصه‌های فشرده جمع کند، استفاده از توکن‌ها را کاهش دهد و اطلاعات حیاتی را حفظ کند.\n",
    "- **برگه یادداشت عامل** حافظه خارجی پایدار فراهم می‌کند که پس از هر کاهش مکالمه باقی می‌ماند.\n",
    "\n",
    "### آنچه ساختید\n",
    "- یک **عامل آگاه به زمینه** که تداوم را در مکالمات چندمرحله‌ای حفظ می‌کند\n",
    "- یک **ابزار خلاصه‌سازی** (`summarize_preferences`) که جزئیات کلیدی کاربر را در قالب فشرده ضبط می‌کند\n",
    "- یک **مکالمه چندمرحله‌ای** که حفظ زمینه و مدیریت تغییرات را نشان می‌دهد\n",
    "\n",
    "### کاربردهای دنیای واقعی\n",
    "- **ربات‌های خدمات مشتری**: ترجیحات را در جلسات طولانی پشتیبانی به خاطر می‌سپارند\n",
    "- **دستیارهای شخصی**: پیگیری پروژه‌های جاری بدون نیاز به توضیح مجدد زمینه\n",
    "- **معلمان آموزشی**: حفظ پیشرفت دانش‌آموز در تعاملات متعدد\n",
    "\n",
    "### گام‌های بعدی\n",
    "- پیاده‌سازی یک ابزار برگه یادداشت کامل با قابلیت پایدارسازی مبتنی بر فایل\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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}