AGENT//LAB // معماری و پیاده‌سازی ایجنت هوشمند خودمختار

SECTION // 02

مسئله واقعی کسب‌وکار: چرا چت‌بات‌های متنی سنتی ناکارآمد هستند؟

چت‌بات‌های مرسوم متنی مبتنی بر پرامپت‌های ایستا (Static Prompting) دچار ۳ نارسایی مهندسی هستند:

۱. توهم اطلاعاتی (Hallucination): بدون اتصال به پایگاه داده زنده، مدل در مورد قیمت و موجودی انبار فرضیه‌پردازی می‌کند.
۲. عدم توانایی اقدام (Inability to Act): یک چت‌بات معمولی نمی‌تواند وضعیت فاکتور را از سرور انبارداری استعلام کند یا کد رهگیری تیپاکس صادر کند.
۳. انسداد در شرایط بحرانی (Dead-End Failure): زمانی که مشتری ناراضی است یا موضوع نیازمند تصمیم مالی یا مدیریتی است، چت‌بات پاسخی عمومی تکرار می‌کند و باعث خشم کاربر می‌شود.

💡 راهکار مهندسی در AGENT//LAB

تبدیل مدل هوش مصنوعی به یک عامل خودمختار ReAct (Reasoning + Action) که ورودی کاربر را بررسی کرده، ابزار مناسب را تشخیص می‌دهد، پاسخ ساختاریافته JSON از وبسایت دریافت می‌کند، و در صورتی که کاری خارج از حدود اختیاراتش باشد، تیکت را با تمام سوابق به تلگرام ادمین ارجاع داده و پاسخ ریپلای‌شده ادمین را بدون واسطه برای مشتری ارسال می‌کند.

SECTION // 03

معماری ۴ لایه اکوسیستم ایجنت هوشمند

جریان پردازش داده‌ها در ۴ زیرسیستم مستقل طراحی شده است تا پایداری و تاب‌آوری سیستم در قطعی‌های شبکه تضمین گردد:

LAYER 01 Perception & Intent دریافت ورودی متن، استخراج موجودیت‌ها (شماره سفارش، نام کالا) و بازخوانی تاریخچه تعاملات قبلی از دیتابیس SQLite.

LAYER 02 ReAct Reasoning Core ارزیابی پرامپت با هسته Gemini، استنتاج نیاز به اقدام و انتخاب بهینه از میان کاتالوگ ابزارهای رجیسترشده.

LAYER 03 Tool Execution Bus دیسپچر ناهمگام پایتون (Asyncio) که وب‌سرویس‌های REST یا دیتابیس را فراخوانی کرده و خروجی ساختاریافته را به ایجنت بازمی‌گرداند.

LAYER 04 Human-in-the-Loop پروتکل ارجاع هوشمند تیکت به ادمین تلگرام، با قابلیت پاسخگویی مستقیم ادمین با ریپلای روی پیام تلگرام.

SECTION // 04 — INTERACTIVE TESTBED

ایستگاه تعاملی زنده: تست عملیاتی ReAct و ابزارخوانی

این ترمینال صرفاً یک رابط چت فرضی نیست؛ موتور ReAct پایتون به صورت کامل در جاوااسکریپت پورت شده و با دیتابیس واقعی کاتالوگ و پیگیری سفارشات ارتباط دارد. می‌توانید ابزارخوانی، استعلام فاکتور و ارجاع به ادمین تلگرام را مستقیماً آزمایش کنید:

DEMO / SIMULATION — محیط شبیه‌سازی کلاینت: این ترمینال برای اثبات معماری ReAct به صورت کلاینت-ساید و قطعی شبیه‌سازی شده است. هیچ تماس زنده با Gemini API یا تلگرام در این نسخه وب برقرار نمی‌شود و کاتالوگ و پیگیری سفارشات بر روی دیتاست نمونه محلی اجرا می‌گردد.

🔍 راهنمای آزمایش سناریوهای واقعی در ترمینال بالا

۱. استعلام قیمت و موجودی: روی چیپ «قیمت و موجودی آیفون ۱۵» کلیک کنید تا اجرای ابزار search_products و نمایش کارت محصول را ببینید.
۲. پیگیری سفارش: روی چیپ «پیگیری سفارش #1001» کلیک کنید تا ابزار track_order فاکتور و کد تیپاکس را استخراج کند.
۳. ارجاع به انسان و شبیه‌سازی ادمین: روی چیپ «ارجاع به پشتیبان انسانی» کلیک کنید؛ تیکت صادر شده و می‌توانید با کلیک روی دکمه شبیه‌سازی، پاسخ ریپلای‌شده ادمین تلگرام را مستقیماً دریافت کنید!
۴. باز کردن کشوی اینسپکتور (Inspector): با کلیک روی نوار پایینی ترمینال، آرگومان‌های خام JSON و زمان پاسخگویی (Latency) را به صورت زنده بررسی کنید.

SECTION // 05

اسکیما و ساختار فراخوانی ابزارها (Function Calling Schema)

اسکیمای ابزارها به صورت رسمی با استانداردهای OpenAPI و Gemini Function Calling در فایل ai_agent.py رجیستر شده است:

# تعریف ساختار رسمی ابزارهای رجیسترشده در Gemini Core
TOOLS_SCHEMA = [
    {
        "name": "search_products",
        "description": "جستجوی محصولات، کالاها، قیمت‌ها و موجودی در فروشگاه",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "query": { "type": "STRING", "description": "نام کالا یا برند" }
            },
            "required": ["query"]
        }
    },
    {
        "name": "track_order",
        "description": "پیگیری وضعیت سفارش بر اساس شماره سفارش یا کد پیگیری",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "order_id": { "type": "STRING", "description": "شماره سفارش ۴ رقمی" }
            },
            "required": ["order_id"]
        }
    },
    {
        "name": "request_human_support",
        "description": "فراخوانی پشتیبان انسانی در صورت نیاز به مداخله ادمین یا شکایات",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "reason": { "type": "STRING", "description": "علت ارجاع به ادمین" }
            },
            "required": ["reason"]
        }
    }
]
                

SECTION // 06

حافظه پایدار نشست و مدیریت تاریخچه مکالمه در SQLite

در مدل‌های زبانی stateless، پیام‌های گذشته نگهداری نمی‌شوند. ماژول database.py پایگاه داده محلی SQLite را برای نگهداری سوابق چت هر کاربر (Session Management) مدیریت می‌کند:

• ذخیره نوبت‌های گفتگو: ثبت پیام‌های کاربر و پاسخ‌های ایجنت به همراه نام ابزارهای فراخوانی‌شده و مهر زمانی (ISO 8601).
• هرس هوشمند پنجره بافت (Context Pruning): محدودسازی تاریخچه ارسالی به مدل به ۱۰ نوبت آخر جهت بهینه‌سازی مصرف توکن و سرعت پاسخ‌دهی.
• ردگیری وضعیت تیکت‌ها: نگهداری وضعیت تیکت‌های ارجاعی به ادمین و ثبت پیام‌های پاسخ ادمین.

SECTION // 07

پروتکل مداخله انسانی دوطرفه (Bidirectional Telegram Handoff)

یکی از بزرگترین تمایزهای معماری این سیستم، اتصال مستقیم به پیام‌رسان تلگرام ادمین است:

۱. با صدور دستور request_human_support، یک پیام فوری به آیدی عددی ادمین (ADMIN_CHAT_ID) در تلگرام ارسال می‌شود که شامل خلاصه گفتگو و نام کاربر است.
۲. ادمین نیازی به ورود به داشبوردهای پیچیده وب ندارد؛ کافیست در همان محیط تلگرام روی پیام تیکت ریپلای (Reply) بزند.
۳. بات تلگرام با خواندن شناسه پیام ریپلای‌شده، کاربر مقصد را از دیتابیس SQLite پیدا کرده و پاسخ ادمین را بدون وقفه به چت کاربر برمی‌گرداند.

SECTION // 08

شبیه‌ساز سرور تست و پل اتصال به ERP و وبسایت واقعی

جهت تست کامل سیستم پیش از دیپلوی روی وبسایت‌های واقعی وردپرس، ووکامرس یا ERPهای سازمانی، سرور تست mock_api.py بر پایه FastAPI توسعه داده شده است. این سرور روت‌های /api/products و /api/orders/{id} را شبیه‌سازی می‌کند و در کلاینت store_api.py با تغییر یک خط کانفیگ به API واقعی مشتری متصل می‌شود.

SECTION // 09

گاردریل‌ها و محافظت در برابر تزریق پرامپت (Prompt Injection)

ایجنت مجهز به قوانین سرسختانه سیستمی در SYSTEM_PROMPT است:

• محدودیت اختیارات: ایجنت اجازه تخفیف خودسرانه، وعده تحویل غیرممکن یا بحث‌های نامربوط خارج از حوزه پشتیبانی فروشگاه را ندارد.
• قرنطینه داده‌های محرمانه: توکن‌های تلگرام و کلیدهای Gemini در فایل محرمانه .env نگهداری شده و هرگز در پاسخ‌های متنی به کاربر نشت نمی‌کنند.
• مدیریت خطای تایم‌اوت ابزارها: در صورت قطع شدن موقت API فروشگاه، ایجنت با پیامی آرامش‌بخش کاربر را راهنمایی کرده و خطای خام ۵۰۰ نشان نمی‌دهد.

SECTION // 10

ماتریس پشته فناوری سیستم

بخش / لایه	فناوری انتخاب‌شده	علت انتخاب و نقش مهندسی
Core Agent Engine	Python 3.10+ & Google Gemini API	قابلیت Native Function Calling با درک بالا از زبان فارسی و سرعت اینفرنس زیر ۸۰۰ میلی‌ثانیه.
Bot Messaging Layer	python-telegram-bot / aiogram	مدیریت غیرهمگام (Asyncio) پیام‌ها، وب‌هوک و پاسخ ریپلای دوطرفه ادمین.
Data Store	SQLite 3 (WAL Mode)	پایگاه داده محلی فوق‌سریع و پایدار، بدون نیاز به دیتابیس خارجی سنگین.
Interactive Web Testbed	Vanilla ES6+ ReAct Simulator	رندرینگ کلاینت‌ساید بدون فریم‌ورک‌های سنگین با خروجی لحظه‌ای تله‌متری عملکرد.

SECTION // 11

نقش من و مالکیت مهندسی در این سیستم

به عنوان معمار سیستم و مهندس هوش مصنوعی (AI Engineer & Architect)، طراحی و پیاده‌سازی صفر تا صد اجزای زیر توسط من انجام شده است:

• طراحی معماری ReAct و نگارش اسکیمای فراخوانی توابع در ai_agent.py.
• توسعه پروتکل اتصال دوطرفه به تلگرام و مدیریت ریپلای ادمین در bot_handlers.py.
• طراحی ساختار پایگاه داده SQLite و هرس تاریخچه چت در database.py.
• پیاده‌سازی سرور تست API و نگارش اسکریپت‌های اعتبارسنجی خودکار در test_agent.py.
• پورت و ساخت ایستگاه شبیه‌ساز زنده تعاملی برای این وبسایت.

SECTION // 12

پیمایش سامانه‌ها و گام بعدی

طراحی و سفارش ایجنت اختصاصی برای کسب‌وکار شما (BUILD AN AGENT)

AGENT//LAB // Autonomous AI Agent Architecture & Working Testbed