‏ساخت ایجنت پروداکشن با Eve ورسل

تو این مقاله اومده که پروتوتایپ کردن یه ایجنت آسونه، ولی رسوندنش به جایی که خطاها رو تمیز مدیریت کنه، بین کاربرها مقیاس بگیره و رفتارش با گذشت زمان قابل پیش‌بینی بمونه، یه مسئلهٔ کاملاً متفاوته. نویسنده Eve ورسل رو به‌عنوان یه فریم‌ورک «اول فایل‌سیستم» معرفی می‌کنه که اگه با Next.js کار کرده باشی، مدل ذهنی‌ش برات آشناست.

بیشتر فریم‌ورک‌ها ازت کلی کد چسبی می‌خوان؛ Eve به‌جاش ساختار ایجنت رو مستقیم به ساختار پوشه‌های پروژه نگاشت می‌کنه: مهارت‌ها تو /skills، زیرایجنت‌ها تو /agents، تنظیمات کانال‌ها تو /channels و ارزیابی‌ها تو /evals. سودش سه چیزه: هر کسی با خوندن دایرکتوری می‌فهمه ایجنت چه توانایی‌هایی داره، مهارت‌ها بین پروژه‌ها قابل استفادهٔ دوباره‌ان، و ارزیابی‌ها روی همون تعریف‌هایی اجرا می‌شن که تو پروداکشن کار می‌کنن، نه روی یه ماک جدا.

پروژه با CLI ساخته می‌شه و تو فایل eve.config.ts مدل و پیش‌فرض‌های سراسری مثل temperature، سقف توکن و تعداد تلاش مجدد تنظیم می‌شن. نویسنده پیشنهاد می‌کنه برای ایجنت‌های پروداکشنی که کار ساختاریافته انجام می‌دن temperature پایین بذاری و در صورت نیاز، همون مقدار رو سطح مهارت یا ایجنت بازنویسی کنی.

مهارت‌ها واحدهای اتمی توانایی ایجنتن: هر مهارت یه فایله که یه تابع تایپ‌شده با نام، توضیح، اسکیمای ورودی و هندلر صادر می‌کنه. نکتهٔ مهم اینه که فیلد description بیشتر از چیزی که فکر می‌کنی اهمیت داره، چون همون چیزیه که ایجنت بر اساسش تصمیم می‌گیره کِی مهارت رو صدا بزنه:

export default defineSkill({
  name: 'searchWeb',
  description: 'Search the web for current information on a given topic',
  input: z.object({
    query: z.string().describe('The search query'),
  }),
  async handler({ query }) {
    const results = await fetchSearchResults(query);
    return { results };
  },
});

سه تا عادت، مهارت دمویی رو به مهارت پروداکشنی تبدیل می‌کنه: تایپ سخت‌گیرانهٔ ورودی با اسکیمای Zod و توضیح روی هر فیلد؛ مدیریت صریح خطا، یعنی به‌جای اینکه یه فراخوانی ناموفق حلقهٔ ایجنت رو بترکونه، یه حالت خطای ساختاریافته مثل { success: false, error } برگردونی؛ و لاگ‌گذاری ساختاریافته در ابتدا و انتهای هر هندلر برای رصدپذیری.

زیرایجنت‌ها بخش مقیاس ماجرا هستن: یه ایجنت تخصصی با پرامپت سیستمی و مجموعه مهارت خودش که ایجنت اصلی می‌تونه کار رو بهش واگذار کنه. قاعدهٔ سرانگشتی نویسنده برای انتخاب بین مهارت و زیرایجنت اینه: اگه یه کنش واحد و محدوده (صدا زدن یه API، نوشتن یه رکورد) مهارته؛ اگه استدلال چندمرحله‌ای یا استفادهٔ پشت‌سرهم از چند مهارت لازم داره، زیرایجنته.

export default defineAgent({
  name: 'main',
  systemPrompt: `You are a business intelligence assistant. For research tasks,
  delegate to the researcher agent.`,
  skills: ['search-crm', 'send-notification'],
  subAgents: ['researcher', 'analyst'],
});

کانال‌ها مشخص می‌کنن ایجنت چطور با دنیای بیرون حرف می‌زنه و Eve به‌صورت داخلی از اسلک، وب‌هوک و HTTP پشتیبانی می‌کنه. برای اسلک باید یه اپ بسازی، Socket Mode رو برای توسعهٔ محلی فعال کنی و اسکوپ‌های لازم رو بدی؛ توکن‌ها هم فقط تو متغیرهای محیطی می‌شینن، نه داخل کد. لایهٔ انتزاعی کانال، رویدادهای ورودی رو نرمال می‌کنه تا ایجنت درگیر پارس کردن پیلود خام اسلک نشه. کانال HTTP هم یه اندپوینت احرازهویت‌شده روی دیپلوی ورسل می‌سازه.

بخش آخر ارزیابیه؛ همون چیزی که به گفتهٔ نویسنده بیشتر تیم‌ها ازش می‌گذرن و نتیجه‌ش کاملاً پیداست. سیستم ارزیابی Eve بهت اجازه می‌ده کیس‌های تست با ورودی و رفتار مورد انتظار تعریف کنی و اون‌ها رو روی تعریف‌های زندهٔ مهارت و ایجنت اجرا کنی. ارزیابی سطح مهارت یه توانایی مشخص رو می‌سنجه (مثلاً پرس‌وجوی معتبر نتیجه برمی‌گردونه و پرس‌وجوی خالی خطای تمیز می‌ده) و ارزیابی سطح ایجنت کل گفت‌وگو رو، مثلاً اینکه ایجنت اصلی درست کار پژوهش رو به زیرایجنت واگذار کرده یا نه.

نکات کلیدی:

• مدل «اول فایل‌سیستم» یعنی ساختار پوشه‌ها همون معماری ایجنته و نیازی به ثبت دستی نیست.
• توضیح هر مهارت مستقیم روی تصمیم ایجنت برای صدا زدنش اثر داره؛ مبهم ننویسش.
• ورودی‌ها رو با اسکیمای تایپ‌شده و توضیح‌دار ببند و خطا رو به‌صورت خروجی ساختاریافته برگردون، نه استثنای پرتاب‌شده.
• کنش واحد یعنی مهارت، کار چندمرحله‌ای یعنی زیرایجنت.
• کانال‌ها رویدادهای اسلک و HTTP رو نرمال می‌کنن و اعتبارنامه‌ها باید تو متغیر محیطی بمونن.
• ارزیابی‌ها روی تعریف‌های واقعی پروداکشن اجرا می‌شن، پس رگرسیون رو قبل از رسیدن به کاربر می‌گیرن.