Google AI Studio Playground یک رابط کاربری بصری برای نمونهسازی اولیه و یادگیری نحوه ساخت عاملهای مدیریتشده بدون نیاز به ایجاد و نوشتن فراخوانیهای API ارائه میدهد.
برای شروع، به برگه Playground در پنل ناوبری Google AI Studio بروید و گزینه Agents را انتخاب کنید.
قالبهای از پیش ساخته شده
تب Agents دارای مجموعهای از قالبها است که با تنظیم پیکربندی ابزار و محیط، عامل Antigravity پایه را از پیش پیکربندی میکنند. همه قالبها متنباز هستند و تحت مخزن google-gemini/gemini-managed-agents-templates منتشر شدهاند. بررسی این قالبها راهی عالی برای یادگیری نحوه ساخت و ساختاردهی عامل مدیریتشده خودتان است.
برای مثال، وقتی قالب AI Radio را انتخاب میکنید، تمام ابزارهای مجاز را فعال میکند و یک فایل تخصصی AGENTS.md و مهارتهای لازم برای تولید برنامههای رادیویی را پیوند میدهد. میتوانید این تنظیمات را در رابط کاربری Playground در بخش Environment ، با کلیک روی دکمه Sources مشاهده کنید.
پیکربندی ابزار
در تنظیمات Agent در Playground، میتوانید دسترسی به ابزارهای داخلی زیر را تغییر دهید:
- جستجوی گوگل: برای دسترسی به اطلاعات در لحظه به وب باز دسترسی پیدا کنید.
- متن URL: محتوای متنی URL های خاص صفحات وب را دریافت و تجزیه کنید.
- اجرای کد: دستورات Bash و Python را مستقیماً در محیط ایزوله sandbox اجرا کنید.
- ابزارهای سیستم فایل: خواندن، نوشتن، فهرست کردن و حذف فایلها در فضای کاری.
پیکربندی محیط
عاملهای مدیریتشده در یک محیط امن و موقت لینوکس اجرا میشوند که فضای کاری و ابزارهای مورد نیاز برای عملکرد آنها را فراهم میکند. برای کسب اطلاعات بیشتر، به راهنمای محیط عامل مدیریتشده مراجعه کنید.
کنترل رفتار عامل
رفتار، شخصیت و قابلیتهای عامل عمدتاً توسط فایلهای موجود در محیط آن تعیین میشود. عامل به طور خودکار پیکربندیها را از یک پوشه ویژه .agents شناسایی و بارگذاری میکند:
-
AGENTS.md: از قبل در متن عامل بارگذاری شده است تا دستورالعملهای سیستم و شخصیت را تعریف کند. -
SKILL.md: در زیر پوشههای مهارت مربوطه (مثلاً.agents/skills/my-skill/SKILL.md) قرار دارد تا قابلیتها و گردشهای کاری خاص را تعریف کند.
فراهم کردن محیط زیست
شما میتوانید با نصب فایلها در محیط، قبل از شروع جلسه، محیطی را که توسط عامل استفاده میشود، پیکربندی کنید. میتوانید با نصب منابع، یک محیط جدید بسازید یا محیط قبلی را بازیابی کنید:
- برای ایجاد یک محیط جدید ، در پنل تنظیمات محیط، روی «افزودن منابع» کلیک کنید و از بین انواع منبع زیر انتخاب کنید:
| نوع منبع | توضیحات | مسیر نصب |
|---|---|---|
| فایلهای درونخطی | فایلهای پیکربندی، مجموعه دادههای آزمایشی یا اسکریپتهای کاربردی (تا سقف ۱۰۰ کیلوبایت) را مستقیماً در رابط کاربری Playground بنویسید یا جایگذاری کنید. | مسیر مقصد تعریفشده توسط کاربر (مثلاً /workspace/scripts/parser.py ). |
| فضای ذخیرهسازی ابری گوگل | یک مخزن ذخیرهسازی ابری عمومی نصب کنید. | یک مسیر سطل GCS (مثلاً gs://your-bucket-name/data/ ) را به یک دایرکتوری فضای کاری (مثلاً /workspace/data/ ) نگاشت میکند. |
| مخازن گیتهاب | کدهای عمومی یا خصوصی را کپی کنید. مخازن خصوصی به یک توکن دسترسی شخصی نیاز دارند: https://<YOUR_TOKEN>@github.com/username/repo.git . | مستقیماً در /workspace/ (معمولاً در زیر /workspace/<repo-name> ) کلون میشود. |
- برای بازیابی یک محیط قبلی ، میتوانید از یک شناسه محیط موجود برای کلون کردن و ایجاد انشعاب از وضعیت دقیق آن استفاده کنید .
استفاده مجدد از شناسه محیط موجود
اگر قبلاً زمانی را برای راهاندازی یک محیط سندباکس صرف کردهاید، لازم نیست از ابتدا شروع کنید. برای استفاده از یک محیط موجود:
- به پنل Environments در AI Studio بروید و Type را به Existing تغییر دهید.
- شناسه محیط را وارد کنید (مثلاً
env_abc123)
برای اطلاعات بیشتر، به پیکربندی یک محیط مراجعه کنید. همچنین میتوانید شناسه محیط جلسه فعلی را از برگه محیط در رابط کاربری بازیابی کنید.
به محض اینکه اولین پیام خود را به عامل ارسال کردید، پیکربندی محیط برای آن جلسه ثابت میشود. در حالی که تعامل به طور فعال در حال اجرا است، نمیتوانید منابع جدید را نصب کنید یا لیست مجوزهای شبکه را تغییر دهید.
محیط را دانلود کنید
پس از ایجاد یک محیط، میتوانید در هر زمان با استفاده از دکمه «دانلود» در تنظیمات محیط نرمافزار AI Studio Playground، اسنپشات محیط را دانلود کنید تا فایلهای محیط را به صورت فایل tarball بازیابی کنید.
مدیریت ایمنی و هزینه
مدیریت مصرف توکن
برخلاف یک درخواست چت استاندارد که یک خروجی واحد تولید میکند، Antigravity Agent یک گردش کار مستقل را اجرا میکند. این برنامه، کد را برنامهریزی، اجرا، نتایج را مشاهده و تکرار میکند. این بدان معناست که یک درخواست واحد میتواند منجر به مصرف نامحدود توکن شود.
برای مدیریت هزینهها، معیارهای خاتمه کار را در اعلانهای خود به روشنی ارائه دهید و وظایف را به طور دقیق برای عامل محدود کنید . یک مثال خوب میتواند اعلانی مانند «درخواست pull را بررسی کنید و پس از ایجاد خلاصه تخفیف، متوقف شوید» باشد. سعی نکنید خودتان اصلاحیه را بنویسید .
هزینههای اضافی
به طور پیشفرض، تمام قالبهای عامل در Playground به سرویس API Gemini دسترسی دارند و میتوانند برای انجام درخواستها، فراخوانیهای API را از محیط انجام دهند. این موارد ممکن است هزینههای اضافی را به همراه داشته باشند که در مصرف توکن منعکس نمیشوند.
به همین ترتیب، اگر خدمات خارجی دیگری را اضافه کنید، ممکن است نماینده با تماس با این خدمات از طرف شما، هزینههای اضافی متحمل شود.
فهرست مجاز شبکه
به طور پیشفرض، در AI Studio تمام درخواستهای خروجی شبکه از داخل محیط sandbox نماینده شما به شدت کنترل و محدود میشوند تا امنیت تضمین شود. برای اینکه به نماینده خود امکان دسترسی به APIهای خارجی، سرویسهای وب یا مدیران بسته را بدهید، باید آنها را صریحاً اعلام کنید:
- به پنل Environments در AI Studio بروید.
- دکمه قوانین کنار شبکه را انتخاب کنید.
- در پنل پیکربندی شبکه ، روی افزودن به لیست مجاز کلیک کنید و جزئیات مربوطه را پر کنید:
- محدودیت دامنه: فقط دامنههای خاص یا الگوهای wildcard اضافه شده به لیست میتوانند توسط ماشین مجازی عامل قابل دسترسی باشند. به عنوان مثال، میتوانید دامنههای دقیقی مانند
api.github.comیا الگوهای کلی مانند*.googleapis.comرا وارد کنید. - افزودن هدر HTTP و تزریق توکن: از گزینه افزودن هدر HTTP برای تزریق ایمن اعتبارنامههای مورد نیاز (مانند توکن API) برای یک دامنه خاص استفاده کنید. این اعتبارنامهها با خیال راحت از طریق یک پروکسی خروجی عبور میکنند و هرگز مستقیماً به عنوان متن خام در داخل جعبه شنی عامل نمایش داده نمیشوند.
- محدودیت دامنه: فقط دامنههای خاص یا الگوهای wildcard اضافه شده به لیست میتوانند توسط ماشین مجازی عامل قابل دسترسی باشند. به عنوان مثال، میتوانید دامنههای دقیقی مانند
همیشه هنگام افزودن دامنهها به لیست مجاز خود احتیاط کنید. اعطای دسترسی به سرویسها به نماینده به این معنی است که میتواند از طرف شما عمل کند، که در صورت عدم نظارت دقیق میتواند منجر به اقدامات ناخواسته شود.
بهترین شیوههای اعتبارسنجی
اگر گردش کار شما مستلزم احراز هویت عامل با سرویسهای خارجی است، شما مسئول تهیه و تعیین محدوده این اعتبارنامهها هستید. برای کاهش ریسک، این دستورالعملها را دنبال کنید:
- از اعتبارنامههای با حداقل دسترسی استفاده کنید: حسابهای کاربری سرویس یا کلیدهای API را فقط با مجوزهایی که نماینده شما نیاز دارد ایجاد کنید. از ارسال اعتبارنامههایی با دسترسی گسترده یا مدیریتی خودداری کنید.
- توکنهای کوتاهمدت را ترجیح دهید: در صورت امکان، از اعتبارنامههای با محدودیت زمانی یا توکنهایی که منقضی میشوند به جای کلیدهای API با طول عمر بالا استفاده کنید.
- دسترسی کامل را در نظر بگیرید: نماینده میتواند از هر اعتبارنامهای که به آن دسترسی دارد برای انجام وظیفهای که به او دادهاید استفاده کند. فقط اعتبارنامههایی را ارائه دهید که مایل به اعطای دسترسی کامل به آنها هستید.
- چرخش منظم اعتبارنامهها: با اعتبارنامههای به اشتراک گذاشته شده با عامل، همانطور که با هر اعتبارنامه برنامهنویسیشدهای رفتار میکنید، رفتار کنید؛ آنها را طبق یک برنامه منظم بچرخانید.
اتصال ابزارها و APIهای خارجی
شما میتوانید ابزارها و APIهای خارجی (مانند سرورهای Model Context Protocol / MCP) را برای گسترش قابلیتهای عامل متصل کنید. هنگام انجام این کار:
- فقط ابزارها را از منابعی که به آنها اعتماد دارید متصل کنید. یک ابزار مخرب یا با نگارش ضعیف میتواند دادهها را افشا کند یا اقدامات ناخواستهای انجام دهد.
- ابزارها را با حداقل مجوزهای مورد نیاز برای مورد استفاده خود پیکربندی کنید. اگر ابزاری از حالت فقط خواندنی پشتیبانی میکند، آن را ترجیح دهید مگر اینکه نوشتن کاملاً ضروری باشد.
- قبل از اتصال یک ابزار به منبع دادهی عملیاتی، آن را با دادههای نمونه یا مصنوعی آزمایش کنید تا مطمئن شوید که عامل از آن طبق انتظار استفاده میکند.
نظارت انسانی
عاملها میتوانند گردشهای کاری چند مرحلهای را با درجه بالایی از استقلال استدلال، برنامهریزی و اجرا کنند. اگرچه این امر قدرتمند است، اما به این معنی نیز هست که شما باید نظارت مناسبی اعمال کنید؛ به خصوص برای کارهایی که دادهها را تغییر میدهند یا با سیستمهای خارجی تعامل دارند.
همیشه خروجیهای حیاتی مانند کد تولید شده، تبدیل دادهها یا تغییرات پیکربندی را قبل از استقرار آنها تأیید کنید.