فراخوانی ساده‌ی API مدل‌های زبانی فقط یک درخواست و پاسخ مقطعی است، اما ساخت یک سیستم هوشمند در محیط واقعی نیازمند هماهنگی ابزارها، مدیریت نشست‌های طولانی و کنترل مصرف حافظه است. اگر همه‌ی وظایف و تاریخچه‌ی ابزارها در یک پنجرهی بافتار انباشته شوند، مصرف توکن سرسام‌آور شده و مدل سریعاً دچار سردرگمی میشود.
در این درس یاد می‌گیرید که چگونه بستر آزمایشی یک عامل هوشمند را در قالب یک کتابخانه سازمان‌دهی کنید. با بهره‌گیری از الگوی Claude Agent SDK، نحوه‌ی تفکیک وظایف از طریق سابایجنتها (Subagents)، ایزوله‌سازی پنجرهی بافتار، اجرای هوک‌های چرخه‌ی حیات و ماندگاری نشست‌ها را بهصورت استاندارد بررسی می‌کنیم.
در نظر داشته باشید که برای راه‌اندازی نسخه‌های واقعی این فریم‌ورک‌ها یا دسترسی به APIهای مستقیم سرویس‌های خارجی مانند Anthropic، کارت‌های بانکی ایرانی قابل استفاده نیستند و فعال‌سازی این سرویس‌ها معمولاً نیازمند راه‌های واسط یا کلیدهای سازگار است. همچنین نصب بسته‌های پایتونی مرتبط از PyPI نیز در شرایط شبکه ایران گاهی ناپایدار بوده و نیازمند تنظیم میرورهای مناسب است.
یک بستر آزمایشی (harness) که می‌توانید آن را ایمپورت کنید: ابزارهای توکار، سابایجنتها برای جداسازی بافتار، هوک‌ها، انتشار ردگیری محاسبات (trace propagation) با استاندارد W3C و ماندگاری نشست‌ها. در این میان، Claude Agent SDK نمونه‌ی مرجع به شمار می‌رود — یعنی همان بستر آزمایشی Claude Code در قالب یک کتابخانه — و Claude Managed Agents نیز گزینه‌ی میزبانی‌شده (hosted) برای کارهای ناهمگام و طولانی‌مدت است.
اهداف یادگیری
- تفاوت بین Anthropic Client SDK (کار با API خام) و Claude Agent SDK (ساختار بستر آزمایشی) را توضیح دهید.
- سابایجنتها — موازی‌سازی و جداسازی بافتار — و زمان به‌کارگیری آنها را شرح دهید.
- متدهای سطح ذخیره‌ساز نشست در SDK پایتون (
append،load،list_sessions،delete،list_subkeys) و نقش پرچم--session-mirrorرا نام ببرید. - یک بستر آزمایشی را با کتابخانه‌ی استاندارد پایتون پیاده‌سازی کنید که شامل ابزارهای توکار، ساخت ساب‌ایجنت با بافتار ایزوله، هوک‌های چرخه‌ی حیات و ذخیره‌ساز نشست باشد.
صورت مسئله
کار با API خام یک مدل زبانی فقط یک رفت‌وبرگشت ساده به شما میدهد. اما یک ایجنت آماده‌ی محیط عملیاتی به اجرای ابزارها، سرورهای MCP، هوک‌های چرخه‌ی حیات، ساخت ساب‌ایجنت، ماندگاری نشست و انتشار ردگیری محاسبات نیاز دارد. Claude Agent SDK تمام این ساختار را در قالب یک کتابخانه عرضه می‌کند — همان بستر آزمایشی که Claude Code استفاده می‌کند، اما این بار برای ساخت ایجنت‌های سفارشی شما.
مفاهیم کلیدی
مقایسه‌ی Client SDK با Agent SDK
- بسته‌ی Client SDK (
anthropic): Messages API خام. مدیریت حلقه، ابزارها و وضعیت برنامه کاملاً بر عهدهی خود شماست. - بسته‌ی Agent SDK (
claude-agent-sdk): اجرای توکار ابزارها، اتصالات MCP، هوک‌ها، ساخت ساب‌ایجنت و ذخیره‌ساز نشست. در واقع همان حلقهی Claude Code در قالب یک کتابخانه است.
ابزارهای توکار
این SDK بیش از 10 ابزار آماده دارد: خواندن و نوشتن فایل، شل، grep، glob، دریافت محتوای وب و موارد دیگر. ابزارهای سفارشی هم با همان رابط استاندارد اسکیمای ابزار ثبت می‌شوند.
سابایجنتها
شرکت Anthropic دو کاربرد اصلی برای سابایجنتها مستند کرده است:
- موازی‌سازی (Parallelization): اجرای همزمان کارهای مستقل. مثلاً «پیدا کردن فایل تست برای هر یک از این 20 ماژول» به 20 تسک موازی توسط سابایجنتها تبدیل میشود.
- جداسازی بافتار (Context isolation): سابایجنتها از پنجرهی بافتار (Context Window) اختصاصی خودشان استفاده میکنند و فقط نتایج به هماهنگکننده (orchestrator) برمی‌گردد. با این کار، سهمیه‌ی بافتار هماهنگکننده دست‌نخورده باقی می‌ماند.
قابلیت‌های تازه‌ی SDK پایتون: متدهای list_subagents() و get_subagent_messages() برای خواندن متن گفت‌وگوهای ساب‌ایجنت.
ذخیره‌ساز نشست
تطابق کامل پروتکل با نسخه‌ی TypeScript:
append(session_id, message)— افزودن یک نوبت گفت‌وگو (turn).load(session_id)— بازیابی گفت‌وگو.list_sessions()— فهرست‌کردن نشست‌ها.delete(session_id)— حذف نشست همراه با حذف آبشاری نشست‌های سابایجنتها.list_subkeys(session_id)— فهرست‌کردن کلیدهای سابایجنتها.
پرچم --session-mirror در رابط خط فرمان، متن گفت‌وگو را همزمان با استریم شدن روی فایلی خارجی مینویسد تا اشکالزدایی آن ساده‌تر شود.
هوک‌ها
هوک‌های چرخه‌ی حیاتی که می‌توانید ثبت کنید:
PreToolUseوPostToolUse— کنترل دسترسی، اعتبارسنجی یا ثبت لاگ قبل و بعد از فراخوانی ابزار.SessionStartوSessionEnd— مقداردهی اولیه و پاک‌سازی منابع در آغاز و پایان نشست.UserPromptSubmit— اعمال پردازش روی ورودی کاربر پیش از دیدن مدل.PreCompact— اجرا پیش از فشرده‌سازی بافتار (compaction).Stop— پاک‌سازی منابع هنگام خروج ایجنت.Notification— هشدارهای جانبی خارج از جریان اصلی.
سیستم‌های حرفه‌ای (مثل گردش کارهای پیشرفته‌ی فاز 14 سرفصل‌ها) از همین هوک‌ها برای تزریق رفتارهای فراگیر و مشترک در کل برنامه استفاده میکنند.
زمینه‌ی ردگیری محاسبات با W3C
اسپن‌های (spans) فعال OpenTelemetry در فراخواننده، از طریق هدرهای W3C trace context به زیرپردازه‌ی خط فرمان منتقل می‌شوند. به این ترتیب، کل ردگیری چندپردازه‌ای شما در بک‌اند بهصورت یک ردگیری محاسبات (trace) یکپارچه نمایش داده میشود.
سرویس Claude Managed Agents
گزینه‌ی میزبانی‌شده‌ی شرکت Anthropic (با هدر بتای managed-agents-2026-04-01). این سرویس برای کارهای ناهمگام و طولانی‌مدت طراحی شده و کش کردن پرامپت (prompt caching) و فشرده‌سازی خودکار بافتار را در دل خود دارد. در اینجا بخشی از کنترل روی جزئیات را در ازای استفاده از زیرساخت مدیریت‌شده معامله می‌کنید.
خطاهای رایج در این الگو
- ساخت بی‌رویه‌ی ساب‌ایجنت: اگر برای 100 تسک بسیار کوچک، 100 ساب‌ایجنت بسازید، بار پردازشی راه‌اندازی بر کار اصلی غلبه می‌کند. به‌جای این کار تسک‌ها را دسته‌بندی (batch) کنید.
- خزش هوک‌ها (Hook creep): اگر هر تیمی هوک‌های خودش را اضافه کند، زمان راه‌اندازی به‌شدت طولانی میشود. هوک‌ها را هر فصل یک بار بازبینی کنید.
- انباشت داده‌های نشست (Session bloat): نشست‌ها روی هم جمع شده و حجم داده‌ها بالا می‌رود. با متد
list_sessionsو یک سیاست انقضا این مسئله را مهار کنید.
پیاده‌سازی
فایل code/main.py ساختار این SDK را در کتابخانه‌ی استاندارد پایتون پیاده‌سازی می‌کند:
- کلاس‌های
ToolوToolRegistryهمراه با ابزارهای توکارread_file،write_fileوlist_dir. - کلاس
Subagent— با بافتار اختصاصی، اجرای ایزوله و بازگرداندن نتایج. - کلاس
SessionStore— متدهای append، load، list، delete و list_subkeys. - کلاس
Hooks— متدهایpre_tool_use،post_tool_use،session_startوsession_end. - یک نمونه‌ی نمایشی: ایجنت اصلی 3 ساب‌ایجنت را بهصورت موازی اجرا می‌کند (هرکدام با بافتار ایزوله)، نتایج را جمع‌آوری کرده و نشست را ذخیره می‌کند.
اجرای برنامه:
python3 code/main.pyخروجی ردگیری محاسبات نشان میدهد که بافتار ساب‌ایجنت کاملاً ایزوله مانده (اندازه‌ی بافتار هماهنگکننده محدود باقی می‌ماند)، هوک‌ها به‌درستی اجرا می‌شوند و نشست ماندگار می‌ماند.
کاربردها
- بسته‌ی Claude Agent SDK برای محصولاتی که اولویتشان کار با Claude است و ساختار بستر آزمایشی Claude Code را می‌خواهند.
- سرویس Claude Managed Agents برای پردازش‌های ناهمگام و طولانی‌مدت در بستر میزبانی‌شده.
- بسته‌ی OpenAI Agents SDK (درس 16) برای راهکارهای معادل در دنیای OpenAI.
- ترکیب LangGraph + ابزارهای سفارشی اگر به‌جای این الگو، یک ماشین وضعیت (State Machine) گراف‌محور می‌خواهید.
خروجی نهایی
فایل outputs/skill-claude-agent-scaffold.md یک پروژه‌ی کامل مبتنی بر Claude Agent SDK می‌سازد که شامل سابایجنتها، هوک‌ها، ذخیره‌ساز نشست، اتصال به سرور MCP و انتشار ردگیری محاسبات W3C است.
تمرین‌ها
- یک سازنده‌ی ساب‌ایجنت اضافه کنید که 20 تسک را در دسته‌های 5تایی از ساب‌ایجنت‌های موازی اجرا کند. اندازه‌ی بافتار هماهنگکننده را در مقایسه با حالت «یک ساب‌ایجنت به ازای هر تسک» بسنجید.
- یک هوک
PreToolUseبنویسید که نرخ فراخوانیwrite_fileرا محدود کند (5 بار در دقیقه برای هر نشست). رفتار سیستم را ردگیری کنید. - متد
list_subkeysرا طوری به کار بگیرید که درخت سابایجنتها را نمایش دهد. در ساختارهای به‌شدت تودرتو این درخت چه شکلی پیدا می‌کند؟ - کد این پیاده‌سازی ساده را به بسته‌ی پایتونی واقعی
claude-agent-sdkمنتقل کنید. ثبت ابزارها چه تفاوتی می‌کند؟ - مستندات Claude Managed Agents را بخوانید. در چه شرایطی از حالت میزبانی شخصی (self-hosted) به سرویس مدیریت‌شده مهاجرت می‌کنید؟
اصطلاحات کلیدی
| اصطلاح | در گفت‌وگوهای عامیانه | معنای دقیق فنی |
|---|---|---|
| Agent SDK | «Claude Code در قالب یک کتابخانه» | ساختار بستر آزمایشی: ابزارها، MCP، هوک‌ها، سابایجنتها و ذخیره‌ساز نشست |
| Subagent | «ایجنت فرزند» | بافتار جداگانه و سهمیه‌ی مصرف مجزا؛ نتایج به سطح بالا برمی‌گردند |
| Session store | «دیتابیس گفت‌وگو» | ذخیره، بازیابی، فهرست‌کردن و حذف نوبت‌های گفت‌وگو همراه با حذف آبشاری سابایجنتها |
| Hook | «کال‌بک‌های چرخه‌ی حیات» | توابعی برای قبل/بعد از فراخوانی ابزار، نشست، ارسال پرامپت، فشرده‌سازی و توقف |
| W3C trace context | «ردگیری محاسبات بین‌پردازه‌ای» | انتشار اسپن والد به زیرپردازه‌ی خط فرمان |
| Managed Agents | «بستر آزمایشی میزبانی‌شده» | اجرای کارهای ناهمگام و طولانی‌مدت به میزبانی Anthropic |
--session-mirror |
«آینه‌ی متن گفت‌وگو» | ثبت نوبت‌های گفت‌وگو در فایلی خارجی همزمان با استریم شدن |
| MCP server | «محیط ابزارها» | منبع ابزار یا داده‌ی خارجی متصل به ایجنت |
برای مطالعه‌ی بیشتر
- مروری بر Claude Agent SDK — فرم کتابخانه‌ای Claude Code
- مقاله وبلاگ Anthropic: ساخت ایجنت‌ها با Claude Agent SDK — الگوهای سطح تولید
- مروری بر Claude Managed Agents — گزینه‌ی میزبانی‌شده
- مستندات OpenAI Agents SDK — همتای این بستر در اکوسیستم OpenAI