ماژول ۰۴: عامل‌های هوش مصنوعی با ابزارها

March 10, 2026 · View on GitHub

فهرست مطالب

مرور ویدئویی

این جلسه زنده را تماشا کنید که توضیح می‌دهد چگونه با این ماژول شروع کنید:

چه چیزهایی یاد خواهید گرفت

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

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

پیش‌نیازها

تکمیل ماژول ۰۱ - مقدمه (منابع Azure OpenAI مستقر شده‌اند)
توصیه می‌شود ماژول‌های قبلی تکمیل شده باشند (این ماژول به مفاهیم RAG از ماژول ۰۳ در مقایسه ابزارها در مقابل RAG اشاره دارد)
فایل .env در دایرکتوری ریشه با اعتبارنامه‌های Azure (ایجاد شده توسط azd up در ماژول ۰۱)

توجه: اگر ماژول ۰۱ را تکمیل نکردید، ابتدا دستورالعمل‌های استقرار آنجا را دنبال کنید.

درک عامل‌های هوش مصنوعی با ابزارها

📝 توجه: در این ماژول اصطلاح «عامل‌ها» به دستیاران هوش مصنوعی مجهز به قابلیت فراخوانی ابزار اشاره دارد. این با الگوهای Agentic AI (عامل‌های خودکار با برنامه‌ریزی، حافظه و استدلال چندمرحله‌ای) که در ماژول ۰۵: MCP پوشش داده خواهد شد، متفاوت است.

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

بدون ابزار مدل فقط حدس می‌زند — با ابزار می‌تواند APIها، محاسبات را اجرا کند و داده‌های زمان واقعی بازگرداند.

یک عامل هوش مصنوعی با ابزارها از الگوی استدلال و عمل (ReAct) پیروی می‌کند. مدل فقط پاسخ نمی‌دهد — درباره آنچه نیاز دارد فکر می‌کند، با فراخوانی یک ابزار عمل می‌کند، نتیجه را مشاهده می‌کند و سپس تصمیم می‌گیرد که دوباره عمل کند یا پاسخ نهایی را ارائه دهد:

۱. استدلال — عامل سؤال کاربر را تجزیه و تحلیل می‌کند و تعیین می‌کند چه اطلاعاتی نیاز دارد
۲. عمل — عامل ابزار مناسب را انتخاب کرده، پارامترهای درست را تولید می‌کند و آن را فرا می‌خواند
۳. مشاهده — عامل خروجی ابزار را دریافت کرده و ارزیابی می‌کند
۴. تکرار یا پاسخ — اگر داده بیشتری لازم باشد، حلقه تکرار می‌شود؛ در غیر این صورت پاسخ نهایی به زبان طبیعی تنظیم می‌شود

چرخه ReAct — عامل درباره آنچه باید انجام دهد استدلال می‌کند، با فراخوانی ابزار عمل می‌کند، نتیجه را مشاهده می‌کند و تا رسیدن به پاسخ نهایی حلقه می‌زند.

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

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

تعاریف ابزار

WeatherTool.java | TemperatureTool.java

شما توابعی با توضیحات واضح و مشخصات پارامتر تعریف می‌کنید. مدل این توضیحات را در درخواست سیستم خود مشاهده کرده و می‌فهمد هر ابزار چه کاری انجام می‌دهد.

@Component
public class WeatherTool {
    
    @Tool("Get the current weather for a location")
    public String getCurrentWeather(@P("Location name") String location) {
        // منطق جستجوی آب و هوای شما
        return "Weather in " + location + ": 22°C, cloudy";
    }
}

@AiService
public interface Assistant {
    String chat(@MemoryId String sessionId, @UserMessage String message);
}

// دستیار به طور خودکار توسط Spring Boot متصل شده است به:
// - بین ChatModel
// - تمام روش‌های @Tool از کلاس‌های @Component
// - ChatMemoryProvider برای مدیریت جلسه

نمودار زیر هر نکته را تجزیه کرده و نشان می‌دهد چگونه هر قطعه به هوش مصنوعی کمک می‌کند زمان فراخوانی ابزار و آرگومان‌های پاس داده شده را بفهمد:

آناتومی تعریف یک ابزار — @Tool به هوش مصنوعی می‌گوید چه زمانی از آن استفاده کند، @P هر پارامتر را توصیف می‌کند، و @AiService در زمان راه‌اندازی همه چیز را متصل می‌کند.

🤖 با GitHub Copilot چت کنید: WeatherTool.java را باز کنید و بپرسید:

"چگونه یک API واقعی هواشناسی مثل OpenWeatherMap را به جای داده‌های شبیه‌سازی شده ادغام کنم؟"

"یک توضیح خوب برای ابزار چگونه است که به هوش مصنوعی در استفاده صحیح کمک می‌کند؟"

"چگونه خطاها و محدودیت‌های نرخ API را در پیاده‌سازی ابزار مدیریت کنم؟"

تصمیم‌گیری

وقتی کاربر می‌پرسد «آب و هوای سیاتل چگونه است؟»، مدل به‌طور تصادفی ابزار انتخاب نمی‌کند. هدف کاربر را با تمام توضیحات ابزارهایی که به آنها دسترسی دارد مقایسه می‌کند، برای هر کدام نمره‌ای از نظر ارتباط می‌دهد و بهترین تطابق را انتخاب می‌کند. سپس یک فراخوانی تابع ساختاریافته با پارامترهای صحیح تولید می‌کند — در این مورد مقدار location را "Seattle" تنظیم می‌کند.

اگر هیچ ابزاری با درخواست کاربر تطابق نداشته باشد، مدل به پاسخ دادن از دانش خود بازمی‌گردد. اگر چندین ابزار تطبیق داشتند، دقیق‌ترین ابزار انتخاب می‌شود.

چگونه هوش مصنوعی تصمیم می‌گیرد از کدام ابزار استفاده کند

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

اجرا

AgentService.java

Spring Boot رابط @AiService اعلامی را با تمام ابزارهای ثبت‌شده به‌صورت خودکار متصل می‌کند و LangChain4j فراخوانی ابزارها را به‌طور خودکار اجرا می‌کند. پشت صحنه، یک فراخوانی کامل ابزار از شش مرحله عبور می‌کند — از سؤال زبان طبیعی کاربر تا پاسخ زبان طبیعی نهایی:

روند انتها به انتها — کاربر سؤال می‌کند، مدل یک ابزار انتخاب می‌کند، LangChain4j آن را اجرا می‌کند و مدل نتیجه را در پاسخ طبیعی جای می‌دهد.

اگر ToolIntegrationDemo را در ماژول ۰۰ اجرا کرده باشید، قبلاً این الگو را دیده‌اید — ابزارهای Calculator به همین صورت فراخوانی شدند. نمودار توالی زیر دقیقاً نشان می‌دهد در آن دمو چه اتفاقی افتاد:

حلقه فراخوانی ابزار از دمو Quick Start — AiServices پیام و طرحواره‌های ابزار شما را به LLM می‌فرستد، LLM با یک فراخوانی تابع مانند add(42, 58) پاسخ می‌دهد، LangChain4j روش Calculator را به‌صورت محلی اجرا می‌کند و نتیجه را برای پاسخ نهایی بازمی‌گرداند.

🤖 با GitHub Copilot چت کنید: AgentService.java را باز کنید و بپرسید:

"الگوی ReAct چگونه کار می‌کند و چرا برای عامل‌های هوش مصنوعی مؤثر است؟"

"عامل چگونه تصمیم می‌گیرد کدام ابزار را به چه ترتیبی استفاده کند؟"

"اگر اجرای یک ابزار شکست خورد چه اتفاقی می‌افتد — چگونه باید خطاها را به‌طور قابل اعتماد مدیریت کنم؟"

تولید پاسخ

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

معماری: اتصال خودکار در Spring Boot

این ماژول از ادغام LangChain4j با Spring Boot با رابط‌های اعلامی @AiService استفاده می‌کند. در زمان راه‌اندازی، Spring Boot هر @Component که شامل متدهای @Tool است، bean مدل چت شما و ChatMemoryProvider را پیدا کرده، و همه را در یک رابط Assistant بدون کد اضافی متصل می‌کند.

رابط @AiService مدل چت، مؤلفه‌های ابزار و ارائه‌دهنده حافظه را به هم متصل می‌کند — Spring Boot همه اتصال‌ها را به‌طور خودکار مدیریت می‌کند.

روند کامل چرخه درخواست به‌صورت نمودار توالی — از درخواست HTTP تا کنترلر، سرویس و پراکسی متصل خودکار، و تا اجرای ابزار و بازگشت پاسخ:

نمودار توالی فراخوانی ابزار در Spring Boot

چرخه کامل درخواست در Spring Boot — درخواست HTTP از کنترلر و سرویس عبور می‌کند تا به پراکسی Assistant متصل خودکار برسد که LLM و فراخوانی‌های ابزار را به‌طور خودکار مدیریت می‌کند.

مزایای کلیدی این روش:

اتصال خودکار Spring Boot — مدل چت و ابزارها به‌صورت خودکار تزریق می‌شوند
الگوی @MemoryId — مدیریت حافظه مبتنی بر جلسه به‌طور خودکار
یک نمونه واحد — ساخته شدن یک بار Assistant و استفاده مجدد برای عملکرد بهتر
اجرای نوع امن — متدهای جاوا مستقیماً با تبدیل نوع فراخوانی می‌شوند
هماهنگی چندمرحله‌ای — زنجیره‌سازی ابزار را به‌طور خودکار مدیریت می‌کند
کد اضافی صفر — بدون نیاز به فراخوانی دستی AiServices.builder() یا نگهداری HashMap حافظه

روش‌های جایگزین (فراخوانی دستی AiServices.builder()) کد بیشتری می‌طلبند و از مزایای ادغام Spring Boot محروم‌اند.

زنجیره‌سازی ابزار

زنجیره‌سازی ابزار — قدرت واقعی عامل‌های مبتنی بر ابزار وقتی ظاهر می‌شود که یک سؤال واحد به چندین ابزار نیاز داشته باشد. از عامل بپرسید «آب و هوای سیاتل به فارنهایت چقدر است؟» و عامل به طور خودکار دو ابزار را زنجیره می‌کند: ابتدا getCurrentWeather را برای دریافت دما به سلسیوس فراخوانی می‌کند، سپس مقدار را به celsiusToFahrenheit برای تبدیل می‌فرستد — همه در یک دور گفتگو.

زنجیره‌سازی ابزار در عمل — عامل ابتدا getCurrentWeather را فراخوانی می‌کند، سپس نتیجه سلسیوس را به celsiusToFahrenheit می‌دهد و پاسخ ترکیبی ارائه می‌دهد.

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

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

این اتفاق در یک دور گفتگو رخ می‌دهد. عامل به طور مستقل چندین فراخوانی ابزار را هماهنگ می‌کند.

اجرای برنامه

تأیید استقرار:

اطمینان حاصل کنید که فایل .env در دایرکتوری ریشه با اعتبارنامه‌های Azure وجود دارد (در ماژول ۰۱ ایجاد شده است). این دستور را از پوشه ماژول (04-tools/) اجرا کنید:

Bash:

cat ../.env  # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نمایش دهد

PowerShell:

Get-Content ..\.env  # باید AZURE_OPENAI_ENDPOINT ، API_KEY ، DEPLOYMENT را نمایش دهد

شروع برنامه:

توجه: اگر قبلاً همه برنامه‌ها را با استفاده از ./start-all.sh از دایرکتوری ریشه (طبق ماژول ۰۱) اجرا کرده‌اید، این ماژول در پورت ۸۰۸۴ در حال اجراست. می‌توانید دستورات شروع را رد کرده و مستقیماً به http://localhost:8084 بروید.

گزینه ۱: استفاده از داشبورد Spring Boot (توصیه شده برای کاربران VS Code)

کانتینر توسعه شامل افزونه داشبورد Spring Boot است که رابط بصری برای مدیریت همه برنامه‌های Spring Boot ارائه می‌دهد. این را در نوار فعالیت در سمت چپ VS Code (آیکون Spring Boot) پیدا کنید.

از داشبورد Spring Boot می‌توانید:

همه برنامه‌های Spring Boot موجود در فضای کاری را ببینید
برنامه‌ها را با یک کلیک شروع/توقف کنید
لاگ‌های برنامه را به‌صورت زنده مشاهده کنید
وضعیت برنامه را رصد کنید به‌سادگی روی دکمه پخش کنار "ابزارها" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را همزمان اجرا کنید.

نمای داشبورد Spring Boot در VS Code به این صورت است:

داشبورد Spring Boot در VS Code — شروع، توقف و نظارت بر همه ماژول‌ها از یک محل

گزینه ۲: استفاده از اسکریپت‌های شل

شروع همه برنامه‌های تحت وب (ماژول‌های ۰۱-۰۴):

Bash:

cd ..  # از دایرکتوری ریشه
./start-all.sh

PowerShell:

cd ..  # از دایرکتوری ریشه
.\start-all.ps1

یا فقط همین ماژول را شروع کنید:

Bash:

cd 04-tools
./start.sh

PowerShell:

cd 04-tools
.\start.ps1

هر دو اسکریپت به صورت خودکار متغیرهای محیطی را از فایل ریشه .env بارگیری می‌کنند و در صورتی که فایل‌های JAR وجود نداشته باشند آن‌ها را می‌سازند.

توجه: اگر ترجیح می‌دهید همه ماژول‌ها را پیش از شروع به صورت دستی بسازید:

Bash:
cd ..  # Go to root directory
mvn clean package -DskipTests
PowerShell:
cd ..  # Go to root directory
mvn clean package -DskipTests

در مرورگر خود به آدرس http://localhost:8084 بروید.

برای توقف:

Bash:

./stop.sh  # فقط این ماژول
# یا
cd .. && ./stop-all.sh  # همه ماژول‌ها

PowerShell:

.\stop.ps1  # فقط این ماژول
# یا
cd ..; .\stop-all.ps1  # همه ماژول‌ها

استفاده از برنامه

این برنامه یک رابط وب فراهم می‌کند که می‌توانید با یک عامل هوش مصنوعی که به ابزارهای هواشناسی و تبدیل دما دسترسی دارد تعامل کنید. نمای رابط به این صورت است — که شامل مثال‌های شروع سریع و یک پنل چت برای ارسال درخواست‌ها است:

رابط ابزارهای عامل هوش مصنوعی - مثال‌های سریع و رابط چت برای تعامل با ابزارها

امتحان استفاده ساده از ابزار

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

آزمایش زنجیر کردن ابزارها

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

مشاهده جریان گفتگو

رابط چت سابقه گفتگو را حفظ می‌کند و امکان تعامل چند مرحله‌ای را فراهم می‌آورد. می‌توانید تمام سوالات و پاسخ‌های قبلی را ببینید که پیگیری گفتگو و درک نحوه ساخت زمینه توسط عامل در چندین تبادل را آسان می‌کند.

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

آزمایش درخواست‌های مختلف

ترکیب‌های مختلف را امتحان کنید:

جستجوی هوا: "هوا در توکیو چطور است؟"
تبدیل دما: "۲۵ درجه سلسیوس چقدر در کلوین است؟"
پرسش‌های ترکیبی: "هوا در پاریس را بررسی کن و بگو آیا بالای ۲۰ درجه سلسیوس است یا نه"

توجه کنید که عامل چگونه زبان طبیعی را تفسیر می‌کند و آن را به فراخوانی‌های مناسب ابزار نگاشت می‌کند.

مفاهیم کلیدی

الگوی ReAct (استدلال و اقدام)

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

اهمیت توضیحات ابزارها

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

مدیریت جلسه

حاشیه‌نویسی @MemoryId امکان مدیریت خودکار حافظه مبتنی بر جلسه را فعال می‌کند. هر شناسه جلسه یک نمونه ChatMemory مخصوص به خود را دارد که توسط مولفه ChatMemoryProvider مدیریت می‌شود، پس چندین کاربر می‌توانند همزمان با عامل تعامل داشته باشند بدون اینکه گفتگوهایشان با هم مخلوط شوند. نمودار زیر نشان می‌دهد چگونه چند کاربر به حافظه‌های مجزا بر اساس شناسه‌های جلسه ارجاع داده می‌شوند:

هر شناسه جلسه به یک سابقه گفتگو ایزوله شده نگاشت می‌شود — کاربران هرگز پیام‌های همدیگر را نمی‌بینند.

مدیریت خطا

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

ابزارهای موجود

نمودار زیر اکوسیستم گسترده‌ای از ابزارها را که می‌توانید بسازید نشان می‌دهد. این ماژول ابزارهای هواشناسی و دمایی را نشان می‌دهد، اما همان الگوی @Tool برای هر متد جاوا قابل استفاده است — از پرس‌وجوهای پایگاه داده تا پردازش پرداخت.

هر متد جاوایی که با @Tool نشانه‌گذاری شود برای هوش مصنوعی در دسترس قرار می‌گیرد — این الگو شامل پایگاه داده‌ها، APIها، ایمیل، عملیات فایل و بیشتر می‌شود.

کی از عوامل مبتنی بر ابزار استفاده کنیم

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

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

ابزارها در مقابل RAG

ماژول‌های ۰۳ و ۰۴ هر دو قابلیت‌های هوش مصنوعی را گسترش می‌دهند ولی به صورت بنیادی متفاوت. RAG به مدل دسترسی به دانش می‌دهد با بازیابی اسناد. ابزارها به مدل امکان انجام عملیات با فراخوانی توابع را می‌دهند. نمودار زیر این دو رویکرد را کنار هم مقایسه می‌کند — از نحوه عملکرد هر گردش کار تا مزایا و معایب آن‌ها:

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

در عمل، بسیاری از سیستم‌های تولیدی هر دو رویکرد را ترکیب می‌کنند: RAG برای پایه‌گذاری پاسخ‌ها در مستندات شما، و ابزارها برای واکشی داده‌های زنده یا انجام عملیات.

گام‌های بعدی

ماژول بعدی: 05-mcp - Model Context Protocol (MCP)

ناوبری: ← قبلی: ماژول ۰۳ - RAG | بازگشت به اصلی | بعدی: ماژول ۰۵ - MCP →

سلب مسئولیت:
این سند با استفاده از خدمات ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی خطاها یا نواقصی باشند. سند اصلی به زبان بومی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه نیستیم.