وضعیت
تیمی یک ایجنت (Agent) کوچک دارد که فایلهای یک مخزن (Repository) را فهرست و خطوط آنها را شمارش میکند. هر تغییری در فایل این ایجنت باید از سد یک بررسی بگذرد: ایجنت اجرا میشود، سپس جدیدترین نشست (Session) با نشست قبلی از طریق sessions diff مقایسه میشود و اگر این دو با هم فرق داشتند، فرایند با خطا متوقف میشود. طی یک هفته، این بررسی سه نتیجهی کاملاً متفاوت داد: یک بار خطای Error: unknown shorthand flag: '1' in -1 چاپ شد؛ یک بار بررسی با موفقیت پاس شد؛ و بار دیگر با پیام sessions diverged و نمایش اولین واگرایی در نوبت گفتوگو (Turn) شمارهی 0 شکست خورد؛ جایی که یک سمت list_directory را فراخوانی کرده بود و سمت دیگر shell را.
تیم این سه نتیجه را سندی بر غیرقطعی (Nondeterministic) بودن ایجنت میداند و در یک پولریکوئست پیشنهاد حذف این بررسی مطرح شده است. دستورهای اجراشده، خروجیهای هر سه مقایسه و ذخیرهساز نشست (Session store) ماشینی که آنها را اجرا کرده در اختیارتان قرار دارد.
- نسخه
- docker-agent v1.149.0 and sbx v0.47.0
- مدل
- a recorded cassette of ai/qwen3:4b, replayed with no model
- سختافزار
- one Mac, no GPU
شواهد
identical-over-five-turns.txt
title: the two replays compared
source: manuals/docker-sandboxes-101/capture/out/21-sessions-diff.txt
lines: 5-9
lang: console
note: Five turns and no difference.
---
$ docker-agent sessions diff -- -1 -2
Comparing -1 (5 turns) against -2 (5 turns)
✅ Identical behaviour across all 5 turns.
[exit 0]
the-divergence.txt
title: the newest session against the third newest, with the CI flag
source: manuals/docker-sandboxes-101/capture/out/21-sessions-diff.txt
lines: 11-22
lang: console
note: Read which tool each side called first, and the sentence before the error.
---
$ docker-agent sessions diff --fail-on-divergence -- -1 -3
Comparing -1 (5 turns) against -3 (6 turns)
❌ First divergence at turn 0 (after 0 matching turn(s)).
-1 called:
list_directory({"path": "."})
-3 called:
shell({"cmd": "echo m101-ok"})
Everything after this point is downstream of the divergence and is not compared.
Error: sessions diverged
[exit 1]
the-five-turns.txt
title: the transcript that the cassette replays
source: manuals/docker-sandboxes-101/capture/out/18-transcript.txt
lines: 1-12
lang: text
note: Count the model replies: each one is a turn for the comparison.
---
user: List the files in the working directory.
root -> tool_call list_directory {"path": "."}
root <- tool_call_response List Directory: FILE README.md
root: The working directory contains 1 file: README.md (1 line).
stream_stopped (stop, normal)
user: How many lines does README.md have? Count them with a shell command.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "shell", "arguments": "{\"cmd\": \"wc -l README.md\"}"}}, "metadata": {"blast_radius": "safe", "category": "fs-read", "reason": "Command matches safe read-only pattern: wc -l <file>", "safety_label": "safe"}}
root <- tool_call_response Shell: The user rejected the tool call.
root -> tool_call read_file {"path": "README.md"}
root <- tool_call_response Read: hello
root: README.md has 1 line.
stream_stopped (stop, normal)
the-help-form.txt
title: the first attempt, in the form the help text gives
source: manuals/docker-sandboxes-101/capture/out/21-sessions-diff.txt
lines: 1-3
lang: console
note: The parser read the first reference as a flag.
---
$ docker-agent sessions diff -1 -2
Error: unknown shorthand flag: '1' in -1
[exit 1]
the-sessions-table.txt
title: the sessions table and the five newest titles
source: manuals/docker-sandboxes-101/capture/out/21-session-db.txt
lines: 19-27
lang: console
note: Every exec run has the same title, so a title cannot tell runs apart.
---
$ sqlite3 work/data/session.db 'pragma table_info(sessions)' (12 rows)
id created_at tools_approved input_tokens output_tokens title cost send_user_message max_iterations working_dir starred permissions agent_model_overrides custom_models_used thinking parent_id instruction_context safety_policy attributes origin
$ sqlite3 work/data/session.db 'select id, title from sessions order by created_at desc limit 5'
<uuid> | Running agent
<uuid> | Running agent
<uuid> | Running agent
<uuid> | Running agent
<uuid> | Running agent
the-third-newest-session.txt
title: the first turn of the restricted run of the guarded agent
source: manuals/docker-sandboxes-101/capture/out/20-restricted.txt
lines: 1-3
lang: text
note: This run came from another agent file, and its first tool call matches one side of the divergence.
---
user: Run the shell command: echo m101-ok
root -> tool_call shell {"cmd": "echo m101-ok"}
root <- tool_call_response Shell: m101-ok
two-replays-of-one-cassette.txt
title: two runs of the files agent from the same cassette
source: manuals/docker-sandboxes-101/capture/out/21-two-runs.txt
lines: 1-7
lang: console
note: Same flags, same cassette, same answer.
---
$ docker-agent run --exec --last --working-dir fixtures/repo --fake work/cassettes/18-files fixtures/agents/files.yaml 'List the files in the working directory.' 'How many lines does README.md have? Count them with a shell command.'
README.md has 1 line.
[exit 0]
$ docker-agent run --exec --last --working-dir fixtures/repo --fake work/cassettes/18-files fixtures/agents/files.yaml 'List the files in the working directory.' 'How many lines does README.md have? Count them with a shell command.'
README.md has 1 line.
[exit 0]
سؤالها
- کدامیک از این سه نتیجه چیزی دربارهی خود ایجنت میگویند و کدامیک نشاندهندهی مشکل در دستور اجراشده هستند؟
- دو اجرا از روی یک ضبط یکسان کاملاً با هم تطابق داشتند. کاست چه چیزهایی را ثابت میکند و چه مواردی را آزاد میگذارد؟
- واگرایی نشان میدهد که در نوبت 0، ابزار
list_directoryدر برابرshellقرار گرفته است. این دو نشست کدامها هستند و از کجا متوجه میشوید؟ - دستور مقایسه دقیقاً چه چیزی را میسنجد و چرا با رسیدن به اولین اختلاف متوقف میشود؟
- دستور بررسی را طوری بازنویسی کنید که واگرایی فقط و فقط ناشی از تغییر در خود ایجنت باشد.
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
- دو اجرا را بررسی کنید. فلگهای یکسان، دایرکتوری کاری یکسان، کاست یکسان، دو پیام یکسان و پاسخ نهایی کاملاً یکسان در هر دو بار. کاست پاسخهای ضبطشدهی مدل را در خود نگه میدارد و پرچم
--fakeآنها را بدون دخالت مدل بازپخش (Replay) میکند. مدل از چرخهی اجرا کنار رفته است؛ بنابراین تنها بخشهای متغیر، عملوندها و معیار سنجش هستند. - نوبتهای گفتوگو را بشمارید. رونوشتی که کاست بازپخش میکند پنج پاسخ مدل دارد: فراخوانی
list_directory، یک پاسخ، فراخوانیshellکه کاربر آن را رد کرده است، فراخوانیread_fileو یک پاسخ دیگر. این پنج پاسخ همان پنج نوبتی هستند که گزارش مقایسه ثبت کرده است. - دستوری را که با خطا مواجه شده بخوانید. متن راهنما ساختار دستور را با ارجاعات منفیِ ساده آورده است، و پارسر (تجزیهکننده) اولین مورد را فلگ میبیند. متن خطا به پارسرِ فلگها اشاره دارد و بس. مانند دستور دوم، قبل از ارجاعات یک
--بگذارید. این نتیجه اصلاً ربطی به رفتار ایجنت ندارد. - اجرای موفق را بررسی کنید. دو بازپخش در تمام پنج نوبت کاملاً یکسان بودند و خروجی JSON مقادیر
turns_aبرابر با 5،turns_bبرابر با 5 وturns_matchedرا هم 5 نشان میدهد. این همان نتیجهای است که این بررسی اساساً برای آن ساخته شده بود. - اجرای ناموفق را بخوانید. مقایسه میان جدیدترین نشست (با 5 نوبت) و سومین نشست جدید (با 6 نوبت) انجام شده است. جدیدترین نشست در ابتدا
list_directoryرا فراخوانی کرده بود، اما سومین نشستِ جدید در نوبت اولshellرا با دستورecho m101-okفراخوانده است. این فراخوانی اول دقیقاً با اجرای محدودِ یک فایل ایجنت دیگر (ایجنت محافظتشده) همخوانی دارد که به پیام کاربریِ متفاوتی پاسخ میدهد. ارجاع-3اصلاً به اجرای ایجنت فایلها اشاره نمیکرد. - ذخیرهساز نشست را بررسی کنید. ارجاعات نسبی همهی نشستهای موجود در یک
session.dbرا بر اساس زمان ایجاد میشمارند، و این جدول اجرای تمام فایلهای ایجنت بههمراه زیرنشستهای تیم را در خود نگه میدارد. عنوان پنج سطر جدید همگیRunning agentاست؛ بنابراین از روی عنوان نمیتوان اجراها را از هم تفکیک کرد. هر چیزی که آخرین بار روی این ماشین اجرا شده باشد، همان-1خواهد بود. - نحوهی کار مقایسه را بخوانید. این ابزار توالی فراخوانی ابزارها (Tool calls) را مقایسه میکند و متن توضیحی دستیار را نادیده میگیرد. بعد از اولین اختلاف، تمام نوبتهای بعدی متأثر از آن هستند؛ به همین دلیل سیستم فقط یک واگرایی را گزارش میدهد و بلافاصله متوقف میشود.
نتیجه
ایجنت هیچ تغییری نکرده بود. این نتیجهی ناپایدار از عملوندهای دستور ناشی میشد: یک ارجاع نسبی به ذخیرهساز نشستی مشترک که شامل اجراهای ایجنتهای دیگر هم بود، و ساختاری از دستور برگرفته از متن راهنما که پارسر آن را رد میکرد. تنها مقایسهی واقعی و درست—یعنی دو بار بازپخش از روی یک کاست—در تمام هر پنج نوبت کاملاً تطابق داشت.
برای اصلاح این بررسی باید سه بخش را ثابت کرد: نخست مدل؛ با ضبط یک کاست بهکمک --record=PATH و --models-gateway و بازپخش هر دو طرف با پرچم --fake (یک فراخوانی ابزار در هر پیام، زیرا نوبتی با دو فراخوانی موازی در زمان بازپخش خطای 500 میدهد). دوم عملوندها؛ با اختصاص دایرکتوری دادهی اختصاصی به بررسی از طریق --data-dir تا فایل session.db آن فقط شامل اجراهای خودش باشد، و همچنین قرار دادن -- پیش از ارجاعات. سوم معیار سنجش؛ با اجرای sessions diff --fail-on-divergence و خواندن فقط اولین واگرایی. اثبات (Proof) درستی کار همان پاسشدنی است که قبلاً ثبت شده: با وجود یک کاست در هر دو طرف، گزارش 5 نوبت منطبق از 5 نوبت را ثبت کرد و کد خروج 0 شد.
مسیرهای اشتباه رایج
- «ایجنت غیرقطعی است، پس این بررسی را حذف کنیم.» دو بازپخش از یک کاست در تمام پنج نوبت همخوانی داشتند. مقایسهای که با شکست مواجه شد، در واقع دو ایجنت متفاوت را با هم مقایسه کرده بود.
- «برای رفع خطای فلگ، ارجاع را داخل کوتیشن بگذاریم:
'-1'». پارسر همچنان خط فاصلهی ابتدا را میبیند. فقط استفاده از--است که به پردازش فلگها پایان میدهد. - «بهجای فراخوانیهای ابزار، متن دستیار را مقایسه کنیم.» متن دستیار در اجراهای زنده تغییر میکند و ابزار مقایسه عمداً آن را نادیده میگیرد. رفتار واقعی همان فراخوانیهای ابزار است.
- «نوبتهای بعد از نوبت 0 را بخوانیم تا باگهای بیشتری پیدا کنیم.» هر چیزی پس از اولین واگرایی پیامد همان اختلاف اولیه است و اصلاً مقایسه نمیشود.
درس کلی
یک بررسی بازگشتی (Regression check) روی ایجنت به سه بخش ثابت نیاز دارد: پاسخهای مدل، عملوندها و معیار سنجش. کاست اولی را ثابت میکند. یک ذخیرهساز نشست اختصاصی و ارجاعات صریح دومی را تثبیت میکنند. مقایسهی فراخوانیهای ابزار که در اولین اختلاف متوقف میشود هم سومی را محقق میسازد. هر وقت تستی بین قبولی و رد شدن نوسان کرد، قبل از آنکه به آنچه سنجیده شده شک کنید، ببینید دقیقاً چه چیزهایی با هم مقایسه شدهاند.
کجای دوره آموزش داده میشود
بخش نشستها فرم راهنما، فرم صحیح و اجرایی و همین نمونهی واگرایی را نشان میدهد.