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

مقدمه و راه‌اندازی اولیه پروژه پایتون

در این راهنما، ما یک نسخه ابتدایی از یک ویرایشگر کد مبتنی بر هوش مصنوعی را خواهیم ساخت که قابلیت‌های مشابه Claude Code یا Cursor را ارائه می‌دهد. این ابزار به عنوان یک عامل هوشمند عمل می‌کند و از API رایگان Gemini گوگل قدرت می‌گیرد. اگر پیش از این از ویرایشگرهای کد AI عامل‌محور استفاده کرده‌اید، با مفهومی که قصد داریم بسازیم آشنا هستید. نکته قابل توجه این است که با دسترسی به یک مدل زبان بزرگ (LLM)، ساخت یک عامل سفارشی و تا حدودی مؤثر، بسیار ساده‌تر از آن چیزی است که تصور می‌شود. این راهنمای جامع و کاملاً متنی به شما کمک می‌کند تا گام‌به‌گام این پروژه را پیاده‌سازی کنید و به درک عمیق‌تری از نحوه کار ابزارهای پیشرفته هوش مصنوعی در پشت صحنه برسید.

پیش‌نیازهای لازم برای شروع

برای اینکه بتوانید این مسیر آموزشی را به خوبی دنبال کنید و پروژه را با موفقیت تکمیل کنید، آشنایی با چند مفهوم و ابزار کلیدی ضروری است. شما باید:

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


• نحوه استفاده از خط فرمان مشابه یونیکس را بدانید. این شامل دستورات پایه برای ناوبری در فایل‌ها و دایرکتوری‌ها، اجرای اسکریپت‌ها و مدیریت محیط است.

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

عامل هوش مصنوعی ما چه کاری انجام می‌دهد؟

برنامه‌ای که ما در این پروژه می‌سازیم، یک ابزار خط فرمان (CLI) است که وظایف کدنویسی را با استفاده از قابلیت‌های یک LLM انجام می‌دهد. این عامل به گونه‌ای طراحی شده است که:

1. یک وظیفه کدنویسی را می‌پذیرد (مثلاً: "رشته‌ها در برنامه من به درستی تقسیم نمی‌شوند، لطفاً مشکل را رفع کن").


2. از مجموعه‌ای از توابع از پیش تعریف شده برای کار روی وظیفه انتخاب می‌کند. این توابع شامل موارد زیر هستند:
   
   
   
   • اسکن فایل‌ها در یک دایرکتوری.
   
   
   • خواندن محتویات یک فایل.
   
   
   • بازنویسی محتویات یک فایل.
   
   
   • اجرای مفسر پایتون بر روی یک فایل.
   
   
   
   


3. مرحله دوم را تکرار می‌کند تا وظیفه به پایان برسد (یا در صورت عدم موفقیت، تا زمانی که حد مجاز تکرار به اتمام برسد).

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

راه‌اندازی محیط توسعه پایتون

اولین گام عملی برای آغاز پروژه، راه‌اندازی یک محیط مجازی پایتون است. محیط‌های مجازی پایتون روشی مؤثر برای جدا نگه داشتن وابستگی‌های پروژه (مانند کتابخانه‌های Google AI که از آنها استفاده خواهیم کرد) از سایر پروژه‌ها در سیستم شما هستند. این کار از تداخل نسخه‌ها و مشکلات احتمالی جلوگیری می‌کند.

• برای ایجاد یک پروژه جدید، از ابزار `uv` استفاده کنید. این دستور نه تنها دایرکتوری پروژه را ایجاد می‌کند، بلکه Git را نیز مقداردهی اولیه می‌کند.


• پس از ایجاد پروژه، یک محیط مجازی در ریشه دایرکتوری پروژه خود ایجاد کنید.


• نکته امنیتی مهم: همیشه دایرکتوری محیط مجازی (که معمولاً `.venv` نامیده می‌شود) را به فایل `.gitignore` خود اضافه کنید. این کار از ارسال ناخواسته فایل‌های حجیم و غیرضروری به مخزن Git جلوگیری می‌کند.


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


• با استفاده از `uv`، دو وابستگی ضروری را به پروژه اضافه کنید: `google-genai` (نسخه ۱.۱۲.۱) و `python-dotenv` (نسخه ۱.۱.۰). این وابستگی‌ها به فایل `pyproject.toml` اضافه خواهند شد.

مدل‌های زبان بزرگ (LLM) مانند ChatGPT، Claude و Google Gemini، ستاره‌های درخشان دنیای هوش مصنوعی هستند. برای پروژه ما، شما می‌توانید یک LLM را به عنوان یک "تولیدکننده متن هوشمند" در نظر بگیرید. ما از API Gemini گوگل برای تقویت عامل خود استفاده خواهیم کرد، که علاوه بر هوشمندی قابل قبول، یک لایه رایگان نیز ارائه می‌دهد. توکن‌ها واحد اندازه‌گیری متن برای LLM‌ها هستند و تقریباً هر ۴ کاراکتر یک توکن محسوب می‌شوند. مهم است که از میزان مصرف توکن خود آگاه باشید، زیرا تمام فراخوانی‌های API، حتی در طول آزمایش‌های محلی، توکن مصرف می‌کنند و در صورت اتمام سهمیه رایگان، ممکن است مجبور شوید تا زمان بازنشانی آن (معمولاً ۲۴ ساعت) صبر کنید.

اتصال به Gemini API: دریافت کلید و تست اولیه

برای اینکه عامل ما بتواند با مدل Gemini ارتباط برقرار کند، به یک کلید API نیاز داریم. مراحل زیر نحوه دریافت و استفاده از این کلید را توضیح می‌دهد:

1. اگر قبلاً حساب کاربری ندارید، در Google AI Studio یک حساب ایجاد کنید.


2. دکمه "Create API Key" را فشار دهید و کلید API را دریافت کنید.


3. کلید API کپی شده را در یک فایل جدید به نام `.env` در ریشه دایرکتوری پروژه خود قرار دهید. فرمت فایل باید به صورت `API_KEY=YOUR_API_KEY` باشد.


4. خطر امنیتی: فایل `.env` را به فایل `.gitignore` خود اضافه کنید. هرگز کلیدهای API، رمز عبور یا سایر اطلاعات حساس را به مخزن Git متعهد نکنید.


5. فایل `main.py` را به روز کنید تا متغیرهای محیطی از فایل `.env` را با استفاده از کتابخانه `dotenv` بارگذاری کند و کلید API را بخواند.


6. کتابخانه `genai` را ایمپورت کرده و یک نمونه جدید از کلاینت Gemini با استفاده از کلید API ایجاد کنید.


7. برای دریافت پاسخ از مدل `gemini-2.0-flash-001` (که دارای لایه رایگان سخاوتمندانه‌ای است)، از متد `client.models.generate_content()` استفاده کنید. دو پارامتر اصلی `model` (نام مدل) و `contents` (متن درخواست شما به مدل) را مشخص کنید. سپس ویژگی `.text` از پاسخ را چاپ کنید تا جواب مدل را ببینید.


8. علاوه بر پاسخ متنی، تعداد توکن‌های مصرف شده در هر تعامل را نیز نمایش دهید. پاسخ شامل ویژگی `usage_metadata` است که شامل `prompt_token_count` (توکن‌های درخواست) و `candidates_token_count` (توکن‌های پاسخ) می‌شود.

توجه: API جیمینای یک سرویس وب خارجی است و ممکن است گاهی کند یا غیرقابل اعتماد باشد. بنابراین، در طول تست و توسعه، صبور باشید.

دریافت کلید و اتصال به Gemini API

در دنیای پرشتاب هوش مصنوعی، مدل‌های زبان بزرگ (LLM) نقش محوری ایفا می‌کنند و محصولاتی نظیر ChatGPT، Claude، Cursor و Google Gemini همگی بر پایه این فناوری پیشرفته بنا شده‌اند. این مدل‌ها را می‌توان به عنوان یک مولد متن هوشمند در نظر گرفت: شما یک درخواست (prompt) به آن می‌دهید و در ازای آن متنی را دریافت می‌کنید که مدل فکر می‌کند پاسخ مناسبی به درخواست شماست. در این راهنما، ما بر روی استفاده از Gemini API گوگل تمرکز خواهیم کرد تا یک عامل هوش مصنوعی (AI agent) کارآمد و سفارشی بسازیم. ویژگی برجسته Gemini API، علاوه بر هوشمندی قابل قبول آن، ارائه یک لایه رایگان (free tier) است که آن را برای توسعه‌دهندگان و پروژه‌های آموزشی بسیار جذاب می‌کند.

آشنایی با توکن‌ها و محدودیت‌های Gemini API

در کار با LLMها، درک مفهوم "توکن" از اهمیت بالایی برخوردار است. توکن‌ها واحد اندازه‌گیری میزان متنی هستند که LLM باید پردازش کند؛ به طور تقریبی، هر توکن معادل ۴ کاراکتر در اکثر مدل‌هاست. نظارت بر مصرف توکن‌ها برای مدیریت هزینه‌ها و ماندن در محدوده لایه رایگان Gemini API حیاتی است. لازم به ذکر است که تمامی فراخوانی‌های API، حتی در طول آزمایش‌های محلی، توکن‌های تخصیص‌یافته به حساب رایگان شما را مصرف می‌کنند. بنابراین، اگر سهمیه شما تمام شود، ممکن است لازم باشد تا ریست شدن آن (معمولاً ۲۴ ساعت) منتظر بمانید. بازتولید کلید API باعث ریست شدن سهمیه نمی‌شود، بنابراین مدیریت مصرف در طول توسعه بسیار مهم است.

مراحل دریافت و پیکربندی کلید API

برای شروع به کار با Gemini API، ابتدا نیاز به دریافت یک کلید API دارید. این فرایند شامل چند مرحله ساده است:

1. در صورتی که حساب کاربری ندارید، یک حساب در Google AI Studio ایجاد کنید.


2. بر روی دکمه "Create API Key" کلیک کنید. اگر در حین این مرحله سردرگم شدید، می‌توانید از مستندات گوگل کمک بگیرید. اگر از قبل یک حساب GCP و پروژه‌ای دارید، می‌توانید کلید API را در همان پروژه ایجاد کنید؛ در غیر این صورت، AI Studio به طور خودکار یک پروژه برای شما ایجاد خواهد کرد.


3. کلید API کپی شده را در یک فایل جدید با نام .env در دایرکتوری پروژه خود جایگذاری کنید. محتوای فایل باید به شکل زیر باشد: API_KEY=YOUR_API_KEY


4. فایل .env را به فایل .gitignore خود اضافه کنید. این یک گام امنیتی بسیار مهم است؛ هیچ‌گاه نباید کلیدهای API، رمزهای عبور یا سایر اطلاعات حساس را به گیت (Git) کامیت (commit) کنید.

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

نحوه ادغام و تعامل با Gemini API در پایتون

پس از دریافت کلید API، گام بعدی ادغام آن با کد پایتون پروژه شماست. برای این کار، ابتدا باید متغیرهای محیطی را از فایل .env بارگذاری کرده و سپس از کتابخانه google-genai برای تعامل با مدل Gemini استفاده کنید:

1. فایل main.py را به روز رسانی کنید تا هنگام شروع برنامه، متغیرهای محیطی را با استفاده از کتابخانه dotenv بارگذاری کرده و کلید API را بخواند.


2. کتابخانه genai را ایمپورت کرده و با استفاده از کلید API، یک نمونه جدید از کلاینت Gemini ایجاد کنید.


3. از متد client.models.generate_content() برای دریافت پاسخ از مدل gemini-2.0-flash-001 استفاده کنید. این مدل دارای یک لایه رایگان سخاوتمندانه است. شما نیاز به دو پارامتر نام‌گذاری شده دارید: model (نام مدل) و contents (درخواست متنی شما به مدل).


4. متد generate_content یک شیء GenerateContentResponse برمی‌گرداند. برای مشاهده پاسخ مدل، ویژگی .text این پاسخ را پرینت کنید. اگر همه چیز به درستی کار کند، باید بتوانید کد خود را اجرا کرده و پاسخ مدل را در ترمینال خود مشاهده کنید.


5. علاوه بر پرینت پاسخ متنی، تعداد توکن‌های مصرفی را نیز چاپ کنید. پاسخ شامل ویژگی .usage_metadata است که شامل prompt_token_count (توکن‌های در درخواست) و candidates_token_count (توکن‌های در پاسخ) است.

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

تعریف ابزارها: کار با فایل و اجرای کد

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

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

توابع هسته‌ای برای تعامل با سیستم فایل

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

1. 
   دریافت اطلاعات فایل‌ها (get_files_info): این تابع مسئول اسکن یک دایرکتوری و ارائه اطلاعاتی از قبیل نام و اندازه فایل‌ها است. هدف آن بازگرداندن یک رشته متنی است که محتویات دایرکتوری را به LLM گزارش می‌دهد. این یک گام حیاتی برای LLM است تا بتواند از ساختار پروژه مطلع شود. برای جلوگیری از دسترسی‌های غیرمجاز، مسیرها همواره نسبت به یک "working_directory" (دایرکتوری کاری) مشخص اعتبارسنجی می‌شوند.
   


2. 
   خواندن محتوای فایل (get_file_content): این ابزار به عامل امکان می‌دهد تا محتویات یک فایل مشخص را به صورت یک رشته بخواند. برای مدیریت بهینه مصرف توکن‌های LLM، محتوای فایل‌های بزرگتر از ۱۰۰۰۰ کاراکتر به صورت خودکار کوتاه شده و یک پیام هشدار به انتهای آن اضافه می‌شود. این محدودیت تضمین می‌کند که عامل بدون مصرف بی‌رویه منابع، به اطلاعات مورد نیاز دسترسی پیدا کند. همچون توابع دیگر، دسترسی به مسیرها به دایرکتوری کاری محدود می‌شود.
   


3. 
   نوشتن/بازنویسی محتوای فایل (write_file_content): این تابع به عامل قدرت تغییر و ذخیره فایل‌ها را می‌دهد. در صورتی که فایل مورد نظر وجود نداشته باشد، آن را ایجاد می‌کند و سپس محتوای داده شده را در آن می‌نویسد یا بازنویسی می‌کند. بازخورد موفقیت‌آمیز بودن عملیات به صورت یک رشته، برای ادامه منطق تصمیم‌گیری عامل ضروری است. این عملیات نیز مانند موارد قبل، تحت محدودیت‌های امنیتی دایرکتوری کاری انجام می‌شود.
   

اجرای کد پایتون و ملاحظات امنیتی

یکی از قدرتمندترین و در عین حال خطرناک‌ترین قابلیت‌هایی که می‌توان به یک عامل هوش مصنوعی داد، توانایی اجرای کد است. تابع run_python_file این امکان را فراهم می‌کند که عامل بتواند فایل‌های پایتون را اجرا کرده و خروجی آن‌ها را مشاهده کند. این تابع از subprocess.run برای اجرای کد استفاده می‌کند و خروجی‌های استاندارد (stdout) و خطاهای استاندارد (stderr) را دریافت و در یک رشته قالب‌بندی شده بازمی‌گرداند.

با این حال، ارائه قابلیت اجرای کد به یک LLM، خطرات امنیتی ذاتی را به همراه دارد. به همین دلیل، اقدامات احتیاطی سختگیرانه‌ای در نظر گرفته شده است:

• 
  محدودیت دایرکتوری کاری: عامل تنها مجاز به اجرای کد در دایرکتوری کاری تعریف شده است و هرگونه تلاش برای اجرای فایل‌ها در خارج از این محدوده با خطا مواجه می‌شود. این مهمترین لایه محافظتی برای جلوگیری از دسترسی یا تغییرات غیرمجاز در سیستم عامل است.
  


• 
  مهلت زمانی اجرا: یک مهلت زمانی ۳۰ ثانیه‌ای برای اجرای هر فایل پایتون در نظر گرفته شده است تا از حلقه‌های بی‌نهایت یا اجرای بی‌رویه کد جلوگیری شود.
  


• 
  اعتبارسنجی نوع فایل: تابع تنها فایل‌هایی را اجرا می‌کند که پسوند .py داشته باشند.
  


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

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

فراخوانی توابع و حلقه بازخورد عامل

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

1. 
   اعلام توابع (Function Declaration): ابتدا، به LLM اعلام می‌شود که چه توابعی برای آن در دسترس است و ساختار (schema) هر تابع (نام، پارامترها و توضیحات) چگونه است. این کار با استفاده از ساختارهایی مانند types.FunctionDeclaration انجام می‌شود.
   


2. 
   دریافت درخواست کاربر: عامل یک وظیفه یا درخواست را از کاربر دریافت می‌کند.
   


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


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


5. 
   بازگشت نتیجه به LLM: نتیجه اجرای تابع به عنوان بخشی از تاریخچه مکالمه به LLM بازگردانده می‌شود.
   

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

پیاده‌سازی مکانیزم فراخوانی توابع توسط LLM

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

اعلام توابع و تعریف شمای آن‌ها

اولین مرحله برای قادر ساختن LLM به "فراخوانی" توابع، اعلام این توابع به مدل است. این کار با ساخت یک "اعلامیه تابع" یا "اسکیما" برای هر تابع انجام می‌شود که به LLM می‌گوید چگونه از آن تابع استفاده کند. این اسکیما شامل نام تابع، توضیحات آن، و پارامترهای مورد نیاز به همراه نوع داده و توضیحاتشان است. برای مثال، تابعی مانند get_files_info که لیست فایل‌های یک دایرکتوری را برمی‌گرداند، نیاز به پارامتری برای مسیر دایرکتوری دارد. مهم است که برخی پارامترها، مانند working_directory که محدوده عملیات عامل را تعیین می‌کند، به صورت دستی کنترل شوند و به LLM اجازه دستکاری آن‌ها داده نشود تا از خطرات امنیتی احتمالی جلوگیری شود.

پس از تعریف اسکیمای هر تابع با استفاده از types.FunctionDeclaration، این اعلامیه‌ها در یک لیست از ابزارهای موجود (available_functions) جمع‌آوری می‌شوند. این لیست سپس به متد client.models.generate_content به عنوان پارامتر tools ارسال می‌شود. علاوه بر این، باید اعلان سیستم (System Prompt) را به‌روزرسانی کنیم تا دستورالعمل‌های واضحی در مورد نحوه استفاده از این توابع به LLM ارائه دهد. این اعلان سیستم، رفتار LLM را در انتخاب و پیشنهاد توابع راهنمایی می‌کند. برای تست این مکانیزم، پس از دریافت پاسخ از LLM، علاوه بر بررسی محتوای متنی، ویژگی .function_calls پاسخ را نیز بررسی می‌کنیم. اگر LLM فراخوانی تابعی را پیشنهاد داده باشد، نام تابع و آرگومان‌های آن را نمایش می‌دهیم، در غیر این صورت، متن عادی نمایش داده می‌شود. این فرآیند برای توابع دیگر مانند get_file_content (خواندن محتوای فایل)، write_file_content (نوشتن یا بازنویسی فایل) و run_python_file (اجرای کد پایتون) نیز تکرار می‌شود.

اجرای عملی توابع و حلقه بازخورد عامل

پس از اینکه LLM توانایی انتخاب تابع مناسب را پیدا کرد، گام بعدی اجرای واقعی آن تابع است. برای این منظور، تابعی به نام call_function ایجاد می‌شود که مسئولیت اجرای هر یک از توابع تعریف شده را بر عهده دارد. این تابع، نام تابع پیشنهادی LLM و آرگومان‌های آن را دریافت می‌کند. در اینجا، working_directory به صورت دستی به آرگومان‌ها اضافه می‌شود تا امنیت عملیات تضمین شود. یک دیکشنری از نگاشت نام تابع به شیء تابع واقعی به ما کمک می‌کند تا تابع مورد نظر را به صورت پویا فراخوانی کنیم (با استفاده از **some_args برای ارسال آرگومان‌ها). پس از اجرای تابع، نتیجه به صورت یک رشته بازگردانده می‌شود که در نهایت به types.Content با فرمت from_function_response تبدیل و برای LLM ارسال می‌گردد.

نقطه اوج این پیاده‌سازی، ایجاد "حلقه عامل" (Agent Loop) است. یک عامل واقعی، توانایی تکرار بر روی نتایج خود و استفاده مداوم از ابزارهایش را دارد. این حلقه شامل فراخوانی مکرر LLM و حفظ تاریخچه کامل مکالمه (لیست messages) است. در هر تکرار، LLM با در نظر گرفتن کل تاریخچه مکالمه، گام بعدی را تصمیم می‌گیرد. این گام می‌تواند تولید متن باشد یا پیشنهاد فراخوانی یک تابع. اگر تابع فراخوانی شود، نتیجه آن به تاریخچه مکالمه اضافه می‌شود تا LLM در مرحله بعد از آن بهره ببرد. این حلقه تا زمانی که LLM پاسخ نهایی متنی را تولید کند یا به حداکثر تعداد تکرار برسد، ادامه می‌یابد. این مکانیزم بازخورد، به عامل هوش مصنوعی امکان می‌دهد تا وظایف پیچیده را گام به گام حل کند، به مشکلات واکنش نشان دهد و در نهایت به یک راه‌حل کارآمد دست یابد.

ملاحظات امنیتی و پایداری

در حین پیاده‌سازی این قابلیت‌ها، به خصوص توابعی که امکان خواندن، نوشتن یا اجرای فایل‌ها را دارند، رعایت ملاحظات امنیتی از اهمیت بالایی برخوردار است. محدود کردن دسترسی عامل به یک working_directory مشخص و اعمال محدودیت زمانی برای اجرای کد پایتون (مثلاً ۳۰ ثانیه)، گاردریل‌های اساسی برای جلوگیری از سوءاستفاده یا ایجاد مشکل هستند. همچنین، برای جلوگیری از مصرف بیش از حد توکن‌ها، محدود کردن حجم فایل‌های خوانده شده (مثلاً حداکثر ۱۰۰۰۰ کاراکتر) ضروری است. باید توجه داشت که نسخه‌ای که ما می‌سازیم، یک مدل "بازیچه" برای اهداف آموزشی است و فاقد تمام ویژگی‌های امنیتی و ایمنی یک عامل هوش مصنوعی تولیدی است. بنابراین، هرگز نباید این برنامه را به دیگران برای استفاده در محیط‌های حساس ارائه داد.

با پیاده‌سازی این مکانیزم فراخوانی توابع و حلقه بازخورد، شما یک پایه قوی برای ساخت عوامل هوش مصنوعی پیشرفته‌تر ایجاد کرده‌اید. این توانایی به عامل اجازه می‌دهد تا به صورت هوشمندانه با محیط خود تعامل کند، خطاها را تشخیص دهد، و راه‌حل‌های خلاقانه برای مسائل برنامه‌نویسی ارائه کند. آزمون و خطا با اعلان‌های مختلف (Prompt Engineering) برای بهبود رفتار LLM در این زمینه، یک مهارت کلیدی است که با تمرین به دست می‌آید.

ساخت حلقه عملیاتی عامل برای حل مسئله

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

مفهوم حلقه بازخورد در عامل‌های هوش مصنوعی

برخلاف مدل‌های زبانی که غالباً به صورت "یک مرحله‌ای" (one-shot) عمل کرده و به هر درخواست یک پاسخ واحد می‌دهند، عامل‌های هوش مصنوعی برای حل مسائل پیچیده‌تر نیاز به حفظ یک تاریخچه گفتگو دارند. این تاریخچه شامل پیام‌های قبلی کاربر و پاسخ‌های مدل است و به عامل این امکان را می‌دهد که هر ورودی جدید را در بستر کلی مکالمه ارزیابی کند. این ویژگی برای سناریوهایی که نیاز به گام‌های متعدد و تعامل با ابزارهای مختلف دارند، بسیار حیاتی است. هدف نهایی ساخت یک عامل کدنویس است که بتواند وظایف برنامه‌نویسی را با استفاده از مجموعه‌ای از توابع از پیش تعریف‌شده و با یک چرخه بازخورد مداوم به انجام برساند.

ساختار گفتگو و مدیریت تاریخچه پیام‌ها

برای پیاده‌سازی این حلقه عملیاتی، لازم است که یک لیست پویا از پیام‌ها ایجاد و نگهداری شود. این لیست، که به عنوان تاریخچه مکالمه عمل می‌کند، شامل تعاملات بین "کاربر" و "مدل" است. هنگامی که کاربر یک وظیفه کدنویسی را به عامل می‌دهد، این درخواست به عنوان یک پیام با نقش "user" به لیست اضافه می‌شود. سپس، مدل بر اساس این تاریخچه، پاسخ خود را تولید می‌کند که می‌تواند شامل یک فراخوانی تابع یا یک پاسخ متنی نهایی باشد. اگر مدل تصمیم به فراخوانی تابعی بگیرد، این فراخوانی به لیست پیام‌ها اضافه می‌شود. پس از اجرای تابع توسط سیستم، نتیجه آن نیز به عنوان پیامی با نقش "user" (نشان‌دهنده خروجی ابزار) به تاریخچه اضافه می‌گردد. این روش تضمین می‌کند که LLM همیشه به یک نمای جامع و به‌روز از وضعیت موجود دسترسی داشته و می‌تواند تصمیمات آگاهانه‌تری برای گام‌های بعدی اتخاذ کند.

هر بار که متد client.models.generate_content() فراخوانی می‌شود، کل لیست messages به مدل ارسال می‌شود. این کار حیاتی است زیرا به مدل امکان می‌دهد تا بر اساس تمامی تعاملات قبلی، بهترین گام بعدی را تعیین کند. پس از دریافت پاسخ، اگر مدل یک کاندید (candidate) حاوی فراخوانی تابع را برگرداند، محتوای آن به لیست messages افزوده می‌شود. سپس، با استفاده از تابعی مانند call_function، فراخوانی تابع واقعی انجام شده و نتیجه آن (که باید به صورت یک رشته باشد) به یک types.Content تبدیل شده و به عنوان یک پیام جدید با نقش "user" به تاریخچه پیام‌ها اضافه می‌شود. این فرآیند در یک حلقه تکرار می‌شود تا وظیفه به طور کامل انجام شود.

حلقه تکرار عملیاتی و اتمام کار

برای مدیریت فرآیند تکراری حل مسئله، یک حلقه تعریف می‌شود که متد generate_content را به طور مکرر فراخوانی می‌کند. این حلقه برای جلوگیری از اجرای بی‌نهایت، به حداکثر ۲۰ تکرار محدود شده است. در هر تکرار، عامل با استفاده از تاریخچه پیام‌ها، پاسخ جدیدی را از LLM دریافت می‌کند. اگر پاسخ مدل شامل یک متن نهایی (response.text) باشد، این به معنای اتمام وظیفه است و حلقه شکسته می‌شود. در غیر این صورت، مدل فراخوانی یک تابع را پیشنهاد می‌کند، که سپس اجرا شده و نتیجه آن به تاریخچه مکالمه اضافه می‌گردد تا در تکرار بعدی مورد استفاده قرار گیرد. استفاده از بلوک‌های try-except در این حلقه برای مدیریت خطاهای احتمالی و افزایش پایداری عامل ضروری است.

جمع‌بندی و توصیه‌های نهایی

تبریک می‌گوییم! شما با موفقیت یک عامل هوش مصنوعی پایه را ساختید که می‌تواند فایل‌ها را بخواند، بنویسد، کد پایتون اجرا کند و با استفاده از یک حلقه بازخورد، بر اساس نتایج خود، عملیات را تکرار و بهینه‌سازی کند. این پروژه یک پایه مستحکم برای توسعه عامل‌های هوش مصنوعی پیچیده‌تر فراهم می‌آورد و به شما کمک می‌کند تا نحوه کارکرد داخلی ابزارهای هوش مصنوعی را درک کنید. با این حال، باید همواره احتیاط را رعایت کنید؛ اجازه دسترسی یک مدل زبانی بزرگ (LLM) به سیستم فایل و مفسر پایتون می‌تواند خطرات امنیتی جدی ایجاد کند. ابزاری که ما ساختیم، نسخه‌ای "اسباب‌بازی" از ابزارهای پیشرفته‌تری مانند Cursor یا Claude Code است و حتی آن‌ها نیز در سطح تولید (production) کاملاً امن نیستند. بنابراین، در هنگام کار با این عامل، بسیار محتاط باشید و آن را برای وظایف حساس یا اشتراک‌گذاری با دیگران استفاده نکنید.

برای افزایش قابلیت‌های عامل خود، می‌توانید با ارائه وظایف پیچیده‌تر، رفع اشکالات دشوارتر، بازسازی بخش‌هایی از کد، یا افزودن قابلیت‌های کاملاً جدید، آن را آزمایش کنید. همچنین، می‌توانید ارائه دهندگان LLM دیگر یا مدل‌های Gemini متفاوت را امتحان کنید و توابع بیشتری برای فراخوانی به عامل خود اضافه کنید. همیشه قبل از اجرای عامل بر روی کدهای واقعی، تغییرات خود را در کنترل نسخه (مانند Git) ثبت کنید تا در صورت لزوم بتوانید به نسخه قبلی بازگردید. این تجربه عملی به شما در درک عمیق‌تر نحوه عملکرد ابزارهای هوش مصنوعی و تقویت مهارت‌های پایتون و برنامه‌نویسی تابعی کمک شایانی خواهد کرد. برای یادگیری بیشتر در زمینه بک‌اند و مهندسی داده، می‌توانید به منابع آموزشی معتبر مراجعه کنید و مسیر یادگیری خود را ادامه دهید.