بخش 7.5 · اکوسیستم

یک دیپ ایجنت به‌همراه ساب‌ایجنت و فایل‌ها

A deep agent with a subagent and files

فهرست مطالب
  1. آنچه در این دمو ساخته می‌شود
  2. روند اجرای ثبت‌شده
  3. آنچه این اجرا نشان می‌دهد

یک دیپ ایجنت (Deep Agent) روی مدلی محلی، برنامه‌ریزی می‌کند، می‌نویسد و بازبینی را طی 7 فراخوانی مدل به ساب‌ایجنت می‌سپارد؛ اولین فراخوانی آن برای وظیفه‌ای کوتاه، 3,651 توکن پرامپت ارسال می‌کند.

شاید ایجنتی بخواهید که پیش‌نویس سندی را بنویسد، از ایجنت دوم بخواهد آن را بازبینی کند و سپس اصلاحات را اعمال نماید. Deep Agents ابزارهای فایل، ابزار task و ساب‌ایجنت‌ها (Subagent) را یک‌جا در اختیارتان می‌گذارد. با این حال، همچنان باید بدانید هر فراخوانی چقدر هزینه دارد و کدام بخش از یک نتیجه‌ی نامطلوب ناشی از خود مدل بوده است.

پس از پایان این بخش، می‌توانید یک دیپ ایجنت با یک ساب‌ایجنت را روی مدلی محلی بسازید. همچنین می‌توانید توکن‌های هر فراخوانی مدل را ثبت کنید و اجرای برنامه را فراخوانی‌به‌فراخوانی بخوانید.

آنچه در این دمو ساخته می‌شود

کد متعلق به خود ماست. این کد از نسخه‌ی 0.7.38 بسته‌ی deepagents در کنار ChatOllama و Qwen3 8B با دمای (temperature) 0، مقدار seed برابر با 42 و با استدلال خاموش (reasoning off) استفاده می‌کند.

این دمو بک‌اند (backend) پیش‌فرض را حفظ می‌کند که فایل‌ها را در وضعیت (state) ایجنت نگه می‌دارد؛ بنابراین می‌توانید تک‌تک فراخوانی‌ها را بخوانید. در مجموعه‌وظایف بخش 1.2، این پیکربندی در وظایف کار با فایل و بازیابی (Retrieval) روی مدل‌های Qwen3 4B و 8B از یک حلقه‌ی ساده شکست خورد. وقتی کار با فایل‌های واقعی سر و کار دارد، همان‌طور که بخش 7.4 نشان می‌دهد، FilesystemBackend را ارسال کنید.

این دمو این بخش‌ها را به کار می‌گیرد:

ایجنت یک ساب‌ایجنت به نام editor دارد. ساب‌ایجنت یک دیکشنری شامل یک نام، توضیحی که ایجنت اصلی آن را می‌خواند، و پرامپت سیستمی اختصاصی خودش است:

ایجنت عمیق و ویرایشگر آن capture/demos/deep-agent/deep_agent.py
    agent = create_deep_agent(
        model=model,
        system_prompt="You write clear technical documents. Keep the files you write in /notes/.",
        subagents=[{**EDITOR, "model": model}],
        middleware=[TodoListMiddleware()],
        checkpointer=InMemorySaver(),
    )

وظیفه، یادداشت‌های انتشار (release notes) برای سه تغییر، بازبینی توسط ویراستار، اصلاحات و متن نهایی را می‌خواهد. پرامپت سیستمی ویراستار جملات بالای 25 کلمه و جملات مجهول را مطالبه می‌کند. ویراستار اصلاحات را برمی‌گرداند و خودش چیزی را ویرایش نمی‌کند.

یک کال‌بک (callback) هر فراخوانی مدل را ثبت می‌کند. این کال‌بک مقدار usage_metadata را از پاسخ و lc_agent_name را از متادیتای فراخوانی می‌خواند. Deep Agents این نام را برای ساب‌ایجنت روی editor تنظیم می‌کند؛ بنابراین کال‌بک می‌تواند این دو ایجنت را از یکدیگر تشخیص دهد.

روند اجرای ثبت‌شده

اجرا شامل 7 فراخوانی مدل در 62.0 ثانیه بود. فراخوانی اول 22.6 ثانیه طول کشید که شامل بارگذاری مدل در Ollama هم می‌شود:

هفت فراخوانی مدل capture/lab/deep-agent/run.log
  call  1  main    in  3651  out  120   22.6 s  -> write_todos
  call  2  main    in  3872  out  124    6.7 s  -> write_file
  call  3  main    in  4016  out   58    3.2 s  -> task
  call  4  editor  in  1977  out   27    8.4 s  -> read_file
  call  5  editor  in  2113  out  143    7.4 s  -> answer
  call  6  main    in  4225  out  104    6.3 s  -> write_todos
  call  7  main    in  4446  out  111    7.4 s  -> answer

ایجنت اصلی یک فهرست وظایف (todo list) نوشت، فایل /notes/release-2.0.md را ایجاد کرد و task را فراخواند. ویراستار فایل را خواند و پاسخ داد. سپس ایجنت اصلی وظایف خود را تیک زد و متن فایل را در پاسخ برگرداند. این ایجنت هرگز edit_file را صدا نزد، چون ویراستار هیچ موردی برای اصلاح برنگردانده بود:

آنچه ویرایشگر بازگرداند capture/lab/deep-agent/run.log
  result    task: The file `/notes/release-2.0.md` has been read successfully. Here is the content: ``` ## Version 2.0 Release Notes The sync command now resumes an interrupted upload from the last finished part, ensuring seamless continuity for large file transfers. … ``` No sentences in this file exceed 25 words, and there are no sentences in passive voice. Therefore, no fixes or improvements are needed.

نسخه فایل داخل پاسخ در محل علامت‌گذاری برش خورده است.

فایلی که در این اجرا نوشته شد، شامل دو جمله‌ی مجهول است:

دو جمله از فایل نهایی capture/lab/deep-agent/run.log
The config file has been moved from ~/.tool.toml to the XDG config folder. The old path still works for one release, ensuring backward compatibility during the transition.

The --verbose flag has been removed. Use --log-level debug in its place for detailed logging and debugging information.

آنچه این اجرا نشان می‌دهد

ما نتیجه را اندازه گرفتیم: یک بار اجرا روی Mac، پردازنده‌ی Apple M1 Max با 10 هسته، 64 گیگابایت حافظه و Ollama 0.31.1. ایجنت اصلی 5 فراخوانی مدل با 20,210 توکن پرامپت انجام داد. ویراستار 2 فراخوانی با 4,090 توکن پرامپت داشت. این دو در مجموع برای فایلی با 458 کاراکتر، 24,300 توکن پرامپت فرستادند و 687 توکن خروجی گرفتند. تصویر تک‌تک فراخوانی‌ها را نشان می‌دهد.

توکن‌های پرامپت در هر فراخوانی مدل ایجنت عمیقهر فراخوانی ایجنت اصلی بیش از 3,600 توکن پرامپت ارسال کرد، و فراخوانی‌های ویرایشگر با دو ابزار کمتر، حدود نصف این مقدار ارسال کردند.
توکن‌های پرامپت هر فراخوانی مدل ایجنت عمیق نمودار نقطه‌ای توکن‌های پرامپت مربوط به 7 فراخوانی مدل در یک بار اجرای ایجنت عمیق روی Mac با Qwen3 8B. ایجنت اصلی 5 فراخوانی با مقادیر 3651، 3872، 4016، 4225 و 4446 توکن، در مجموع 20210 توکن، همراه با 9 ابزار متصل انجام داد. ساب‌ایجنت ویرایشگر 2 فراخوانی با 1977 و 2113 توکن، در مجموع 4090 توکن، با 7 ابزار متصل داشت. 0 1k 2k 3k 4k 5k 1 2 3 4 5 6 7 فراخوانی مدل، به ترتیب اجرا توکن‌های پرامپت فراخوانی 3651 write_todos 3872 write_file 4016 task 1977 read_file 2113 answer 4225 write_todos 4446 answer ایجنت اصلی: 5 فراخوانی، 20210 توکن ساب‌ایجنت ویرایشگر: 2 فراخوانی، 4090 توکن برچسب روی محور، ابزاری است که فراخوانی درخواست کرده بود. فراخوانی‌های 4 و 5 درون ابزار task با 7 ابزار به‌جای 9 ابزار اجرا شدند.
هر نقطه نشان‌دهنده یک فراخوانی مدل در یک بار اجرا روی Mac با مدل Qwen3 8B است. نقاط آبی ایجنت اصلی و نقاط نیلی ویرایشگر هستند. برچسب روی محور، ابزاری است که فراخوانی درخواست کرده بود. برگرفته از capture/lab/summary/demos-mac.json.

اولین فراخوانی ایجنت اصلی برای وظیفه‌ای در حدود 100 کلمه، 3,651 توکن فرستاد. بیشتر این مقدار ناشی از بستر آزمایشی (harness) است: پرامپت سیستمی Deep Agents و اسکیماهای 9 ابزار. بخش 7.4 هزینه‌ی اضافی بستر آزمایشی را روی Qwen3 8B بین 2,075 تا 2,251 توکن در هر فراخوانی برآورد کرد. در هر فراخوانی بعدی، پیام‌های اجرای برنامه هم روی آن اضافه می‌شوند.

ویراستار 7 ابزار در اختیار داشت: ابزارهای فایل، بدون task و write_todos. پیام‌های آن شامل پرامپت سیستمی خودش و شرح وظیفه از سوی ایجنت اصلی بود؛ بنابراین حجم فراخوانی‌هایش تقریباً نصف شد. ساب‌ایجنت راهکاری برای دور نگه داشتن یک وظیفه‌ی جانبی و طولانی از زمینه‌ی (context) ایجنت اصلی است.

شکست بازبینی، ناشی از خروجی خود مدل است. ویراستار دو جمله‌ی مجهول را ندید و ایجنت اصلی هم به بازبینی اعتماد کرد. LangChain تک‌تک گام‌های خواسته‌شده از سوی مدل را اجرا کرد: نوشتن فایل، فراخوانی task، خواندن، و به‌روزرسانی فهرست وظایف. مدلی قوی‌تر، یا بررسی جملات مجهول در سطح کد، می‌توانست نتیجه را تغییر دهد. اولی به انتخاب مدل برمی‌گردد و دومی ابزاری است که خودتان می‌نویسید.

منابع: capture/demos/deep-agent/deep_agent.py، capture/demos/deep-agent/run.sh، capture/demos/deep-agent/README.md؛ capture/lab/deep-agent/run.log، capture/lab/deep-agent/run.jsonl، capture/lab/summary/demos-mac.json؛ libs/deepagents/deepagents/graph.py و libs/deepagents/deepagents/middleware/subagents.py در نسخه‌ی deepagents 0.7.38؛ libs/langchain_v1/langchain/agents/factory.py در نسخه‌ی langchain==1.5.0.

ترجمه‌ی فارسی A deep agent with a subagent and files از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما