ساخت ایجنت پشتیبانی مشتری؛ حلقه‌ای که مدل را از حرف‌زدن به عمل‌کردن می‌رساند

مهدی مسئول پشتیبانی یک فروشگاه اینترنتی لوازم خانگی است. هر روز صبح که پنل تیکت‌ها را باز می‌کند، سه‌چهارم پیام‌ها یک الگوی تکراری دارند: «شمارهٔ تماس ثبت‌شده‌ام را برایم بخوانید»، «سفارش من به کجا رسید؟» و «این سفارش را لغو کنید». او یک ربات هوشمند روی سایت گذاشته که با مدل زبانی جواب می‌دهد و ربات هم مؤدبانه و روان حرف می‌زند — اما وقتی مشتری می‌پرسد وضعیت سفارش ۸۳۱۲ چیست، ربات با اطمینان کامل می‌گوید «سفارش شما ارسال شده است». چنین سفارشی اصلاً وجود ندارد. مهدی فکر می‌کند مدل دروغ می‌گوید. مدل دروغ نمی‌گوید؛ فقط هیچ راهی ندارد که به پایگاه دادهٔ فروشگاه نگاه کند، و وقتی راه نگاه‌کردن نباشد، مدل زبانی محتمل‌ترین جمله را می‌سازد.

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

آنچه در این درس یاد می‌گیرید

• تعریف سه ابزار پایهٔ یک ایجنت پشتیبانی — خواندن اطلاعات مشتری، خواندن جزئیات سفارش و لغو سفارش — و اینکه توضیح هر ابزار چرا بخشی از پرامپت است.
• حلقهٔ ایجنتی: چطور با stop_reason بفهمید مدل ابزار می‌خواهد و نتیجه را با tool_result برگردانید.
• نقش tool_use_id در گره‌زدن پرسش و پاسخ ابزار، و اینکه چرا فراموش‌کردنش سامانه را در چندابزاری خراب می‌کند.
• یک اصلاح مهم روی کد رسمی: چرا باید تاریخچه را «اضافه» کنید نه «بازسازی».
• تفاوت بنیادی ابزار خواننده با ابزار اقدام‌کننده، و اینکه لغو سفارش چرا نباید بی‌واسطه به مدل سپرده شود.
• مدیریت خطا به‌عنوان بخشی از قرارداد ابزار، نه یک استثنا.

سه ابزار، سه قرارداد روشن

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

tools = [
    {
        "name": "get_customer_info",
        "description": "Retrieves customer information based on their customer ID. Returns the customer's name, email, and phone number.",
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_id": {"type": "string", "description": "The unique identifier for the customer."}
            },
            "required": ["customer_id"],
        },
    },
    {
        "name": "get_order_details",
        "description": "Retrieves the details of a specific order based on the order ID. Returns the order ID, product name, quantity, price, and order status.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "The unique identifier for the order."}
            },
            "required": ["order_id"],
        },
    },
    {
        "name": "cancel_order",
        "description": "Cancels an order based on the provided order ID. Returns a confirmation message if the cancellation is successful.",
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "The unique identifier for the order to be cancelled."}
            },
            "required": ["order_id"],
        },
    },
]

به جملهٔ آخر هر توضیح دقت کنید: «چه چیزی برمی‌گرداند». این عادت کوچک، مدل را از حدس‌زدن نجات می‌دهد. وقتی مدل بداند get_order_details وضعیت سفارش را هم برمی‌گرداند، دیگر برای پاسخ به «سفارشم کجاست؟» دو ابزار پشت سر هم صدا نمی‌زند.

پشت هر ابزار، یک تابع معمولی

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