طراحی ابزار و طرحواره ابزار
توسعه عاملهای هوشمند (Agentic Ai) با Langchain و Langgraph
- Define LangChain tools with clear descriptions, typed arguments, and predictable return values.
- Design read-only file search and calculator tools.
- Validate tool inputs and return actionable errors.
چرا ابزارها قرارداد میخواهند؟
**قرارداد ابزار**
هر ابزار باید هدف، ورودی و خروجی قابل پیشبینی داشته باشد.
```mermaid
flowchart LR
A["درخواست کاربر"] --> B["انتخاب ابزار"]
B --> C["اعتبارسنجی"]
C -->|معتبر| D["اجرا"]
C -->|نامعتبر| E["خطای قابل اقدام"]
D --> F["خروجی پایدار"]
```
تعریف ابزار و توضیح دقیق
**انتخاب ابزار**
درخواست: مجموع 18 و 24.
1. انتخاب `calculate`
2. ساخت `expression = "18 + 24"`
3. محاسبه: `18 + 24 = 42`
4. خروجی: `"42"` با نوع `str`
**ایمنی ورودی**
اجرای مستقیم متن دلخواه امن نیست؛ parser محدود و اعتبارسنجی لازم است.
دو ابزار با طراحی روشن
**دو طراحی**
- `search_files`: خواندن فایل، بدون تغییر، همراه مسیر و شمارهٔ خط
- `calculate`: فقط عملیات مجاز روی دو عدد
**محاسبهٔ ضرب**
ورودی: `7`, `5`, `multiply`.
شرط add نادرست است؛ شرط subtract نادرست است؛ شرط multiply درست است.
`7 * 5 = 35` و خروجی `"35"` است.
اعتبارسنجی و خطای قابل اقدام
**تقسیم معتبر**
`18 / 6`:
1. عمل مجاز است.
2. `6 == 0` نادرست است.
3. `result = 18 / 6`
4. `result = 3.0`
5. خروجی: `OK: 3.0`
**تقسیم نامعتبر**
`18 / 0`:
1. عمل مجاز است.
2. `0 == 0` درست است.
3. تقسیم اجرا نمیشود.
4. خروجی، علت و راه اصلاح را اعلام میکند.
قرارداد پایدار، نه استثنای خام
**قرارداد خروجی**
- موفق: `OK: <value>`؛ عملیات انجام شده است.
- ناموفق: `ERROR: <actionable message>`؛ علت و راه اصلاح روشن است.
**دو پاسخ واقعی**
ضرب: `7 * 5 = 35`، سپس `OK: 35`.
تقسیم بر صفر: اجرا متوقف میشود، سپس پیام `ERROR` علت و شرط اصلاح را اعلام میکند.
```mermaid
flowchart TD
A["ورودی ابزار"] --> B{"اعتبارسنجی"}
B -->|موفق| C["اجرای محدود"]
C --> D["OK: value"]
B -->|شکست| E["ERROR: علت + راه اصلاح"]
D --> F["ادامهٔ Agent"]
E --> G["اصلاح ورودی"]
```
بازگشت به دوره