ساخت ایجنت و ابزار در LangChain با API پیکو هوش

ایجنت آماده

از LangChain نسخه‌ی ۱.۰ به بعد، ایجنت‌های ابزارمحور با create_agent از langchain.agents ساخته می‌شوند (مستندات مهاجرت رسمی: create_react_agent از langgraph.prebuilt به create_agent در langchain.agents منتقل شد و آرگومان prompt به system_prompt تغییر نام داد). مدل می‌تواند یک شیء مدل از پیش ساخته‌شده مثل ChatOpenAI ما باشد:

from langchain.agents import create_agent

agent = create_agent(
    model=llm,
    tools=tools,
    system_prompt="تو دستیار دقیقی هستی و فارسی پاسخ می‌دهی.",
)
out = agent.invoke({"messages": [{"role": "user", "content": "۱۲۰ را در ۴۲۵۰۰ ضرب کن و نتیجه را بگو."}]})
print(out["messages"][-1].content)

این کد برای langchain>=1.0 است (که Python 3.10+ می‌خواهد). اگر نسخه‌ی ۰.۳ یا قدیمی‌تر دارید، معادل آن from langgraph.prebuilt import create_react_agent و create_react_agent(llm, tools) است. مستندات رسمی مثال صریحی از ChatOpenAI با create_agent نشان نمی‌دهند و فقط می‌گویند model یک رشته‌ی "provider:model" یا نمونه‌ی مدل را می‌پذیرد؛ با پیکو هوش از نمونه‌ی ChatOpenAI با base_url استفاده کنید، نه رشته‌ی provider. برای کنترل کامل گراف به آموزش LangGraph بروید.

نکات تولید

1. محدودیت تکرار: برای جلوگیری از حلقه‌ی بی‌پایان، recursion_limit (کلید تنظیم LangGraph که زیر ایجنت است) را تنظیم کنید: agent.invoke(input, config={"recursion_limit": 10}).
2. اعتبارسنجی ورودی ابزار: هرگز خروجی مدل را بی‌چون‌وچرا اجرا نکنید (مثلاً شل یا SQL). لیست مجاز تعریف کنید.
3. هزینه: هر دور حلقه یک درخواست کامل با کل تاریخچه است؛ توکن ورودی با هر دور بیشتر می‌شود. روش حساب در تخمین هزینه.
4. خطاهای موقت: max_retries در ChatOpenAI را بگذارید.

عیب‌یابی

کنترل انتخاب ابزار

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

forced = llm.bind_tools(tools, tool_choice="word_count")   # فقط این ابزار
auto = llm.bind_tools(tools)                                # پیش‌فرض: خود مدل تصمیم می‌گیرد

پشتیبانی از tool_choice به مدل بستگی دارد. اگر خطای پارامتر نامعتبر گرفتید، آن را حذف و در توضیح ابزار و پرامپت سیستم راهنمایی بدهید.

ابزار با خروجی ساخت‌یافته و مدیریت خطا

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

@tool
def divide(a: float, b: float) -> str:
    """a را بر b تقسیم می‌کند."""
    if b == 0:
        return "خطا: تقسیم بر صفر ممکن نیست؛ مقدار b را عوض کن."
    return str(a / b)

تست ایجنت

چند سناریوی ثابت (golden test) بنویسید و با temperature=0 اجرا کنید. هر بار که مدل یا پرامپت را عوض می‌کنید، تست‌ها را دوباره بزنید. چون هزینه‌ی هر درخواست مطابق توکن است، تست‌ها را با مدل اقتصادی (claude-haiku-5-5) هم امتحان کنید و فقط در صورت نیاز به مدل قوی‌تر بروید. قیمت‌ها در صفحه‌ی قیمت آمده است.

ایجنت و حافظه

برای نگه‌داشتن تاریخچه‌ی گفتگو بین چند فراخوان، از checkpointer در LangGraph یا مدیریت دستی لیست messages استفاده کنید. فقط پیام‌های لازم را نگه دارید و نتایج بزرگ ابزارها را قبل از افزودن به تاریخچه خلاصه کنید؛ این کار هم هزینه را کم می‌کند و هم خطر پرشدن پنجره‌ی زمینه را.

سوالات متداول

کدام مدل‌ها برای ایجنت بهتر هستند؟

مدل‌های قوی‌تر معمولاً ابزار را دقیق‌تر انتخاب می‌کنند. gpt-6-sol و claude-sonnet-5-5 نقطه‌ی شروع خوبی هستند؛ مدل نهایی را با تست خودتان انتخاب کنید. فهرست در کاتالوگ.

آیا می‌توانم چند ابزار هم‌زمان صدا بزنم؟

بسته به مدل، ممکن است در یک پاسخ چند tool_call بیاید؛ حلقه‌ی بالا همه را اجرا می‌کند.

آیا ابزار جستجوی وب داخلی دارید؟

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

مستندات بیشتر؟

مستندات API و صفحه‌ی LangChain.