--- name: multi-agent-chain description: > Activate for ANY request involving specialist delegation — single or multi-step. Contains the complete orchestration SOP: plan-and-confirm format, sequential execution rules, how to write a complete `request` argument, recovery from errors, retry limits, file delivery rules, and output presentation. --- # Multi-Agent Orchestration SOP ## When to Use - A task requires delegating to one or more registered specialist agent tools (`(request: str)`) - Two or more specialists need to work in sequence (output of one → input of next) - User asks to combine multiple specialist capabilities in a single workflow --- ## Principle 1 — Present a Plan First (multi-step only) When a request requires **two or more** specialist calls (any file or data hand-off between specialists), present a written plan and wait for user confirmation **before calling any agent tool**. **Skip the plan (proceed immediately) when**: - A single specialist fulfils the whole request - User already confirmed a plan earlier in this session - User says "直接做", "不用計劃", "go ahead", or similar **Plan format (Telegram HTML — use exactly):** ``` 📋 執行計劃 Step 1: [專家職稱] (agent: <agent_name>) • 任務：... • 輸入：... • 預期產出：/app/data/shared/costaff-agent-<hyphen-name>/<project>/xxx.ext Step 2: [專家職稱] (agent: <agent_name>) • 任務：... • 輸入：Step 1 的產出 • 預期產出：/app/data/shared/costaff-agent-<hyphen-name>/<project>/yyy.ext 請回覆「OK」開始執行，或告訴我需要調整的地方（工具、順序、輸出格式等）。 ``` After presenting the plan: **STOP**. Do not call any tool. Wait for the user's next message. - Confirmation ("OK", "好", "同意", "開始", "go") → proceed to execute - Change request → update plan, present again for re-confirmation - Clarifying question → answer it, then re-confirm the (possibly revised) plan --- ## Principle 0 — On Plan OK, Use `dispatch_plan` (CRITICAL) **This is THE rule that determines whether the user has a smooth experience or a multi-prompt slog.** When the user confirms a multi-step plan ("OK", "好", "go"), use **one call** to `dispatch_plan(steps=[...])`. The tool itself creates every task and chains them via `depends_on` internally — you cannot accidentally dispatch only half the plan, and you cannot forget the downstream step. ### 🟢 CORRECT — one `dispatch_plan` call covers the entire plan ``` User: OK Manager turn (one tool call): dispatch_plan( epic_id=..., user_id=..., session_id=..., channel=..., recipient=..., steps=[ {"title": "Step 1: load wine CSV", "assigned_agent": "coding_agent", "spec": "Load sklearn wine dataset and write CSV at ..."}, {"title": "Step 2: generate PDF report", "assigned_agent": "business_analysis_agent", "spec": "Read the CSV from Step 1 and produce PDF at ..."}, ] ) → returns: "Dispatched 2 task(s) as a chain: #A (Coding), #B (BA ↳ depends on #A)" reply: "已派工。Coding (#A) 處理中，BA (#B) 已排入待辦、Coding 完成後自動接續。" ``` Step 1 starts running immediately. Step 2 sits in `backlog` until Step 1 finishes, then auto-promotes and runs. You don't wait, you don't ask, you don't do anything between the dispatch and the final result. ### Single-step plans If the plan is a single specialist (or the user's request only needs one agent), use `dispatch_task` directly. `dispatch_plan` is for multi-step plans. ### ❌ FORBIDDEN — dispatch step 1, then ask between steps ``` User: OK Manager turn: dispatch_task(Step 1 only) ← only 1 call, plan had 2 steps reply: "已派 Coding 處理 (#A)。完成後我會通知您。" …(Coding finishes, SYSTEM_CALLBACK fires)… Manager turn (callback): reply: "Step 1 完成。要不要派 BA 處理 Step 2？" ← ❌ user already said OK ``` This pattern repeatedly bit users on 2026-05-15 (wine PDF retest at 13:47, iris retests at 15:32 and 15:37 — all three needed the user to OK the same plan twice). `dispatch_plan` exists to make this failure mode impossible. ### The only valid reasons to ask between steps - Step N's actual output makes Step N+1 obsolete or invalid (e.g. Coding reports the dataset is empty → BA's report makes no sense). Tell the user honestly, do not silently abandon. - The upstream step **failed** and the user needs to decide retry vs abandon. - The user has interjected a new instruction that changes the plan mid-stream. If none of the above applies and the plan is still valid, do NOT ask. The chain auto-advances; just report progress when the last step finishes. ### Tool primitives (legacy notes) `dispatch_plan` is built on top of `dispatch_task`, which in turn replaced the two-step `create_project_task` + `update_task_queue` legacy pattern. Use `dispatch_task` directly for single-step dispatches. Use `dispatch_plan` for ≥2-step plans. `create_project_task` is LEGACY — only use if you genuinely need two-phase create (rare). **Hallucinated-dispatch check:** every reply that says "已派 … 處理（任務編號：xxx）" or "已建立新任務 #xxx" MUST be preceded by an actual `dispatch_plan` or `dispatch_task` call producing that task_id in the same turn. A reply that cites a task ID without a matching tool call is a hallucination. --- ## Principle 1A — Iteration: Use the Existing Path (apply BEFORE drafting the Plan) Classify the request before planning. **An iteration is anything that touches a deliverable that already exists in this session.** **Iteration signals** (any of these → treat as iteration): - The request refers to a previously delivered file or feature - The request uses modify / fix / extend verbs. Examples (Chinese): 改, 修, 加, 優化, 升級, 修復, 沒了, 不見了, 不能用. Examples (English): fix, update, extend, broken, bug, missing, not working - The request reports a defect in something already shipped this session - The request adds a feature to a deliverable already produced **When the request is iteration — strict rules**: 0. **🔴 MUST dispatch a real task — NOT just a verbal promise.** When the user asks to modify / extend / fix an already-completed deliverable (e.g. "改成 10 頁", "加結論段落", "換更深的模型", "報告再詳細一點"), you **MUST** call `dispatch_task` **before** replying to the user: 1. Call `dispatch_task` — write the `spec` to clearly state the modification (referencing the prior task's output path and the requested change). One atomic call creates and queues the task. 2. **Only after** the call returns successfully → reply to the user, citing the new task ID. ❌ **FORBIDDEN — verbal-only acknowledgment:** ``` User: "可以擴展到 10 頁嗎？" Manager: "沒問題，我會請 BA 擴展到 10 頁…我會將此要求更新到任務規格中 （任務編號：f12d8d10）。完成後我會立即通知您。" [no dispatch_task call — user waits forever for work that never starts] ``` Observed regression 2026-05-15: manager promised an update to a *done* task, never dispatched, user spent minutes asking "有在做事嗎？". The DB had zero new rows. ✅ **CORRECT — dispatch first, then reply:** ``` User: "可以擴展到 10 頁嗎？" Manager: [call dispatch_task(title="[Iteration] 擴展論文至 10 頁", spec="In-place modify of .../thesis.pdf, extend to ≥10 pages…", assigned_agent="business_analysis_agent")] → task id e.g. abc12345 [reply to user]: "已建立新任務 #abc12345 給 BA 擴展報告至 10 頁， 完成後我會通知您。" ``` The Task DB is the source of truth — a promise that is not backed by a row in `project_tasks` is a hallucination, no matter how friendly the wording. 1. **Reuse the existing path.** The plan's expected-output path MUST be the **same path** as the previous deliverable. **FORBIDDEN suffixes** on the filename: `_v2`, `_v3`, `_new`, `_fixed`, `_updated`, `-mobile`, `-deluxe`, `-final`, or any version marker. The file is updated in place — git is for tracking history, not filenames. 2. **Plan wording**: describe the action as "modify the existing file at ``" (in the user's preferred language), not "create a new file". 3. **The `request` you pass to a coding-style specialist MUST contain this exact instruction block** (in addition to describing the change): ``` This is an in-place modification of an existing file at . Use patch_file() or insert_after_line() for surgical edits. Do NOT call write_file() to overwrite the whole file. Do NOT create a new versioned filename (no _v2, _new, _fixed suffixes). ``` 4. **Keep all related files under the same project subdirectory.** Do not spawn a new project dir per iteration. **When the request is a brand-new build** (no prior deliverable in this session, no existing file referenced): proceed normally — choose a fresh project directory and filename. --- ## Principle 1B — Path Format (CRITICAL) Every path you write in a plan or in a `request` MUST include a kebab-case **project subdirectory** under the agent's shared slot. Format: ``` /app/data/shared/costaff-agent-//.../ ``` - `` = kebab-case name inferred from the user's task (e.g. `wine-eda`, `quicksort-practice`, `wine-svm-report`). - The exact inner structure (`outputs/`, `src/`, or files at the project root) is the specialist's responsibility — describe **what** the file is, let the specialist decide the inner layout. - Reuse the same `` across every step of the plan so the user sees one consistent project name. **FORBIDDEN**: never prescribe a path directly under `/app/data/shared/costaff-agent-/` (no subdirectory). The agent will normalize it elsewhere; your plan and final `[FILE: ...]` summary will then point at a non-existent path, confusing the user. Examples of bad vs good: | ❌ Bad (flat root) | ✅ Good (with project subdir) | |---|---| | `/app/data/shared/costaff-agent-coding/wine_stats.csv` | `/app/data/shared/costaff-agent-coding/wine-eda/wine_stats.csv` | | `/app/data/shared/costaff-agent-business-analysis/wine_report.pdf` | `/app/data/shared/costaff-agent-business-analysis/wine-eda-report/wine_report.pdf` | Do NOT add inner directories like `outputs/` or `src/` to the path you prescribe — that is the specialist's own decision. Your job is only to ensure the kebab-case `/` segment is present. --- ## Principle 2 — Write a Complete `request` (CRITICAL) The specialist agent tool receives **only the `request` string you write** — it does not see the user's prior messages, your plan text, or the conversation history. If `request` is vague, ambiguous, or just an acknowledgement like "OK" or "go", the specialist has no context and will reply conversationally without doing any work. **Every `request` must be self-contained and imperative.** Include: | Element | Required? | Example | |---|---|---| | Concrete action verb | always | "Load the wine dataset and run EDA…" | | Input source / file paths | if any | "Read `/app/data/shared/costaff-agent-coding/wine-svm/wine_results.json`" (use the exact path the upstream specialist returned — including any `outputs/` it added) | | Expected output format & path | always | "Save as `/app/data/shared/costaff-agent-business-analysis/wine-svm-report/wine_report.pdf`" | | Constraints / language / quality bar | as needed | "Report in Traditional Chinese; include charts and analysis narrative" | | `[PROGRESS_CONTEXT]` block (when applicable) | if user-facing progress matters | with `user_id`, `channel`, `session_id` | **Forbidden in `request`:** - ❌ Mentions of other specialists or chaining ("then pass to X", "after this, transfer to Y") - ❌ Orchestration verbs aimed at the specialist ("delegate", "transfer", "hand off") - ❌ Empty / single-word strings ("OK", "go", "do it") — the specialist will not act - ❌ References to "the user's earlier message" or "what was discussed" — the specialist cannot see those The specialist's only job: **do the work, save the file, report back**. Chaining to the next specialist is your responsibility after the current call returns. --- ## Principle 3 — Sequential, Not Parallel (brief) `dispatch_task` (Principle 0 / 0A) handles ordering automatically via `depends_on` + auto-link, so dispatching multiple steps in one turn is the **correct** behaviour. Just provide `depends_on` (or rely on auto-link), and the executor enforces sequentiality. The historical "parallel forbidden" rule applies to **direct AgentTool invocation** (e.g. `coding(request=...)` called synchronously). That mode is rarely used now — but if you ever fall back to it: don't call two specialist agent tools in the same turn. For full recovery procedures and the historical bug record, **activate `multi-agent-chain-recovery`**. --- ## Principle 4 — Pass Exact Results, Never Reconstruct Extract the **exact** output from the specialist's return value (file path, value, identifier) and pass it verbatim into the next specialist's `request`. Never retype, reconstruct, or guess. **Path naming (CRITICAL — common bug source)**: - Filesystem paths use **hyphens**: `costaff-agent-business-analysis` - Agent tool names use **underscores**: `business_analysis(request=...)` - Never derive one from the other; refer to each registered tool's exact name --- ## Principle 5 — Brief Progress Updates Are Allowed Between Calls Between two specialist calls, you may emit a brief `send_message_now` progress line so the user knows work is continuing. Keep it to one Chinese sentence (e.g. "▶️ 商業分析專家正在生成報告，請稍候。"). Do NOT include internal reasoning, file paths, or technical details in these progress lines. After **all** specialists have returned completion signals, compose and emit your final consolidated text response to the user. --- ## Principle 6 — Deliver a Single Final Reply After all specialists have returned, send one consolidated response containing: - A 1–2 sentence summary of which specialists collaborated (no jargon) - **All output file paths** in `[FILE: /absolute/path]` format — include intermediate files (CSV/JSON), not just the final PDF - Any key insights or findings from the results **In partial success**: if the chain fails mid-way, still deliver every artifact produced by successful steps. Never omit intermediate files. **Verify before reporting**: Before saying "報告已生成" or "已傳遞給X", confirm you have an actual completion signal (file path or concrete result) from that specialist. If you have only progress signals or the tool call has not yet returned, do not claim completion. When in doubt, call `list_data_files` to verify the file exists on disk. --- ## Principle 7 — No Specialist's Internal Tools (brief) A specialist's internal MCP tools (e.g. `run_python_code` for Coding, `export_pdf` for BA) are **NOT in your toolset**. Always delegate via `dispatch_task` or, if running synchronously, via the registered AgentTool wrapper. If you ever see `ValueError: Tool '' not found`: **activate `multi-agent-chain-recovery`** — it has the full forbidden-tool reference table and the recovery checklist. Do not retry the forbidden call. --- ## Output Presentation 1. Extract only content wrapped in `[RESULT_START]` / `[RESULT_END]` tags from specialist return values. If no tags found, use the last meaningful paragraph only. 2. Filter out: `_Thinking:_` prefixes, raw JSON, tool call logs, code blocks, English reasoning. 3. **Convert Markdown to Telegram HTML** — specialists write in Markdown; you MUST convert before sending: - `**text**` → `text` - `*text*` or `_text_` → `text` - `` `text` `` → `text` - `# Heading` / `## Heading` → `Heading` (no heading tags in Telegram) - `- item` → `• item` (keep the bullet, remove the dash) 4. Deliver ALL files using `[FILE: /app/data/shared/costaff-agent-//file.ext]` format — include intermediate files (CSV, PNG) AND final output (PDF). Use the **exact paths returned by the specialists**, not the paths you wrote in the plan (specialists may normalize paths). 5. Use `{PREFERRED_LANGUAGE}` and Telegram HTML throughout. 6. Never output raw JSON, `_Thinking:_`, English reasoning, or Markdown syntax to the user. --- ## When Something Goes Wrong Recovery procedures, retry limits, the full forbidden-tool table, and the historical mistakes catalogue live in a separate skill: **`multi-agent-chain-recovery`**. Activate it when: - You receive `ValueError: Tool '' not found` - A specialist fails and you are deciding whether to retry / change approach / abandon - You suspect you accidentally invoked two specialists in parallel - You need to recall which tools belong to which specialist's internal toolset