پرش به مطلب اصلی

عامل‌های هوش مصنوعی

یک عامل هوش مصنوعی دستیاری چندمرحله‌ای است. گفتگو را می‌خواند، برنامه‌ریزی می‌کند، ابزارها را (ابزارهای AI شما، ابزارهای MCP و جست‌وجو در پایگاه دانش) فراخوانی می‌کند، نتایج را بررسی می‌کند و دوباره مدل را صدا می‌زند تا به پاسخ برسد. گره ایجاد تکمیل چت هوش مصنوعی فقط یک بار مدل را فراخوانی می‌کند و پاسخ می‌دهد؛ اما گره عامل هوش مصنوعی می‌تواند در چارچوب محدودیت‌هایی که شما تعیین می‌کنید، پیش از ارائه پاسخ چندین فراخوانی مدل و ابزار انجام دهد.

وقتی درخواستی به چند مرحله نیاز دارد از عامل استفاده کنید، مثلاً «سفارش مشتری را پیدا کن، وضعیت تحویل را بررسی کن و تاریخ جدید پیشنهاد بده». برای پاسخ مستقیم بر پایه دستورالعمل‌ها و یک پایگاه دانش، گره AI ساده‌تر و ارزان‌تر است.

اجزای اصلی​

بخشچیستکجا تنظیم می‌شود
AI Harnessموتوری که حلقه عامل را اجرا می‌کند: موتور خود MonoChat، یک SDK عامل یا یک سرویس عامل میزبانی‌شده.تنظیمات › اتوماسیون › هارنس‌های AI
مدل‌هامدل‌های AI که عامل با آن‌ها فکر می‌کند: یک مدل اصلی، یک مدل جایگزین اختیاری و یک مدل سریع اختیاری. harnessهای میزبانی‌شده به‌جای آن‌ها از مدل‌های ارائه‌دهنده خودشان استفاده می‌کنند.گره عامل هوش مصنوعی
ابزارهامحدوده‌های AI، توابع ابزار AI و ابزارهای MCP.گره عامل هوش مصنوعی
بودجه اجرامحدودیت فراخوانی مدل، فراخوانی ابزار، توکن، مدت زمان و تلاش مجدد برای هر اجرا.گره عامل هوش مصنوعی
اجرایک بار اجرای عامل. هر اجرا در اجراهای عامل هوش مصنوعی ثبت می‌شود.توسط گره یا API ایجاد می‌شود

هارنس‌های AI​

تنظیمات › اتوماسیون › هارنس‌های AI harnessهایی را فهرست می‌کند که عامل‌های شما می‌توانند روی آن‌ها اجرا شوند: harnessهایی که MonoChat برای همه فضاهای کاری ارائه می‌دهد و آن‌هایی که شما با اعتبارنامه‌های خودتان اضافه می‌کنید.

Harnessمحل اجرامدل‌هایی که استفاده می‌کندچه کسی اضافه می‌کند
MonoChat Nativeداخل MonoChatمدل‌های AI شماMonoChat
OpenAI Agents SDKداخل MonoChatمدل‌های AI شماMonoChat
Claude Agent SDKروی اجراکننده عامل MonoChatمدل‌های AI شماMonoChat
piروی اجراکننده عامل MonoChatمدل‌های AI شماMonoChat
OpenAI Agents APIدر ابر OpenAIمدل‌های مجاز harnessشما، با کلید API اوپن‌ای‌آی خودتان (ممکن است MonoChat هم یکی ارائه دهد)
Claude Managed Agentsدر ابر Anthropicمدل‌های مجاز harnessشما، با کلید API شرکت Anthropic (ممکن است MonoChat هم یکی ارائه دهد)
نقطه پایانی سفارشیروی سرور خودتانمدل‌های AI شما (اختیاری)شما، با endpoint و secret خودتان

harnessهایی که روی MonoChat اجرا می‌شوند را خود MonoChat ارائه می‌دهد؛ فضای کاری شما فقط می‌تواند harnessهایی را اضافه کند که اعتبارنامه خودش را می‌گیرند. Claude Agent SDK و pi به اجراکننده عامل MonoChat نیاز دارند: در جایی که راه‌اندازی نشده باشد، اجرا روی آن‌ها با پیام «This harness is not available on this server.» ناموفق می‌شود.

هر harnessی که باشد، کنترل در دست MonoChat می‌ماند: هر فراخوانی مدل در harnessی که از مدل‌های AI شما استفاده می‌کند از MonoChat عبور می‌کند (پس صورتحساب و بودجه اعمال می‌شود)، هر فراخوانی ابزار، توابع، ابزارهای MCP و محدوده‌های AI را در فضای کاری شما اجرا می‌کند و بودجه روی همه harnessها اعمال می‌شود.

افزودن harness​

  1. به تنظیمات › اتوماسیون › هارنس‌های AI بروید و روی + (ایجاد) کلیک کنید.
  2. یک نام و در صورت تمایل توضیحات وارد کنید.
  3. Harness را انتخاب کنید. هر گزینه می‌گوید کجا اجرا می‌شود.
  4. زیر اعتبارنامه‌ها، آنچه harness نیاز دارد را وارد کنید:
    • OpenAI Agents API، Claude Managed Agents: کلید API.
    • نقطه پایانی سفارشی: Endpoint و کلید API.
  5. برای harness میزبانی‌شده، مدل‌های مجاز را پر کنید: نام مدل‌های ارائه‌دهنده را وارد کنید (مثلاً شناسه مدل OpenAI یا Anthropic). با افزودن مدل تا ۱۰ مدل اضافه کنید. عامل‌های این harness فقط می‌توانند از این فهرست انتخاب کنند.
  6. روی ذخیره کلیک کنید.

هنگام ویرایش harness، نوع Harness قابل تغییر نیست و فیلد کلید این عبارت را نشان می‌دهد: کلید API (برای حفظ کلید ذخیره‌شده خالی بگذارید).

Claude Managed Agents

اولین باری که harness از این نوع استفاده می‌شود، MonoChat یک عامل و یک environment در آن حساب Anthropic ایجاد می‌کند و پس از آن دوباره از آن‌ها استفاده می‌کند.

نقطه پایانی سفارشی​

harness نقطه پایانی سفارشی اجراها را به سرویس خودتان می‌فرستد، مثلاً یک عامل خودمیزبان. برای هر اجرا، MonoChat یک POST به <Endpoint>/runs با Authorization: Bearer <API Key> ارسال می‌کند. بدنه درخواست شامل شناسه اجرا، دستورالعمل‌ها، ورودی، پیام‌های گفتگو، بودجه، نام‌های مستعار مدل (agent-main، agent-fallback، agent-fast) و سه URL همراه با یک توکن مخصوص این اجراست:

  • یک درگاه مدل (آدرس‌های پایه سازگار با OpenAI به شکل …/v1 و سازگار با Anthropic) که مدل‌های AI گره را فراخوانی می‌کند و بودجه را اعمال می‌کند،
  • یک سرور MCP که ابزارهای اجرا را در اختیار می‌گذارد،
  • یک URL رویدادها که سرویس شما نتیجه را در آن گزارش می‌کند (completed همراه با result، یا failed همراه با error).

توکن اجرا با پایان اجرا از کار می‌افتد.

گره عامل هوش مصنوعی​

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

فیلدها​

بخشفیلدتوضیحات
نامنام گره که روی بوم نمایش داده می‌شود.
AI Harnessالزامی. harnessی که عامل را اجرا می‌کند.
دستورالعمل‌هادستورالعمل‌های سیستمی عامل: نقش، لحن، قوانین و کارهایی که مجاز است انجام دهد یا نه.
وظیفه (به دستورالعمل‌های عامل اضافه می‌شود؛ می‌توان از برچسب‌ها استفاده کرد)کاری که این گره از عامل می‌خواهد. بعد از دستورالعمل‌ها اضافه می‌شود و می‌تواند از همان برچسب‌های پرامپت گره AI استفاده کند، مثلاً برای درج اطلاعات مشتری.
مدل‌هامدل اصلیمدلی که عامل از آن استفاده می‌کند. برای همه harnessها به‌جز نقطه پایانی سفارشی الزامی است.
مدل جایگزین (پس از رسیدن به حد نرم)مدلی که عامل پس از رسیدن به حد نرم فراخوانی‌های مدل به آن تغییر می‌کند، معمولاً مدلی ارزان‌تر یا سریع‌تر.
مدل سریع (وظایف سبک پس‌زمینه)مدلی که harness می‌تواند برای فراخوانی‌های سبک پس‌زمینه‌اش استفاده کند.
مدل (یکی از مدل‌های مجاز Harness)برای harness میزبانی‌شده به‌جای سه فیلد بالا نمایش داده می‌شود.
گفتگوی عاملگفتگوادامه نشست عامل موجود (پیش‌فرض) یا شروع نشست عامل جدید. به نشست‌های عامل نگاه کنید.
کلید وظیفه (گفتگوهای جداگانه عامل برای هر وظیفه)اختیاری. در یک گفتگو برای هر کلید یک نشست عامل جداگانه نگه می‌دارد، مثلاً booking و support.
محدودیت تاریخچه پیامتعداد پیام‌های گفتگو که به عامل داده می‌شود.
مدل‌های AI تبدیل گفتار به متنمدلی با قابلیت رونوشت. پیام‌های صوتی گفتگو به‌صورت متن به عامل می‌رسند.
تنظیمات ابزارمحدوده‌های AIپایگاه‌های دانشی که عامل می‌تواند در آن‌ها جست‌وجو کند. به‌عنوان ابزار جست‌وجوی پایگاه دانش در اختیار عامل قرار می‌گیرند.
ابزار AIتوابعی از نوع ابزار AI که عامل می‌تواند فراخوانی کند.
تعیین ابزارهای محتوای کلاینت MCP هوش مصنوعیپنلی را باز می‌کند که در آن ابزارهای MCP را اضافه می‌کنید. به کلاینت‌های MCP نگاه کنید.
پیام‌هاارسال پیام‌های میانی به مشتریبه‌طور پیش‌فرض خاموش است. وقتی روشن باشد، آنچه عامل هنگام کار می‌نویسد (مثلاً «بگذارید سفارش شما را بررسی کنم») برای مشتری ارسال می‌شود؛ وقتی خاموش باشد، به‌صورت پیام whisper که فقط تیم شما می‌بیند به نشست اضافه می‌شود.
ارسال پاسخبه‌طور پیش‌فرض روشن است. پاسخ نهایی عامل را برای مشتری ارسال می‌کند. برای استفاده از پاسخ فقط داخل جریان، آن را خاموش کنید.
بودجه اجراحداکثر فراخوانی مدلپیش‌فرض ۴.
حد نرم: فراخوانی مدلاختیاری. پس از این تعداد فراخوانی مدل، عامل به مدل جایگزین تغییر می‌کند. باید کمتر از حداکثر فراخوانی مدل باشد و به مدل جایگزین نیاز دارد.
حداکثر فراخوانی ابزارپیش‌فرض ۶. با مقدار 0، اجرا به‌محض اینکه عامل بخواهد ابزاری را فراخوانی کند با وضعیت بودجه تمام شد پایان می‌یابد.
حداکثر کل توکن‌هاپیش‌فرض ۲۰۰۰۰. توکن‌های ورودی و خروجی همه فراخوانی‌های مدل در اجرا.
حداکثر مدت (ثانیه)پیش‌فرض ۳۰.
حداکثر تلاش مجددپیش‌فرض ۲. تعداد دفعاتی که یک فراخوانی ناموفق مدل دوباره تلاش می‌شود.
نکته

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

هشدار

harnessهای میزبانی‌شده از حد نرم پشتیبانی نمی‌کنند، چون نمی‌توانند به مدل جایگزین تغییر کنند. برای آن‌ها حد نرم: فراخوانی مدل را خالی بگذارید.

وقتی جریان به گره می‌رسد چه اتفاقی می‌افتد​

  1. MonoChat موجودی شما و تنظیمات گره را بررسی می‌کند و یک اجرا را شروع می‌کند. اجرا ابتدا در صف و سپس در حال اجرا است. نمونه جریان روی گره منتظر می‌ماند.
  2. عامل دستورالعمل‌ها و وظیفه را دریافت می‌کند و، اگر جریان به یک گفتگو تعلق داشته باشد، پیام‌های گفتگو را تا محدودیت تاریخچه پیام همراه با رونویسی پیام‌های صوتی.
  3. عامل مدل‌ها و ابزارها را فراخوانی می‌کند تا به پاسخ برسد یا یک محدودیت فرا برسد. متنی که میان فراخوانی‌های ابزار می‌نویسد به‌عنوان پیام میانی در نظر گرفته می‌شود.
  4. وقتی اجرا پایان می‌یابد:
    • اگر تکمیل‌شده باشد و ارسال پاسخ روشن باشد، پاسخ برای مشتری ارسال می‌شود. پاسخ‌های بلند اگر از حد کانال بیشتر شوند (۴۰۹۶ نویسه در WhatsApp) به چند پیام تقسیم می‌شوند؛
    • اگر به شکل دیگری پایان یافته باشد، یک پیام whisper با متن «AI agent run ended: status. error» برای تیم شما به نشست اضافه می‌شود.
  5. جریان روی خروجی‌ای ادامه می‌یابد که با نحوه پایان اجرا مطابقت دارد.

اجراهای یک نشست عامل یکی‌یکی و به ترتیب پردازش می‌شوند.

خروجی‌ها​

خروجیچه زمانی
تکمیل‌شدهعامل با یک پاسخ کار را تمام کرد.
بودجه تمام شداجرا حداکثر فراخوانی مدل، حداکثر فراخوانی ابزار یا حداکثر کل توکن‌ها را مصرف کرد.
مهلت زمانی تمام شداجرا به حداکثر مدت (ثانیه) رسید.
نفرت‌پراکنی، Jailbreak، آسیب به خود، محتوای جنسی، خشونتفیلتر محتوای ارائه‌دهنده مدل اجرا را برای این دسته متوقف کرد. این‌ها همان خروجی‌هایی هستند که گره AI دارد.
در صورت شکستاجرا به هر دلیل دیگری ناموفق بود یا لغو شد. توقف توسط فیلتر محتوا نیز در گره‌هایی که پیش از وجود این خروجی‌ها ذخیره شده‌اند به اینجا می‌رسد؛ برای دریافت آن‌ها چنین گرهی را باز کنید و ذخیره کنید.

دست‌کم تکمیل‌شده و در صورت شکست را وصل کنید. الگوی رایج این است که بودجه تمام شد، مهلت زمانی تمام شد و در صورت شکست را به گره تخصیص گفتگو بفرستید تا یکی از هم‌تیمی‌ها کار را به دست بگیرد.

نشست‌های عامل​

نشست عامل، حافظه عامل در میان اجراهاست. MonoChat برای هر گفتگو، harness و کلید وظیفه یک نشست عامل فعال نگه می‌دارد.

  • ادامه نشست عامل موجود از همان نشست دوباره استفاده می‌کند، پس عامل از جایی که مانده ادامه می‌دهد. در harnessهای میزبانی‌شده، نشست خود ارائه‌دهنده هم ادامه می‌یابد.
  • شروع نشست عامل جدید نشست فعال را می‌بندد و از نو شروع می‌کند، مثلاً در آغاز یک موضوع جدید.
  • کلید وظیفه نشست‌های مستقل را کنار هم در یک گفتگو نگه می‌دارد.

صورتحساب​

  • فراخوانی‌های مدل روی مدل‌های AI ارائه‌شده توسط MonoChat طبق معمول از موجودی شما کسر می‌شوند. فراخوانی‌های مدل‌های خودتان را ارائه‌دهنده شما صورتحساب می‌کند.
  • harnessی که MonoChat ارائه می‌دهد می‌تواند برای هر اجرا، هر دقیقه و هر فراخوانی ابزار هزینه خودش را داشته باشد و، برای harness میزبانی‌شده، توکن‌هایی که ارائه‌دهنده‌اش گزارش می‌کند. این هزینه‌ها در تراکنش‌ها با عنوان اجرای عامل هوش مصنوعی، مدت عامل هوش مصنوعی، فراخوانی ابزار عامل هوش مصنوعی و دسته‌های توکن AI نمایش داده می‌شوند.
  • harnessی که با اعتبارنامه‌های خودتان اضافه می‌کنید کارمزد MonoChat ندارد؛ ارائه‌دهنده آن شما را صورتحساب می‌کند.
  • وقتی موجودی شما کافی نباشد، اجرا شروع نمی‌شود.

رویداد پایان اجرای عامل هوش مصنوعی​

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

شروع عامل از کد​

توابع سفارشی و کلاینت‌های API می‌توانند با این متدها عامل‌ها را اجرا کنند (مجوز شروع اجراهای عامل AI در اتوماسیون / مشاهده اجراهای عامل AI در اتوماسیون / لغو اجراهای عامل AI در اتوماسیون):

متدکاری که انجام می‌دهد
business.tenants.automation.ai.aiAgentRuns.createیک اجرا را شروع می‌کند. aiAgentRunId و aiAgentSessionId را برمی‌گرداند.
business.tenants.automation.ai.aiAgentRuns.showیک اجرا (_id) را با وضعیت، مصرف، مراحل و نتیجه‌اش برمی‌گرداند.
business.tenants.automation.ai.aiAgentRuns.cancelیک اجرای در صف یا در حال اجرا (_id) را لغو می‌کند.

create پارامترهای aiHarnessClientId، input (وظیفه) و در صورت نیاز sessionId (برای کار در یک گفتگو)، aiAgentSessionId، taskKey و isNewSession را می‌گیرد، و options با همان تنظیمات گره: instructions، aiModelClientId، fallbackAiModelClientId، fastAiModelClientId، harnessModel، toolCustomFunctionIds، aiScopeIds، aiMcpClientDatas، messageHistoryLimit، speechToTextAiModelClientId، forwardIntermediateMessages، willSendAnswer و یک budget الزامی. در API، مقدار پیش‌فرض forwardIntermediateMessages و willSendAnswer برابر false است.

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

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

مجوزها​

مجوزاجازه می‌دهد
مشاهده / ایجاد / به‌روزرسانی / حذف هارنس‌های AI در اتوماسیونمدیریت هارنس‌های AI
مشاهده اجراهای عامل AI در اتوماسیوندیدن اجراهای عامل هوش مصنوعی
شروع اجراهای عامل AI در اتوماسیونفراخوانی aiAgentRuns.create
لغو اجراهای عامل AI در اتوماسیونفراخوانی aiAgentRuns.cancel

نقش‌ها را ببینید.