feat(example): add multi_agent_support — customer-support triage flagship example

.claude/settings.local.json

@@ -20,7 +20,8 @@
       "Bash(do uv:*)",
       "Bash(echo \"$f OK\")",
       "Bash(done)",
-      "Bash(python3:*)"
+      "Bash(python3:*)",
+      "Bash(rtk git *)"
     ]
   }
 }

docs/examples.en.md

@@ -1,17 +1,19 @@
 # Examples
 
-This repository currently maintains only two example groups.
+This repository currently maintains three example groups: `quickstart`, `production_coding_agent`, and `multi_agent_support`.
 
-This is not a reduction — it reflects a deliberate decision to keep the repository focused on real, runnable, testable examples and to stop documentation from referencing deleted historical directories.
+All other historical examples are retired — the repository is deliberately focused on real, runnable, testable examples to stop documentation from referencing deleted directories.
 
-Unless noted otherwise, both examples use MiniMax's Anthropic-compatible API endpoint and require `MINIMAX_API_KEY`.
+Unless noted otherwise, examples that need a real LLM use MiniMax's Anthropic-compatible endpoint and expect `MINIMAX_API_KEY` (or equivalent `LLM_API_KEY` / `LLM_API_BASE` / `LLM_MODEL`).
 
 ## Which One to Start With
 
 - First time running the repository
   - Start with `quickstart`
-- Want a high-density, production-layered example
+- Want a high-density, production-layered *single-agent* example
   - Go to `production_coding_agent`
+- Want a complete *multi-agent* application exercising the `agent_router` seam (customer-support triage)
+  - Go to `multi_agent_support`
 - Want to learn custom plugin / seam development
   - Read [Plugin Development](plugin-development.md) first
   - Then look at `tests/fixtures/` and `examples/production_coding_agent/app/`
@@ -99,6 +101,55 @@ Related tests:
 uv run pytest -q tests/integration/test_production_coding_agent_example.py
 ```
 
+## `examples/multi_agent_support/`
+
+Purpose:
+
+- A complete multi-agent application that exercises the `agent_router` seam end-to-end
+- Customer-support triage scenario: concierge → refund_specialist / tech_support → account_lookup
+- Covers every contract in the `agent-router` spec: `delegate` / `transfer`, all three `session_isolation` modes, `max_delegation_depth` enforcement, `AgentNotFoundError`, `default_child_budget` fallback, and `metadata["handoff_from"]` propagation
+
+Key files:
+
+- `examples/multi_agent_support/agent_mock.json` — offline mock config (four agents)
+- `examples/multi_agent_support/agent_real.json` — real-LLM config (Anthropic-compatible)
+- `examples/multi_agent_support/app/deps.py` — `SupportDeps` (`CustomerStore` + `TicketStore` + `trace`)
+- `examples/multi_agent_support/app/plugins.py` — `ToolPlugin` subclasses (lookup, router-bound, action)
+- `examples/multi_agent_support/app/protocol.py` — pydantic envelopes (`CustomerIntent`, `TicketDraft`, `DelegationTraceEntry`)
+- `examples/multi_agent_support/scenarios.py` — the four scenario functions shared by demo and integration test
+- `examples/multi_agent_support/run_demo_mock.py` — offline demo (no API key)
+- `examples/multi_agent_support/run_demo_real.py` — real-LLM demo
+
+Demonstrates:
+
+- All three `agent_router.delegate` session isolation modes (shared / isolated / forked)
+- `agent_router.transfer` handoff semantics + `HandoffSignal` capture
+- Nested delegation depth propagation via `RunRequest.metadata`
+- Error paths: `DelegationDepthExceededError` and `AgentNotFoundError`
+- How to layer an app-defined protocol (deps, pydantic envelopes, trace log) on top of SDK seams
+
+Run:
+
+```bash
+# Offline mock (default CI path)
+uv run python examples/multi_agent_support/run_demo_mock.py
+```
+
+```bash
+# Real LLM (needs .env)
+cp examples/multi_agent_support/.env.example examples/multi_agent_support/.env
+# edit .env with LLM_API_KEY / LLM_API_BASE / LLM_MODEL
+uv run python examples/multi_agent_support/run_demo_real.py
+```
+
+Related tests:
+
+```bash
+uv run pytest -q tests/integration/test_multi_agent_support_example.py
+```
+
+Further reading: [multi-agent-support-example](multi-agent-support-example.en.md) — a walkthrough of the four scenarios, naming the `agent-router` spec requirement each exercises.
+
 ## Running Integration Tests
 
 All maintained examples have accompanying integration tests:
@@ -126,8 +177,9 @@ For the most effective path through this repository:
 
 1. `quickstart`
 2. `production_coding_agent`
-3. [Plugin Development](plugin-development.md)
-4. [Repository Layout](repository-layout.md)
+3. `multi_agent_support` (if your use case involves multi-agent coordination)
+4. [Plugin Development](plugin-development.md)
+5. [Repository Layout](repository-layout.md)
 
 ## research_analyst
 

docs/examples.md

@@ -1,18 +1,20 @@
 # 示例说明
 
-当前仓库只保留两组维护中的 example。
+当前仓库保留三组维护中的 example：`quickstart`、`production_coding_agent`、`multi_agent_support`。
 
-这不是“缩水”，而是把仓库收回到真实、可跑、可测的维护面，避免文档继续引用已经删除的历史目录。
+其余历史示例已下线 —— 把仓库收回到真实、可跑、可测的维护面，避免文档继续引用已经删除的历史目录。
 
-除特别说明外，这两组 example 都默认使用 MiniMax 的 Anthropic-compatible 接口，
-需要 `MINIMAX_API_KEY`。
+除特别说明外，涉及真实 LLM 的 example 都默认使用 MiniMax 的 Anthropic-compatible 接口，
+需要 `MINIMAX_API_KEY`（或等价的 `LLM_API_KEY`/`LLM_API_BASE`/`LLM_MODEL`）。
 
 ## 怎么选
 
 - 第一次跑仓库
   - 先看 `quickstart`
-- 想看一个高设计密度、贴近真实应用分层的例子
+- 想看一个高设计密度、贴近真实应用分层的单 agent 例子
   - 看 `production_coding_agent`
+- 想看一个完整行使 `agent_router` seam 的多 agent 应用（客服分诊）
+  - 看 `multi_agent_support`
 - 想学自定义 plugin / seam
   - 先读 [插件开发](plugin-development.md)
   - 再看 `tests/fixtures/` 和 `examples/production_coding_agent/app/`
@@ -100,6 +102,55 @@ uv run python examples/production_coding_agent/run_benchmark.py
 uv run pytest -q tests/integration/test_production_coding_agent_example.py
 ```
 
+## `examples/multi_agent_support/`
+
+用途：
+
+- 演示一个完整行使 `agent_router` seam 的多 agent 应用
+- 客服分诊场景：concierge → refund_specialist / tech_support → account_lookup
+- 覆盖 `agent_router` 规范的每一条契约：`delegate` / `transfer`、三种 `session_isolation` 模式、`max_delegation_depth` 限制、`AgentNotFoundError`、`default_child_budget` 兜底、`metadata["handoff_from"]` 传播
+
+关键文件：
+
+- `examples/multi_agent_support/agent_mock.json` — 离线 mock 配置（四个 agent）
+- `examples/multi_agent_support/agent_real.json` — 真实 LLM 配置（Anthropic-compatible）
+- `examples/multi_agent_support/app/deps.py` — `SupportDeps`（`CustomerStore` + `TicketStore` + `trace`）
+- `examples/multi_agent_support/app/plugins.py` — `ToolPlugin` 子类（lookup、router-bound、action）
+- `examples/multi_agent_support/app/protocol.py` — pydantic 信封（`CustomerIntent`、`TicketDraft`、`DelegationTraceEntry`）
+- `examples/multi_agent_support/scenarios.py` — demo 和集成测试共享的四个场景函数
+- `examples/multi_agent_support/run_demo_mock.py` — 离线演示（无 API key）
+- `examples/multi_agent_support/run_demo_real.py` — 真实 LLM 演示
+
+展示内容：
+
+- `agent_router.delegate` 的三种 `session_isolation` 模式（shared / isolated / forked）
+- `agent_router.transfer` 的 handoff 语义 + `HandoffSignal` 捕获
+- 嵌套 delegation 的 depth 传递（通过 `RunRequest.metadata`）
+- 错误路径：`DelegationDepthExceededError` 与 `AgentNotFoundError`
+- 如何把 app-defined 协议（deps、pydantic 信封、trace 日志）叠在 SDK seam 之上
+
+运行：
+
+```bash
+# 离线 mock（CI 默认路径）
+uv run python examples/multi_agent_support/run_demo_mock.py
+```
+
+```bash
+# 真实 LLM（需要 .env）
+cp examples/multi_agent_support/.env.example examples/multi_agent_support/.env
+# 编辑 .env 填入 LLM_API_KEY / LLM_API_BASE / LLM_MODEL
+uv run python examples/multi_agent_support/run_demo_real.py
+```
+
+相关验证：
+
+```bash
+uv run pytest -q tests/integration/test_multi_agent_support_example.py
+```
+
+进一步阅读：[multi-agent-support-example](multi-agent-support-example.md) —— 四个场景逐个走，每个场景标注它行使了 `agent-router` 规范的哪条契约。
+
 ## 如果你想学自定义扩展
 
 虽然当前 repo 不再保留一堆独立 demo 目录，但”怎么自定义”并没有消失，主要参考面是：
@@ -118,8 +169,9 @@ uv run pytest -q tests/integration/test_production_coding_agent_example.py
 
 1. `quickstart`
 2. `production_coding_agent`
-3. [插件开发](plugin-development.md)
-4. [仓库结构](repository-layout.md)
+3. `multi_agent_support`（如果你的场景涉及多 agent 协作）
+4. [插件开发](plugin-development.md)
+5. [仓库结构](repository-layout.md)
 
 ## 运行集成测试