از اجرای یک ایجنت هوش مصنوعی تا ساخت یک محصول قابل‌انتقال

از اجرای یک ایجنت هوش مصنوعی تا ساخت یک محصول قابل‌انتقال؛ مسیر توسعه AI Product Orchestrator

مقدمه

یکی از چالش‌های مهم در توسعه سامانه‌های هوش مصنوعی، عبور از مرحله ساخت و اجرای اولیه به مرحله تولید یک محصول مستقل، قابل‌نگهداری و قابل‌استقرار روی زیرساخت‌های مختلف است. ممکن است یک سامانه چندایجنتی روی یک سرور به‌خوبی کار کند، اما تا زمانی که کد، تنظیمات، وابستگی‌ها و روش استقرار آن استاندارد نشده باشند، انتقال آن به سرور دیگر می‌تواند به پروژه‌ای زمان‌بر و پرخطا تبدیل شود.

در پروژه AI Product Orchestrator، هدف این است که زیرساختی برای هماهنگ‌سازی ایجنت‌های تخصصی هوش مصنوعی توسعه داده شود؛ زیرساختی که بتواند در تحلیل محصولات، طراحی معماری نرم‌افزار، طراحی پایگاه داده و API، برنامه‌ریزی فرانت‌اند، تدوین راهبرد آزمون و تولید مستندات نقش داشته باشد.

در این مسیر، پس از راه‌اندازی زیرساخت اجرایی و تکمیل گردش‌کارهای اصلی، به مرحله ششم پروژه رسیده‌ایم: بسته‌بندی، استقرار و مستندسازی محصول.

زیرساخت پروژه چگونه شکل گرفته است؟

بر اساس وضعیت ثبت‌شده پروژه، سه جزء اصلی در مرحله پیشین آماده شده‌اند:

• Agno AgentOS: محیط اجرای ایجنت‌ها و گردش‌کارهای هوش مصنوعی.

• LiteLLM: لایه اتصال و مسیریابی درخواست‌ها به مدل‌های زبانی.

• Workflow و ایجنت‌های تخصصی: منطق هماهنگ‌سازی وظایف و توسعه قابلیت‌های تخصصی برای تحلیل و طراحی محصول.

همچنین، ایجنت‌های تکمیلی برای غنی‌سازی نتایج به گردش‌کار اضافه شده‌اند. با وجود این پیشرفت‌ها، پروژه هنوز روی سرور ۵۲ قرار دارد و برای آن یک مخزن استاندارد و مستقل ایجاد نشده است.

این وضعیت، مسئله اصلی مرحله جدید را مشخص می‌کند: چگونه می‌توان سامانه‌ای را که روی یک سرور کار می‌کند، به محصولی تبدیل کرد که روی یک سرور جدید نیز با حداقل تنظیمات قابل اجرا باشد؟

چرا مرحله بسته‌بندی و استقرار اهمیت دارد؟

اجرای موفق یک پروژه روی سرور توسعه، به‌تنهایی به معنای آماده‌بودن آن برای انتقال یا بهره‌برداری مستقل نیست. برای دستیابی به این هدف، باید چند مسئله به‌صورت هم‌زمان حل شوند:

۱. استانداردسازی کد

کدهای مربوط به موتور گردش‌کار، مسیریابی، تنظیمات، مدل‌ها، وضعیت اجرا، ایجنت‌ها و ذخیره‌سازی باید در ساختاری مشخص قرار گیرند. این ساختار، توسعه مشارکتی، بررسی تغییرات و نگهداری پروژه را ساده‌تر می‌کند.

۲. قابل‌تکرارکردن استقرار

با استفاده از Docker و Docker Compose می‌توان محیط اجرا و وابستگی‌های سرویس را تعریف کرد تا فرایند نصب روی سرورهای مختلف تا حد امکان یکسان باشد.

۳. جداسازی تنظیمات از کد

اطلاعات حساس مانند کلیدهای دسترسی مدل‌ها و تنظیمات اتصال به پایگاه داده نباید در مخزن کد قرار گیرند. در عوض، فایل .env.example باید نام متغیرهای موردنیاز را مشخص کند تا هر محیط مقادیر واقعی خود را به‌صورت جداگانه تنظیم کند.

۴. مستندسازی برای کاربران و توسعه‌دهندگان

یک محصول قابل‌انتقال به راهنمای نصب، معماری، تنظیمات، به‌روزرسانی، پشتیبان‌گیری و عیب‌یابی نیاز دارد. این مستندات وابستگی به حافظه افراد و دانش ضمنی تیم را کاهش می‌دهند.

معماری پیشنهادی برای بسته‌بندی پروژه

در مرحله ششم، ساخت مخزن مستقلی با نام پیشنهادی ai-product-orchestrator در نظر گرفته شده است. ساختار مخزن باید کد، فایل‌های استقرار، مستندات، اسکریپت‌ها و آزمون‌ها را از یکدیگر تفکیک کند.

ساختار کلی پیشنهادی به این صورت است:

ai-product-orchestrator/
├── README.md
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
├── LICENSE
├── workflow/
│   ├── engine.py
│   ├── router.py
│   ├── config.py
│   ├── schemas.py
│   ├── prompts.py
│   ├── models.py
│   ├── state.py
│   ├── agents/
│   └── storage/
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT.md
│   ├── CONFIGURATION.md
│   └── AGENT_DESIGN.md
├── scripts/
│   ├── install.sh
│   ├── start.sh
│   └── healthcheck.sh
└── tests/

این ساختار، طرح هدف پروژه است و به‌خودی‌خود به معنای ایجادشدن همه فایل‌ها یا تأیید عملکرد آن‌ها نیست.

Docker؛ گامی برای استقلال از سرور فعلی

یکی از اهداف اصلی این مرحله، تعریف محیط اجرا با Dockerfile و Docker Compose است. در Dockerfile باید نسخه مشخصی از Python، وابستگی‌های موردنیاز و فرمان اجرای برنامه تعیین شوند. در فایل Compose نیز باید سرویس AgentOS، نگاشت پورت‌ها، متغیرهای محیطی، سیاست راه‌اندازی مجدد و محل نگهداری داده‌های ماندگار تعریف شوند.

برای مثال، سیاست restart: unless-stopped می‌تواند به راه‌اندازی مجدد خودکار کانتینر پس از توقف کمک کند؛ البته این سیاست به‌تنهایی سلامت کامل برنامه یا اتصال موفق به مدل‌ها را تضمین نمی‌کند.

هدف آن است که پس از آماده‌شدن مخزن و تنظیم فایل محیطی، فرایند اولیه استقرار با دستورهای ساده‌ای مانند نمونه زیر انجام شود:

git clone <repository-url>
cd ai-product-orchestrator
cp .env.example .env
docker compose up -d

آدرس مخزن در این مثال جایگزین‌پذیر است؛ زیرا تا زمان ثبت و تأیید مخزن نهایی، نمی‌توان یک نشانی واقعی برای آن اعلام کرد.

مدیریت امن اطلاعات حساس

در یک سامانه مبتنی بر مدل‌های زبانی، تنظیمات اتصال به LiteLLM، کلیدهای دسترسی، نشانی پایگاه داده و مشخصات مدل‌ها از اهمیت ویژه‌ای برخوردارند.

به همین دلیل، فایل .env.example باید فقط نام متغیرها و مقادیر نمونه غیرحساس را شامل شود؛ برای نمونه:

LITELLM_BASE_URL=
LITELLM_API_KEY=

AGENT_MODEL_FAST=
AGENT_MODEL_DEEP=
AGENT_MODEL_ALT=

DATABASE_URL=
PORT=

مقادیر واقعی باید خارج از مخزن نگهداری شوند و فایل .env نیز در .gitignore قرار گیرد. در محیط‌های عملیاتی حساس، استفاده از سامانه مدیریت اسرار و محدودکردن سطح دسترسی‌ها نیز باید در نظر گرفته شود.

مستندات؛ بخشی از خود محصول

در این پروژه، مستندسازی صرفاً کاری جانبی نیست، بلکه یکی از اجزای اصلی آماده‌سازی برای استقرار مستقل محسوب می‌شود.

راهنمای اصلی باید توضیح دهد که پروژه چه مسئله‌ای را حل می‌کند، از چه اجزایی تشکیل شده است، چگونه مدل‌ها را مسیریابی می‌کند و ایجنت‌های تخصصی چگونه در گردش‌کار مشارکت دارند.

در کنار آن، فایل docs/DEPLOYMENT.md باید پیش‌نیازهای سرور، مراحل نصب، تنظیم LiteLLM، اجرای کانتینرها، بررسی سلامت، به‌روزرسانی و پشتیبان‌گیری را پوشش دهد. راهنمای معماری و تنظیمات نیز باید به‌گونه‌ای نوشته شوند که توسعه‌دهنده جدید بتواند بدون اتکا به توضیحات شفاهی، اجزای اصلی سیستم را بشناسد.

برای نمایش ارتباط اجزا نیز می‌توان از نمودار Mermaid استفاده کرد. نمای ساده‌شده جریان پیشنهادی چنین است:

flowchart TD
    U[User] --> A[AgentOS]
    A --> M[Manager Agent]
    M --> R[Router]
    R --> L[LiteLLM]
    L --> X[Language Models]
    M --> S[Specialist Agents]
    S --> D[Generated Documents]

این نمودار نمای مفهومی معماری است؛ جزئیات واقعی جریان اجرا باید با پیاده‌سازی نهایی تطبیق داده شوند.

چگونه موفقیت استقرار را ارزیابی کنیم؟

صرف بالا آمدن کانتینر برای تأیید آمادگی محصول کافی نیست. معیارهای پایان مرحله ششم، علاوه بر ایجاد مخزن و مستندات، شامل اجرای واقعی پروژه در یک محیط جداگانه است.

در این آزمون باید مشخص شود که:

• مخزن مستقل ساخته شده و کدهای موردنیاز در Git قرار گرفته‌اند.

• Dockerfile و فایل Compose با محیط واقعی پروژه سازگارند.

• تنظیمات حساس از کد و مخزن جدا شده‌اند.

• سرویس AgentOS اجرا می‌شود و بررسی سلامت آن موفق است.

• اتصال به LiteLLM برقرار می‌شود.

• یک آزمون دود (Smoke Test) از مسیر اصلی گردش‌کار با موفقیت اجرا می‌شود.

• روش‌های شروع، توقف، به‌روزرسانی و پشتیبان‌گیری مستند شده‌اند.

برای بررسی اولیه نیز دستورهایی مانند docker ps و درخواست به مسیر سلامت سرویس، در صورت پشتیبانی برنامه از آن مسیر، مفید خواهند بود. مسیر /health و پورت مورد استفاده باید با تنظیمات واقعی برنامه تطبیق داده شوند.

مهم‌ترین آزمون، نصب روی محیطی جدا از سرور ۵۲ است؛ زیرا این آزمون مشخص می‌کند که آیا پروژه واقعاً به یک بسته قابل‌انتقال تبدیل شده یا هنوز به تنظیمات و وابستگی‌های پنهان سرور اولیه متکی است.

جمع‌بندی

مرحله ششم پروژه AI Product Orchestrator، گذار از یک سامانه اجرایی روی سرور مشخص به یک محصول استاندارد و قابل‌انتقال را هدف قرار می‌دهد. ایجاد مخزن Git، تعریف محیط Docker، جداسازی اسرار، تهیه مستندات و آزمون روی سرور تمیز، اجزای اصلی این گذار هستند.

نکته مهم آن است که در این مرحله، هدف و معیارهای انجام کار مشخص شده‌اند، اما تکمیل پروژه تنها زمانی قابل تأیید است که مخزن ساخته شود، استقرار مستقل واقعاً اجرا شود و آزمون‌های لازم موفق باشند.

پس از تحقق این معیارها، می‌توان به مرحله بعدی توسعه فکر کرد: بهبود فرایند انتشار نسخه‌ها، آزمون‌های خودکار، پایش سرویس‌ها و آماده‌سازی محصول برای استفاده گسترده‌تر.

این همان تفاوت میان «برنامه‌ای که روی یک سرور اجرا می‌شود» و «محصولی که می‌توان آن را به‌صورت قابل‌تکرار نصب، نگهداری و توسعه داد» است.