مستندات ساخت ایجنت با پایتون

LangGraph چیست؟

آشنایی با LangGraph، کتابخانۀ متن‌باز ساخت ایجنت‌های هوش مصنوعی، و نخستین ایجنت آن روی مدل‌های DaLAi.

LangGraph (لنگ‌گراف) کتابخانۀ متن‌باز پایتون برای ساختن ایجنت (عامل) هوش مصنوعی است: برنامه‌ای که با یک مدل زبانی تصمیم می‌گیرد، ابزار صدا می‌زند و کاری چندمرحله‌ای را تا آخر پیش می‌برد. سازندۀ آن شرکت LangChain است و با مجوز MIT رایگان در اختیار همه است. در این صفحه می‌بینید LangGraph چیست، کی به کارش ببرید و چطور نخستین ایجنت را با مدل‌های DaLAi بسازید؛ نمونه کدها را روی همین درگاه اجرا کرده‌ایم.

LangGraph چیست و چطور کار می‌کند؟

در LangGraph کار ایجنت را به شکل یک گراف می‌نویسید. هر گره (node) یک گام است، مثلاً صدا زدن مدل یا اجرای یک ابزار، و یال‌ها (edges) می‌گویند پس از هر گام نوبت کدام گام است. همۀ گره‌ها یک «حالت» (state) مشترک را می‌خوانند و به‌روز می‌کنند، مثلاً فهرست پیام‌های گفت‌وگو. سازندگانش آن را چارچوبی سطح پایین برای هماهنگ کردن ایجنت‌ها می‌دانند: به جای یک جعبۀ آماده، اجزایی می‌دهد که با آن‌ها مسیر کار ایجنت را دقیق در اختیار می‌گیرید.

LangGraph چه امکاناتی دارد؟

LangGraph، LangChain و Deep Agents چه فرقی دارند؟

کتابخانهکی به کارش ببریم
LangChainشروع سریع: اتصال به مدل‌ها و ابزارها و الگوهای آمادۀ ایجنت، که خودشان روی LangGraph ساخته شده‌اند
LangGraphکنترل کامل مسیر کار، حالت و حافظه؛ ایجنت‌های چندمرحله‌ای و چندایجنتی
Deep Agentsایجنت آماده برای کارهای طولانی، با برنامه‌ریزی، فایل و زیرایجنت؛ روی LangGraph اجرا می‌شود

اگر ایجنتی می‌خواهید که بیشتر امکاناتش از پیش آماده باشد، Deep Agents را ببینید.

نصب LangGraph و اتصال به DaLAi

pip install -U langgraph langchain-openai

LangGraph به مدل خاصی بسته نیست. مدل را با کتابخانۀ langchain-openai و از راه API سازگار با OpenAI در DaLAi صدا می‌زنیم. کلید DaLAi را در یک متغیر محیطی بگذارید تا در کد نوشته نشود. در macOS و Linux:

export DALAI_API_KEY=sk-YOUR-KEY

و در PowerShell ویندوز:

$env:DALAI_API_KEY="sk-YOUR-KEY"

نخستین گراف

این گراف یک گره دارد که مدل را صدا می‌زند:

import os
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START, END

llm = ChatOpenAI(
    model="deepseek-v3-2",
    base_url="https://dalai.ir/v1",
    api_key=os.environ["DALAI_API_KEY"],
)

def chatbot(state: MessagesState):
    return {"messages": [llm.invoke(state["messages"])]}

graph = StateGraph(MessagesState)
graph.add_node("chatbot", chatbot)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
app = graph.compile()

question = "LangGraph را در یک جمله معرفی کن."
result = app.invoke({"messages": [{"role": "user", "content": question}]})
print(result["messages"][-1].content)

MessagesState حالتی آماده است که فهرست پیام‌ها را نگه می‌دارد. START و END آغاز و پایان گراف‌اند و compile گراف را برای اجرا آماده می‌کند.

ایجنت با ابزار و حافظه

ایجنت واقعی ابزار دارد و گفت‌وگو را به یاد می‌آورد. در این نمونه، مدل هر جا لازم بداند ابزار count_letters را صدا می‌زند، و InMemorySaver گفت‌وگوی هر رشته (thread_id) را نگه می‌دارد:

import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.checkpoint.memory import InMemorySaver

llm = ChatOpenAI(model="deepseek-v3-2", base_url="https://dalai.ir/v1", api_key=os.environ["DALAI_API_KEY"])

@tool
def count_letters(text: str) -> int:
    """تعداد حرف‌های یک متن را، بدون فاصله‌ها، می‌شمارد."""
    return len(text.replace(" ", ""))

tools = [count_letters]
llm_with_tools = llm.bind_tools(tools)

def agent(state: MessagesState):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

graph = StateGraph(MessagesState)
graph.add_node("agent", agent)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", tools_condition)
graph.add_edge("tools", "agent")
app = graph.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "user-1"}}
q1 = "عبارت «هوش مصنوعی» چند حرف دارد؟"
r1 = app.invoke({"messages": [{"role": "user", "content": q1}]}, config)
print(r1["messages"][-1].content)

q2 = "سؤال قبلی من چه بود؟"
r2 = app.invoke({"messages": [{"role": "user", "content": q2}]}, config)
print(r2["messages"][-1].content)

tools_condition اگر مدل ابزاری خواسته باشد کار را به گره tools می‌فرستد، وگرنه گراف را تمام می‌کند. وقتی این کد را روی DaLAi اجرا کردیم، مدل ابزار را با متن درست صدا زد، پاسخ داد که عبارت ۹ حرف دارد و در نوبت دوم سؤال قبلی را به یاد آورد.

کدام مدل را انتخاب کنم؟

نمونه‌ها با deepseek-v3-2 نوشته شده‌اند، که ارزان است و ابزار صدا می‌زند. برای کارهای پیچیده‌تر فقط نام مدل را عوض کنید، مثلاً claude-sonnet-4-5، یا claude-opus-4-6 برای سخت‌ترین کارها. مقایسۀ مدل‌ها در آشنایی با مدل‌ها و قیمت هر کدام در مدل‌ها و قیمت‌ها است.

چند نکته پیش از ساخت ایجنت

پرسش‌های رایج

LangGraph رایگان است؟ بله. کتابخانه‌ای متن‌باز با مجوز MIT است و هزینه فقط برای مدل‌هایی است که صدا می‌زنید.

با Claude هم کار می‌کند؟ بله. در همین کدها نام مدل را claude-sonnet-4-5 بگذارید؛ آدرس و کلید همان است. ببینید: API کلود.

برای استفاده از LangGraph در ایران تحریم‌شکن لازم است؟ درخواست‌هایی که ایجنت شما به مدل می‌فرستد به آدرس DaLAi می‌رود که در ایران است، پس برای آن‌ها تحریم‌شکن، فیلترشکن یا VPN لازم نیست.

چطور دسترسی بگیرم؟ DaLAi در دورۀ راه‌اندازی آزمایشی است و ثبت‌نام با دعوت‌نامه انجام می‌شود. برای درخواست دسترسی به support@dalai.ir ایمیل بزنید.