تابع
create_agentیک گراف LangGraph را با یک نودmodel، در صورت وجود ابزارها یک نودtools، و به ازای هر هوک میدلور (middleware hook) یک نود، با محدودیت بازگشت 9999 کامپایل میکند.
یک مدل، دو ابزار و یک پرامپت به create_agent میدهید و در خروجی شیئی با متدهای invoke و stream دریافت میکنید. در ظاهر شبیه یک دستیار چت معمولی است؛ اما در اصل یک گراف کامپایلشدهی LangGraph است و هر خطا، تکهی استریم و چکپوینت ایجنت، نام یکی از نودهای همین گراف را نشان میدهد.
پس از پایان این بخش، متوجه میشوید هر آرگومان create_agent کدام نود را اضافه میکند و حلقهی میان آنها کِی متوقف میشود. همچنین میتوانید مقادیر پیشفرض گراف کامپایلشده را بخوانید و بگویید لایهی ایجنت چقدر هزینه دارد.
ورودیهای create_agent
create_agent: تابعی در langchain.agents که یک مدل، ابزارها، پرامپت و میدلور را به CompiledStateGraph تبدیل میکند.
امضای این تابع در نسخهی پینشده، دو پارامتر موضعی و سیزده پارامتر کلیدواژهای دارد {{code libs/langchain_v1/langchain/agents/factory.py}}. جدول زیر مشخص میکند هر پارامتر چه تغییری در گراف به وجود میآورد:
| پارامتر | مقدار پیشفرض | تغییر ایجادشده |
|---|---|---|
model |
اجباری | مقدار رشتهای از init_chat_model رد میشود. مدل از نود model فراخوانی میشود. |
tools |
None |
توابع و اشیای BaseTool در نود tools اجرا میشوند. دیکشنری (dict) یک ابزار ارائهدهنده (provider tool) است که به مدل بایند میشود و خود گراف هرگز آن را اجرا نمیکند. |
system_prompt |
None |
رشته به یک SystemMessage تبدیل میشود. این پیام در هر فراخوانی مدل پیش از سایر پیامها قرار میگیرد و وارد وضعیت (state) نمیشود. |
middleware |
() |
هر هوک از هر میدلور به یک نود یا یک پوششدهنده (wrapper) تبدیل میشود. میدلور میتواند ابزارها و کلیدهای وضعیت جدیدی هم بیفزاید. |
response_format |
None |
یک اسکیما، یک ابزار خروجی ساختاریافته (structured output) یا قالبی از ارائهدهنده اضافه میکند. بخش 4.2 هر دو را توضیح میدهد. |
state_schema، context_schema |
None |
نوع دادهی وضعیت و نوع دادهی context برای هر بار اجرا. |
checkpointer، store |
None |
وضعیت ذخیرهشده به ازای هر ترد (thread) و حافظهی بلندمدت. بخش 5 به هر دو میپردازد. |
interrupt_before، interrupt_after |
None |
توقفهای ایستا قبل یا بعد از نودهای مشخصشده. |
name، debug، cache، transformers |
None، False، None، None |
نام گراف، خروجی دیباگ، کش نود و ترنسفورمرهای استریم. |
بخش 3.2 نشان میدهد نام رشتهایِ مدل چگونه پردازش و تعیین میشود. بخش 3.5 نیز دلیل ماندن پرامپت بیرون از وضعیت را بررسی میکند.
نودها
کیت، ایجنت بخش 1.3 را با یک ابزار و بدون میدلور میسازد. این گراف کامپایلشده چهار نود دارد:
[
"__start__",
"model",
"tools",
"__end__"
]نود tools تنها در صورتی وجود دارد که ایجنت ابزاری برای اجرا داشته باشد یا میدلوری با هوک wrap_tool_call تعریف شده باشد {{code libs/langchain_v1/langchain/agents/factory.py}}. بدون هیچ ابزاری، همان فراخوانی سه نود میسازد:
[
"__start__",
"model",
"__end__"
]میدلور نود اضافه میکند. هر هوک before_agent، before_model، after_model و after_agent به نودی تبدیل میشود که نامش برگرفته از نام میدلور و نام خود هوک است. کیت سه میدلور به نامهای A، B و C اضافه میکند که هرکدام تمامی این هوکها را دارند:
[
"__start__",
"model",
"tools",
"A.before_agent",
"A.before_model",
"A.after_model",
"A.after_agent",
…
"__end__"
]گرههای B و C حذف شدهاند. آنها از همان الگو پیروی میکنند.
هوکهای wrap_model_call و wrap_tool_call نودی اضافه نمیکنند؛ بلکه درون نود model و نود tools اجرا میشوند. بخش 4.5 ترتیب هر شش هوک را نشان میدهد. شکل مشخص میکند هر آرگومان کدام بخش از گراف را میسازد.
وضعیت
AgentState: نوع دادهی وضعیت در همهی ایجنتها، با کلیدهای messages، jump_to و structured_response.
کلید messages از کاهندهی add_messages بهره میبرد؛ بنابراین هر نود، پیامها را بر اساس id اضافه یا جایگزین میکند. کلید jump_to خصوصی است و تنها یک گام دوام دارد. میدلور آن را برای انتقال جریان اجرا به model، tools یا پایان تنظیم میکند. کلید structured_response فقط در خروجی میآید و هرگز در ورودی قرار نمیگیرد {{code libs/langchain_v1/langchain/agents/middleware/types.py}}. میدلور میتواند کلیدهای اختصاصی خودش را بیفزاید و در صورت تداخل، اولویت با state_schema ارسالی شماست.
حلقه و زمان توقف آن
یالهای بعد از model شرطی هستند:
[
"__start__ -> model",
"model -> __end__ (conditional)",
"model -> tools (conditional)",
"tools -> model (conditional)"
]تابع یال، وضعیت را پس از هر فراخوانی مدل به این ترتیب میخواند {{code libs/langchain_v1/langchain/agents/factory.py:1991-2042}}:
- مقدار
jump_toکه توسط میدلور تعیین شده باشد اولویت دارد. - نبود پیام AI در وضعیت، اجرا را خاتمه میدهد.
- یک پیام AI بدون هیچ فراخوانی ابزاری، اجرا را پایان میدهد.
- فراخوانیهای ابزاری که هنوز نتیجهای ندارند، هرکدام در قالب یک شیء
Sendمجزا بهtoolsفرستاده میشوند تا فراخوانیهای موازی بهصورت وظایف موازی اجرا شوند. - ثبت یک
structured_responseتازه، اجرا را خاتمه میدهد. - در غیر این صورت، اجرا به
modelبرمیگردد.
فراخوانی ابزار مربوط به خروجی ساختاریافته به tools فرستاده نمیشود؛ همانطور که در بخش 4.2 میبینید، نود model خودش آن را پردازش میکند. ایجنتی بدون ابزار و دارای ToolStrategy یا AutoStrategy، بهجای نود tools یک یال مستقیم از model به model دارد. این یال ابتدا jump_to و سپس ثبت یک structured_response جدید را بررسی میکند و در غیر این صورت حلقه میزند {{code libs/langchain_v1/langchain/agents/factory.py:2045-2068}}. اگر ابزاری تعریف نشده باشد و استراتژی ProviderStrategy باشد، نود model مستقیماً به پایان میرسد {{code libs/langchain_v1/langchain/agents/factory.py:1790-1803}}.
رسم گراف
ایجنت را ساختهاید و میخواهید گراف آن را پیش از اجرا ببینید. گراف کامپایلشده میتواند بدون هیچ فراخوانی مدل یا اجرایی، ساختار خود را توصیف کند.
get_graph(): متدی در گراف کامپایلشده که شیء Graph را از پکیج langchain_core همراه با نودها و یالهایش برمیگرداند {{code libs/langgraph/langgraph/pregel/main.py}}.
graph.nodes:
{
…
"tools": {
"name": "tools",
"data": "ToolNode",
"metadata": {
"__tools": [
"add"
]
}
},
…
}به گره tools خلاصه شده است. سایر گرهها هیچ متادادهای ندارند.
هر نود شیء اجراکنندهی خود را نگهداری میکند؛ مانند شیء ToolNode در نود tools. هر یال یک پرچم conditional دارد. نود tools نام ابزارهایش را بهصورت متادیتا نگه میدارد.
draw_mermaid(): متدی در Graph که گراف را در قالب متن فلوچارت Mermaid برمیگرداند. این متد به هیچ پکیج جانبی یا شبکهای نیاز ندارد {{code libs/core/langchain_core/runnables/graph_mermaid.py}}.
graph TD;
__start__([<p>__start__</p>]):::first
model(model)
tools(tools<hr/><small><em>__tools = add</em></small>)
__end__([<p>__end__</p>]):::last
__start__ --> model;
model -.-> __end__;
model -.-> tools;
tools -.-> model;
classDef default fill:#f2f0ff,line-height:1.2
classDef first fill-opacity:0
classDef last fill:#bfb6fcهر خط نود یک id و یک برچسب ارائه میدهد. عبارت :::first برای مشخص کردن __start__ و :::last برای نشان دادن __end__ است. خط یال با علامت --> یال ساده و با -.-> یال شرطی را مشخص میکند. شکل هر خط متن را با تصویر نمودار تطبیق میدهد. تمام نمودارهای این راهنما از روی چنین متنی رسم شدهاند که مستقیماً از گراف کامپایلشده استخراج شده است.
xray: آرگومانی در get_graph که نود زیرگراف را باز میکند و نودهای درونش را داخل یک کادر رسم میکند. مقدار True تمام سطوح را باز میکند و دادن یک عدد صحیح مشخص میکند چند سطح باز شوند {{code libs/langgraph/langgraph/pregel/main.py}}.
یک گراف والد با یک زیرگراف، این تفاوت را آشکار میسازد. فراخوانی get_graph() زیرگراف را در قالب یک نود واحد یعنی inner نشان میدهد؛ در حالی که get_graph(xray=True) دو نود درونی را بهجای آن به نمایش میگذارد:
[
"__start__",
"prepare",
"finish",
"__end__",
"inner:shout",
"inner:ask_ok"
]بخش 6.7 گراف والد را به هر دو شکل رسم میکند. ایجنتی که با create_agent ساخته میشود نود زیرگراف ندارد؛ بنابراین xray هیچ تغییری در گراف آن ایجاد نمیکند.
draw_ascii(): متدی در Graph که گراف را بهصورت متنی رسم میکند. این متد به پکیج grandalf نیاز دارد و langchain-core آن را نصب نمیکند {{code libs/core/langchain_core/runnables/graph_ascii.py:205}}. پینِ کیت ما این پکیج را به همراه ندارد، در نتیجه این فراخوانی خطا میدهد:
draw_ascii():
raised builtins.ImportError: Install grandalf to draw graphs: `pip install grandalf`.اگر میخواهید نمودار متنی را در ترمینال ببینید، پکیج grandalf را در محیط خودتان نصب کنید.
draw_mermaid_png(): متدی در Graph که متن Mermaid را به یک تصویر PNG تبدیل میکند. روش پیشفرض رسم در این متد، شیوهی API است:
keyword defaults:
{
"draw_method": "api",
"base_url": null,
"max_retries": 1,
"output_file_path": null
}روش API کل متن Mermaid را با الگوریتم base64 کدگذاری میکند. سپس نتیجه را در URL یک درخواست GET به یک سرویس عمومی رندرینگ میفرستد {{code libs/core/langchain_core/runnables/graph_mermaid.py:463-501}}. بنابراین، نام نودها، نام ابزارها و متادیتای نودها در قالب این URL از دستگاه شما خارج میشوند. روی گرافی که نامهای محرمانه دارد، این متد پیشفرض را صدا نزنید.
پارامتر base_url همین درخواست را به سرور Mermaid تحت مدیریت خودتان میفرستد {{code libs/core/langchain_core/runnables/graph_mermaid.py:463}}. روش PYPPETEER رندر را درون یک مرورگر هدلس محلی و به کمک پکیج pyppeteer انجام میدهد. البته آن صفحه نیز اسکریپت Mermaid را از یک شبکهی توزیع محتوای عمومی (CDN) میخواند؛ در نتیجه همچنان به اینترنت وابسته است {{code libs/core/langchain_core/runnables/graph_mermaid.py:389-393}}. کیت ما هیچکدام از این دو روش را فراخوانی نمیکند؛ بلکه متن Mermaid را ذخیره کرده و تصاویر این راهنما همان متن را بهصورت آفلاین رسم میکنند.
فراخوانیهای موازی ابزار و max_concurrency
max_concurrency: کلیدی در تنظیمات اجرا (run config) که سقف تعداد وظایف همزمان در یک گام را تعیین میکند.
ما این مورد را اندازه گرفتیم: فراخوانیهای موازی ابزار را روی سیستم مهمان با معماری x86 و 32 هستهی مجازی (vCPU) سنجیدیم. از مدل Qwen3 4B بین 1 تا 16 فراخوانی موازی درخواست شد و مدل به ترتیب 2، 2، 4، 8 و 16 فراخوانی ایجاد کرد. سلولهای ToolNode پاسخ واقعی مدل را، هرکدام 5 بار اجرا کردند. تابع create_agent در هر اجرا مدل را صدا زد و درخواست 8 ابزار داد؛ هرکدام 3 بار. ابزار مورد استفاده دستور 200 میلیثانیهای pg_sleep را در PostgreSQL اجرا میکرد.
ToolNode و نوع فراخوانی |
16 فراخوانی، سقف 1 | 16 فراخوانی، سقف 8 | 16 فراخوانی، بدون سقف |
|---|---|---|---|
invoke، ابزار سنکرون |
3,331.0 میلیثانیه، 1 فراخوانی همزمان | 460.0 میلیثانیه، 8 فراخوانی همزمان | 264.2 میلیثانیه، 16 فراخوانی همزمان |
ainvoke، ابزار آسنکرون |
233.7 میلیثانیه، 16 فراخوانی همزمان | 233.1 میلیثانیه، 16 فراخوانی همزمان | 233.7 میلیثانیه، 16 فراخوانی همزمان |
ainvoke، ابزار سنکرون |
267.1 میلیثانیه، 16 فراخوانی همزمان | 266.5 میلیثانیه، 16 فراخوانی همزمان | 269.2 میلیثانیه، 16 فراخوانی همزمان |
create_agent و نوع فراخوانی |
8 فراخوانی، سقف 1 | 8 فراخوانی، سقف 4 | 8 فراخوانی، بدون سقف |
|---|---|---|---|
invoke، ابزار سنکرون |
1,674.0 میلیثانیه، 1 فراخوانی همزمان | 437.2 میلیثانیه، 4 فراخوانی همزمان | 229.2 میلیثانیه، 8 فراخوانی همزمان |
ainvoke، ابزار آسنکرون |
1,668.7 میلیثانیه، 1 فراخوانی همزمان | 421.9 میلیثانیه، 4 فراخوانی همزمان | 210.5 میلیثانیه، 8 فراخوانی همزمان |
ainvoke، ابزار سنکرون |
1,669.7 میلیثانیه، 1 فراخوانی همزمان | 431.0 میلیثانیه، 4 فراخوانی همزمان | 231.2 میلیثانیه، 8 فراخوانی همزمان |
هر سلول ToolNode میانهی زمان واقعی و بیشترین تعداد فراخوانیهای همزمان را نشان میدهد. هر سلول create_agent میانهی زمان از شروع اولین ابزار تا پایان آخرین ابزار را نمایش میدهد. با احتساب مدل، کل اجرا بین 12 تا 14 ثانیه طول کشید. همهی اجراهای موفق، هر فراخوانی را دقیقاً یکبار اجرا کردند و یک ToolMessage برای آن نوشتند.
تابع create_agent در تمام حالتها سقف را اعمال کرد، زیرا هر فراخوانی یک وظیفهی مجزای Send به شمار میآید. در حالت بدون سقف، ابزارهای سنکرون در یک استخر نخ (thread pool) اجرا میشوند. استخر پیشفرض پایتون برابر است با min(32, cpu+4). این مقدار روی مک 10 هستهای برابر با 14 و روی سیستم مهمان 32 بود؛ جایی که 16 فراخوانی همزمان سنکرون در 264 میلیثانیه اجرا شدند.
کلید max_concurrency اندازهی آن استخر را نیز مشخص میکند؛ بنابراین مقداری بزرگتر از پیشفرض، ظرفیت استخر را افزایش میدهد {{code libs/core/langchain_core/runnables/config.py:659-675}}. ابزارهای آسنکرون تحت متد ainvoke هیچ سقف پیشفرضی نداشتند. ابزاری که صرفاً بدنهی آسنکرون داشت در متد invoke، در 125 سطر از 125 سطر ToolNode و در 9 اجرا از 9 اجرای ایجنت خطای NotImplementedError داد.
یک ToolNode ساده تحت ainvoke، هم برای ابزارهای آسنکرون و هم ابزارهای سنکرون سقف را نادیده گرفت. گزارش langgraph#8517 حالت آسنکرون را شرح داده است {{issue langgraph#8517}}. اجراهای ما نیز آن را بازتولید کرد و نشان داد ابزارهای سنکرون در مسیر آسنکرون هم دچار همین وضعیت میشوند. البته تحت متد invoke، نود ToolNode سقف را رعایت کرد. وقتی ابزاری سرویسی با محدودیت نرخ درخواست را صدا میزند، روی اجرا مقدار max_concurrency را تعیین کنید؛ و چنانچه به اعمال این سقف تحت ainvoke نیاز دارید، از create_agent بهره ببرید.
مقادیر پیشفرض روی گراف کامپایلشده
تابع create_agent پیش از برگرداندن گراف، تنظیمی روی آن قرار میدهد:
agent.config:
{
"recursion_limit": 9999,
"metadata": {
"ls_integration": "langchain_create_agent"
},
"configurable": {}
}
agent.stream_mode = 'updates'
type langgraph.graph.state.CompiledStateGraphخلاصه شده به پیکربندی، حالت استریم و نوع.
سقف 9999 گام روی تمام اجراهایی که recursion_limit اختصاصی خود را ارسال نکنند اعمال میشود. حالت پیشفرض استریم updates است؛ بنابراین استریمی که حالتی برایش مشخص نشده باشد، به ازای هر نود اجراشده یک تکه تولید میکند. در بخش 1.3 یک ایجنت را تا رسیدن به این محدودیت اجرا کردیم و تکهها را نشان دادیم. همچنین ارسال name، کلید lc_agent_name را به متادیتا میافزاید.
هزینهی لایهی ایجنت
ما این مورد را اندازه گرفتیم: یک وظیفه روی سیستم مک: دو ابزار و سه فراخوانی مدل در ارتباط با Qwen3 4B روی Ollama، در 40 اجرای تصادفی برای هر کدام. یک حلقهی سادهی openai و create_agent اسکیمای ابزارهای یکسانی فرستادند و در تمام دفعات پاسخ برابری دریافت کردند. یک پروکسی زمان هر فراخوانی مدل را ثبت کرد و زمان خارج از مدل همان زمان باقیمانده از اجرا در نظر گرفته شد.
| حالت | میانهی زمان خارج از مدل | اختلاف نسبت به حلقهی ساده، در همان دور |
|---|---|---|
حلقهی سادهی openai |
25.1 میلیثانیه | خط مبنا |
حلقهی ChatOpenAI.bind_tools |
29.3 میلیثانیه | 6.6 میلیثانیه |
create_agent |
37.6 میلیثانیه | 15.6 میلیثانیه |
create_agent به همراه InMemorySaver |
37.6 میلیثانیه | 12.2 میلیثانیه |
گراف دستساز StateGraph |
36.7 میلیثانیه | 11.5 میلیثانیه |
لایهی ایجنت به ازای هر فراخوانی مدل حدود 5 میلیثانیه به زمان اضافه کرد. با create_agent، تنها 2.3 درصد از زمان یک اجرای 1.8 ثانیهای خارج از پردازش مدل سپری شد. بخش 8.3 تصویر کاملی از هزینهها به همراه توکنها، بایتهای ارسالی درخواست و زمان import ارائه میدهد.
منابع: capture/out/05-agent-graph.txt، capture/out/09-middleware-order.txt، capture/out/48-draw-agent.txt، capture/out/52-draw-subgraph.txt، capture/s_draw.py؛ capture/lab/summary/parallel-tools-x86.json، capture/lab/T08-parallel-tools-x86/01-counts.jsonl، capture/lab/T08-parallel-tools-x86/04-toolnode.jsonl، capture/lab/T08-parallel-tools-x86/05-agent.jsonl، capture/lab/T08-parallel-tools-x86/t08_real.py؛ گزارش langgraph#8517؛ capture/lab/summary/overhead-mac-real.json، capture/lab/T01-overhead-mac-real/01-runs.jsonl، capture/lab/T01-overhead-mac-real/t01_real.py؛ libs/langchain_v1/langchain/agents/factory.py و libs/langchain_v1/langchain/agents/middleware/types.py، libs/core/langchain_core/runnables/config.py در langchain==1.5.0؛ libs/langgraph/langgraph/graph/state.py و libs/langgraph/langgraph/pregel/main.py در langgraph 1.2.22؛ libs/core/langchain_core/runnables/graph.py، libs/core/langchain_core/runnables/graph_mermaid.py، و libs/core/langchain_core/runnables/graph_ascii.py در langchain-core 1.8.0.