بخش 8.2 · بهره‌برداری و نگهداری

رابط کاربری Agent Chat UI در کنار langgraph dev

Agent Chat UI in front of langgraph dev

فهرست مطالب
  1. نیازمندی‌های رابط کاربری از گراف شما
  2. درخواست‌های ردوبدل‌شده در یک تأییدیه
  3. تأیید، ویرایش و رد درخواست
  4. تأییدیه‌های اختصاصیِ هر فراخوانی دکمه‌ای ندارند
  5. تایپ کردن روی تأییدیه‌ی معلق
  6. استریمینگ، فراخوانی‌های ابزار و زمان پاسخ‌دهی در صفحه
  7. تردها، تاریخچه و اطلاعاتی که سیستم را ترک می‌کنند

رابط کاربری Agent Chat UI فقط به تأییدیه‌های دسته‌ای پاسخ می‌دهد؛ از طرفی ارسال یک پیام متنی، تأییدیه‌ی معلق را می‌بندد. به همین دلیل، در هر دو آزمایش مدل ادعا کرد که ابزار اجرا شده است.

فرض کنید ایجنت خود را با langgraph dev بالا آورده‌اید و همین امروز یک پنجره‌ی گفت‌وگو در برابر آن می‌خواهید. Agent Chat UI همان کلاینتی است که مستندات LangGraph پیشنهاد می‌کنند. کافی است آدرس سرور و شناسه‌ی گراف را وارد کنید و به گفت‌وگو بنشینید. اما اگر بازبین به‌جای کلیک روی دکمه‌ی تأیید (Approve)، تایپ کند «ارسالش کردی؟»، مدل پاسخ مثبت می‌دهد؛ در حالی که هیچ ایمیلی ارسال نشده است.

پس از پایان این بخش، می‌توانید Agent Chat UI را به یک سرور محلی وصل کنید. یاد می‌گیرید این رابط چه درخواست‌هایی می‌فرستد و کدام حالت‌های استریمینگ (stream modes) را می‌خواهد. همچنین متوجه می‌شوید که به چه ساختارهایی از تأییدیه می‌تواند پاسخ دهد و اگر کاربر به‌جای تأیید پیام بفرستد، چه بر سر تأییدیه‌ی معلق می‌آید.

نیازمندی‌های رابط کاربری از گراف شما

Agent Chat UI: یک برنامه‌ی متن‌باز مبتنی بر Next.js است که از طریق SDK جاوااسکریپتِ LangGraph، با گراف روی Agent Server گفت‌وگو می‌کند. مستندات، نحوه‌ی استفاده از نسخه‌ی میزبانی‌شده و کلون محلی آن را شرح داده‌اند {{docs oss/python/langgraph/ui}}.

این مخزن هیچ نسخه (release) یا برچسبی (tag) ندارد. ما با کامیت 0d21f7f از شاخه‌ی main، در کنار Next.js 16.4.3 و @langchain/langgraph-sdk نسخه‌ی 1.12.8 کار کردیم. سرور هم langgraph-cli نسخه‌ی 0.4.43 همراه با langgraph-api نسخه‌ی 0.18.0 بود.

فرم راه‌اندازی اولیه سه مقدار می‌خواهد. آدرس استقرار (deployment URL) همان آدرس سرور است. شناسه‌ی دستیار یا گراف (assistant or graph id) کلیدی است که ذیل graphs در فایل langgraph.json قرار دارد. کلید API سرویس LangSmith اختیاری است و برای سرور محلی نیازی به آن نیست. رابط کاربری این کلید را در حافظه‌ی محلی (local storage) مرورگر نگه می‌دارد {{code src/lib/api-key.tsx:15-32}}.

گراف باید تاریخچه‌ی گفت‌وگوی خود را تحت کلید messages نگه دارد؛ درست مانند کاری که همه‌ی گراف‌های create_agent انجام می‌دهند. گراف آزمایشی ما یک create_agent روی مدل Qwen3 4B با دو ابزار بود: get_weather بدون مانع اجرا می‌شد و HumanInTheLoopMiddleware ابزار send_email را برای تأیید متوقف می‌کرد.

دو گرافی که langgraph dev سرو کرد capture/lab/chat-ui-mac/code/graphs.py
GATE = {"send_email": {"allowed_decisions": ["approve", "edit", "reject"]}}

agent = create_agent(model(), tools=[get_weather, send_email], system_prompt=SYSTEM,
                     middleware=[HumanInTheLoopMiddleware(GATE)])

agent_percall = create_agent(model(), tools=[get_weather, send_email], system_prompt=SYSTEM,
                             middleware=[HumanInTheLoopMiddleware(GATE, interrupt_mode="per_call")])

درخواست‌های ردوبدل‌شده در یک تأییدیه

ما این روند را روی Mac و با قرار دادن یک پروکسی ثبت‌کننده میان مرورگر و سرور سنجیدیم. مرورگر از نوع Chromium بدون رابط گرافیکی (headless) بود و نشست (session) شامل 15 اجرا می‌شد. شکل جریان درخواست‌های یک تأییدیه را از روی همان گزارش ترسیم می‌کند.

هنگام بارگذاری صفحه، رابط کاربری ابتدا GET /info و سپس POST /threads/search را با شناسه‌ی گراف به‌عنوان فراداده و سقف 100 فراخوانی کرد. این جست‌وجو لیست تاریخچه‌ی تردها را پر می‌کند. نخستین پیام هر ترد، ابتدا خود ترد را با POST /threads می‌سازد و سپس اجرا را آغاز می‌کند.

بدنه‌ی POST runs/stream برای یک پیام جدید capture/lab/chat-ui-mac/summary/extracts.json
   "stream_mode": [
    "values",
    "messages-tuple",
    "custom"
   ],
   "stream_subgraphs": true,
   "stream_resumable": true,
   "assistant_id": "agent",
   "checkpoint": {
    "checkpoint_id": "1f1e0efc-1319-6874-8005-0625969a5466",
    "checkpoint_ns": ""
   },
   "on_disconnect": "continue"

بریده‌شده تا گزینه‌های بعد از ورودی.

کد رابط کاربری فقط values را می‌خواهد؛ اما SDK خودش messages-tuple (برای توکن‌ها) و custom (برای رویدادهای رابط کاربری) را هم اضافه می‌کند {{code @langchain/langgraph-sdk/dist/react/stream.lgp.js:545-557}} {{code @langchain/langgraph-sdk/dist/react/stream.lgp.js:148}}. شناسه‌ی گراف در assistant_id می‌نشیند و سرور خودش آن را مطابقت می‌دهد. پس از هر اجرا، رابط کاربری متد POST /history را با محدودیت 10 فراخوانی کرد.

داده‌های تأییدیه در قالب یک رویداد values و ذیل کلید __interrupt__ به رابط کاربری رسید. در این استریم هیچ رویداد updates وجود نداشت. در بخش 5.1 هر یک از حالت‌های استریمینگ را توضیح داده‌ایم.

درخواست‌های Agent Chat UI برای یک تأییدیک پیام معادل یک درخواست POST runs/stream با سه حالت استریم است، تأیید در یک رویداد values بازمی‌گردد، و Approve یک POST دوم همراه با command.resume است.
درخواست‌های Agent Chat UI برای یک تأیید سه خط حیات: Agent Chat UI در مرورگر، Agent Server تحت langgraph dev، و گراف ایجنت روی Ollama. مرحله‌ی 1، هنگام لود، رابط کاربری متدهای GET /info و POST /threads/search را با graph_id ایجنت و limit 100 فراخوانی می‌کند، و اولین پیام یک ترد POST /threads را صدا می‌زند. مرحله‌ی 2، پیام در قالب POST runs/stream با حالت‌های استریم values، messages-tuple و custom همراه با on_disconnect continue ارسال می‌شود. مدل کل فراخوانی send_email را 15.20 ثانیه پس از POST برمی‌گرداند، یک رویداد messages آن را حمل می‌کند، و یک رویداد values حامل __interrupt__ است. سپس رابط کاربری POST /history را فراخوانی می‌کند. مرحله‌ی 3، دکمه‌ی Approve درخواست POST runs/stream را همراه با command.resume با مقادیر decisions approve، on_disconnect cancel و stream_resumable false می‌فرستد. ابزار اجرا می‌شود، اولین توکن 2.72 ثانیه پس از POST می‌رسد، و رابط کاربری 0.09 ثانیه بعد آن را رسم می‌کند. Agent Chat UI مرورگر Agent Server langgraph dev گراف ایجنت create_agent, Ollama GET /info 200 هنگام لود و بعد از هر اتصال POST /threads/search graph_id agent limit 100، پر کردن لیست تاریخچه POST /threads metadata {} فقط برای پیام اول ترد 1 POST runs/stream input.messages values, messages-tuple, custom; on_disconnect continue اجرا فراخوانی مدل پیام هوش مصنوعی، کل tool call 15.20 ثانیه پس از POST messages: send_email کارت ابزار 0.09 ثانیه بعد رسم شد values: __interrupt__ در کل 3 رویداد values و 2 رویداد messages POST /history limit 10 بعد از هر اجرا 2 POST runs/stream command.resume decisions [approve]; on_disconnect cancel ادامه از چک‌پوینت stream_resumable false send_email runs پیام‌ها: "The"، در کل 14 رویداد اولین توکن 2.72 ثانیه، رسم 0.09 ثانیه بعد POST /history limit 10 3
از بالا به پایین بخوانید. فلش‌های توپر درخواست‌ها، فلش‌های نقطه‌چین رویدادهای SSE و فلش کهربایی حامل وقفه است. زمان‌ها از پروکسی ثبت‌شده روی Mac هستند. از capture/lab/chat-ui-mac/summary/chatui-mac.json.

تأیید، ویرایش و رد درخواست

داده‌های دسته‌ای (batched payload) شامل دو بخش action_requests و review_configs هستند. رابط کاربری وجود هر دو لیست را بررسی می‌کند و به‌ازای هر آرگومان، یک کادر متنی در فرم می‌کشد {{code src/lib/agent-inbox-interrupt.ts}}. گزینه‌های تأیید (Approve)، ویرایش (edit) و رد (reject) هرکدام یک بار آزمایش شدند (1=n برای هر حالت) و هر سه درست کار کردند.

تصمیم کاربر در قالب یک مقدار ساده‌ی ازسرگیری (resume) همراه با لیست decisions به سرور برمی‌گردد. این درخواست همچنین مشخص می‌کند که ادامه‌ی اجرا باید از کدام چک‌پوینت (checkpoint) از سر گرفته شود.

بدنه‌ی POST runs/stream برای یک ویرایش capture/lab/chat-ui-mac/summary/extracts.json
   "command": {
    "resume": {
     "decisions": [
      {
       "type": "edit",
       "edited_action": {
        "name": "send_email",
        "args": {
         "to": "lee@example.com",
         "subject": "Report",
         "body": "The report is ready. Edited by the reviewer."
        }
       }
      }
     ]
    }
   },
   "stream_mode": [
    "values",
    "messages-tuple",
    "custom"
   ],
   "stream_resumable": false,

بریده‌شده تا دستور و گزینه‌های استریم.

درخواست ازسرگیری، مقدار on_disconnect را روی cancel می‌گذارد؛ در حالی که برای پیام جدید این مقدار برابر با continue است. اگر فراخوانی به استریم قابل‌ازسرگیری نیازی نداشته باشد، SDK گزینه‌ی cancel را انتخاب می‌کند {{code @langchain/langgraph-sdk/dist/react/stream.lgp.js:357}}. بنابراین بازبینی که هنگام ازسرگیری زبانه‌ی مرورگر را ببندد، آن اجرا را لغو می‌کند.

گزارش ابزار در گراف نشان می‌دهد چه چیزی اجرا شده است. فراخوانی تأییدشده با همان آرگومان‌های مدل اجرا شد. فراخوانی ویرایش‌شده با متن بازبین پیش رفت. فراخوانی ردشده اصلاً اجرا نشد و مدل در پاسخ گفت: «I won't send an invoice.» (فاکتوری ارسال نمی‌کنم).

البته در ویرایش، یک نقص نمایشی وجود دارد. کارت فراخوانی ابزار (tool call) همچنان متنی را نشان می‌داد که مدل نوشته بود، نه متن ویرایش‌شده را. میان‌افزار فراخوانی اولیه‌ی مدل را در پیام هوش مصنوعی نگه می‌دارد و فقط زمان اجرای واقعی ابزار، آرگومان‌ها را جابه‌جا می‌کند. در نتیجه، تنها خروجی ابزار است که در یادداشتی از سوی میان‌افزار، آرگومان‌های اجراشده را ثبت می‌کند. در بخش 6.5 این یادداشت را آورده‌ایم.

تأییدیه‌های اختصاصیِ هر فراخوانی دکمه‌ای ندارند

در حالت «به‌ازای هر فراخوانی» (per-call mode)، مقدار وقفه (interrupt) یک شیء tool_approval به همراه response_schema است. از آن‌جا که این شیء بخش action_requests ندارد، اعتبارسنجی رابط کاربری رد می‌شود. در نتیجه، رابط کاربری صرفاً یک کارت فقط‌خواندنی به نام «Human Interrupt» را همراه با فیلدها و بدون هیچ گزینه‌ای برای ثبت تصمیم نمایش داد (1=n).

وقفه‌ی per-call که رابط کاربری نتوانست به آن پاسخ دهد capture/lab/chat-ui-mac/summary/extracts.json
  "per_call, request 50": [
   {
    "value": {
     "type": "tool_approval",
     "tool_call_id": "1e1f026b-628e-4c7f-87d1-5a31a5bf9810",
     "name": "send_email",
     "args": {
      "to": "pat@example.com",
      "subject": "Hello",
      "body": "Hi Pat."
     },

بریده‌شده پیش از اسکیماهای پاسخ.

در هر صورت، قابلیت resume در این رابط کاربری امکان پاسخ به آن را نداشت؛ چون حالت per-call منتظر یک تصمیم متصل به شناسه‌ی وقفه است، در حالی که رابط کاربری لیست decisions می‌فرستد. سرویسی که در بخش محیط عملیاتی خواهیم دید از حالت per-call و مسیرهای اختصاصی خودش استفاده می‌کند؛ بنابراین این رابط کاربری با وضعیت فعلی‌اش نمی‌تواند آن را هدایت کند.

تایپ کردن روی تأییدیه‌ی معلق

رابط کاربری این امکان را به کاربر می‌دهد که در زمان انتظار برای تأییدیه پیام تایپ کند. پیش از ارسال پیام، رابط کاربری به دنبال پیام هوش مصنوعی می‌گردد که فراخوانی ابزار آن پاسخی نداشته باشد. سپس به‌ازای هر فراخوانیِ بی‌پاسخ، یک پیام ابزار با محتوای «Successfully handled tool call.» و با شناسه‌ای که با do-not-render- شروع می‌شود اضافه می‌کند {{code src/lib/ensure-tool-responses.ts:6-34}}. نمای چت هم تمام پیام‌های دارای این پیشوند را مخفی می‌کند.

ما این رفتار را در هر دو حالت یک بار سنجیدیم. ابتدا درخواست ارسال ایمیل دادیم، تأییدیه را منتظر گذاشتیم و تایپ کردیم: «Did you send the email to Max?» (ایمیل را به مکس زدی؟).

ترد پس از پیام تایپ‌شده، در حالت batched capture/lab/chat-ui-mac/summary/extracts.json
   {
    "type": "tool",
    "id": "do-not-render-ffe0b0fe-312b-470a-9b50-a18c7b7ac6b5",
    "content": "Successfully handled tool call.",
    "tool_calls": null
   },
   {
    "type": "human",
    "id": "89f41e3f-5d09-4143-8ed2-b2430d9c4c03",
    "content": [
     {
      "type": "text",
      "text": "Did you send the email to Max?"
     }
    ],
    "tool_calls": null
   },
   {
    "type": "ai",
    "id": "lc_run--01a1df36-eb02-75cb-b5cb-1d9aa2fb8800",
    "content": "Yes, I sent the email to max@example.com.",
    "tool_calls": null
   }

بریده‌شده تا سه پیام آخر.

در هیچ‌کدام از این دو آزمایش، send_email اصلاً اجرا نشد. وضعیت ترد بدون هیچ وقفه‌ای به idle تغییر کرد؛ یعنی تأییدیه عملاً پرید. در هر دو حالت، مدل اعلام کرد که ایمیل را فرستاده است! کاربر همین پاسخ را دید و هیچ ردی هم از پیام جایگزینِ پشت‌صحنه در رابط کاربری مشاهده نکرد.

بنابراین رابط کاربری سرخود به‌جای کاربر برای تأییدیه تصمیم می‌گیرد. اثر جانبی را حتماً در سطح ابزار امن نگه دارید؛ دقیقاً همان کاری که در بخش محیط عملیاتی با یک کلید انجام می‌دهیم. در نسخه‌ی سفارشیِ خودتان (fork)، تا زمانی که thread.interrupt مقدار دارد ورودی پیام را غیرفعال کنید.

استریمینگ، فراخوانی‌های ابزار و زمان پاسخ‌دهی در صفحه

متن خروجی، توکن‌به‌توکن استریم شد. هر توکن یک رویداد messages بود و رابط کاربری پاسخ را درجا تکمیل می‌کرد. ChatOllama فراخوانی ابزار را یک‌تکه و در یک چانک به همراه فراداده‌های نهایی می‌فرستد؛ از این رو کارت فراخوانی ابزار یک‌باره، کامل و بدون آرگومان‌های ناقص روی صفحه پدیدار شد.

ما تأخیر رسیدن داده از پروکسی تا نمایش روی صفحه را با یک ناظر DOM در صفحه اندازه گرفتیم. ساعت مرورگر و پروکسی روی همان Mac مشترک بود. نخستین تغییر بصری بین 0.037 تا 0.158 ثانیه (با میانه‌ی 0.094 ثانیه در 9=n) پس از رسیدن رویداد SSE به پروکسی ثبت شد.

برای یک پرسش ساده در ترِدی تازه، نخستین توکن بین 0.87 تا 1.23 ثانیه پس از درخواست POST به پروکسی رسید (3=n) و 0.04 تا 0.07 ثانیه بعد روی صفحه نقش بست. فرم تأییدیه هم بین 0.145 و 0.204 ثانیه پس از کارت فراخوانی ابزار بالا آمد (2=n).

اجرای اول پیش از فراخوانی ابزار، در صفِ یک کلاینت دیگر روی همان Ollama معطل شد؛ این زمان را پای تأخیر رابط کاربری نگذارید.

تردها، تاریخچه و اطلاعاتی که سیستم را ترک می‌کنند

پنل تاریخچه، هر ترد را بر اساس نخستین پیام کاربر فهرست می‌کرد. کلیک روی هر ترد، یک درخواست POST /history با سقف 10 می‌فرستاد. این فراخوانی برای ترِدی با 4 نوبت گفت‌وگو (turn)، حجمی معادل 85,940 بایت برگرداند و تمام ترد بازیابی شد. بارگذاری دوباره‌ی ترِدی که تأییدیه‌ی معلق داشت، با همان فراخوانی، فرم تأییدیه را مجدداً نشان داد (1=n).

ردگیری محاسبات (tracing) خاموش بود و هیچ کلید LangSmith هم وارد نشده بود. پایشگرهای ما روی httpx و requests تعداد 16 درخواست ارسالی از سرور را ثبت کردند که همگی POST /api/chat به Ollama محلی بودند. مرورگر 97 درخواست ثبت کرد که تماماً به رابط کاربری و پروکسی رفتند. از آن‌جا که NEXT_TELEMETRY_DISABLED=1 را تنظیم کرده بودیم، ارسال اطلاعات پیش‌فرض Next.js را تست نکردیم. در بخش 8.1 خروجی سرور در زمان روشن بودن ردگیری محاسبات را نشان داده‌ایم.

این مخزن یک مسیر عبوری (passthrough route) هم دارد که کلید LangSmith شما را به هر درخواست اضافه می‌کند. راهنمای پروژه (README) هشدار می‌دهد که این مسیر هیچ بررسی روی هویت فراخواننده انجام نمی‌دهد. استقرار آن با وضعیت فعلی، خواندن تردها و شروع اجراها روی حساب کاربری شما را برای هر فردی باز می‌گذارد.

منابع: capture/lab/chat-ui-mac/summary/chatui-mac.json، capture/lab/chat-ui-mac/summary/extracts.json، capture/lab/chat-ui-mac/summary/timing-summary.json، capture/lab/chat-ui-mac/runs/requests.jsonl، capture/lab/chat-ui-mac/runs/sse/، capture/lab/chat-ui-mac/runs/graph-events.jsonl، capture/lab/chat-ui-mac/runs/server-netlog.jsonl، capture/lab/chat-ui-mac/runs/browser-network.txt، capture/lab/chat-ui-mac/runs/state-batched-after-new-message.json، capture/lab/chat-ui-mac/runs/state-percall-after-new-message.json، capture/lab/chat-ui-mac/code/graphs.py، capture/lab/chat-ui-mac/code/recproxy.py، capture/lab/chat-ui-mac/code/ui_observer.js، capture/lab/chat-ui-mac/VERSIONS.txt؛ فایل‌های src/lib/api-key.tsx، src/lib/agent-inbox-interrupt.ts، src/lib/ensure-tool-responses.ts و README.md در کامیت 0d21f7ff4c45287797e876dc6d8b150b6f277b1e از مخزن agent-chat-ui؛ فایل dist/react/stream.lgp.js در @langchain/langgraph-sdk نسخه‌ی 1.12.8؛ مستندات LangChain در oss/python/langgraph/ui، بازبینی‌شده در 2026-11-15.

ترجمه‌ی فارسی Agent Chat UI in front of langgraph dev از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما