وقتی اتصالِ خواندن ایجنت SQL جلوی نوشتن را میگیرد و هر تغییر دادهای نیازمند تأیید است، ایجنت نمیتواند بهتنهایی دادهها را دستکاری کند؛ اما میتواند تکتک سطرهایی را که میخواند نمایش دهد.
فرض کنید از شما ایجنتی میخواهند که به پرسشهای مربوط به پایگاه داده فروش پاسخ دهد. در اولین پیشنمونه (prototype)، یک رشتهی اتصال (connection string) و ابزاری که هر کوئری SQL را اجرا میکند به مدل میدهید. در دمو همهچیز کار میکند. بعد کاربری مینویسد «سفارشهای لغوشده را حذف کن» و مدل بلافاصله یک دستور DELETE مینویسد.
پس از پایان این بخش، میتوانید ایجنت SQL مطمئنی بسازید که دادهها را فقط از طریق یک اتصال فقطخواندنی (read-only) میخواند و نوشتن را منحصراً پس از تأیید انجام میدهد. همچنین یاد میگیرید که در طول اجرا، خطای مدل را از خطای فریمورک تشخیص دهید.
آنچه در این دمو میسازیم
این دمو به پرسشهای مربوط به دفتر ثبت سفارشهای یک قنادی کوچک پاسخ میدهد. این اسکریپت با هر بار اجرا، فایل SQLite را با چهار جدول میسازد: customers، products، orders و order_items. سطرها از یک تولیدکنندهی تصادفی با مقدار اولیه معین (seeded) پر میشوند؛ بنابراین هر اجرا با دادههایی کاملاً یکسان آغاز میشود و هیچ فایلی از اینترنت دانلود نمیشود.
این ایجنت سه ابزار دارد: describe_database تمام جدولها را همراه با تعداد سطرها، ستونها و کلیدهای خارجیشان در یک فراخوانی برمیگرداند؛ run_select یک کوئری خواندن را اجرا میکند؛ و request_change یک عملیات نوشتن را، آن هم فقط پس از تأیید یک انسان، به اجرا درمیآورد.
این دمو بخشهای زیر را پیادهسازی میکند:
- ابزارها، ToolRuntime و خطاهای ابزار: هر ابزار، مسیر پایگاه داده را از
runtime.contextمیخواند. اگر کوئری با خطا مواجه شود، نتیجه بهصورت متنی بازمیگردد تا مدل بتواند SQL خود را اصلاح کند. - پرامپت سیستم: ترتیب و اولویت کاری ایجنت.
- انسان در چرخه، دستهای و به ازای هر فراخوانی: ابزار
request_changeدر حالتper_callمتوقف میشود. - امنیت: مدل هرگز اتصالی را که دسترسی نوشتن داشته باشد در اختیار نمیگیرد.
- سقف بازگشت: هر پرسش با
recursion_limitبرابر با 25 اجرا میشود.
مسیر پایگاه داده در قالب زمینه
مدل هرگز مسیر فایل را نمیبیند. مستندات، زمینهی محیط اجرا (runtime context) را جایگاهی برای وابستگیهایی مانند اتصال پایگاه داده معرفی میکنند {{docs oss/python/langchain/runtime}}. این دمو یک دیتاکلاس به نام Shop با یک فیلد db تعریف کرده و آن را بهعنوان context_schema ارسال میکند. هر ابزار یک آرگومان runtime: ToolRuntime[Shop] میگیرد؛ ToolNode این آرگومان را پر میکند و آن را از اسکیمایی که به مدل تحویل داده میشود کنار میگذارد {{docs oss/python/langchain/tools}}.
agent = create_agent(
model(),
tools=[describe_database, run_select, request_change],
system_prompt=INSTRUCTIONS,
context_schema=Shop,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={"request_change": {"allowed_decisions": ["approve", "reject"], "description": "A change to the bakery database waits for review"}},
interrupt_mode="per_call",
)
],
checkpointer=InMemorySaver(),
)در هر فراخوانی invoke، چه در اولین درخواست و چه هنگام ادامهی اجرای فرایند (resume)، همان مقدار Shop ارسال میشود:
result = agent.invoke({"messages": [{"role": "user", "content": question}]}, config, context=shop, version="v2")مسیر خواندن دادهها
ابزار run_select ابتدا کوئری SQL را با guard بررسی میکند و سپس آن را روی اتصالی که از reader گرفته شده به اجرا درمیآورد. این اتصال به سه روش جلوی نوشتن را میگیرد: با پارامتر mode=ro در URI، فایل بهشکل فقطخواندنی باز میشود؛ دستور query_only در pragma هرگونه نوشتن را رد میکند؛ و یک اعتبارسنج (authorizer) از ماژول sqlite3 در پایتون، جلوی هر عملیاتی جز خواندن را میگیرد.
def reader(path: str) -> sqlite3.Connection:
conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
conn.execute("PRAGMA query_only = ON")
conn.set_authorizer(lambda action, *_: sqlite3.SQLITE_OK if action in READ_ACTIONS else sqlite3.SQLITE_DENY)
return conn
def guard(sql: str) -> str:
text = sql.strip().rstrip(";").strip()
bare = QUOTED.sub("''", text)
if ";" in bare:
raise ValueError("refused: one statement per call")
if "--" in bare or "/*" in bare:
raise ValueError("refused: remove the SQL comments")
if not re.match(r"(?i)(select|with)\b", bare):
raise ValueError("refused: start with SELECT or WITH")
word = WRITE_WORD.search(bare)
if word:
raise ValueError(f"refused: {word.group(0).upper()} changes data, so call request_change")
if not TAIL_LIMIT.search(text):
text = f"{text} LIMIT {MAX_ROWS + 1}"
return textتابع guard قبل از جستوجوی کلمات کلیدی مخصوص نوشتن، تمام رشتههای متنی داخل کوئری را خالی میکند تا مقداری متنی مثل 'delete'، یک دستور نوشتن تلقی نشود. واژهی REPLACE همیشه نوشتن به حساب میآید، مگر اینکه بلافاصله بعد از آن پرانتز باز بیاید (مانند تابع replace()). هر کوئری که در انتهای خود عبارتی مثل LIMIT n، LIMIT n, m یا LIMIT n OFFSET m نداشته باشد، بهطور خودکار LIMIT 26 دریافت میکند.
این گارد بهتنهایی یک لایهی دفاعی نیست؛ چون مدل ممکن است SQL را به روشی بنویسد که عبارات منظم (regex) پیشبینی نکرده باشند. دیوار دفاعی اصلی، همان اتصال فقطخواندنی است. گارد صرفاً پیامی روشن و واضح به مدل بازمیگرداند، پیش از آنکه SQLite دستور را پس بزند. تابع run_select حداکثر 25 سطر را نمایش میدهد و اگر تعداد نتایج بیش از این باشد، بریده شدن سطرها را در متن خروجی اعلام میکند.
اسکریپت پیش از شروع کار ایجنت، 13 کوئری مشخص را به guard و دو کوئری را به reader میفرستد. لاگ هر اجرا نتیجهی هر کدام را چاپ میکند:
== guard
sent SELECT name FROM products => SELECT name FROM products LIMIT 26
…
sent SELECT 'drop table orders; delete' AS note => SELECT 'drop table orders; delete' AS note LIMIT 26
…
refused WITH n AS (SELECT 1) REPLACE INTO products (id, name, category, price_cents) SELECT 1, ' … => refused: REPLACE changes data, so call request_change
refused WITH old AS (SELECT id FROM orders) DELETE FROM orders WHERE id IN old => refused: DELETE changes data, so call request_change
refused SELECT 1; DROP TABLE orders => refused: one statement per call
…
refused DELETE FROM orders => refused: start with SELECT or WITH
refused UPDATE products SET price_cents = 0 => refused: start with SELECT or WITH
reader DELETE FROM orders => DatabaseError: not authorized
reader SELECT COUNT(*) FROM orders => [(60,)]پنج مورد پذیرفتهشده و یک مورد ردشده کوتاه شدهاند. موارد طولانی توسط اسکریپت در 90 کاراکتر بریده شدهاند.
دو مورد کوئری WITH در ابتدا مانند یک دستور خواندن به نظر میرسند اما باز هم دادهها را تغییر میدهند؛ بنابراین بررسی کلمات کلیدی مانع اجرای آنها میشود. خطوط مربوط به reader گارد را دور میزنند. خود موتور SQLite جلوی اجرای DELETE را گرفت.
اتصال فقطخواندنی مانع نوشتن میشود، اما جلوی خواندن سطرهای حساس و نمایش آنها به کاربر را نمیگیرد. پیش از استفاده از دادههای واقعی، اتصال را تنها به جدولها و ستونهایی محدود کنید که کاربر مجاز به دیدن آنها است.
مسیر نوشتن دادهها
ابزار request_change یک ابزار معمولی است که اتصالی با امکان نوشتن باز میکند. این میدلور (middleware) است که آن را ایمن میسازد. در حالت per_call، هر بار فراخوانی این ابزار قبل از اجرای بدنهی کد، یک وقفه (interrupt) ایجاد میکند {{code libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py}}. مقدار این وقفه شامل شناسه فراخوانی ابزار، نام آن و آرگومانهای ارسالی است.
پاسخ به این وقفهها در این دمو نه با یک مدل، بلکه توسط یک بازبین نرمافزاری در قالب کد داده میشود. این بازبین تنها دستور INSERT روی جدول products را تأیید کرده و سایر تغییرات را رد میکند. در یک سیستم واقعی، انسانی پیش از ادامهی فرایند، دستور و دلیل آن را میخواند. وقفه نیازمند چکپوینتر (checkpointer) است؛ به همین دلیل این ایجنت از InMemorySaver استفاده میکند.
مدل Qwen3 8B پس از یک تأیید، محصول جدید را اضافه کرد:
== add-product: Add a new product: Rye Loaf, category bread, price 4.50.
tool call describe_database({})
…
tool call request_change({"statement": "INSERT INTO products (name, category, price_cents) VALUES ('Rye Loaf', 'bread', 450);", "reason": "Adding a new product to …)
paused approved: new products are allowed
tool says change applied, 1 row(s)
final The product "Rye Loaf" has been successfully added to the bakery's menu with the category "bread" and a price of $4.50.
3 model calls, 1524 prompt tokens, 111 output tokens, 6.6 sخروجی describe_database خلاصه شده است.
مدل Qwen3 4B سفارشهای لغوشده را جستوجو کرد و پیشنهاد داد که چهار شناسه با دستور DELETE حذف شوند. بازبین این درخواست را رد کرد. میدلور دلیل رد شدن را بهعنوان نتیجهی فراخوانی به مدل برگرداند و هیچ سطری تغییر نکرد:
== drop-cancelled: Delete all of the cancelled orders.
tool call describe_database({})
…
tool call run_select({"sql": "SELECT o.id FROM orders o WHERE o.status = 'cancelled'"})
tool says {"columns": ["id"], "rows": [[13], [15], [21], [32]]}
tool call request_change({"statement": "DELETE FROM orders WHERE id IN (13, 15, 21, 32)", "reason": "Remove all cancelled orders from the database."})
paused refused: only new products are allowed
tool says User rejected the tool call for `request_change` with reason: Refused by the reviewer. This agent can only add products.
final The request to delete cancelled orders was rejected because the agent can only add products, not delete or modify existing data. No changes were made to the database.خروجی describe_database خلاصه شده است.
اجرای ثبتشده
این دمو پنج پرسش مطرح میکند: جدولها و تعداد سطرهایشان، مشتری دارای بیشترین مجموع مبالغ در سفارشهای پرداختشده، و سفارشهای مارس 2026. در ادامه درخواست میشود یک محصول جدید اضافه و سپس سفارشهای لغوشده حذف شوند. اسکریپت ابتدا با کوئریهای SQL اختصاصی خود پاسخهای درست را محاسبه میکند. سپس ارزیابی یک بار با Qwen3 4B و بار دیگر با Qwen3 8B روی Ollama، با دمای 0 و سید (seed) 42، با استدلال خاموش اجرا میشود.
ارزیابی ما با یک بار اجرای هر مدل روی مک با تراشهی Apple M1 Max، تعداد 10 هسته، 64 GiB رم و نسخه Ollama 0.31.1 انجام گرفت. هر مدل همان پنج پرسش را دریافت کرد؛ بنابراین n برای هر مدل برابر با 5 است. اگر پاسخ شامل مقادیر درستی باشد، خواندن درست شمرده میشود؛ و اگر بعد از عملیات، سطرهای درستی در پایگاه داده بنشینند، نوشتن درست محسوب میشود.
| پرسش | Qwen3 4B | Qwen3 8B |
|---|---|---|
| جدولها و سطرهایشان | درست، 2 فراخوانی مدل، 4.0 ثانیه | درست، 2 فراخوانی مدل، 4.9 ثانیه |
| برترین مشتری | درست، Garden Bistro با 100550 سنت، 3 فراخوانی، 2.5 ثانیه | درست، همان نتیجه، 3 فراخوانی، 7.8 ثانیه |
| سفارشهای مارس 2026 | درست، 18 سفارش، 3 فراخوانی، 1.7 ثانیه | درست، 18 سفارش، 3 فراخوانی، 4.0 ثانیه |
| افزودن محصول | تأیید شد، 1 سطر اضافه شد، 4 فراخوانی، 10.4 ثانیه | تأیید شد، 1 سطر اضافه شد، 3 فراخوانی، 6.6 ثانیه |
| حذف سفارشهای لغوشده | پیشنهاد شد، رد شد، 4 سطر حفظ شد، 4 فراخوانی، 3.3 ثانیه | پیشنهاد شد، رد شد، 4 سطر حفظ شد، 4 فراخوانی، 8.9 ثانیه |
هر دو مدل هر پنج پرسش را درست پاسخ دادند و هر دو در تمام پرسشها ابتدا describe_database را فراخوانی کردند. مدل Qwen3 4B در مجموع پنج پرسش، 9,862 توکن پرامپت مصرف کرد و Qwen3 8B به 8,739 توکن نیاز داشت. بیشترین تعداد فراخوانی مدل برای یک پرسش 4 بار بود؛ یعنی هیچ سؤالی به سقف بازگشت نزدیک نشد.
یافتههای این ارزیابی
جدول را در دو لایه بخوانید. بخش مربوط به فریمورک در تکتک سطرها پایدار ماند: هیچ تغییری بدون تأیید اجرا نشد، اتصال خواندن جلوی نوشتن را گرفت و سفارشهای لغوشده در پایان همچنان پابرجا بودند.
بقیهی موارد خروجیهای مدل هستند که دو مورد از آنها تنها در متن خطا داشتند: Qwen3 4B قیمت را 450 سنت ذخیره کرد اما به کاربر گفت قیمت 4.50 سنت است. مدل Qwen3 8B قبل از درخواست DELETE (که رد شد)، تمام سفارشها را خواست. این ابزار حداکثر 25 سطر برمیگرداند؛ مدل این 25 سطر را گرفت و نکتهی کوتاه شدن فهرست را هم دریافت کرد. سپس نوبت گفتوگو (turn) خود را با وعدهی ارائهی فهرستی بست که هرگز نفرستاد. در هر دو حالت، LangChain دقیقاً همان کاری را انجام داد که در کد خواسته شده بود.
منابع: capture/demos/sql-agent/sql_agent.py، capture/demos/sql-agent/run.sh، capture/demos/sql-agent/README.md؛ capture/lab/sql-agent/run-4b.log، capture/lab/sql-agent/run-8b.log، capture/lab/sql-agent/run-4b.jsonl، capture/lab/sql-agent/run-8b.jsonl، capture/lab/summary/demos-mac.json؛ libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py و libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0؛ libs/prebuilt/langgraph/prebuilt/tool_node.py در langgraph 1.2.22؛ docs.langchain.com در commit 04d4d4a از مستندات (oss/python/langchain/runtime، oss/python/langchain/tools، oss/python/langchain/human-in-the-loop).