ساخت یک AI Agent کاربردی: واژه‌نامه‌ای عملی

یک AI agent برنامه‌ای است که یک هدف را می‌گیرد، دنباله‌ای از اقدامات را تصمیم می‌گیرد و آن اقدامات را با استفاده از ابزارها تا زمانی که هدف برآورده شود یا تسلیم شود اجرا می‌کند. این با یک chatbot متفاوت است، که فقط به پیام‌ها پاسخ می‌دهد. یک agent برنامه‌ریزی می‌کند، توابع را فراخوانی می‌کند، نتایج را بررسی می‌کند و تنظیم می‌کند. اگر فقط از ChatGPT از طریق مرورگر استفاده کرده‌اید، ساخت اولین agent شما جایی است که مدل از یک تولیدکننده متن متوقف می‌شود و به یک جزء در یک سیستم بزرگ‌تر تبدیل می‌شود.

حلقه اصلی

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

1. Agent یک تکلیف را دریافت می‌کند ("ارزان‌ترین پرواز به لیسبون ماه آینده را پیدا کن و خلاصه ایمیل تهیه کن").
2. مدل را با تکلیف به اضافه توضیح ابزارهای دسترس فراخوانی می‌کند.
3. مدل یا پاسخ نهایی یا فراخوانی ابزار برمی‌گرداند، مثل search_flights(destination="Lisbon", month="2025-06").
4. کد شما آن تابع را اجرا می‌کند، نتیجه واقعی را دریافت می‌کند و آن را دوباره به context مدل تغذیه می‌کند.
5. مدل تصمیم می‌گیرد بعد چه کند: یک ابزار دیگر را فراخوانی کن، درخواست توضیح کن یا پایان دهید.

این الگو اغلب ReAct loop نام دارد (reasoning به اضافه acting)، و ستون فقرات frameworks مثل LangChain's agent executors، LlamaIndex agents و OpenAI's function-calling API است. می‌توانید کل چیز را در کمتر از 100 خط Python فقط با یک LLM API و یک while loop پیاده‌سازی کنید — frameworks راحتی را اضافه می‌کنند، نه جادو.

ابزارها چیزی هستند که آن را یک agent می‌کند

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

def get_weather(city: str) -> str:
    """Return current weather for a given city."""
    resp = requests.get(f"https://api.weather.example/v1/{city}")
    return resp.json()["summary"]

با function-calling OpenAI، شما یک JSON schema را در کنار این تابع می‌فرستید و مدل فراخوانی ساختار‌یافته‌ای مثل {"name": "get_weather", "arguments": {"city": "Lisbon"}} به جای متن آزاد خروجی می‌دهد. کد شما آن را تحلیل می‌کند، تابع واقعی را اجرا می‌کند و نتیجه را به عنوان یک پیام جدید در مکالمه برمی‌گرداند. تا زمانی‌که مدل اطلاعات کافی برای پاسخ داشته باشد تکرار کنید.

حافظه و state

یک فراخوانی API تنها حافظه‌ای فراتر از context window ندارد. Agents به state صریح نیاز دارند: یک فهرست دراز‌مدت از پیام‌ها (تاریخ مکالمه) و اغلب یک ذخیره‌سازی جداگانه برای فacts بلندمدت. برای تکالیف کوتاه، یک Python list از dicts نمایندگی کننده مکالمه کافی است. برای agents که نیاز به یادآوری اشیاء در سراسر sessions دارند، می‌رویدبه یک vector database (Chroma, Pinecone, Qdrant) برای ذخیره و بازیابی اطلاعات گذشته مرتبط از طریق embeddings.

این را در ابتدا بیش‌تر طراحی نکنید. تعداد تعجب‌انگیزی از پروژه‌های "agent" نه به این دلیل ناکام می‌شوند که LLM ضعیف است بلکه به این دلیل که state management بی‌نظم است: پیام‌های تکراری، رشد context نامحدود یا از دست دادن track کنندگی ابزار کدام call به کدام نتیجه تعلق دارد.

یک مثال کاری حداقلی

اینجا شکل یک agent بسیار ساده با استفاده از API OpenAI است، بدون framework:

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=[weather_tool_schema],
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            result = get_weather(**json.loads(call.function.arguments))
            messages.append(msg)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })
    else:
        print(msg.content)
        break

این یک agent واقعی، کاربردی است. هر چیز دیگر — استراتژی‌های برنامه‌ریزی، هماهنگی multi-agent، pipeline‌های retrieval — بر روی این حلقه ساخته می‌شود.

جایی که شکست می‌خورد

Agents به روش‌های قابل پیش‌بینی شکست می‌خوریند: حلقه‌های نامحدود tool-call زمانی که مدل نمی‌تواند بگوید موفق شده، آرگومان‌های تابع توهم‌پردازی شده و هزینه‌های فرار از دوباره فراخوانی ابزارهای گران. با یک سقف iteration سخت (مثلاً 10 مرحله) و ثبت هر tool call در حین توسعه محافظت کنید. آرگومان‌ها را قبل از اجرای هر چیزی که یک سیستم واقعی را لمس می‌کند اعتبار سنجی کنید — یک agent که می‌تواند ایمیل ارسال کند یا shell commands اجرا کند نیاز به همان sanitization ورودی دارد که برای کد رو‌به‌رو کاربر اعمال می‌کنید، زیرا LLM تاثیر گذار است، در اثر، یک کاربر نامعتبر تولید آن ورودی.

قدم بعدی

وقتی حلقه کار می‌کند، مشکلات جالب شروع می‌شود: انتخاب بین طراحی single-agent و multi-agent، تصمیم‌گیری درباره میزان خودمختاری که باید اعطا کنید و آزمایش agents با قابلیت اعتماد زمانی که خروجی آن‌ها deterministic نیست. Korra Studio's AI و Python tracks retrieval-augmented generation، طراحی prompt و tool-calling patterns را به عمق بیشتری پوشش می‌دهند اگر می‌خواهید از اینجا ساخت ادامه دهید.