وبلاگ
OpenAI Agents API در ۲۰۲۶؛ راهنمای ساخت عاملهای چندمرحلهای امن
فهرست مطالب
“تسلط به برنامهنویسی پایتون با هوش مصنوعی: آموزش کدنویسی هوشمند با ChatGPT”
0 تا 100 عطرسازی + (30 فرمولاسیون اختصاصی حامی صنعت)
Claude & GPT Credit – API | IDE | n8n
خرید کردیت API برای Claude و GPT با امکان استفاده در IDE و n8n. مناسب برنامهنویسی، تولید محتوا، تحلیل داده و ساخت اتوماسیون؛ راهنمای اتصال و پشتیبانی حامی صنعت همراه سفارش ارائه میشود. مدل و مقدار اعتبار را پیش از خرید بررسی کنید و برای دریافت کردیت API اقدام کنید.
Gemini Plus ششماهه
اکانت Leonardo.ai با 8500 کردیت
خرید اکانت ChatGPT Plus یک ماهه با کردیت CODEX اختصاصی
دایرکت اتوماتیک اینستاگرام حامی | اشتراک ۳۰روزه یک پیج
اشتراک ۳۰روزه پنل دایرکت اتوماتیک اینستاگرام حامی برای یک پیج؛ پاسخ خودکار کامنت و دایرکت، کمپین کلمه کلیدی، قفل فالو، جذب لید، دکمه و لینک و گزارش تحلیل پیج. پاسخهای ثابت بدون نیاز به هوش مصنوعی کار میکنند و اتصال OpenAI Compatible اختیاری است. همین حالا اشتراک پنل اینستاگرام را تهیه کنید و راهاندازی را از داخل پنل فارسی شروع کنید.
دوره آموزش Flutter و برنامه نویسی Dart [پروژه محور]
دوره جامع آموزش برنامهنویسی پایتون + هک اخلاقی [با همکاری شاهک]
دوره جامع آموزش فرمولاسیون لوازم آرایشی
دوره جامع علم داده، یادگیری ماشین، یادگیری عمیق و NLP
OpenAI Agents API در ۲۰۲۶؛ چطور عاملهای چندمرحلهای را پایدار و امن بسازیم؟

یک چتبات پاسخ میدهد؛ یک agent باید برنامهریزی کند، ابزار بهکار ببرد، خطا را مدیریت کند و کار را تا نتیجه دنبال کند. اما چطور جلوی اقدام اشتباه را میگیریم؟ OpenAI در سپتامبر ۲۰۲۶ Agents API را در نسخهٔ بتا عمومی معرفی کرد؛ زیرساختی برای ساخت عاملهای ابری با نشستهای ماندگار، ابزار، محیط اجرای کد و امکان ادامهٔ کار پس از وقفه. در بهروزرسانیهای بعدی نیز امکاناتی مانند تغییر ابزارهای نشست، فشردهسازی زمینه و رایانهگردی مرورگر به این خانواده اضافه شد. این راهنما معماری، کاربرد، کنترل و ارزیابی را از پایه توضیح میدهد.
این مقاله تا ۱۹ نوامبر ۲۰۲۶ با تکیه بر مستندات رسمی توسعهدهندگان OpenAI بهروز شده است. Agents API هنوز در مسیر بتا توصیف شده و قابلیتها، قیمت، مدلهای پشتیبانیشده و شرایط دسترسی ممکن است تغییر کنند. برای پیادهسازی، مستندات همان روز و حساب خود را بررسی کنید. مثالهای این راهنما الگوهای طراحی هستند، نه تضمین اینکه هر قابلیت در هر حساب یا منطقه فعال است.
OpenAI Agents API چیست؟
Agents API یک مسیر توسعه برای ساخت عاملهای ابری با harness مدیریتشده است. OpenAI در معرفی سپتامبر ۲۰۲۶ گفت این API تجربهٔ مهندسی پشت Codex را به توسعهدهندگان میآورد: مدیریت زمینه، استفاده از ابزار، هماهنگی عاملهای فرعی و زیرساختی که میتواند برای مدت طولانی کار کند، در محیطی برای فایل و اجرای کد. هدف این نیست که فقط یک پیام به مدل بدهید و متن بگیرید؛ هدف ساخت یک جلسهٔ چندمرحلهای است که وضعیت، ابزار و پیشرفت آن قابل پیگیری باشد.
در یک workflow معمولی، برنامهٔ شما درخواست کاربر را میگیرد، نشست را آغاز یا ادامه میدهد، مدل را با دستور و ابزارهای مجاز فراخوانی میکند، رویدادهای ابزار را دریافت میکند و نتیجه را به کاربر میرساند. اگر مدل نیاز به اجرای کد یا خواندن فایل داشته باشد، محیط اجرایی مناسب باید آماده شود. اگر فرایند متوقف شود، شناسهٔ نشست و وضعیت ذخیرهشده به ادامهٔ کار کمک میکند. در طراحی واقعی، برنامهٔ میزبان هنوز مسئول مجوز کاربر، داده، تصمیم انتشار و تجربهٔ محصول است.
فرق agent با زنجیرهٔ سادهٔ API در میزان اختیار و حلقهٔ اجرا است. زنجیرهٔ ثابت معمولاً چند مرحلهٔ شناختهشده دارد: استخراج داده، خلاصه، اعتبارسنجی. agent ممکن است با توجه به نتیجه تصمیم بگیرد ابزار دیگری را فراخوانی کند یا مسئله را دوباره صورتبندی کند. این انعطاف میتواند مفید باشد، اما هزینه، خطایابی و ریسک را بالا میبرد. اگر workflow شما کاملاً قابل پیشبینی است، یک برنامهٔ صریح و محدود شاید سادهتر و قابل اعتمادتر باشد.
معماری مدیریتشده باعث نمیشود همهٔ مسئولیتها به ارائهدهنده منتقل شوند. اپلیکیشن شما باید احراز هویت کاربر، مجوز ابزار، سیاست نگهداری داده، تأیید عمل، محدودیت بودجه، رسیدگی به خطا و ثبت رویداد را طراحی کند. اگر agent حساب مشتری را تغییر میدهد، این تصمیم همچنان در محصول شما اتفاق میافتد. اگر ابزار از MCP استفاده میکند، باید بدانید چه سروری متصل است و چه دادهای به آن میرسد. کنترل دامنهٔ عمل را از سمت برنامه اعمال کنید، نه فقط در prompt.
چه زمانی از Agents API استفاده کنیم؟
Agents API را زمانی ارزیابی کنید که یک کار چندمرحلهای است، بین مراحل باید وضعیت نگه دارید، ابزارهای مختلف دخیلاند یا کار ممکن است از یک نوبت مکالمه طولانیتر شود. نمونهها میتواند بررسی یک پروژهٔ کدنویسی، جمعآوری منابع و آمادهسازی گزارش، یا مرور یک پروندهٔ بزرگ باشد. در همهٔ این موارد باید خروجی قابل بازبینی، توقف، ادامه و خطایابی اهمیت داشته باشد.
اگر فقط به یک پاسخ کوتاه نیاز دارید، نشست پایدار و sandbox ممکن است پیچیدگی غیرضروری باشند. اگر مراحل از پیش معلوم و کمریسکاند، یک درخواست مدل بههمراه ابزارهای محدود ممکن است کافی باشد. معیار تصمیم، عنوان جذاب «agent» نیست؛ ببینید آیا قابلیت مدیریت نشست، رویداد، ابزار و بازیابی واقعاً مسئلهای را حل میکند. هر جزء جدید هزینهٔ توسعه، زیرساخت، logging و آزمون اضافه میکند.
برای تصمیم معماری، کار را به سه گروه تقسیم کنید: پاسخ مستقیم، workflow ثابت، و workflow تطبیقی چندمرحلهای. پاسخ مستقیم معمولاً به یک درخواست مدل نیاز دارد. workflow ثابت با منطق روشن در کد اجرا میشود. workflow تطبیقی میتواند به agent نیاز داشته باشد، اما تنها اگر تفاوت مسیرها معنادار باشد و تصمیم مدل را بتوان کنترل کرد. داشتن چند ابزار بهتنهایی agent را ضروری نمیکند.
| نوع کار | گزینهٔ شروع | چه وقت Agent ارزش دارد؟ | کنترل لازم |
|---|---|---|---|
| پاسخ یکمرحلهای | درخواست معمول API | معمولاً نیازی نیست | اعتبارسنجی خروجی |
| فرایند ثابت | کد workflow صریح | اگر نگهداری نشست یا ابزار پویا لازم است | تست هر مرحله و مدیریت خطا |
| کار چندمرحلهای تطبیقی | Agents API در محیط محدود | وقتی انتخاب مرحله و ادامهٔ کار انعطاف لازم دارد | مجوز، توقف، تأیید و rollback |
یک نشانهٔ خوب برای agent این است که بتوانید یک وظیفهٔ واقعی را با چند زیرمرحله شرح دهید و دلیل نیاز به تصمیم پویا را توضیح دهید. یک نشانهٔ بد این است که «میخواهیم یک AI agent داشته باشیم» اما نتوانید بگویید چه ابزارهایی لازماند، کجا باید متوقف شود و خروجی موفق چیست. قبل از انتخاب API، وضعیت فعلی را رسم کنید و مسیر سادهتر را نیز با آن مقایسه کنید.
اجزای اصلی معماری یک عامل ابری
۱. دستور و دامنهٔ وظیفه: درخواست کاربر را به هدف قابل انجام و محدود تبدیل کنید. مشخص کنید کار تا کجا پیش میرود، چه دادهای را میتواند ببیند و چه عملهایی ممنوع است. دامنهٔ مبهمی مثل «همه چیز را مرتب کن» برای agent خطرناک است؛ هدفی مثل «سه فایل گزارش را خلاصه کن، اختلاف عددها را فهرست کن و پیش از ارسال از من تأیید بگیر» قابل کنترلتر است.
۲. مدل و تنظیمات: مدل، سطح reasoning، زمان پاسخ و نرخ هزینه را براساس وظیفه انتخاب کنید. مدل قویتر لزوماً همیشه لازم نیست. برای کار کمریسک و تکراری، مدل سریعتر یا مسیر سادهتر را بسنجید؛ برای تصمیم دشوار، مدل مناسب را با نمونههای واقعی ارزیابی کنید. نام مدل را در پیکربندی نگه دارید تا تغییر و rollback بدون بازنویسی کد ممکن باشد.
۳. ابزارها: هر ابزار باید ورودی، خروجی، خطا و مجوز مشخص داشته باشد. یک ابزار جستوجو فقط بخواند؛ ابزار تغییر رکورد جدا باشد. برای هر عمل، محدودیت اندازه، دامنهٔ منابع و timeout تعیین کنید. نتیجهٔ ابزار را بررسی کنید و به مدل نشان دهید اگر عملیات شکست خورده است. یک ابزار قدرتمند با دسترسی گسترده میتواند اثر یک prompt injection را تشدید کند.
۴. نشست و وضعیت: برای هر کار شناسهٔ نشست یا شناسهٔ داخلی داشته باشید، مالکیت آن را به کاربر مشخص وصل کنید و وضعیت مرحله را ثبت کنید. نگهداری مکالمه به معنی ذخیرهٔ همهٔ دادهها برای همیشه نیست. فقط دادهٔ لازم را حفظ کنید، مدت نگهداری را تعریف کنید و امکان پایان یا پاککردن کار را فراهم کنید. نشستهای سازمانی باید از یکدیگر جدا باشند.
۵. محیط اجرا: اگر عامل کد اجرا میکند یا فایل میسازد، sandbox را از سامانهٔ اصلی جدا کنید. ورودی ساختگی یا کپی محدود بدهید؛ secrets و اطلاعات تولیدی را به محیط آزمایشی منتقل نکنید. دسترسی شبکه را محدود نگه دارید و حجم CPU، حافظه و زمان را کنترل کنید. قبل از استفادهٔ فایل تولیدشده در production، محتوا و مجوز آن را بازبینی کنید.
۶. نظارت و رویدادها: درخواستها، پاسخهای ابزار، خطاها، زمان، هزینه و تصمیمهای تأیید را به شکل امن ثبت کنید. از ثبت دادهٔ خصوصی غیرضروری پرهیز کنید. شناسهٔ هر اجرای agent را با رخدادهای محصول مرتبط کنید تا بتوانید علت خطا را پیدا کنید. شمار تلاش مجدد، توقف دستی و انتقال به انسان معیارهای مهمی هستند.
۷. انسان در حلقه: برای هر عمل بیرونی تعیین کنید آیا نیاز به تأیید دارد. انتشار، ارسال، پرداخت، حذف و تغییر اطلاعات کاربر معمولاً باید قبل از اجرا برای تأیید نمایش داده شوند. تأیید باید شامل خلاصهٔ اثر، مقصد و دادهٔ نهایی باشد؛ یک دکمهٔ مبهم «ادامه» آگاهی کافی ایجاد نمیکند.
نشست ماندگار، sandbox و بازیابی پس از وقفه
در معرفی سپتامبر، OpenAI از نشستهای durable برای ادامهٔ کار در چند نوبت، جریاندادن پیشرفت و اتصال ابزارها و MCP serverها گفت. این قابلیت برای کارهای طولانی مفید است، اما «ماندگار» را با «همیشه امن» یا «بیهزینه» اشتباه نگیرید. نشست باید مالک داشته باشد، زمان انقضا یا سیاست نگهداری داشته باشد و امکان توقف داشته باشد. اگر کاربری نشست دیگری را به دست آورد، اطلاعات پروژه یا اقدامات قبلی میتواند افشا شود.
بازیابی باید از وضعیت مشخص انجام شود. اگر عامل پس از اجرای ابزار قطع شد، برنامه باید بداند آیا ابزار واقعاً عمل را انجام داده یا خیر. در غیر این صورت، retry میتواند پیام را دوباره ارسال یا پرداخت را تکرار کند. برای عملیات حساس، idempotency key و بررسی نتیجهٔ قبلی بگذارید. بازیابی کورکورانهٔ آخرین درخواست میتواند side effect تکراری ایجاد کند.
OpenAI توضیح داده که sandbox میتواند در محیط مدیریتشده، زیرساخت خود شما یا یکی از شریکهای پشتیبانیشده باشد. انتخاب این مسیر به داده، کنترل، هزینه، latency و نیازهای تطبیق بستگی دارد. sandbox مدیریتشده میتواند شروع را آسانتر کند؛ محیط خودمیزبان ممکن است کنترل بیشتری بدهد اما نگهداری و امنیت آن با تیم شماست. مزیت هر دو را با threat model و نیاز سازمانی مقایسه کنید.
در changelog اکتبر، sandboxهای میزبانیشدهٔ OpenAI برای Agents API با Artifact SDK و مهارتهایی برای ساخت و ویرایش spreadsheet، presentation و Word document بهروزرسانی شدهاند. اگر از artifact استفاده میکنید، محتوا و فرمولها را بررسی کنید؛ فایل ایجادشده ممکن است اشتباه یا ناقص باشد. نسخهٔ سند، منبع داده و تغییرهایی که agent انجام داده را نگه دارید. هر فایل را پیش از ارسال به مخاطب یا استفادهٔ تجاری بازبینی کنید.
در یک کار چندساعته، فشردهسازی زمینه (compaction) میتواند برای ادامهٔ مکالمه مفید باشد. یادداشت اکتبر میگوید compaction در پسزمینه بهطور پیشفرض اجرا میشود و حالت blocking نیز با تنظیم مربوط قابل انتخاب است. فشردهسازی ممکن است بخشی از زمینه را خلاصه کند یا استفادهٔ توکن را افزایش دهد. اگر جزئیات سند یا قواعد مهماند، پس از هر compaction رفتار عامل را در نمونههای طولانی آزمایش کنید و خلاصهٔ وضعیت قابل بازرسی داشته باشید.
در همان بهروزرسانی، قابلیت time awareness آزمایشی و خاموش بهطور پیشفرض توصیف شده است. اگر agent بر اساس زمان برنامهریزی میکند، مشخص کنید timestamp از کجا میآید، منطقهٔ زمانی چیست و هر چند وقت یکبار یادآوری میشود. زمان نادرست میتواند کار زمانبندیشده را زود یا دیر اجرا کند. زمان را از محیط معتبر در اختیار مدل بگذارید و برای اقدامهای زمانحساس بررسی منطقی در کد داشته باشید.
اتصال ابزارها و MCP؛ مرز داده و دستور
OpenAI در معرفی Agents API امکان اتصال ابزار و MCP server را مطرح میکند. MCP استانداردی برای دسترسی مدل به ابزار و منابع بیرونی است، اما نام استاندارد بهتنهایی امنیت ایجاد نمیکند. هر سرور ابزار باید قابل شناسایی، مجاز و محدود باشد. قبل از اتصال، نام endpoint، scope، نوع دادهٔ قابل خواندن یا نوشتن و مالک آن را مشخص کنید. ابزارهای قدیمی یا ناشناخته را در محیط production با دسترسی کامل وصل نکنید.
خروجی ابزار را بهعنوان دادهٔ نامطمئن در نظر بگیرید. صفحهٔ وب یا سند ممکن است متنهایی داشته باشد که میگویند «دستورهای قبلی را نادیده بگیر» یا «اطلاعات محرمانه را بفرست». مدل نباید این متن را بهعنوان مجوز جدید تفسیر کند. کد شما باید اختیار هر ابزار را به کاربر و هدف مربوط وصل کند و اجازه ندهد ابزار از متن دریافتشده، scope بیشتری بگیرد.
ابزارها را کوچک و تکمنظوره بسازید. ابزار «خواندن سفارش» را از «لغو سفارش» جدا کنید؛ ابزار «پیشنویس ایمیل» را از «ارسال ایمیل» جدا کنید. پاسخ ابزار باید خلاصه و ساختاریافته باشد و اطلاعات غیرضروری را به مدل ندهد. برای مقدارهای حساس، کد سمت سرور را اعتبارسنجی کنید. ورودی مدل هرگز تنها اعتبارسنج درخواست برای حذف، پرداخت یا تغییر حساب نباشد.
اگر چند ابزار به هم متصلاند، مسیر اعتماد را رسم کنید: مدل به کدام ابزار دسترسی دارد، ابزار از کجا داده میگیرد و داده به چه سرویس دیگری میرود؟ لاگکردن این مسیر برای عیبیابی و تحلیل حادثه لازم است. هنگام تست، رفتار ابزار را با پاسخهای ناقص، timeout و مقدار نادرست بررسی کنید. agent باید بتواند شکست را اعلام کند، نه اینکه آن را با یک پاسخ قطعی بپوشاند.
تأیید انسانی و کنترل عمل بیرونی
در بعضی نسخههای Agents API، OpenAI ویژگی automatic review را برای پروژههای واجد شرایط شرح داده است. در آن مسیر، مدل میتواند بعضی درخواستهای ابزار یا permission را بررسی و تأیید یا رد کند. این قابلیت جای سیاست سازمان یا تصمیم انسانی برای اقدام حساس نیست؛ مستندات خود آن را برای درخواستها و permissionهای پشتیبانیشده و با محدودیت معرفی میکنند. پیش از فعالسازی، دامنه، هزینه و محدودیتهای review را بخوانید و با آزمون داخلی اعتبارسنجی کنید.
برای تأیید مؤثر، کاربر باید بداند چه چیزی قرار است اتفاق بیفتد. نام عمل، مقصد، دادهٔ درگیر و پیامد احتمالی را نمایش دهید. مثال بد، دکمهای است که فقط میگوید «بله». مثال بهتر، نمایش «ارسال این پیام به این گیرنده» یا «حذف این رکورد از این حساب» همراه با خلاصهٔ محتوا است. برای پرداخت یا تغییر برگشتناپذیر، احراز هویت مجدد یا تأیید دوم را در نظر بگیرید.
اگر عامل فقط پیشنویس میسازد، کاربر میتواند آن را ویرایش کند. اگر عامل پیام را ارسال میکند، مرحلهٔ approval باید پس از ساخت نهایی پیام باشد. اگر محتوا پس از تأیید تغییر کند، تأیید قبلی دیگر معتبر نیست. در طراحی API، نتیجهٔ تأیید را به همان نسخهٔ عمل پیوند دهید و قبل از اجرا تغییر ناخواسته را دوباره بررسی کنید.
برای کارهای برنامهریزیشده، امکان لغو باید تا جای ممکن وجود داشته باشد. اگر یک automation آغاز شد، کاربر یا مدیر باید بتواند آن را متوقف کند و بفهمد کدام مرحله کامل شده است. «توقف» باید روی وظیفهٔ واقعی اثر بگذارد، نه صرفاً رابط را ببندد. رویدادهای نیمهتمام را مشخص کنید تا پس از قطع اتصال، دوبارهکاری رخ ندهد.
یک workflow نمونه از شروع تا نتیجه
فرض کنید مشتری میخواهد گزارشی از چند فایل قرارداد بگیرد. ابتدا برنامه درخواست و فایلهای مجاز را شناسایی میکند، مالکیت دسترسی را میسنجد و فایلهای شخصی یا خارج از محدوده را رد میکند. سپس agent با ابزار خواندن فایل به اسناد دسترسی مییابد، گزارههای کلیدی و محل استناد را استخراج میکند و فهرست پرسشهای بیپاسخ را میسازد. هنوز هیچ ایمیلی ارسال یا سند اصلی تغییر داده نشده است.
در مرحلهٔ بعد، برنامهٔ شما خروجی استخراج را بررسی میکند: آیا منبع به فایل مجاز مربوط است؟ آیا شناسهٔ بند معتبر است؟ آیا agent ادعایی بدون استناد آورده؟ اگر جواب قابل قبول بود، یک پیشنویس گزارش ساخته میشود. کاربر گزارش را مشاهده میکند و میتواند آن را ویرایش کند یا سؤال تکمیلی بپرسد. اگر قرار است گزارش برای فرد دیگری ارسال شود، نام مقصد و محتوای نهایی پیش از ارسال نمایش داده میشود.
در تمام مراحل، رویدادها با شناسهٔ کار ثبت میشوند: نشست آغاز شد، کدام ابزار خواند، چه چیزی استخراج شد، کدام check شکست خورد و آیا انسان تأیید داد. log نباید متن محرمانهٔ کامل را بدون نیاز ذخیره کند؛ میتوان شناسهٔ سند، شمارش و خلاصهٔ پالایششده ثبت کرد. اگر مدل به timeout خورد، برنامه نتیجهٔ ابزار را بررسی میکند و از تکرار همان عملیات جلوگیری میکند.
این مثال برای هر سازمان یکسان نیست. در محیط حقوقی یا پزشکی، قوانین نگهداری و مسئولیت ممکن است متفاوت باشد. نقطهٔ ثابت، کنترل اثر بیرونی است: مدل پیشنویس میدهد، سیستم مجوز و منبع را اعتبارسنجی میکند و انسان نتیجه را تأیید میکند. در وظیفههای کمخطر و قابل برگشت شاید مسیر سادهتر کافی باشد؛ ریسک را با پیامد واقعی بسنجید.
دوازده گام برای ساخت نخستین عامل
- مسئلهٔ کوچک انتخاب کنید. یک کار تکراری و کمریسک را انتخاب کنید، نه «دستیار همهکاره».
- نتیجهٔ موفق را تعریف کنید. معیار پذیرش، قالب و موارد ارجاع را بنویسید.
- دامنهٔ داده را مشخص کنید. معلوم کنید agent چه فایل، پایگاه داده یا صفحهای را میبیند.
- ابزارها را محدود کنید. هر ابزار یک وظیفهٔ مشخص و scope حداقلی داشته باشد.
- روش نشست را طراحی کنید. مالک، انقضا، بازیابی و حذف را تعیین کنید.
- محیط اجرا را ایزوله کنید. دادهٔ آزمایشی و دسترسی شبکهٔ محدود بهکار ببرید.
- مرحلهٔ تأیید را اضافه کنید. ارسال، حذف و تغییر را پیش از اجرا به کاربر نشان دهید.
- خطا و retry را کنترل کنید. از تکرار side effect جلوگیری کنید.
- هزینه را محدود کنید. سقف توکن، تعداد ابزار و زمان اجرا تعریف کنید.
- نمونههای شکست را تست کنید. ورودی ناقص، timeout و prompt injection را اضافه کنید.
- لاگ امن بسازید. شناسهها، زمان و نتیجهٔ پالایششده را ثبت کنید.
- با ترافیک محدود عرضه کنید. شاخص توقف، rollback و مالک مسئول داشته باشید.
در هر گام یک تصمیم ثبت کنید. اگر ابزار لازم نیست، حذفش کنید؛ اگر دادهٔ کامل لازم نیست، فقط قطعهٔ موردنیاز را بدهید. معماری خوب به تعداد agent یا ابزار وابسته نیست؛ به کوچکبودن سطح خطا و شفافیت مسیر وابسته است. برای پروژهٔ اول، مدل را مجبور نکنید دهها کار را در یک نشست انجام دهد. یک وظیفهٔ قابل اندازهگیری تجربهٔ بهتری برای یادگیری و عیبیابی فراهم میکند.
ارزیابی عامل: فراتر از نمرهٔ مدل
agent را در سطح workflow بسنجید، نه فقط متن نهایی. اگر مدل پاسخ خوبی میدهد اما ابزار را با ورودی نادرست صدا میزند، کار شکست خورده است. نرخ موفقیت ابزار، تعداد callها، زمان کل، تعداد توقف دستی، تعداد retry، هزینهٔ هر نتیجه و نیاز به اصلاح را ثبت کنید. برای کار حساس، شدت خطا را جداگانه بنویسید؛ میانگین خوب ممکن است یک خطای نادر اما پرهزینه را پنهان کند.
یک مجموعهٔ تست ۳۰ تا ۱۰۰ موردی بسازید. نمونهها شامل ورودی عادی، دادهٔ ناموجود، سند متناقض، پیام injection، خطای ابزار، قطع ارتباط و درخواست خارج از scope باشند. هر مورد باید انتظار مشخصی داشته باشد: تکمیل، سؤال روشنکننده، ارجاع به انسان یا رد امن. اگر هدف صرفاً پاسخ دادن است، مدل ممکن است در مواردی که باید متوقف شود همچنان ادامه دهد؛ بنابراین توقف درست هم بخشی از کیفیت است.
آزمون آفلاین را پیش از ترافیک واقعی انجام دهید. سپس shadow test اجرا کنید تا agent روی نسخهٔ کپی درخواستها کار کند اما کاربر نتیجهٔ فعلی را دریافت کند. تفاوتها را بدون اثر بیرونی بررسی کنید. پس از آن، میتوانید درصد کمی از ترافیک کمریسک را به نسخهٔ تازه بدهید و بهتدریج افزایش دهید. معیار rollback را پیش از شروع بنویسید: مثلاً افزایش خطای ابزار، هزینه یا شکایت کاربر.
پس از هر تغییر در prompt، مدل، ابزار یا compaction، آزمون رگرسیون اجرا کنید. تغییر یک ابزار میتواند رفتار مدل را عوض کند، حتی اگر مدل همان باشد. نمونههای مشکلساز را به مجموعه اضافه کنید و نسخهٔ قبلی را نگه دارید. ارزیابی مستمر از یک بنچمارک بزرگ اما یکباره برای محصولی که هر هفته تغییر میکند مفیدتر است.
امنیت و حریم خصوصی؛ مواردی که به prompt محدود نمیشوند
prompt injection زمانی رخ میدهد که متن نامطمئن تلاش میکند قواعد عامل را تغییر دهد یا دادهٔ محافظتشده را بخواهد. داده میتواند در صفحهٔ وب، ایمیل، فایل، نتیجهٔ جستوجو یا پیام ابزار باشد. به مدل یادآوری کنید که محتوا دستور نیست، ولی همزمان از کد برای محدودکردن scope و ابزار استفاده کنید. هیچ متن ورودی نباید بتواند مجوزهای سمت سرور را تغییر دهد.
دادهٔ حساس را در محیطی که وضعیت نگهداری یا دسترسی آن را نمیدانید قرار ندهید. سیاست API، قرارداد سازمانی، منطقهٔ پردازش و ابزارهای متصل را بررسی کنید. کلید API را در مرورگر یا کد قابل مشاهدهٔ کاربر نگذارید. برای محیط dev و production کلید جدا و دامنهٔ مجوز جدا داشته باشید. logها را به حد لازم محدود کنید و دسترسی را به افرادی بدهید که واقعاً به آن نیاز دارند.
اگر agent به اجرای کد دسترسی دارد، وابستگیهای پیشنهادی را بررسی کنید، شبکه را محدود کنید، فایلهای حساس را mount نکنید و خروجی را پیش از اجرا بازبینی کنید. محدودیت زمان و منابع مانع حلقهٔ بیپایان یا هزینهٔ غیرمنتظره میشود. دستورهای shell میتوانند فایل را حذف کنند یا داده را بیرون بفرستند؛ هیچ فرمانی را بدون فهم اثر در محیط اصلی اجرا نکنید.
برای agent چندعاملی یا delegation، سطح دسترسی عامل فرعی را محدودتر از عامل اصلی نگه دارید. دادهٔ لازم برای یک زیروظیفه را فقط همانقدر ارسال کنید که لازم است. تعداد agentهای همکار را بیدلیل افزایش ندهید؛ ارتباط میان آنها خطایابی را سخت میکند و احتمال ناهماهنگی را بالا میبرد. اگر میتوانید مسئله را با چند تابع صریح حل کنید، همان ساختار ممکن است سادهتر باشد.
برای تصمیمی که بر شخص اثر میگذارد، انسان باید امکان فهم، اعتراض و اصلاح داشته باشد. agent را تصمیمگیر نهایی استخدام، اعتبار، دسترسی یا خدمات پزشکی قرار ندهید. نتیجهٔ سیستم را به شکل منبعدار و قابل توضیح ارائه کنید و مشخص کنید کدام داده و ابزار استفاده شدهاند. نظارت پس از عرضه بخشی از مسئولیت صاحب محصول است.
هزینه و بهرهوری را چطور حساب کنیم؟
هزینهٔ agent فقط مدل نیست. توکن ورودی و خروجی، ابزار، sandbox، ذخیرهٔ فایل، شبکه، تلاش مجدد، پایش، نیروی انسانی و پشتیبانی را جمع کنید. هزینه را بهازای یک وظیفهٔ پذیرفتهشده محاسبه کنید. اگر agent برای هر درخواست پنج بار ابزار میزند، حتی پاسخ متنی ارزان ممکن است workflow گران بسازد. اگر مدل کار را کامل نمیکند و انسان باید از ابتدا شروع کند، هزینهٔ واقعی بیشتر است.
حداکثر تعداد گام، زمان اجرا، فراخوانی ابزار و بودجهٔ توکن را تعیین کنید. وقتی از سقف عبور کرد، عامل را متوقف و وضعیت را به کاربر نمایش دهید. قرار نیست agent بینهایت تلاش کند تا پاسخ دهد. برای کار روزمره، مسیر کمهزینهتر را اول اجرا کنید و فقط موارد پیچیده را به مدل با استدلال بیشتر بفرستید. مسیریابی را براساس دادهٔ قابل سنجش طراحی کنید.
برای سنجش اثر، قبل و بعد از استقرار را مقایسه کنید: زمان رسیدگی، نرخ خطای اصلاحشده، رضایت کاربر، تعداد escalation، هزینهٔ پشتیبانی و میزان کار دستی. کاهش زمان بهتنهایی کافی نیست اگر خطا و شکایت افزایش یابد. گروه کنترل یا اجرای shadow میتواند نشان دهد نتیجه از agent بوده یا تغییرات دیگر. معیارها را پیشاپیش تعریف کنید تا بعد از دیدن خروجی مطلوب انتخاب نشوند.
آپدیتهای Agents API در پاییز ۲۰۲۶
معرفی سپتامبر API را در بتای عمومی قرار داد و بر نشست پایدار، مدیریت context، هماهنگی زیروظایف، sandbox و اتصال ابزارهای سفارشی یا MCP تأکید کرد. در ۲۹ سپتامبر، رایانهگردی در مرورگر میزبانیشده اضافه شد و تأیید دسترسی وبسایت و ورود به حساب در اختیار اپلیکیشن قرار گرفت. این جزئیات یادآورند که کنترل ورود و وبسایت باید در برنامهٔ میزبان طراحی شود؛ عامل بهطور خودکار مجاز به مشاهدهٔ هر صفحهای نیست.
در اکتبر، changelog از امکان بهروزرسانی ابزارهای نشست موجود خبر داد؛ ابزارهای function و MCP در نوبت بعدی مدل و ابزارهای داخلی در نوبت بعدی وارد میشوند. همچنین compaction در پسزمینه بهطور پیشفرض و time awareness آزمایشی با تنظیم اختیاری توصیف شده است. در ۳۰ اکتبر automatic review برای پروژههای واجد شرایط آمد. این قابلیتها را بر اساس نیاز طراحی کنید و قبل از اتکا در production، محدودیت نسخهٔ بتا را بررسی کنید.
همان ماه، OpenAI-hosted sandboxes مهارتهای ساخت و ویرایش سند، ارائه و صفحهگسترده را دریافت کردند و حالت ultrafast برای برخی مدلها و تنظیمات معرفی شد. همچنین schedule automation برای نشستهای API اعلام شده است. هر قابلیت جدید میتواند امکانات بیشتری بدهد، اما وابستگی تازه، قیمت و سطح خطا را نیز تغییر میدهد. تغییرها را در مستندات، کد و آزمونهای محصول ثبت کنید.
برای اینکه مستندات روز را پیگیری کنید، changelog رسمی را بهعنوان منبع اصلی در نظر بگیرید. خلاصهٔ رسانهای یا آموزش قدیمی ممکن است با API فعلی هماهنگ نباشد. هنگام انتشار مقالهٔ آموزشی، تاریخ آخرین بررسی را درج کنید و دستورالعملهای نسخهٔ قبل را بهعنوان قطعی آموزش ندهید. برای محصولی که به beta وابسته است، برنامهٔ جایگزین و مسیر مهاجرت را در نظر بگیرید.
پرسشهای متداول دربارهٔ OpenAI Agents API
Agents API چیست؟
یک API بتا برای ساخت عاملهای ابری با ابزار، نشست پایدار، اجرای کد و مدیریت مراحل طولانی است. اپلیکیشن شما همچنان مسئول مجوز کاربر، حفاظت داده، تأیید عمل و تجربهٔ محصول است.
آیا برای هر چتباتی به agent نیاز دارم؟
خیر. پاسخهای یکمرحلهای معمولاً به درخواست عادی مدل نیاز دارند و workflowهای ثابت را شاید بتوان با کد ساده مدیریت کرد. agent زمانی ارزش دارد که انتخاب مرحله، ابزار یا ادامهٔ کار واقعاً تطبیقی باشد.
آیا Agents API به MCP وصل میشود؟
OpenAI در معرفی، اتصال ابزارهای سفارشی و MCP serverها را بیان کرده است. جزئیات نسخه و پیکربندی فعلی را در مستندات روز بررسی کنید و هر server را با scope محدود و مالک مشخص متصل کنید.
آیا نشستهای پایدار امن هستند؟
پایداری به شما امکان ادامهٔ کار میدهد، اما امنیت به کنترل مالکیت، مدت نگهداری، مجوزها، حفاظت اطلاعات و امکان توقف بستگی دارد. نشستها را از هم جدا کنید و دادهٔ غیرضروری ذخیره نکنید.
آیا sandbox جلوی همهٔ خطرها را میگیرد؟
خیر. sandbox محیط اجرا را محدود میکند، ولی مجوزهای ابزار، prompt injection، خروجی نادرست و افشای داده همچنان باید کنترل شوند. تنظیمات، شبکه و دادهٔ ورودی را بررسی کنید.
آیا agent میتواند کار را چند روز ادامه دهد؟
OpenAI زیرساخت را برای نشستهای بلندمدت و ادامه پس از وقفه معرفی کرده است؛ مدت و محدودیت دقیق به محصول، مدل و تنظیمات جاری وابسته است. سقف زمان، هزینه و امکان توقف را در برنامه تعریف کنید.
automatic review جای تأیید انسانی را میگیرد؟
نه. این قابلیت برای درخواستها و پروژههای واجد شرایط توصیف شده و محدودیت دارد. برای اقدامهای حساس، سیاست سازمان و تأیید انسانی خود را حفظ کنید و مستندات قابلیت را بخوانید.
چطور از اجرای دوبارهٔ یک عملیات جلوگیری کنم؟
برای عملهای دارای اثر بیرونی idempotency key، بررسی وضعیت قبلی و ثبت نتیجه استفاده کنید. پس از قطع ارتباط، پیش از retry مطمئن شوید عملیات اول اجرا نشده یا بهطور جزئی انجام نشده است.
چه سنجههایی برای agent مهماند؟
نرخ موفقیت کار، صحت ابزار، زمان end-to-end، هزینهٔ هر نتیجهٔ پذیرفتهشده، retry، توقف دستی، شکایت و شدت خطا را بسنجید. تنها کیفیت متن نهایی کافی نیست.
آیا OpenAI-hosted sandbox برای همه مناسب است؟
این به نیاز کنترل، محل داده، هزینه، دسترسی شبکه و سیاست سازمان بستگی دارد. sandbox مدیریتشده میتواند شروع را آسان کند؛ محیط خودتان ممکن است کنترل متفاوتی بدهد اما مسئولیت امنیت و نگهداری را هم افزایش میدهد.
این راهنما بر اساس چه اطلاعاتی نوشته شده است؟
مبنای آن معرفی Agents API و changelog رسمی تا ۱۹ نوامبر ۲۰۲۶ است. چون API در بتای عمومی معرفی شده، قابلیت و شرایط آن ممکن است تغییر کند؛ مستندات روز را بخوانید.
جمعبندی: agent را با اختیار محدود شروع کنید
OpenAI Agents API امکاناتی برای نشست ماندگار، ابزار، sandbox و اجرای کارهای چندمرحلهای فراهم میکند. این امکانات میتوانند ساخت عامل کاربردی را آسانتر کنند، اما نیاز به معماری شفاف را از بین نمیبرند. قبل از ساخت، کار محدود و معیار موفقیت بنویسید، ابزارها را جدا و کمدسترسی کنید، خروجی بیرونی را با انسان تأیید کنید و بازیابی را در برابر اجرای دوباره مقاوم سازید.
برای انتخاب API، پیچیدگی و طول کار، محل داده، هزینهٔ زیرساخت و میزان کنترل لازم را بسنجید. سپس در یک پروژهٔ کوچک و کمخطر آزمون کنید، failure modeها را ثبت کنید و فقط با دادهٔ واقعی rollout را گسترش دهید. Agent خوب لزوماً خودمختارترین عامل نیست؛ عاملی است که کار مشخصی را با مجوز، شواهد و مسیر برگشت روشن انجام میدهد.
اشتراکهای کاربری و API شرایط یکسانی ندارند. قابلیتها، دسترسی و قیمت را پیش از خرید یا پیادهسازی در صفحهٔ رسمی سرویس بررسی کنید.
منابع رسمی و مطالعهٔ بیشتر
- معرفی Agents API از OpenAI؛ نشست، harness، sandbox و ابزارها.
- Changelog رسمی OpenAI API؛ تغییرات Agents API در سپتامبر و اکتبر ۲۰۲۶.
- راهنمای مسیر شروع و معماری Agents API؛ برای توسعهدهندگان.
- راهنمای اتوماسیون AI با API و n8n در حامی صنعت؛ برای workflowهای ساده و قابل پیشبینی.
واژهنامهٔ فنی کوتاه
Agent harness: The runtime and orchestration layer that manages model calls, tools, context, and execution state around an AI agent.
Durable session: A persistent conversation or task state that can continue across multiple turns or after an interruption, subject to retention rules.
Sandbox: An isolated environment for running code or handling files with limited network, data, and compute permissions.
Tool calling: A model request to invoke an application function. The application must validate arguments and enforce authorization before execution.
MCP server: A service that exposes tools or resources through the Model Context Protocol. Each server should have a known owner and narrow scope.
Prompt injection: Untrusted content attempting to override agent instructions or obtain protected data. It can appear inside documents, webpages, emails, or tool results.
Idempotency key: A stable request identifier that helps an application avoid repeating the same side effect when a call is retried.
Human approval: A review step where a user sees and authorizes a consequential action before the application executes it.
Context compaction: A process that summarizes or reduces conversation state to continue a long-running interaction within practical limits.
Shadow test: A parallel evaluation that runs a new workflow on copied requests without changing the result users receive.
Rollback: A controlled return to a previous model or workflow when a deployment causes errors, cost increases, or safety problems.
End-to-end latency: The elapsed time from a user’s request to a usable final result, including model calls, tool execution, retries, and review.
مطالب مرتبط برای ادامهٔ مطالعه
برای بررسی موضوع از زاویههای نزدیک، این راهنماها را هم بخوانید: