راهنمای عملی: اولین دستیار (Agent) هوشمند خودتون رو بسازید! (پروژه گام‌به‌گام)

سلام! خوش اومدید به آخرین مقاله این سری - و شاید هیجان‌انگیزترینش! تا اینجای کار، خیلی چیزها درباره دستیارهای هوشمند (AI Agents) یاد گرفتیم. حالا وقتشه که دست به کار بشیم و واقعاً یه Agent بسازیم!

راستش رو بخواید، من اولین بار که خواستم یه Agent بسازم، سه هفته وقت‌گذاشتم روی خوندن مستندات و دیدن ویدئوها. نتیجه؟ هیچ Agent کاری نساختم! غرق شده بودم توی فریمورک‌ها، فلج شده بودم از انتخاب، و فکر می‌کردم باید اول LangChain، AutoGen و پنج تا ابزار دیگه رو کامل یاد بگیرم. بعد فهمیدم: داشتم برعکس پیش می‌رفتم!

بهترین سازنده‌هایی که می‌شناسم ساده شروع می‌کنن، سریع Ship می‌کنن، و با انجام دادن یاد می‌گیرن.

امروز می‌خوام دقیقاً همونطور که من یاد گرفتم، به شما یاد بدم - با یه پروژه واقعی و کاربردی!

قبل از شروع: انتظاراتتون رو واقعی‌بینانه کنید 🎯

هدف اینه که کسی رو تحت تاثیر قرار بدیم نیست. هدف اینه که بفهمیم Agent‌ها چطور فکر می‌کنن و پاسخ می‌دن. تسلط بر این قبلاً 70 درصد از چیزی هست که باید بدونید.

این راهنما برای چه کسیه:

• ✅ برنامه‌نویسان مبتدی تا متوسط
• ✅ کسانی که می‌خوان سریع شروع کنن
• ✅ افرادی که یادگیری عملی دوست دارن
• ✅ کسانی که صبر ندارن 3 هفته مستندات بخونن!

این راهنما برای چه کسی نیست:

• ❌ کسانی که می‌خوان فقط بخونن ولی نسازن
• ❌ افرادی که دنبال راه‌حل‌های پیچیده بدون کد هستن
• ❌ کسانی که انتظار دارن بدون تلاش همه چیز کامل باشه

پروژه ما: یه Agent پشتیبانی مشتری ساده 🤖

قراره یه Agent بسازیم که:

• سوالات رایج (FAQ) رو جواب بده
• اطلاعات محصول رو بده
• وضعیت سفارش رو چک کنه
• به زبان طبیعی با کاربر صحبت کنه

ساده ولی کاربردی!

چیزهایی که نیاز دارید 📦

1. نصب Python

# بررسی نصب Python python --version  # باید 3.8 یا بالاتر باشه

اگه نصب نیست، از python.org دانلود کنید.

2. حساب OpenAI

• برید به platform.openai.com
• حساب بسازید
• یه API Key بگیرید (اولین $5 رایگانه!)

3. یه ادیتور کد

• VS Code (توصیه می‌کنم)
• یا هر ادیتوری که راحتید

مرحله 1: راه‌اندازی پروژه (10 دقیقه) 🚀

قدم 1.1: ساخت پوشه پروژه

# ساخت پوشه mkdir my-first-agent cd my-first-agent # ساخت محیط مجازی Python python -m venv venv # فعال‌سازی محیط مجازی # در Windows: venv\Scripts\activate # در Mac/Linux: source venv/bin/activate

قدم 1.2: نصب کتابخونه‌ها

pip install openai python-dotenv

قدم 1.3: ساخت فایل .env

# ساخت فایل .env touch .env  # در Mac/Linux # یا در Windows دستی بسازید

داخل فایل .env بنویسید:

OPENAI_API_KEY=sk-your-api-key-here

⚠️ مهم: هیچ وقت این فایل رو به Git اضافه نکنید!

مرحله 2: اولین Agent ساده (15 دقیقه) 💻

بیاید با ساده‌ترین Agent ممکن شروع کنیم:

فایل simple_agent.py:

import os from openai import OpenAI from dotenv import load_dotenv # بارگذاری متغیرهای محیطی load_dotenv() # ساخت کلاینت OpenAI client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) def simple_agent(user_message):    """    ساده‌ترین Agent ممکن    """    response = client.chat.completions.create(        model="gpt-3.5-turbo",  # ارزان‌تر برای تست        messages=[            {                "role": "system",                "content": "تو یه دستیار پشتیبانی مشتری هستی. همیشه مودب و مفید باش."            },            {                "role": "user",                "content": user_message            }        ]    )        return response.choices[0].message.content # تست if __name__ == "__main__":    print("Agent ساده شروع شد! (برای خروج 'quit' بنویسید)\n")        while True:        user_input = input("شما: ")        if user_input.lower() == 'quit':            break                    response = simple_agent(user_input)        print(f"Agent: {response}\n")

اجرا کنید:

python simple_agent.py

تبریک! اولین Agent شما کار می‌کنه! 🎉

ولی این خیلی سادهست. بیاید قوی‌ترش کنیم!

مرحله 3: اضافه کردن حافظه (Memory) (20 دقیقه) 🧠

حالا Agent ما باید گفتگوهای قبلی رو به خاطر بسپره:

فایل agent_with_memory.py:

import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) class AgentWithMemory:    def __init__(self):        self.conversation_history = [            {                "role": "system",                "content": """تو یه دستیار پشتیبانی هستی برای یه فروشگاه آنلاین.                محصولات: لپ‌تاپ (5 میلیون)، موبایل (3 میلیون), هدفون (500 هزار)                زمان ارسال: 2-3 روز کاری                پرداخت: آنلاین و درب منزل                همیشه مودب باش و اطلاعات دقیق بده."""            }        ]        def chat(self, user_message):        # اضافه کردن پیام کاربر به حافظه        self.conversation_history.append({            "role": "user",            "content": user_message        })                # دریافت پاسخ از OpenAI        response = client.chat.completions.create(            model="gpt-3.5-turbo",            messages=self.conversation_history        )                assistant_message = response.choices[0].message.content                # اضافه کردن پاسخ Agent به حافظه        self.conversation_history.append({            "role": "assistant",            "content": assistant_message        })                return assistant_message        def show_memory(self):        """نمایش حافظه (برای دیباگ)"""        print("\n--- حافظه Agent ---")        for msg in self.conversation_history[1:]:  # بدون System prompt            role = "شما" if msg["role"] == "user" else "Agent"            print(f"{role}: {msg['content'][:50]}...")        print("-------------------\n") # تست if __name__ == "__main__":    agent = AgentWithMemory()    print("Agent با حافظه شروع شد!\n")    print("دستورات:")    print("  - هر چیزی بنویسید برای چت")    print("  - 'memory' برای دیدن حافظه")    print("  - 'quit' برای خروج\n")        while True:        user_input = input("شما: ")                if user_input.lower() == 'quit':            break        elif user_input.lower() == 'memory':            agent.show_memory()            continue                    response = agent.chat(user_input)        print(f"Agent: {response}\n")

تست کنید:

python agent_with_memory.py

مثال گفتگو:

شما: سلام، قیمت لپ‌تاپ چنده؟ Agent: سلام! قیمت لپ‌تاپ 5 میلیون تومانه. شما: چه مدت طول می‌کشه برسه؟ Agent: ارسال 2-3 روز کاری طول می‌کشه. شما: اون چیزی که قبلاً گفتی چند بود؟ Agent: قیمت لپ‌تاپ که قبلاً گفتم 5 میلیون تومان بود.

عالی! Agent ما حافظه داره! 🎊

مرحله 4: اضافه کردن ابزارها (Tools) (25 دقیقه) 🔧

حالا بیاید به Agent ابزار بدیم تا بتونه کارهای واقعی انجام بده:

فایل agent_with_tools.py:

import os import json from openai import OpenAI from dotenv import load_dotenv load_dotenv() client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) # دیتابیس ساده (در واقع باید از دیتابیس واقعی استفاده کنید) ORDERS_DB = {    "12345": {        "status": "در حال ارسال",        "product": "لپ‌تاپ",        "date": "1403/08/20"    },    "67890": {        "status": "تحویل داده شده",        "product": "موبایل",        "date": "1403/08/15"    } } PRODUCTS_DB = {    "لپ‌تاپ": {        "price": 5000000,        "stock": 10,        "description": "لپ‌تاپ 15 اینچ، 16GB RAM"    },    "موبایل": {        "price": 3000000,        "stock": 25,        "description": "موبایل 128GB، دوربین 50MP"    },    "هدفون": {        "price": 500000,        "stock": 50,        "description": "هدفون بلوتوث، نویز کنسلینگ"    } } # تعریف ابزارها (Tools) tools = [    {        "type": "function",        "function": {            "name": "check_order_status",            "description": "بررسی وضعیت سفارش با شماره سفارش",            "parameters": {                "type": "object",                "properties": {                    "order_id": {                        "type": "string",                        "description": "شماره سفارش (مثلاً 12345)"                    }                },                "required": ["order_id"]            }        }    },    {        "type": "function",        "function": {            "name": "get_product_info",            "description": "دریافت اطلاعات محصول",            "parameters": {                "type": "object",                "properties": {                    "product_name": {                        "type": "string",                        "description": "نام محصول (لپ‌تاپ، موبایل، یا هدفون)"                    }                },                "required": ["product_name"]            }        }    } ] # پیاده‌سازی ابزارها def check_order_status(order_id):    """بررسی وضعیت سفارش"""    order = ORDERS_DB.get(order_id)    if order:        return json.dumps(order, ensure_ascii=False)    else:        return json.dumps({"error": "سفارش پیدا نشد"}, ensure_ascii=False) def get_product_info(product_name):    """دریافت اطلاعات محصول"""    product = PRODUCTS_DB.get(product_name)    if product:        return json.dumps(product, ensure_ascii=False)    else:        return json.dumps({"error": "محصول پیدا نشد"}, ensure_ascii=False) # نقشه ابزارها available_functions = {    "check_order_status": check_order_status,    "get_product_info": get_product_info } class AgentWithTools:    def __init__(self):        self.conversation_history = [            {                "role": "system",                "content": """تو یه دستیار پشتیبانی فروشگاه آنلاین هستی.                می‌تونی وضعیت سفارش رو چک کنی و اطلاعات محصول بدی.                همیشه مودب و دقیق باش."""            }        ]        def chat(self, user_message):        # اضافه کردن پیام کاربر        self.conversation_history.append({            "role": "user",            "content": user_message        })                # ارسال به OpenAI با ابزارها        response = client.chat.completions.create(            model="gpt-3.5-turbo",            messages=self.conversation_history,            tools=tools,            tool_choice="auto"        )                response_message = response.choices[0].message        tool_calls = response_message.tool_calls                # اگه Agent خواست از ابزار استفاده کنه        if tool_calls:            # اضافه کردن پاسخ Agent به حافظه            self.conversation_history.append(response_message)                        # اجرای هر ابزار            for tool_call in tool_calls:                function_name = tool_call.function.name                function_args = json.loads(tool_call.function.arguments)                                print(f"[Debug] Agent داره از ابزار استفاده می‌کنه: {function_name}")                print(f"[Debug] پارامترها: {function_args}")                                # فراخوانی تابع                function_response = available_functions[function_name](**function_args)                                # اضافه کردن نتیجه به حافظه                self.conversation_history.append({                    "role": "tool",                    "tool_call_id": tool_call.id,                    "name": function_name,                    "content": function_response                })                        # دریافت پاسخ نهایی از Agent            second_response = client.chat.completions.create(                model="gpt-3.5-turbo",                messages=self.conversation_history            )                        final_message = second_response.choices[0].message.content            self.conversation_history.append({                "role": "assistant",                "content": final_message            })                        return final_message        else:            # اگه Agent ابزار استفاده نکرد            assistant_message = response_message.content            self.conversation_history.append({                "role": "assistant",                "content": assistant_message            })            return assistant_message # تست if __name__ == "__main__":    agent = AgentWithTools()    print("Agent با ابزار شروع شد!\n")    print("می‌تونید بپرسید:")    print("  - وضعیت سفارش 12345 چیه؟")    print("  - قیمت لپ‌تاپ چنده؟")    print("  - موجودی موبایل چقدره؟\n")        while True:        user_input = input("شما: ")                if user_input.lower() == 'quit':            break                    response = agent.chat(user_input)        print(f"Agent: {response}\n")

تست کنید:

python agent_with_tools.py

مثال گفتگو:

شما: وضعیت سفارش 12345 چیه؟ [Debug] Agent داره از ابزار استفاده می‌کنه: check_order_status [Debug] پارامترها: {'order_id': '12345'} Agent: سفارش شما (لپ‌تاپ) در حال ارسال هست و در تاریخ 1403/08/20 ثبت شده. شما: قیمت هدفون چنده؟ [Debug] Agent داره از ابزار استفاده می‌کنه: get_product_info [Debug] پارامترها: {'product_name': 'هدفون'} Agent: هدفون بلوتوث با قابلیت نویز کنسلینگ با قیمت 500,000 تومان و 50 عدد موجودی دارم.

واو! Agent ما الان می‌تونه از ابزارها استفاده کنه! 🚀

مرحله 5: رابط کاربری ساده با Streamlit (15 دقیقه) 🎨

بیاید یه رابط کاربری وب ساده براش بسازیم:

نصب Streamlit:

pip install streamlit

فایل app.py:

import streamlit as st from agent_with_tools import AgentWithTools # تنظیمات صفحه st.set_page_config(    page_title="Agent پشتیبانی",    page_icon="🤖",    layout="centered" ) # عنوان st.title("🤖 دستیار هوشمند پشتیبانی") st.markdown("سوالات خودتون رو بپرسید!") # ایجاد Agent (با استفاده از Session State) if "agent" not in st.session_state:    st.session_state.agent = AgentWithTools()    st.session_state.messages = [] # نمایش تاریخچه گفتگو for message in st.session_state.messages:    with st.chat_message(message["role"]):        st.markdown(message["content"]) # ورودی کاربر if prompt := st.chat_input("سوال خودتون رو بپرسید..."):    # نمایش پیام کاربر    st.session_state.messages.append({"role": "user", "content": prompt})    with st.chat_message("user"):        st.markdown(prompt)        # دریافت پاسخ از Agent    with st.chat_message("assistant"):        with st.spinner("در حال فکر کردن..."):            response = st.session_state.agent.chat(prompt)            st.markdown(response)        # ذخیره پاسخ    st.session_state.messages.append({"role": "assistant", "content": response}) # دکمه پاک کردن تاریخچه if st.button("🗑️ پاک کردن تاریخچه"):    st.session_state.agent = AgentWithTools()    st.session_state.messages = []    st.rerun()

اجرا کنید:

streamlit run app.py

یه مرورگر باز میشه و رابط کاربری زیبا رو می‌بینید! 🎉

خطاهای رایج و راه‌حل‌ها 🐛

خطا 1: ModuleNotFoundError

راه‌حل: مطمئن بشید محیط مجازی فعاله و کتابخونه‌ها نصب شدن

خطا 2: AuthenticationError

راه‌حل: API Key رو چک کنید. مطمئن بشید فایل .env درسته

خطا 3: Agent جواب نمی‌ده

راه‌حل: اینترنت رو چک کنید. مطمئن بشید اعتبار OpenAI دارید

خطا 4: Agent ابزار رو فراخوانی نمی‌کنه

راه‌حل: پرامپت سیستم رو واضح‌تر بنویسید. مثال‌ها اضافه کنید

بهبودهای پیشنهادی 🚀

حالا که Agent اصلی شما کار می‌کنه، می‌تونید:

1. دیتابیس واقعی اضافه کنید (PostgreSQL، MongoDB)
2. Authentication بسازید (کاربران مختلف)
3. حافظه بلندمدت (ذخیره در دیتابیس)
4. ابزارهای بیشتر (ارسال ایمیل، SMS، ...)
5. Multi-Agent (چند Agent با هم کار کنن)
6. Deploy کنید (Heroku، AWS، ...)

💡 نکات طلایی برای موفقیت:

1. کوچک شروع کنید → Agent ساده بهتر از Agent پیچیده که کار نمی‌کنه
2. تست کنید → هر تغییر رو تست کنید
3. لاگ بگیرید → print() دوست شماست!
4. صبور باشید → اولین تلاش کامل نیست
5. کپی کنید → از کد‌های آماده استفاده کنید
6. بسازید → تئوری کمک نمی‌کنه، ساختن کمک می‌کنه!

چک‌لیست نهایی ✅

آیا:
✅ Python نصب کردید؟
✅ محیط مجازی ساختید؟
✅ کتابخونه‌ها رو نصب کردید؟
✅ API Key گرفتید؟
✅ Agent ساده رو اجرا کردید؟
✅ حافظه اضافه کردید؟
✅ ابزارها رو پیاده‌سازی کردید؟
✅ رابط کاربری ساختید؟
✅ تست کردید؟

اگه همه جواب‌ها "بله" بود، تبریک! شما الان یه Agent Developer هستید! 🎊

پیام نهایی 💌

بیشتر افراد که این رو می‌خونن هیچی نمی‌سازن. Bookmark می‌کنن، Share می‌کنن، شاید شروع به نصب ابزارها کنن. ولی Ship نمی‌کنن. بیشتر مردم نباشید.

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

پس الان، همین الان، یه چیزی بسازید!

🔙 در این سری گفتیم:

• مقاله 1-11: همه چیز درباره Agent‌ها

🎊 پایان سری!

این آخرین مقاله از سری "انقلاب دستیارهای هوشمند خودکار" بود. امیدوارم این 12 مقاله بهتون کمک کرده باشه که Agent‌ها رو بفهمید و بسازید!

قدم بعدی شما چیه؟

1. Agent خودتون رو بسازید
2. در شبکه‌های اجتماعی Share کنید
3. بهبودش بدید
4. پروژه بعدی رو شروع کنید!

من واقعاً مشتاقم ببینم شما چی می‌سازید! 🚀

سوال نهایی از شما: الان که این سری تموم شد، چه Agent‌ای می‌خواید بسازید؟ من واقعاً کنجکاوم بدونم!

© مجله آرتین | سری مقالات: انقلاب دستیارهای هوشمند خودکار - مقاله 12 از 12 (پایانی)

🎉 تبریک! شما این سری رو کامل کردید!

حالا نوبت شماست که بسازید. به خاطر داشته باشید: بهترین روش یادگیری، ساختنه!