بخش 4.9 · ایجنت، خروجی ساختاریافته و میان‌افزار

یک ایجنت SQL روی پایگاه داده محلی SQLite

A SQL agent over a local SQLite database

فهرست مطالب
  1. آنچه در این دمو می‌سازیم
  2. مسیر پایگاه داده در قالب زمینه
  3. مسیر خواندن داده‌ها
  4. مسیر نوشتن داده‌ها
  5. اجرای ثبت‌شده
  6. یافته‌های این ارزیابی

وقتی اتصالِ خواندن ایجنت SQL جلوی نوشتن را می‌گیرد و هر تغییر داده‌ای نیازمند تأیید است، ایجنت نمی‌تواند به‌تنهایی داده‌ها را دستکاری کند؛ اما می‌تواند تک‌تک سطرهایی را که می‌خواند نمایش دهد.

فرض کنید از شما ایجنتی می‌خواهند که به پرسش‌های مربوط به پایگاه داده فروش پاسخ دهد. در اولین پیش‌نمونه (prototype)، یک رشته‌ی اتصال (connection string) و ابزاری که هر کوئری SQL را اجرا می‌کند به مدل می‌دهید. در دمو همه‌چیز کار می‌کند. بعد کاربری می‌نویسد «سفارش‌های لغوشده را حذف کن» و مدل بلافاصله یک دستور DELETE می‌نویسد.

پس از پایان این بخش، می‌توانید ایجنت SQL مطمئنی بسازید که داده‌ها را فقط از طریق یک اتصال فقط‌خواندنی (read-only) می‌خواند و نوشتن را منحصراً پس از تأیید انجام می‌دهد. همچنین یاد می‌گیرید که در طول اجرا، خطای مدل را از خطای فریم‌ورک تشخیص دهید.

آنچه در این دمو می‌سازیم

این دمو به پرسش‌های مربوط به دفتر ثبت سفارش‌های یک قنادی کوچک پاسخ می‌دهد. این اسکریپت با هر بار اجرا، فایل SQLite را با چهار جدول می‌سازد: customers، products، orders و order_items. سطرها از یک تولیدکننده‌ی تصادفی با مقدار اولیه معین (seeded) پر می‌شوند؛ بنابراین هر اجرا با داده‌هایی کاملاً یکسان آغاز می‌شود و هیچ فایلی از اینترنت دانلود نمی‌شود.

این ایجنت سه ابزار دارد: describe_database تمام جدول‌ها را همراه با تعداد سطرها، ستون‌ها و کلیدهای خارجی‌شان در یک فراخوانی برمی‌گرداند؛ run_select یک کوئری خواندن را اجرا می‌کند؛ و request_change یک عملیات نوشتن را، آن هم فقط پس از تأیید یک انسان، به اجرا درمی‌آورد.

این دمو بخش‌های زیر را پیاده‌سازی می‌کند:

مسیر پایگاه داده در قالب زمینه

مدل هرگز مسیر فایل را نمی‌بیند. مستندات، زمینه‌ی محیط اجرا (runtime context) را جایگاهی برای وابستگی‌هایی مانند اتصال پایگاه داده معرفی می‌کنند {{docs oss/python/langchain/runtime}}. این دمو یک دیتاکلاس به نام Shop با یک فیلد db تعریف کرده و آن را به‌عنوان context_schema ارسال می‌کند. هر ابزار یک آرگومان runtime: ToolRuntime[Shop] می‌گیرد؛ ToolNode این آرگومان را پر می‌کند و آن را از اسکیمایی که به مدل تحویل داده می‌شود کنار می‌گذارد {{docs oss/python/langchain/tools}}.

ایجنت، همراه با سیاق و بازبینی روی ابزار نوشتن capture/demos/sql-agent/sql_agent.py
    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 ارسال می‌شود:

یک پرسش، همراه با سیاق آن capture/demos/sql-agent/sql_agent.py
        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 در پایتون، جلوی هر عملیاتی جز خواندن را می‌گیرد.

اتصال فقط‌خواندنی و گارد محافظ capture/demos/sql-agent/sql_agent.py
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 می‌فرستد. لاگ هر اجرا نتیجه‌ی هر کدام را چاپ می‌کند:

حالت‌های گارد، اجرای Qwen3 8B capture/lab/sql-agent/run-8b.log
== 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 پس از یک تأیید، محصول جدید را اضافه کرد:

درج تأییدشده، Qwen3 8B capture/lab/sql-agent/run-8b.log
== 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 حذف شوند. بازبین این درخواست را رد کرد. میدل‌ور دلیل رد شدن را به‌عنوان نتیجه‌ی فراخوانی به مدل برگرداند و هیچ سطری تغییر نکرد:

حذف ردشده، Qwen3 4B capture/lab/sql-agent/run-4b.log
== 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).

ترجمه‌ی فارسی A SQL agent over a local SQLite database از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما