در این درس، نحوه اجرای نمونههای کد این دوره را بررسی خواهیم کرد.
قبل از اینکه مخزن خود را کلون کنید، به کانال دیسکورد AI Agents For Beginners بپیوندید تا در مورد تنظیمات، سوالات مربوط به دوره یا ارتباط با سایر فراگیران کمک بگیرید.
برای شروع، لطفاً مخزن GitHub را کلون یا فورک کنید. این کار نسخهای از مطالب دوره را برای شما ایجاد میکند تا بتوانید کدها را اجرا، آزمایش و تغییر دهید!
این کار با کلیک بر روی لینک فورک کردن مخزن قابل انجام است.
اکنون باید نسخه فورک شده خود از این دوره را در لینک زیر داشته باشید:

کل مخزن ممکن است بزرگ باشد (~3 گیگابایت) زمانی که تاریخچه کامل و همه فایلها را دانلود کنید. اگر فقط در کارگاه شرکت میکنید یا فقط به چند پوشه درس نیاز دارید، کلون سطحی (یا کلون پراکنده) بیشتر این دانلود را با کوتاه کردن تاریخچه و/یا حذف بلوکها اجتناب میکند.
در دستورات زیر، <your-username> را با URL فورک خود (یا URL اصلی اگر ترجیح میدهید) جایگزین کنید.
برای کلون کردن فقط تاریخچه آخرین کامیت (دانلود کوچک):
git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git
برای کلون کردن یک شاخه خاص:
git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git
این روش از کلون جزئی و بررسی پراکنده استفاده میکند (نیاز به Git 2.25+ و Git مدرن با پشتیبانی از کلون جزئی دارد):
git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git
وارد پوشه مخزن شوید:
برای bash:
cd ai-agents-for-beginners
برای Powershell:
Set-Location ai-agents-for-beginners
سپس مشخص کنید که کدام پوشهها را میخواهید (مثال زیر دو پوشه را نشان میدهد):
git sparse-checkout set 00-course-setup 01-intro-to-ai-agents
پس از کلون کردن و بررسی فایلها، اگر فقط به فایلها نیاز دارید و میخواهید فضای بیشتری آزاد کنید (بدون تاریخچه گیت)، لطفاً متادیتای مخزن را حذف کنید (💀غیرقابل بازگشت — تمام قابلیتهای گیت را از دست خواهید داد: بدون کامیت، پول، پوش یا دسترسی به تاریخچه).
برای لینوکس/macOS:
rm -rf .git
برای ویندوز:
Remove-Item -Recurse -Force .git
یک Codespace جدید برای این مخزن از طریق رابط کاربری GitHub ایجاد کنید.
این دوره مجموعهای از نوتبوکهای Jupyter را ارائه میدهد که میتوانید با آنها تجربه عملی ساخت عوامل هوش مصنوعی را کسب کنید.
نمونههای کد از موارد زیر استفاده میکنند:
نیاز به حساب GitHub - رایگان:
1) چارچوب عامل Semantic Kernel + بازار مدلهای GitHub. با برچسب (semantic-kernel.ipynb) 2) چارچوب AutoGen + بازار مدلهای GitHub. با برچسب (autogen.ipynb)
نیاز به اشتراک Azure: 3) Azure AI Foundry + سرویس عامل Azure AI. با برچسب (azureaiagent.ipynb)
ما شما را تشویق میکنیم که هر سه نوع مثال را امتحان کنید تا ببینید کدام یک برای شما بهتر عمل میکند.
هر گزینهای که انتخاب کنید، تعیین میکند که کدام مراحل تنظیم را باید در زیر دنبال کنید:
NOTE: اگر Python3.12 نصب نشده است، مطمئن شوید که آن را نصب کنید. سپس با استفاده از python3.12 دایرکتوری venv خود را ایجاد کنید تا نسخههای صحیح از فایل requirements.txt نصب شوند.
مثال
ایجاد دایرکتوری محیط مجازی Python:
python3 -m venv venv
سپس محیط venv را فعال کنید برای:
macOS و لینوکس
source venv/bin/activate
ویندوز
venv\Scripts\activate
ما یک فایل requirements.txt در ریشه این مخزن قرار دادهایم که شامل تمام بستههای مورد نیاز Python برای اجرای نمونههای کد است.
میتوانید آنها را با اجرای دستور زیر در ترمینال در ریشه مخزن نصب کنید:
pip install -r requirements.txt
ما توصیه میکنیم یک محیط مجازی Python ایجاد کنید تا از هرگونه تضاد و مشکل جلوگیری شود.
اطمینان حاصل کنید که از نسخه صحیح Python در VSCode استفاده میکنید.
این دوره از بازار مدلهای GitHub استفاده میکند که دسترسی رایگان به مدلهای زبان بزرگ (LLM) را فراهم میکند که شما برای ساخت عوامل هوش مصنوعی از آنها استفاده خواهید کرد.
برای استفاده از مدلهای GitHub، باید یک توکن دسترسی شخصی GitHub ایجاد کنید.
این کار با رفتن به تنظیمات توکنهای دسترسی شخصی در حساب GitHub شما قابل انجام است.
لطفاً هنگام ایجاد توکن، اصل حداقل امتیاز را دنبال کنید. این بدان معناست که شما باید فقط مجوزهایی را که برای اجرای نمونههای کد در این دوره نیاز دارید به توکن بدهید.
گزینه توکنهای دقیق را در سمت چپ صفحه خود انتخاب کنید و به تنظیمات توسعهدهنده بروید.

سپس گزینه ایجاد توکن جدید را انتخاب کنید.

یک نام توصیفی برای توکن خود وارد کنید که هدف آن را منعکس کند و شناسایی آن را در آینده آسان کند.
🔐 توصیه برای مدت زمان توکن
مدت زمان توصیه شده: 30 روز برای امنیت بیشتر، میتوانید مدت زمان کوتاهتری را انتخاب کنید—مانند 7 روز 🛡️ این یک راه عالی برای تعیین هدف شخصی و تکمیل دوره در حالی است که انگیزه یادگیری شما بالا است 🚀.

دامنه توکن را به فورک این مخزن محدود کنید.

مجوزهای توکن را محدود کنید: در زیر Permissions، بر روی تب Account کلیک کنید و دکمه “+ Add permissions” را فشار دهید. یک منوی کشویی ظاهر خواهد شد. لطفاً به دنبال Models بگردید و کادر مربوط به آن را علامت بزنید.

قبل از ایجاد توکن، مجوزهای مورد نیاز را بررسی کنید. 
قبل از ایجاد توکن، مطمئن شوید که آماده ذخیره توکن در مکانی امن مانند یک گاوصندوق مدیریت رمز عبور هستید، زیرا پس از ایجاد آن دیگر نمایش داده نمیشود. 
توکن جدیدی که ایجاد کردهاید را کپی کنید. اکنون باید این توکن را به فایل .env که در این دوره گنجانده شده است اضافه کنید.
.envبرای ایجاد فایل .env دستور زیر را در ترمینال خود اجرا کنید.
cp .env.example .env
این دستور فایل نمونه را کپی کرده و یک فایل .env در دایرکتوری شما ایجاد میکند که در آن مقادیر متغیرهای محیطی را پر میکنید.
با کپی کردن توکن خود، فایل .env را در ویرایشگر متن مورد علاقه خود باز کنید و توکن خود را در قسمت GITHUB_TOKEN جایگذاری کنید.

اکنون باید بتوانید نمونههای کد این دوره را اجرا کنید.
مراحل ایجاد یک هاب و پروژه در Azure AI Foundry را دنبال کنید که در اینجا آمده است: بررسی اجمالی منابع هاب
پس از ایجاد پروژه خود، باید رشته اتصال پروژه خود را دریافت کنید.
این کار با رفتن به صفحه Overview پروژه خود در پورتال Azure AI Foundry قابل انجام است.

.envبرای ایجاد فایل .env دستور زیر را در ترمینال خود اجرا کنید.
cp .env.example .env
این دستور فایل نمونه را کپی کرده و یک فایل .env در دایرکتوری شما ایجاد میکند که در آن مقادیر متغیرهای محیطی را پر میکنید.
با کپی کردن توکن خود، فایل .env را در ویرایشگر متن مورد علاقه خود باز کنید و توکن خود را در قسمت PROJECT_ENDPOINT جایگذاری کنید.
به عنوان یک بهترین روش امنیتی، از احراز هویت بدون کلید برای احراز هویت به Azure OpenAI با Microsoft Entra ID استفاده خواهیم کرد.
سپس، یک ترمینال باز کنید و دستور az login --use-device-code را اجرا کنید تا وارد حساب Azure خود شوید.
پس از ورود، اشتراک خود را در ترمینال انتخاب کنید.
برای درس Agentic RAG - درس 5 - نمونههایی وجود دارد که از Azure Search و Azure OpenAI استفاده میکنند.
اگر میخواهید این نمونهها را اجرا کنید، باید متغیرهای محیطی زیر را به فایل .env خود اضافه کنید:
AZURE_SUBSCRIPTION_ID - جزئیات پروژه را در صفحه Overview پروژه خود بررسی کنید.
AZURE_AI_PROJECT_NAME - در بالای صفحه Overview پروژه خود نگاه کنید.
AZURE_OPENAI_SERVICE - این را در تب Included capabilities برای سرویس Azure OpenAI در صفحه Overview پیدا کنید.
AZURE_OPENAI_RESOURCE_GROUP - به Project properties در صفحه Overview مرکز مدیریت بروید.
GLOBAL_LLM_SERVICE - در زیر Connected resources، نام اتصال Azure AI Services را پیدا کنید. اگر لیست نشده است، در پورتال Azure زیر گروه منابع خود برای نام منبع AI Services بررسی کنید.
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME - مدل جاسازی خود را انتخاب کنید (مثلاً text-embedding-ada-002) و نام Deployment name را از جزئیات مدل یادداشت کنید.
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME - مدل چت خود را انتخاب کنید (مثلاً gpt-4o-mini) و نام Deployment name را از جزئیات مدل یادداشت کنید.
AZURE_OPENAI_ENDPOINT - به دنبال سرویسهای Azure AI بگردید، روی آن کلیک کنید، سپس به Resource Management، Keys and Endpoint بروید، به پایین صفحه “Azure OpenAI endpoints” بروید و یکی از آنها را که “Language APIs” میگوید کپی کنید.
AZURE_OPENAI_API_KEY - از همان صفحه، کلید KEY 1 یا KEY 2 را کپی کنید.
AZURE_SEARCH_SERVICE_ENDPOINT - منبع Azure AI Search خود را پیدا کنید، روی آن کلیک کنید و صفحه Overview را ببینید.
AZURE_SEARCH_API_KEY - سپس به Settings و سپس Keys بروید تا کلید اصلی یا کلید فرعی مدیر را کپی کنید.
AZURE_OPENAI_API_VERSION - به صفحه چرخه عمر نسخه API در زیر آخرین نسخه GA API مراجعه کنید.به جای اینکه اطلاعات ورود خود را به صورت سختکد کنید، از اتصال بدون کلید با Azure OpenAI استفاده خواهیم کرد. برای این کار، DefaultAzureCredential را وارد کرده و بعداً تابع DefaultAzureCredential را برای دریافت اعتبارنامه فراخوانی میکنیم.
from azure.identity import DefaultAzureCredential, InteractiveBrowserCredential
اگر در اجرای این تنظیمات مشکلی دارید، به دیسکورد جامعه Azure AI ما بپیوندید یا یک مشکل جدید ایجاد کنید.
اکنون آماده اجرای کد این دوره هستید. از یادگیری بیشتر درباره دنیای عوامل هوش مصنوعی لذت ببرید!
مقدمهای بر عوامل هوش مصنوعی و موارد استفاده از عوامل
سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش میکنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمههای خودکار ممکن است شامل خطاها یا نادرستیها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفهای انسانی توصیه میشود. ما مسئولیتی در قبال سوء تفاهمها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.