هر تابع
@entrypoint هنگام ازسرگیری، دوباره از ابتدا اجرا میشود؛ اما هر @task که پیش از توقف تمام شده باشد، بهجای اجرای مجدد، نتیجهی ذخیرهشدهی خود را برمیگرداند.
فرض کنید یک تابع معمولی پایتون دارید که سه سرویس را پشت سر هم صدا میزند. حالا میخواهید این تابع برای تایید یک فرد متوقف شود و در برابر ریاستارت شدن برنامه هم دوام بیاورد. اگر بخواهید آن را بهصورت گرهها و یالها بازنویسی کنید، کدی را که در حال حاضر کار میکند دستکاری کردهاید. رابط برنامهنویسی تابعی (functional API) ساختار تابع را دستنخورده نگه میدارد و فقط دور فراخوانیهای آن چکپوینت میگذارد.
پس از پایان این بخش، میتوانید یک تابع را به یک @entrypoint همراه با فراخوانیهای @task تبدیل کنید. همچنین میتوانید پیشبینی کنید که هنگام ازسرگیری کدام فراخوانیها دوباره اجرا میشوند و چطور مقداری را بین دفعات مختلف اجرا نگه دارید.
نقطهی ورود و وظایف آن
نقطهی ورود (Entrypoint): تابعی که با @entrypoint دکوریت شده است. LangGraph آن را مانند گرافی با یک گره تکی اجرا میکند و وقتی چکپوینتری به آن بدهید، چکپوینتها را روی رشتهی گفتوگویش (thread) ذخیره میسازد.
وظیفه (Task): تابعی مجهز به دکوراتور @task. فراخوانی آن بلافاصله یک فیوچر (future) برمیگرداند و LangGraph به محض پایان کار وظیفه، نتیجهاش را ذخیره میکند.
جریان کاری کیت، سه عدد را در دل سه وظیفه دو برابر میکند، آنها را با هم جمع میزند و از یک فرد میپرسد که مجموع نهایی را نگه دارد یا نه. این پرسش در قالب یک وقفه (interrupt) درون یک وظیفه قرار دارد:
@task
def double(x: int) -> int:
runs.append(f"double({x})")
return x * 2
@task
def ask_human(total: int) -> str:
return interrupt({"total": total, "question": "Keep it?"})
@entrypoint(checkpointer=InMemorySaver())
def workflow(numbers: list[int]) -> dict:
futures = [double(n) for n in numbers]
total = sum(f.result() for f in futures)
answer = ask_human(total).result()
return {"total": total, "answer": answer}هر سه فراخوانی double، هر سه وظیفه را پیش از رسیدن به اولین result() آغاز میکنند و هر result() منتظر پایان یکی از آنها میماند.
مستندات رابط تابعی سه قاعده برای این کد مشخص کرده است {{docs oss/python/langgraph/functional-api}}: نقطهی ورود فقط یک آرگومان موضعی (positional argument) میگیرد؛ اگر چکپوینتر تنظیم شده باشد، ورودی و خروجی نقطهی ورود و خروجی هر وظیفه باید قابلیت سریالسازی به JSON را داشته باشند؛ و وظیفه را فقط میتوان از داخل یک نقطهی ورود، وظیفهای دیگر، یا گرهای از یک گراف صدا زد.
توقف اجرای اول درون یک وظیفه
اجرای اول، اعداد 1، 2 و 3 را دو برابر کرد، به عدد 12 رسید و روی پرسش متوقف شد. فراخوانی invoke با آرگومان version="v2" مقدار خروجی و وقفهها را جدا از هم برمیگرداند:
{
"value": {},
"interrupts": [
{
"value": {
"total": 12,
"question": "Keep it?"
},
"id": "<hex-1>",
"response_schema": null
}
]
}
task runs:
[
"double(1)",
"double(2)",
"double(3)"
]مقدار خروجی خالی است، چون تابع چیزی برنگردانده و اجرای آن تمام نشده است.
ازسرگیری و بازیابی وظایف پایانیافته
ارسال Command(resume="yes") روی همان رشتهی گفتوگو، workflow را دوباره از خط اولش اجرا میکند. سه فراخوانی double نتایج ذخیرهشدهی خود را برمیگردانند و بدنهی double اصلاً اجرا نمیشود. تابع ask_human مقدار "yes" را از interrupt دریافت میکند و تابع به پایان میرسد:
{
"total": 12,
"answer": "yes"
}
task runs:
[
"double(1)",
"double(2)",
"double(3)"
]فهرست دفعات اجرای وظایف همچنان سه مورد دارد؛ مستندات نیز همین را میگوید. ازسرگیری از بالاترین نقطهی entrypoint شروع میشود و چکپوینتر نتایج وظایف پایانیافته را برمیگرداند {{docs oss/python/langgraph/functional-api}}. شکل هر دو اجرا را نشان میدهد.
کدی که مستقیماً در خود نقطهی ورود نوشته میشود وظیفه نیست؛ بنابراین همانطور که در مستندات آمده، در هر بار ازسرگیری دوباره اجرا خواهد شد. محاسبهی مجموع در کیت از همین جنس کدهاست، و کیت فقط دفعات اجرای وظایف را ثبت میکند. هر عملیاتی را که اثر جانبی (side effect) دارد درون یک وظیفه بگذارید تا ازسرگیری از نتایج ذخیرهشده پیش برود. کرش کردن برنامه پس از اعمال اثر و پیش از ذخیره شدن نتیجه میتواند باعث اجرای دوبارهی وظیفه شود. بنابراین اثر جانبی را هم بیاثر در تکرار (idempotent) طراحی کنید، همانطور که در بخش 5.3 نشان داده شده است.
استریم updates در یک اجرای جدید، برای هر وظیفهی پایانیافته یک تکهداده (chunk) تولید میکند که کلید آن نام وظیفه است. اجرا با ورودی [5] ابتدا تکهدادهی {"double": 10} و سپس تکهدادهی __interrupt__ را تحویل داد.
مقداری که روی رشتهی گفتوگو میماند
entrypoint.final: مقدار بازگشتی یک نقطهی ورود که خروجی تحویلدادهشده به فراخواننده را از آنچه روی رشتهی گفتوگو ذخیره میشود جدا میکند. مقدار ذخیرهشده، در اجرای بعدی بهعنوان آرگومان previous برمیگردد.
شمارندهی موجود در کیت، هر ورودی را با مجموع ذخیرهشده جمع میزند. این شمارنده یک جمله برمیگرداند و عدد را ذخیره میکند:
@entrypoint(checkpointer=InMemorySaver())
def counter(n: int, *, previous: int | None = None) -> entrypoint.final[int, int]:
total = (previous or 0) + n
return entrypoint.final(value=f"added {n} to {previous}, saved {total}", save=total)سه بار فراخوانی روی یک رشتهی گفتوگو با مقادیر 3، 4 و 5 چنین مقادیری را برگرداند:
three calls:
[
"added 3 to None, saved 3",
"added 4 to 3, saved 7",
"added 5 to 7, saved 12"
]نخستین فراخوانی، مقدار previous را برابر با None دریافت کرد. هر فراخوانی بعدی، عددی را گرفت که فراخوانی قبل از آن ذخیره کرده بود. نوع بازگشتی entrypoint.final[int, int] در کیت با مقدار رشتهای همخوانی ندارد، اما اجرا همچنان کار میکند؛ چون LangGraph آن را بررسی نمیکند.
یک گره، نه گرافی از گرهها
گراف این جریان کاری سه گره دارد: __start__، workflow و __end__. وظایف گره نیستند؛ بنابراین در رسم گراف هیچکدام از آنها دیده نمیشوند. مستندات رابط تابعی میگوید برای ایجنتها و جریانهای کاری جدید از رابط گرافی استفاده کنید. این مستندات، رابط تابعی را برای ایجنتی پیشنهاد میکند که از قبل در کدهای دیگر پیاده شده است و باید روی Agent Server اجرا شود {{docs oss/python/langgraph/functional-api}}.
شکل گراف را بر اساس متن Mermaid آن رسم میکند.
یک وظیفه همچنین میتواند retry_policy ،cache_policy و timeout بگیرد {{code libs/langgraph/langgraph/func/init.py}}. پارامتر timeout فقط روی وظایف ناهمگام (async) کار میکند و روی وظایف همگام (sync) خطای ValueError میدهد. کیت هنوز آنها را روی یک وظیفه اجرا نکرده است. خروجیهای ثبتشدهی آنها در ویرایش بعدی، همراه با دیگر موضوعات بازِ بخش 8.8 ارائه میشوند.
منابع: capture/s_graph.py، capture/out/35-functional-api.txt، capture/out/51-draw-functional.txt؛ libs/langgraph/langgraph/func/init.py در langgraph 1.2.22؛ docs.langchain.com در commit مستندات 04d4d4a (oss/python/langgraph/functional-api).