اجرای یک گراف در LangGraph با هشت حالت، در دو نسخهی چانک و از طریق یک پروتکل رویداد بتا (beta) استریم میشود که تکتک آنها در
langgraphنسخه 1.2.22 ساختار مشخص و ثابتی دارند.
تمام ردیفهای این صفحه مستقیماً از کدهای langgraph نسخه 1.2.22 یا از لاگهای ضبطشدهی یک اجرای واقعی ایجنت استخراج شدهاند. در این اجرا، ایجنت دو فراخوانی مدل و یک فراخوانی ابزار انجام میدهد. در بخش 5.1 توضیح دادهایم که چه زمانی باید از هر حالت استفاده کنید.
حالتهای استریم
تایپ StreamMode هفت حالت را فهرست میکند {{code libs/langgraph/langgraph/types.py:132-134}}. حلقهی اجرا حالت tools را هم میپذیرد، هرچند این مورد در تعریف تایپ نیامده است {{code libs/langgraph/langgraph/pregel/main.py:2949-2950}}. در جدول ثبت مغایرتها در صفحهی منابع، این مورد با شناسه D4 ثبت شده است.
| حالت | ساختار یک چانک در v1 | تعداد چانکها در اجرای ما | فایل لاگ |
|---|---|---|---|
values |
کل وضعیت (state) پس از هر مرحله | 4 | 21-stream-updates-values.txt |
updates |
دیکشنری از نام گره به تغییراتی که گره برگردانده | 3 | 21-stream-updates-values.txt |
messages |
یک تاپل شامل چانک پیام و یک دیکشنری متادیتا | 13 | 22-stream-messages.txt |
custom |
مقداری که گره یا ابزار به stream_writer فرستاده |
0 (چون هیچ ابزاری مقداری نفرستاد) | 23-stream-tasks-custom-debug.txt |
tasks |
شروع وظیفه با id، name، input و triggers، یا نتیجهی وظیفه با error و result |
6 | 23-stream-tasks-custom-debug.txt |
debug |
دیکشنری شامل step، timestamp، فیلد type با مقادیر checkpoint، task یا task_result، و payload |
6 (بدون چکپوینتر) | 23-stream-tasks-custom-debug.txt |
checkpoints |
چکپوینت به همان شکل خروجی get_state |
در پکیج وجود ندارد | ندارد |
tools |
رویداد مربوط به ابزار، طبق جدول زیر | 4 (روی ایجنت slow_sum) |
26-stream-tools-mode.txt |
گرافی که با create_agent ساخته میشود، اگر حالتی برایش تعیین نکنید، بهطور خودکار updates را استریم میکند {{code libs/langgraph/langgraph/graph/state.py:1357}}. یک شیء معمولی Pregel حالت values را استریم میکند {{code libs/langgraph/langgraph/pregel/main.py:715}}. درون یک گراف دیگر هم اگر گرافی بدون تعیین حالت اجرا شود، values را استریم میکند {{code libs/langgraph/langgraph/pregel/main.py:2850-2857}}.
متادیتای هر چانک در حالت messages کلیدهایی مثل langgraph_node، langgraph_step، langgraph_triggers، ls_provider و ls_model_type را در خود دارد. با خواندن langgraph_node میتوانید مدلِ خودِ ایجنت را از مدلی که درون یک ابزار فراخوانی شده تشخیص دهید.
ساختار چانک در نسخه v1
| نوع فراخوانی | خروجی stream |
|---|---|
| یک حالت تکی | خودِ چانک |
| فهرستی از حالتها | یک تاپل بهصورت (mode, chunk) |
یک حالت همراه با subgraphs=True |
یک تاپل بهصورت (namespace, chunk) |
فهرستی از حالتها همراه با subgraphs=True |
یک تاپل بهصورت (namespace, mode, chunk) |
ساختار StreamPart در نسخه v2
وقتی از version="v2" استفاده میکنید، فارغ از اینکه چه حالتهایی خواسته باشید، هر چانک در قالب یک TypedDict با کلیدهای type، ns و data دریافت میشود. مقدار v2 از نسخهی 1.1.0 به langgraph اضافه شد.
| تایپ | مقدار type |
خط در types.py |
|---|---|---|
ValuesStreamPart |
values |
274 |
UpdatesStreamPart |
updates |
286 |
MessagesStreamPart |
messages |
298 |
CustomStreamPart |
custom |
311 |
CheckpointStreamPart |
checkpoints |
322 |
TasksStreamPart |
tasks |
330 |
DebugStreamPart |
debug |
345 |
{{code libs/langgraph/langgraph/types.py:274-379}}
فراخوانی invoke(..., version="v2") خروجی را در قالب شیء GraphOutput با دو فیلد value و interrupts برمیگرداند {{code libs/langgraph/langgraph/types.py:381-421}}. دسترسی به آن مثل یک دیکشنری همچنان کار میکند، اما همانطور که لاگ 24-stream-v2.txt نشان میدهد، اخطار LangGraphDeprecatedSinceV11 صادر میشود.
رویدادهای ابزار
حالت tools برای هر رویدادِ ابزار یک دیکشنری خروجی میدهد. کلید event نوع آن را مشخص میکند:
event |
سایر کلیدها | در اجرای ما |
|---|---|---|
tool-started |
tool_call_id، tool_name، input |
1 |
tool-output-delta |
tool_call_id، delta |
2 (از runtime.emit_output_delta) |
tool-finished |
tool_call_id، output، شیء ToolMessage |
1 |
tool-error |
طبق پروتکل تعریف میشود | 0 |
{{code libs/prebuilt/langgraph/prebuilt/tool_node.py:1766}} {{code langchain_protocol/protocol.py:518-534}}
رویدادهای stream_events در نسخه v3
متد stream_events بهطور پیشفرض از version="v2" استفاده میکند و باید صراحتاً v3 را مشخص کنید {{code libs/langgraph/langgraph/pregel/main.py:3751-3758}}. نسخه v3 آزمایشی (beta) است و هشدار LangChainBetaWarning: The v3 streaming protocol on Pregel is experimental. را صادر میکند {{code libs/langgraph/langgraph/pregel/main.py:3617}}. این متد یک شیء GraphRunStream برمیگرداند؛ طبق لاگ 25-stream-events-v3.txt، اعضای عمومی آن عبارتند از: abort، extensions، interleave، interrupted، interrupts، lifecycle، messages، output، subagents، subgraphs، tool_calls و values.
| قاعده | محل در کد |
|---|---|
فرستادن stream_mode و subgraphs در نسخه v3 خطای TypeError میدهد. |
{{code libs/langgraph/langgraph/pregel/main.py:395-400}} |
اجرای همگام (sync) متد stream_events در نسخههای v1 یا v2 خطای NotImplementedError میدهد. برای این نسخهها از astream_events استفاده کنید. |
{{code libs/core/langchain_core/runnables/base.py:1818}} |
ساختار رویدادها در این بسته آموزشی روی نسخهی 0.0.21 از langchain-protocol فیکس شده است. |
capture/requirements.txt |
هر رویداد خام در قالب یک فریم است؛ با type از نوع event، یک method، بخش params (شامل namespace، timestamp و data) و یک شمارهی توالی (seq). اجرای نمونهی ما 23 فریم تولید کرد: 4 فریم values، 17 فریم messages و 2 فریم tools.
method |
محتوای data |
خط در protocol.py |
|---|---|---|
lifecycle |
وضعیت گراف یا سابایجنت: started، running، completed، failed یا interrupted |
269، 462 |
messages |
رویداد پیام و متادیتای آن | 273 |
tools |
رویداد ابزار | 277 |
input.requested، input.answered |
یک وقفه (interrupt) و پاسخ آن | 281، 285 |
values، updates، checkpoints، custom، tasks |
دادههای حالت متناظرِ همان نام در نسخهی v1 | 289 تا 305 |
{{code langchain_protocol/protocol.py:269-306}}
یک فریم messages، برای هر پیام مدل یکی از رویدادهای زیر را در خود دارد:
| رویداد | کلیدها | در اجرای ما |
|---|---|---|
message-start |
role، id |
2 |
content-block-start |
index، content |
2 |
content-block-delta |
index، delta؛ مانند {"type": "text-delta", "text": "The"} |
9 (شامل 8 مورد text-delta و 1 مورد tool-call-delta) |
content-block-finish |
index، content، کل بلوک |
2 |
message-finish |
در اجرای ما کلیدی نداشت | 2 |
error |
طبق پروتکل تعریف میشود | 0 |
{{code langchain_protocol/protocol.py:470-495}}
سرویسدهندهای که آرگومانهای فراخوانی ابزار را استریم میکند، دلتاهای tool-call-delta میفرستد {{code langchain_protocol/protocol.py:177}}. مدل ChatOllama کل فراخوانی را یکجا در یک چانک و قبل از چانک آخر ارسال میکند. بنابراین اجرای v3 در این بسته، تنها یک رویداد tool-call-delta دارد که کل دادههای فراخوانی را در بر میگیرد.
منابع: libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/pregel/main.py و libs/langgraph/langgraph/graph/state.py در langgraph نسخه 1.2.22؛ libs/prebuilt/langgraph/prebuilt/tool_node.py در langgraph-prebuilt نسخه 1.1.2؛ libs/core/langchain_core/runnables/base.py در langchain-core نسخه 1.8.0؛ langchain_protocol/protocol.py در langchain-protocol نسخه 0.0.21؛ capture/requirements.txt، capture/README.md، capture/out/21-stream-updates-values.txt، capture/out/22-stream-messages.txt، capture/out/23-stream-tasks-custom-debug.txt، capture/out/24-stream-v2.txt، capture/out/25-stream-events-v3.txt، capture/out/25-stream-events-v3.events.json و capture/out/26-stream-tools-mode.txt.