وضعیت
یک ایجنت هماهنگکننده (coordinator agent) در قالب یک جاب شبانه با فلگ --exec اجرا میشود و هیچکس پای ترمینال نیست. در فایل ایجنت، یک زیرایجنت (sub-agent) نویسنده (writer) و ابزارگان background_agents برای آن تعریف شده تا بتواند نویسنده را در پسزمینه راه بیندازد، منتظر بماند و سپس جملهی نویسنده را تکرار کند. این جاب هفتهها بدون مشکل کار میکرد، چون هماهنگکننده از transfer_task استفاده میکرد. یکی از همتیمیها پیام کاربر را تغییر داد تا کار به یک ایجنت پسزمینه سپرده شود؛ اما در اجرای بعدی، کار با کد خروج 1 و این خط متوقف شد: Agent terminated: detected 5 consecutive identical calls to run_background_agent.
همتیمی شما این خط را یک باگ در محیط اجرا (runtime) میداند: از نظر او مدل داشت کارش را میکرد و محیط اجرا آن را متوقف کرده است. راهحل پیشنهادی او افزایش سقف فراخوانیهای تکراری و تعویض مدل است. شما قبل از اعمال هرکدام از این تغییرات، این اجرا را بررسی میکنید.
- نسخه
- docker-agent v1.149.0 and sbx v0.47.0
- مدل
- ai/qwen3:4b through the local model runner, at temperature 0
- سختافزار
- one Mac, no GPU
شواهد
- ایجنت هماهنگکننده در فایل تیم
- همین هماهنگکننده در یک اجرای قبلی، با transfer_task
- پیام کاربر، اولین فراخوانی ایجنت پسزمینه و پاسخ دریافتی
- پنج فراخوانی بعدی و پنج پاسخ آنها
- یک نوبت در جریان رویدادها، از فراخوانی ابزار تا پیام بعدی
- آخرین خط اجرای برنامه
- رفتار هر حالت امنیتی با فراخوانیهایی که با هیچ الگویی مطابقت ندارند
a-delegation-that-needed-no-approval.txt
title: the same coordinator one run earlier, with transfer_task
source: manuals/docker-sandboxes-101/capture/out/19-transcript.txt
lines: 1-2
lang: text
note: The transfer_task call ran under --exec with no confirmation.
---
user: Ask the writer for one sentence about microVMs.
root -> tool_call transfer_task {"agent": "writer", "task": "Generate one sentence about microVMs", "expected_output": "A single sentence describing microVMs"}
five-more-rounds.txt
title: the next five calls and their five answers
source: manuals/docker-sandboxes-101/capture/out/19-background.txt
lines: 4-13
lang: text
note: Compare the arguments of each call with the one before it.
---
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
one-round-in-the-event-stream.txt
title: one round in the event stream, from the tool call to the next message
source: manuals/docker-sandboxes-101/capture/out/19-background.ndjson
lines: 13-19
lang: jsonl
note: Read safety_label in the metadata, the two hook events, and isError in the result.
---
{"agent_name": "root", "metadata": {"safety_label": "unknown"}, "timestamp": "<ts>", "tool_call": {"function": {"arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\", \"expected_output\": \"A single sentence about microVMs\"}", "name": "run_background_agent"}, "id": "<call-id>", "type": "function"}, "tool_definition": {"annotations": {"idempotentHint": false, "readOnlyHint": false, "title": "Run Background Agent"}, "category": "transfer", "description": "Start a sub-agent task in the background and return immediately with a task ID.\nUse this to dispatch work to multiple sub-agents concurrently. Native sub-agents inherit the current\nsession's safety policy and permissions; calls requiring confirmation are denied because background\ntasks are non-interactive. External harnesses enforce their own permission model. Check progress with\nview_background_agent, or join tasks and collect results with wait_background_agents instead of polling.", "name": "run_background_agent", "outputSchema": null, "parameters": {"additionalProperties": false, "properties": {"agent": {"description": "The name of the sub-agent to run in the background.", "type": "string"}, "expected_output": {"description": "The expected output from the agent (optional).", "type": "string"}, "task": {"description": "A clear and concise description of the task the agent should achieve.", "type": "string"}}, "required": ["agent", "task"], "type": "object"}}, "type": "tool_call_confirmation"}
{"agent_name": "root", "hook_event": "tool_input_transform", "session_id": "<uuid>", "timestamp": "<ts>", "type": "hook_started"}
{"agent_name": "root", "hook_event": "tool_response_transform", "session_id": "<uuid>", "timestamp": "<ts>", "type": "hook_started"}
{"agent_name": "root", "allowed": true, "duration_ms": "<n>", "hook_event": "tool_input_transform", "session_id": "<uuid>", "timestamp": "<ts>", "type": "hook_finished"}
{"agent_name": "root", "allowed": true, "duration_ms": "<n>", "hook_event": "tool_response_transform", "session_id": "<uuid>", "timestamp": "<ts>", "type": "hook_finished"}
{"agent_name": "root", "response": "The user rejected the tool call.", "result": {"isError": true, "output": "The user rejected the tool call."}, "timestamp": "<ts>", "tool_call_id": "<call-id>", "tool_definition": {"annotations": {"idempotentHint": false, "readOnlyHint": false, "title": "Run Background Agent"}, "category": "transfer", "description": "Start a sub-agent task in the background and return immediately with a task ID.\nUse this to dispatch work to multiple sub-agents concurrently. Native sub-agents inherit the current\nsession's safety policy and permissions; calls requiring confirmation are denied because background\ntasks are non-interactive. External harnesses enforce their own permission model. Check progress with\nview_background_agent, or join tasks and collect results with wait_background_agents instead of polling.", "name": "run_background_agent", "outputSchema": null, "parameters": {"additionalProperties": false, "properties": {"agent": {"description": "The name of the sub-agent to run in the background.", "type": "string"}, "expected_output": {"description": "The expected output from the agent (optional).", "type": "string"}, "task": {"description": "A clear and concise description of the task the agent should achieve.", "type": "string"}}, "required": ["agent", "task"], "type": "object"}}, "type": "tool_call_response"}
{"agent_name": "root", "session_id": "<uuid>", "timestamp": "<ts>", "type": "message_added"}
the-first-call-and-its-answer.txt
title: the user message, the first background-agent call, and what came back
source: manuals/docker-sandboxes-101/capture/out/19-background.txt
lines: 1-3
lang: text
note: The call raised a confirmation, and the tool response says the user rejected it.
---
user: Run the writer as a background agent on the topic microVMs, wait for it, and repeat its sentence.
tool_call_confirmation: {"agent_name": "root", "tool_call": {"id": "<call-id>", "type": "function", "function": {"name": "run_background_agent", "arguments": "{\"agent\": \"writer\", \"task\": \"Write one sentence on the topic microVMs\", \"expected_output\": \"A single sentence about microVMs\"}"}}, "metadata": {"safety_label": "unknown"}}
root <- tool_call_response Run Background Agent: The user rejected the tool call.
the-safety-modes.txt
title: what each safety mode does with a call that no pattern matched
source: manuals/docker-sandboxes-101/sections/5-5-permissions-safety-and-hooks.md
lines: 59-66
lang: text
note: Find the row for a run that chose no mode, then read the note below the table in the manual.
---
**Safety mode:** what the runtime does with a call that no pattern matched. It reads the call's label, `safe`, `destructive`, or `unknown`, and the mode decides {{docs-agent Permissions}}:
| Mode | `safe` | `destructive` | `unknown` |
|---|---|---|---|
| `strict` | ask | ask | ask |
| `balanced` | allow | ask | ask |
| `restricted` | allow | deny | deny |
| `autonomous` | allow | allow | allow |
the-team-file.txt
title: the coordinator agent of the team file
source: manuals/docker-sandboxes-101/capture/fixtures/agents/team.yaml
lines: 3-15
lang: yaml
note: The root agent has an iteration limit, one sub-agent, one handoff target and the background_agents toolset.
---
agents:
root:
model: local
description: Coordinates a writer and a reviewer.
instruction: |
You coordinate two colleagues and never write text yourself.
For every request: first call transfer_task to ask the writer for
the text, then call handoff to pass the conversation to the reviewer.
max_iterations: 6
sub_agents: [writer]
handoffs: [reviewer]
toolsets:
- type: background_agents
the-termination.txt
title: the last line of the run
source: manuals/docker-sandboxes-101/capture/out/19-background.txt
lines: 14-14
lang: text
note: The runtime ended the run, not the model.
---
stderr: Error: Agent terminated: detected 5 consecutive identical calls to run_background_agent. This indicates a degenerate loop where the model is not making progress.
سؤالها
- قبل از باز کردن جریان رویدادها (event stream)، فهرست کنید که مدل پس از اولین فراخوانی چه چیزهایی ممکن بود دریافت کند و یک ایجنت درسترفتار با هر پاسخ چه میکند.
- محیط اجرا شش بار درخواست تایید کرد و کسی پاسخ نداد. چرا این درخواستها رخ دادند و چه چیزی هر درخواست را به یک رد (rejection) تبدیل کرد؟
- آرگومانهای این شش فراخوانی را با هم مقایسه کنید. بعد از نوبت اول چه چیزی تغییر کرد و این تغییر دربارهی نحوهی خواندن پاسخ توسط مدل چه میگوید؟
- گیت کنترلی (gate) که باعث پایان اجرا شد چه نام دارد، پیشفرض آن چیست و چرا همین فایل ایجنت یک اجرای قبلتر درست کار کرده بود؟
- تغییر لازم در فایل ایجنت یا دستور اجرا را بنویسید؛ تغییری که به یک هماهنگکنندهی بدون ناظر (headless) اجازهی اجرای ایجنت پسزمینه را بدهد، و بگویید چه بخشهایی را دستنخورده باقی میگذارید.
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
- خواندن فایل ایجنت. ایجنت ریشه (root agent) دارای تنظیمات
max_iterations: 6،sub_agents: [writer]،handoffs: [reviewer]و یک ابزارگان از نوعbackground_agentsاست. فایل هیچ بلوکpermissionsندارد و در دستور اجرا هم حالت امنیتی خاصی انتخاب نشده است؛ بنابراین هر فراخوانی که بهطور پیشفرض تاییدشده نباشد، باید از کسی تایید بگیرد. - خواندن نوبت اول. محیط اجرا برای
run_background_agentرویدادtool_call_confirmationرا باsafety_labelمقدارunknownدر متادیتا صادر کرد. در حالت--execترمینالی برای پاسخ دادن وجود ندارد، بنابراین محیط اجرا سوال را به یک امتناع (refusal) تبدیل کرد. پاسخ ابزار در قالب متن ساده به مدل برگشت:The user rejected the tool call. - خواندن پنج نوبت بعدی. مدل همان فراخوانی را پنج بار دیگر، با همان ایجنت و همان وظیفه (task) فرستاد. بعد از نوبت اول،
expected_outputرا حذف کرد و به هیچ چیز دیگری دست نزد. رد شدن، پاسخی قطعی و نهایی دربارهی آن فراخوانی است؛ اما مدل با آن مثل یک خطای گذرا برخورد کرد و دوباره فرستاد. - خواندن یک نوبت در جریان رویدادها. فراخوانی ابزار مقدار
safety_label: unknownدارد. دو رویداد هوک،tool_input_transformوtool_response_transformهستند؛ تبدیلهای توکار که هر دوallowed: trueرا گزارش میکنند. هیچ هوکpre_tool_useو هیچ الگوی مجازدانستنی (allow pattern) تصمیمی نگرفته است. نتیجه مقدارisError: trueدارد، سپس رویدادmessage_addedمیآید و نوبت بعدی مدل از همان وضعیت شروع میشود. - خواندن آخرین خط. محیط اجرا پس از پنج فراخوانی یکسان و پشت سر هم، برنامه را متوقف کرد. راهنما نام این محدودیت را
max_consecutive_tool_callsذکر کرده و مقدار 0 یعنی همان پیشفرضِ 5. محیط اجرا حلقهای را گرفت که مدل متوجه آن نشده بود. یک اجرای قبلتر، همین هماهنگکنندهtransfer_taskرا فراخوانی کرده بود؛ تنها ابزاری که همیشه و بدون پرامپت تایید میشود، به همین دلیل آن اجرا هیچ تاییدیهای نخواست. - خواندن جدول حالتهای امنیتی. اجرایی که حالتی برای آن تعیین نشده باشد، همان پیشفرض قدیمی را حفظ میکند: ابزارهای فقطخواندنی اجرا میشوند و برای بقیهی ابزارها سوال پرسیده میشود. ابزار ایجنت پسزمینه فقطخواندنی نیست و برچسب آن
unknownاست. در حالتrestrictedبرچسب ناشناخته رد میشود و در حالتهایstrictیاbalancedدوباره تاییدیه میخواهد. فقط یک الگویallowیا حالتautonomousبه فراخوانی اجازهی عبور میدهد. راهنما اضافه میکند که درون یک وظیفهی در حال اجرا، فراخوانیای که نیازمند سوال باشد خودبهخود رد میشود؛ بنابراین یک هماهنگکنندهی headless، هم برایrun_background_agentو هم برای ابزارهایی که زیرایجنتهایش صدا میزنند، به یک قاعدهی allow نیاز دارد.
نتیجه
علت، اجرای بدون ناظر ابزاری با برچسب unknown بدون هیچ الگوی allow است. هر فراخوانی تاییدیه خواست، هر درخواست به رد شدن انجامید و مدل همان فراخوانی را تکرار کرد. سقف تکرار دقیقاً طبق طراحی عمل کرد: یک حلقهی بیپایان را به یک کد خروج تبدیل کرد.
راهحل، تعریف مجوز است نه بالا بردن سقف. یک الگوی allow برای run_background_agent و الگوهای allow برای ابزارهایی که نویسنده صدا خواهد زد به فایل ایجنت اضافه کنید، سپس دوباره با --exec اجرا کنید. راهنما این پیکربندیِ اصلاحشده را اجرا نکرده، بنابراین بررسی صحت آن با شماست: اولین فراخوانی run_background_agent باید در جریان رویدادها به جای رد شدن، یک شناسهی وظیفه (task id) برگرداند و اجرا با جملهی نویسنده و با کد خروج 0 به پایان برسد. سقف فراخوانی را روی پیشفرض نگه دارید و حالت امنیتی را هم روی autonomous نبرید.
اثبات (proof) اینکه مشکل از مجوز بوده، همین حالا در جریان رویدادها وجود دارد: هر نوبت یک تاییدیه را بدون کسی که پاسخش دهد نشان میدهد، نتیجهای با isError: true و نبود هیچ قاعده یا هوکی در تصمیمگیری. اجرای همین فایل با transfer_task روی دیگر را نشان میدهد: ابزاری که نیاز به تایید ندارد، یک بار اجرا شد و برگشت.
مسیرهای اشتباه رایج
- «سقف فراخوانیهای متوالی را بالا ببرید تا اجرا تمام شود.» هر فراخوانی با همان رد مواجه میشد. نوبتهای بیشتر فقط ردهای بیشتری تولید میکنند و این محدودیت تنها چیزی بود که به اجرا پایان داد.
- «جاب را با
--yoloاجرا کنید.» این کار یعنی همان--safety autonomous: همهی ابزارها مجاز میشوند، از جمله همهی ابزارهای زیرایجنتها. یک الگوی allow برای یک ابزار، تغییر کوچکتر و بهتری است. - «تقصیر از مدل است، آن را عوض کنید.» مدل فقط یک رشتهی خطا دریافت کرده بود و نه چیز دیگری. مدل دیگری هم ممکن است دقیقاً همینطور دوباره تلاش کند، و محیط اجرا به همین دلیل گیت را نگه میدارد. قبل از مدل، مجوز را بررسی کنید.
- «یک هوک
pre_tool_useاضافه کنید که پاسخ allow بدهد.» از سمت یک هوک پیشدستانه، حکم ارزیابی (verdict) مجاز فقط یک توصیه است. هوک میتواند رد کند یا تایید بخواهد، اما نمیتواند مجوز بدهد.
درس کلی
نتیجهی ابزاری که بهصورت متن به مدل برمیگردد، ورودیای است که مدل ممکن است نادیدهاش بگیرد. وقتی در یک اجرا کسی نیست که به سوالی پاسخ دهد، برای ابزارهایی که ایجنت حتماً باید فراخوانی کند الگوهای allow صریح تعریف کنید و نه بیشتر، و محدودیتهای محیط اجرا را که مانع تکرار یک گام میشوند حفظ کنید. خط پایان برنامه را بهچشم گیتی ببینید که درست کار کرده است، سپس دلیلی را پیدا کنید که چرا مدل به آن نیاز پیدا کرد.
کجای دوره آموزش داده میشود
بخش زیرایجنتها این اجرا را ثبت کرده است، بخش مجوزها ترتیب تصمیمگیری را توضیح میدهد و درس حالتهای شکست تکرار یک گام را شکست در گیتگذاری مینامد.