چیت‌شیت

برنامه‌ریزی ایجنت: جریان‌های کاری، HTN و برنامه‌ریزی و اجرا

Agent Planning: Workflows, HTN, Plan-Execute

انتخاب یک جریان کاری، یک برنامه‌ریز HTN یا تکاملی، یا مجری با قابلیت بازبرنامه‌ریزی. استفاده از کتابخانه‌ی استاندارد Python در درس‌ها.

  • ۱۲ بخش
  • ۴ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. انتخاب یک برنامه‌ریز
  2. پنج الگوی جریان کاری در کد
  3. مجری برنامه‌ریزی و اجرا
  4. موج‌های برنامه‌ی مبتنی بر شواهد
  5. اجرای یک ایجنت با قابلیت بازبرنامه‌ریزی
  6. برنامه‌ریز HTN با طرح پشتیبانِ مدل زبانی
  7. اصطلاحات برنامه‌ریزی
  8. مقادیر پیش‌فرض
  9. خرابی‌ها و راه‌حل‌ها
  10. دستورها
  11. پرسش‌ها
  12. نکات

انتخاب یک برنامه‌ریز

مقایسه
فاکتورWorkflowHTN + ChatHTNAlphaEvolveReAct / ReWOO
تصمیم‌گیرندهمهندسانلایه‌ی نمادینانتخاب توسط ارزیابمدل
تضمینتعداد گام‌های محدودصحت قابل‌اثباتبهترین برنامه بر اساس برازشفاقد تضمین‌های رسمی
نیازمندی‌هاگام‌های قابل‌شمارشاسکیمای عملگرهابرازش قابل‌ارزیابی با ماشینمدل زبانی در چرخه (LLM in the loop)
کاربرد مناسبقابل‌پیش‌بینی، ملزم به انطباقزمان‌بندی، وابسته به خط‌مشیبهینه‌سازی کامپایلرپژوهش‌های باز و نامحدود
نقش مدل زبانیفراخوانی در مسیرهای کد ثابتتجزیه‌ی وظیفه در طرح پشتیبانپیشنهاد جهش‌هاانتخاب تک‌تک گام‌ها

پنج الگوی جریان کاری در کد

کار و کد
وظیفهکد
زنجیره‌سازی پرامپت: خروجی N ورودی N+1 استprompt_chain(input_text, llm, steps)
مسیریابی: طبقه‌بندی و سپس توزیعroute(input_text, classifier, handlers)
موازی‌سازی: N اجرا، رأی اکثریتparallel_vote(prompt, llm, n=5)
هماهنگ‌کننده-کارگرها: انتخاب متخصصانorchestrator_workers(task, workers, synth)
ارزیاب-بهینه‌ساز: تکرار حلقه تا PASSevaluator_optimizer(task, proposer, evaluator, max_iter=5)
برچسب مسیریابی ناشناخته`handlers.get("default")` gives "escalate to human"
اجرای هر پنج دموpython3 code/main.py

مجری برنامه‌ریزی و اجرا

گام‌به‌گام
  1. برنامه‌ریزتابع planner(goal, history, None) اولین برنامه را برمی‌گرداند. رویداد plan.commit.
  2. مجریگام plan[cursor] را از طریق توزیع‌کننده‌ی وظایف اجرا می‌کند. رویدادهای step.start و step.end.
  3. مجریدر صورت موفقیت، نتیجه به تاریخچه افزوده شده و مکان‌نما به گام بعدی منتقل می‌شود.
  4. مجریدر صورت بروز استثنا، step.error را ذخیره و مقدار last_error را تعیین می‌کند.
  5. بررسی سقف بودجهشرط replans_used >= self.max_replans منجر به شکست با وضعیت replan_budget می‌شود.
  6. برنامه‌ریزفراخوانی planner(goal, history, last_error) یک برنامه‌ی جدید ارائه می‌دهد. رویداد plan.draft.
  7. مجریرویداد plan.diff را ارسال، برنامه‌ی جدید را commit و مقدار cursor = 0 را تنظیم می‌کند.
  8. مجریآخرین گام با موفقیت به پایان می‌رسد. رویداد session.complete همراه با goal_met.

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

معماری
depends_ondepends_onقراردادموج 1، بازبینی قراردادپیاده‌سازیموج 2، unittestمستنداتموج 2، check_links.pyیکپارچه‌سازیموج 3، گیت پذیرش

اجرای یک ایجنت با قابلیت بازبرنامه‌ریزی

کد
python
agent = PlanExecuteAgent(
    planner=make_deterministic_planner(fail_step_id=2, recovery="route_around"),
    executor=executor,            # تابع (tool_name, args) -> result، بروز خطای ToolFailure
    max_steps=12, max_replans=5,  # هر دو بودجه قطعی هستند
)
res = agent.run("ship the report")
res.status, res.reason            # وضعیت‌های "completed" و "goal_met"
res.revisions                     # لیستی از PlanDiff
r.to_dict()                       # مقادیر revision، removed، added و revised
Step(2, "transform", {"mode": "v2"}, "computed via fallback")

برنامه‌ریز HTN با طرح پشتیبانِ مدل زبانی

کد
python
op = Operator("open_editor", ("logged_in",), ("editor_open",))
m = Method("ship_change_m1", "ship_change", ("logged_in",),
           ("open_editor", "write_tests", "run_tests", "open_pr"))
planner = HTNPlanner(operators=operators, methods=methods, llm=llm)
plan = planner.plan("ship_change", {"logged_in"})  # لیستی از عملگرها یا None
planner.cached_methods                             # تجزیه‌های مدل زبانی برای فراخوانی بعدی نگهداری می‌شوند
planner.llm.calls                                  # 0 فراخوانی جدید در صورت اصابت به کش (cache hit)

اصطلاحات برنامه‌ریزی

مفهوم‌ها
عملگر (Operator)
جزء سازنده‌ی اقدام همراه با پیش‌شرط‌ها و اثرات.
روش (Method)
شیوه‌ای برای شکستن یک وظیفه‌ی مرکب به زیروظایف، همراه با پیش‌شرط‌ها.
ChatHTN
برنامه‌ریز نمادین در صورت عدم تطابق هیچ روشی، از مدل زبانی راهنمایی می‌خواهد.
تابع برازش (Fitness Function)
امتیازی قطعی و قابل‌ارزیابی با ماشین روی خروجی‌ها.
مدل زبانی تقویت‌شده (Augmented LLM)
مدل زبانی به اضافه‌ی جستجو، ابزارها و حافظه؛ کوچک‌ترین واحد مستقل.
expected_outcome
شرط موفقیتِ برنامه‌ریز که مجری آن را الزام‌آور نمی‌داند.
بازبرنامه‌ریزی (Replan)
سپردن خطا به برنامه‌ریز؛ این کار یک اسکریپت ساده را به ایجنت تبدیل می‌کند.

مقادیر پیش‌فرض

پیش‌فرض‌ها
تنظیمپیش‌فرضیادداشت
max_steps12تمام دفعات اجرای گام‌ها، شامل بازبرنامه‌ریزی‌ها
max_replans5فراخوانی‌های برنامه‌ریز پس از برنامه‌ی نخست
max_depth12حد بازگشت HTN و سپس مقدار None
max_iter5دورهای ارزیاب-بهینه‌ساز
n5رأی‌دهندگان در تابع parallel_vote
generations12دموی تکاملی، نگهداری 3 مورد برتر از 6 مورد

خرابی‌ها و راه‌حل‌ها

عیب‌یابی
  • خطای failed با دلیل replan_budget

    علت
    برنامه‌ریز همان برنامه‌ی معیوب را تکرار می‌کند
    راه‌حل
    ارسال مقدار last_error و تغییر مسیر برای دور زدن آن
  • خطای failed با دلیل step_budget

    علت
    بازبرنامه‌ریزی‌ها گام‌هایی فراتر از max_steps اضافه می‌کنند
    راه‌حل
    تولید برنامه‌های کوتاه‌تر یا بازاستفاده از تاریخچه
  • خطای failed با دلیل no_plan

    علت
    برنامه‌ریز مقدار [] را بازگردانده است
    راه‌حل
    افزودن برنامه‌ی بازیابی اختصاصی برای آن خطا
  • dependency cycle among:

    علت
    آیتم‌ها معطل یکدیگر مانده‌اند
    راه‌حل
    حل تناقض یا بن‌بست زمینه‌ای میان آن‌ها
  • has no repository evidence

    علت
    آیتم فاقد مقدار در فیلد evidence است
    راه‌حل
    ارجاع به یک فکت یا داده‌ی معتبر در مخزن
  • has no proof command

    علت
    فیلد proof خالی است
    راه‌حل
    تعریف دقیق یک دستور بررسی
  • فروپاشی صحت HTN

    علت
    نبود اسکیمای پیش‌شرط/اثر
    راه‌حل
    اعتبارسنجی خروجی مدل زبانی در برابر عملگرها
  • عدم همگرایی روند تکاملی

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

دستورها

دستورها
دستورکاربرد
python3 code/main.pyاجرای دموی درس و چاپ ردگیری محاسبات
python3 -m unittest discover code/tests -vاجرای تست‌های برنامه‌ی شواهد
outputs/evidence-plan.jsonنوشته‌شده در درس 44، با وضعیت ready یا blocked

پرسش‌ها

پرسش و پاسخ
جریان کاری یا ایجنت؟
جریان کاری زمانی که گام‌ها قابل‌شمارش باشند؛ ایجنت زمانی که گام بعدی به نتیجه‌ی قبلی وابسته باشد.
چرا سقف‌گذاری برای بازبرنامه‌ریزی و گام‌ها؟
تعیین سقف باعث می‌شود فرآیند، سریع‌تر و با دلیلی روشن‌تر با شکست مواجه شود.
چرا ChatHTN از نظر درستی تضمین‌شده است؟
خروجی مدل زبانی تنها در قالب کاندیداهای تجزیه‌ی وظیفه پذیرفته می‌شود و اسکیما موارد نامعتبر را رد می‌کند.
کدام گام‌ها هم‌زمان اجرا می‌شوند؟
گام‌های واقع در یک موج یکسان؛ یکپارچه‌سازی منتظر اتمام هر دو branch می‌ماند.

نکات

نکته‌ها
  • کار را با فراخوانی مستقیم API آغاز کنید؛ پیش از HTN، از ReAct یا ReWOO استفاده کنید.
  • قرارداد را پیش از پیاده‌سازی‌های آن تعیین کنید.
  • برای هر وظیفه کاری یک شناسه، تغییر، شواهد، وابستگی‌ها و اثبات مشخص کنید.
  • در هر بازنگری، تفاوت برنامه (plan diff) را ثبت کنید؛ برنامه را بدون ثبت رد تغییر ندهید.
  • برنامه را در کنار خود کار ذخیره کنید، نه در چک‌باکس‌های چت.