Unified Agent + reusable Go agent core.
update docs
+418
-2
+8
web/vitepress/docs/.vitepress/i18n.ts
+8
web/vitepress/docs/.vitepress/i18n.ts
+2
web/vitepress/docs/guide/built-in-tools.md
+2
web/vitepress/docs/guide/built-in-tools.md
···
72
72
- Current depth limit: the built-in subtask mechanism currently allows only one child layer. A child task cannot spawn another child task.
73
73
- Current observer hint: `spawn` accepts an optional `observe_profile` parameter. `default` keeps mid-run previews conservative, `long_shell` is suited to long shell/log output, and `web_extract` suppresses raw noisy output until better stage signals exist.
74
74
75
+
For parameter details, result envelope fields, and the difference between `spawn` and `bash.run_in_subtask=true`, see [Subagents and Subtasks](/guide/subagents).
76
+
75
77
## Runtime Tools
76
78
77
79
These tools are injected dynamically while the agent is running.
+1
web/vitepress/docs/guide/docs-map.md
+1
web/vitepress/docs/guide/docs-map.md
+1
web/vitepress/docs/guide/overview.md
+1
web/vitepress/docs/guide/overview.md
···
19
19
- To get running quickly: read [Quickstart (CLI)](/guide/quickstart-cli)
20
20
- To embed it into a Go project: read [Create Your Own AI Agent in 24 Lines](/guide/build-your-own-agent)
21
21
- To understand long-running entry points: read [Runtime Modes](/guide/runtime-modes)
22
+
- To delegate isolated child work: read [Subagents](/guide/subagents)
22
23
- For pre-production governance: read [Security and Guard](/guide/security-and-guard)
+132
web/vitepress/docs/guide/subagents.md
+132
web/vitepress/docs/guide/subagents.md
···
1
+
---
2
+
title: Subagents and Subtasks
3
+
description: "When to use `spawn`, when to use `bash.run_in_subtask`, and what the runtime guarantees."
4
+
---
5
+
6
+
# Subagents and Subtasks
7
+
8
+
Mistermorph currently has two explicit ways to put work behind a child-task boundary:
9
+
10
+
- `spawn`: starts a child agent with its own LLM loop and an explicit tool whitelist.
11
+
- `bash.run_in_subtask=true`: runs one shell command inside a direct subtask boundary without starting a second LLM loop.
12
+
13
+
Both paths return the same `SubtaskResult` envelope shape and share the same depth limit.
14
+
15
+
## Which entry to use
16
+
17
+
- Use `spawn` when the child work still needs agent-style tool reasoning, such as `read_file` plus `url_fetch`, or a fetch-then-extract flow.
18
+
- Use `bash.run_in_subtask=true` when the work is already one concrete shell command or script.
19
+
- Do not use a child task for trivial one-step work that the parent can complete directly.
20
+
21
+
Current status: both paths are synchronous. The parent waits until the child finishes. This is isolation, not background execution.
22
+
23
+
## `spawn`
24
+
25
+
`spawn` is an engine-scoped tool. It appears when an agent engine is assembled for a run.
26
+
27
+
Parameters:
28
+
29
+
- `task`: required child prompt.
30
+
- `tools`: required non-empty array of tool names the child may use.
31
+
- `model`: optional child model override. Defaults to the parent model.
32
+
- `output_schema`: optional contract label for structured output.
33
+
- `observe_profile`: optional observer hint. Supported values are `default`, `long_shell`, and `web_extract`.
34
+
35
+
Runtime behavior:
36
+
37
+
- The child registry starts from the `tools` names you pass. Unknown or unavailable names are ignored.
38
+
- If none of the requested tool names are available in the parent registry, the call fails.
39
+
- `spawn` is never re-exposed inside the child, even if you include it in `tools`.
40
+
- The current depth limit is `1`, so a child task cannot start another child task.
41
+
- Raw child transcript is not pushed back into the parent loop by default.
42
+
43
+
### About `output_schema`
44
+
45
+
`output_schema` is a schema identifier, not a built-in JSON Schema registry.
46
+
47
+
If you set it:
48
+
49
+
- the child is told to produce JSON final output;
50
+
- the runtime requires the final output to be JSON or JSON-parsable text;
51
+
- the same identifier is echoed back in `output_schema`.
52
+
53
+
Mistermorph does not validate the returned object against a real schema definition for you.
54
+
55
+
## Result Envelope
56
+
57
+
Both `spawn` and direct subtasks return JSON in this shape:
58
+
59
+
```json
60
+
{
61
+
"task_id": "sub_123",
62
+
"status": "done",
63
+
"summary": "subtask completed",
64
+
"output_kind": "text",
65
+
"output_schema": "",
66
+
"output": "child result",
67
+
"error": ""
68
+
}
69
+
```
70
+
71
+
Field meanings:
72
+
73
+
- `status`: currently `done` or `failed`.
74
+
- `summary`: short status text suitable for parent-side progress or preview.
75
+
- `output_kind`: `text` or `json`.
76
+
- `output_schema`: empty for plain text output, or the identifier you passed in.
77
+
- `output`: child result payload.
78
+
- `error`: non-empty only when the child fails.
79
+
80
+
## `bash.run_in_subtask=true`
81
+
82
+
This is the lighter child-task path.
83
+
84
+
- It uses the subtask runner directly and does not start a second LLM loop.
85
+
- Its `output_schema` is fixed to `subtask.bash.result.v1`.
86
+
- Its observer profile is fixed to `long_shell`.
87
+
- The `output` payload contains `exit_code`, truncation flags, `stdout`, and `stderr`.
88
+
89
+
Example payload:
90
+
91
+
```json
92
+
{
93
+
"task_id": "sub_456",
94
+
"status": "done",
95
+
"summary": "bash exited with code 0",
96
+
"output_kind": "json",
97
+
"output_schema": "subtask.bash.result.v1",
98
+
"output": {
99
+
"exit_code": 0,
100
+
"stdout_truncated": false,
101
+
"stderr_truncated": false,
102
+
"stdout": "hello\n",
103
+
"stderr": ""
104
+
},
105
+
"error": ""
106
+
}
107
+
```
108
+
109
+
Use this when you want a separate child-task envelope around one shell step, but do not need the child to make more tool calls.
110
+
111
+
## Config and Embedding
112
+
113
+
- `tools.spawn.enabled` controls only the explicit `spawn` tool entry.
114
+
- Direct subtasks such as `bash.run_in_subtask=true` still use the subtask runtime even if `tools.spawn.enabled=false`.
115
+
- `integration.Config.BuiltinToolNames` can include or omit `spawn`. It is not limited to static tools.
116
+
- If you build an engine directly with `agent.New(...)`, `spawn` is enabled by default. Disable it with `agent.WithSpawnToolEnabled(false)`.
117
+
118
+
Example:
119
+
120
+
```go
121
+
cfg := integration.DefaultConfig()
122
+
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
123
+
cfg.Set("tools.spawn.enabled", true)
124
+
```
125
+
126
+
If you omit `spawn` from `BuiltinToolNames`, the agent loses the explicit child-agent tool, but the underlying subtask runtime can still be used by internal callers such as `bash.run_in_subtask=true`.
127
+
128
+
See also:
129
+
130
+
- [Built-in Tools](/guide/built-in-tools)
131
+
- [Create Your Own AI Agent: Advanced](/guide/build-your-own-agent-advanced)
132
+
- [Config Fields](/guide/config-reference)
+2
web/vitepress/docs/ja/guide/built-in-tools.md
+2
web/vitepress/docs/ja/guide/built-in-tools.md
···
72
72
- 現在の深さ制限: 組み込み subtask 機構は今のところ 1 層までです。子タスクの中からさらに子タスクを起動することはできません。
73
73
- 現在の観測ヒント: `spawn` は任意で `observe_profile` を受け取れます。`default` は実行中プレビューを保守的に扱い、`long_shell` は長いシェル出力やログ向き、`web_extract` は生の高ノイズ出力をいったん抑えます。
74
74
75
+
引数の詳細、返り値 envelope の各フィールド、`bash.run_in_subtask=true` との違いは [Subagent と子タスク](/ja/guide/subagents) を参照してください。
76
+
75
77
## ランタイムツール
76
78
77
79
これらのツールは、Agent 実行中に動的に注入されます。
+1
web/vitepress/docs/ja/guide/docs-map.md
+1
web/vitepress/docs/ja/guide/docs-map.md
+1
web/vitepress/docs/ja/guide/overview.md
+1
web/vitepress/docs/ja/guide/overview.md
···
19
19
- まず素早く動かしたい: [クイックスタート（CLI）](/ja/guide/quickstart-cli)
20
20
- Go プロジェクトに組み込みたい: [24行のコードで自分の AI Agent を作る](/ja/guide/build-your-own-agent)
21
21
- 長時間動かす入口を理解したい: [Runtime モード](/ja/guide/runtime-modes)
22
+
- 子タスクへの委譲を理解したい: [Subagent](/ja/guide/subagents)
22
23
- 本番前のガバナンスを確認したい: [セキュリティと Guard](/ja/guide/security-and-guard)
+132
web/vitepress/docs/ja/guide/subagents.md
+132
web/vitepress/docs/ja/guide/subagents.md
···
1
+
---
2
+
title: Subagent と子タスク
3
+
description: "`spawn` を使う場面、`bash.run_in_subtask` を使う場面、そして runtime が何を保証するかをまとめる。"
4
+
---
5
+
6
+
# Subagent と子タスク
7
+
8
+
Mistermorph には現在、子タスク境界を明示的に作る方法が二つあります。
9
+
10
+
- `spawn`: 独立した LLM loop を持つ子 agent を起動し、使えるツールを明示的に制限する。
11
+
- `bash.run_in_subtask=true`: 1 本の shell コマンドを direct subtask 境界で実行し、2 回目の LLM loop は起動しない。
12
+
13
+
どちらも最後は同じ `SubtaskResult` envelope を返し、深さ制限も共有します。
14
+
15
+
## どちらを使うか
16
+
17
+
- 子タスク側でもツール推論が必要なら `spawn` を使います。たとえば `url_fetch` のあとに抽出する、`read_file` と `bash` を組み合わせる、といった流れです。
18
+
- 仕事の中身がすでに 1 本の shell コマンドなら `bash.run_in_subtask=true` を使います。
19
+
- 親がそのまま実行できる小さな 1 ステップ作業なら、わざわざ子タスクに分けない方がよいです。
20
+
21
+
現状も重要です。どちらも同期実行で、親は子タスク終了まで待ちます。解決しているのは隔離と結果の収束であり、バックグラウンド実行ではありません。
22
+
23
+
## `spawn`
24
+
25
+
`spawn` は engine スコープのツールです。1 回の agent engine が組み上がったときにだけ現れます。
26
+
27
+
引数:
28
+
29
+
- `task`: 必須。子タスクのプロンプト。
30
+
- `tools`: 必須。子タスクが使えるツール名の非空配列。
31
+
- `model`: 任意。子タスク用モデル上書き。省略時は親モデルを使います。
32
+
- `output_schema`: 任意。構造化出力の契約名。
33
+
- `observe_profile`: 任意。観測ヒント。現在は `default`、`long_shell`、`web_extract` をサポートします。
34
+
35
+
実行時の挙動:
36
+
37
+
- 子タスク registry は渡した `tools` だけから作られます。未知の名前や親 registry に存在しない名前は無視されます。
38
+
- 最終的に使えるツールが 1 つも残らなければ呼び出しは失敗します。
39
+
- `tools` に `spawn` 自身を入れても、子タスクには再公開されません。
40
+
- 現在の深さ制限は `1` です。つまり子タスクの中からさらに子タスクは起動できません。
41
+
- 子タスクの生 transcript はデフォルトで親 loop に戻しません。
42
+
43
+
### `output_schema` とは何か
44
+
45
+
`output_schema` は構造化出力の識別子であって、組み込み JSON Schema レジストリではありません。
46
+
47
+
これを指定すると:
48
+
49
+
- 子タスクには JSON の最終出力を求めます。
50
+
- runtime は最終出力が JSON、または JSON として解釈できる文字列であることを要求します。
51
+
- 返り値の envelope では同じ識別子が `output_schema` にそのまま入ります。
52
+
53
+
ただし Mistermorph 自体が実在する schema 定義でオブジェクト検証までは行いません。
54
+
55
+
## 返り値 Envelope
56
+
57
+
`spawn` と direct subtask はどちらも次の形の JSON を返します。
58
+
59
+
```json
60
+
{
61
+
"task_id": "sub_123",
62
+
"status": "done",
63
+
"summary": "subtask completed",
64
+
"output_kind": "text",
65
+
"output_schema": "",
66
+
"output": "child result",
67
+
"error": ""
68
+
}
69
+
```
70
+
71
+
各フィールド:
72
+
73
+
- `status`: 現状は主に `done` または `failed`。
74
+
- `summary`: 親側の進捗表示や短い要約に使う短文。
75
+
- `output_kind`: `text` または `json`。
76
+
- `output_schema`: テキスト出力なら空、構造化出力なら渡した識別子。
77
+
- `output`: 子タスクの本体結果。
78
+
- `error`: 失敗時だけ非空になります。
79
+
80
+
## `bash.run_in_subtask=true`
81
+
82
+
こちらはより軽い子タスク経路です。
83
+
84
+
- subtask runner を直接使い、2 回目の LLM loop は起動しません。
85
+
- `output_schema` は `subtask.bash.result.v1` に固定です。
86
+
- 観測 profile は `long_shell` に固定です。
87
+
- `output` には `exit_code`、切り捨てフラグ、`stdout`、`stderr` が入ります。
88
+
89
+
payload 例:
90
+
91
+
```json
92
+
{
93
+
"task_id": "sub_456",
94
+
"status": "done",
95
+
"summary": "bash exited with code 0",
96
+
"output_kind": "json",
97
+
"output_schema": "subtask.bash.result.v1",
98
+
"output": {
99
+
"exit_code": 0,
100
+
"stdout_truncated": false,
101
+
"stderr_truncated": false,
102
+
"stdout": "hello\n",
103
+
"stderr": ""
104
+
},
105
+
"error": ""
106
+
}
107
+
```
108
+
109
+
長い shell 実行を独立 envelope で包みたいが、子タスク側で追加のツール判断までは不要、という場面で使います。
110
+
111
+
## 設定と組み込み
112
+
113
+
- `tools.spawn.enabled` が制御するのは明示的な `spawn` ツール入口だけです。
114
+
- `tools.spawn.enabled=false` でも、`bash.run_in_subtask=true` のような direct subtask は subtask runtime を使います。
115
+
- `integration.Config.BuiltinToolNames` には `spawn` を含めることも外すこともできます。対象は静的ツールだけではありません。
116
+
- `agent.New(...)` で直接 engine を作る場合、`spawn` はデフォルトで有効です。無効化したいなら `agent.WithSpawnToolEnabled(false)` を使います。
117
+
118
+
例:
119
+
120
+
```go
121
+
cfg := integration.DefaultConfig()
122
+
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
123
+
cfg.Set("tools.spawn.enabled", true)
124
+
```
125
+
126
+
`BuiltinToolNames` から `spawn` を外すと、agent 表面からは明示的な child-agent ツールが消えます。ただし基盤の subtask runtime 自体は残るため、`bash.run_in_subtask=true` のような内部入口は引き続き利用できます。
127
+
128
+
あわせて読む:
129
+
130
+
- [組み込みツール](/ja/guide/built-in-tools)
131
+
- [自分の AI Agent を作る：上級編](/ja/guide/build-your-own-agent-advanced)
132
+
- [設定フィールド](/ja/guide/config-reference)
+2
web/vitepress/docs/zh/guide/built-in-tools.md
+2
web/vitepress/docs/zh/guide/built-in-tools.md
···
72
72
当前深度限制：内置 subtask 机制现在只允许一层子任务，子任务里不能再继续启动下一层子任务。
73
73
当前观察提示：`spawn` 支持可选 `observe_profile` 参数。`default` 会保守处理运行中预览，`long_shell` 适合长命令和日志，`web_extract` 会先压制原始高噪声输出，等后续阶段信号或更高层摘要。
74
74
75
+
参数细节、返回 envelope 字段，以及它和 `bash.run_in_subtask=true` 的差别，见 [Subagent 与子任务](/zh/guide/subagents)。
76
+
75
77
## 运行时工具
76
78
77
79
这些工具会在 Agent 运行时动态注入。
+1
web/vitepress/docs/zh/guide/docs-map.md
+1
web/vitepress/docs/zh/guide/docs-map.md
+3
-2
web/vitepress/docs/zh/guide/overview.md
+3
-2
web/vitepress/docs/zh/guide/overview.md
···
10
10
- 桌面 App，作为个人 AI 助理或者用它管理多个 Mister Morph 实例。
11
11
- CLI 工作流
12
12
- 单独运行面向不同 Channels 的 Agent 进程，例如 Telegram、Slack 等等。
13
-
- 使用 Console Web 界面，也可以用来管理多个 Mister Murph 实例。
13
+
- 使用 Console Web 界面，也可以用来管理多个 Mister Morph 实例。
14
14
- 运行一次性 Agent 任务。
15
15
- Go 内嵌 core 到你的程序，给你的程序注入机魂。
16
16
17
17
## 选择你的路径
18
18
19
19
- 先快速跑通：看 [快速开始](/zh/guide/quickstart-cli)
20
-
- 嵌入到 Go 项目：看 [用 Mister Murph 嵌入 Agent 到自己的程序](/zh/guide/build-your-own-agent)
20
+
- 嵌入到 Go 项目：看 [把 Agent 嵌到自己的程序里](/zh/guide/build-your-own-agent)
21
21
- 了解长期运行入口：看 [Runtime 模式](/zh/guide/runtime-modes)
22
+
- 了解子任务委托：看 [Subagent 与子任务](/zh/guide/subagents)
22
23
- 上线前治理：看 [安全与 Guard](/zh/guide/security-and-guard)
+132
web/vitepress/docs/zh/guide/subagents.md
+132
web/vitepress/docs/zh/guide/subagents.md
···
1
+
---
2
+
title: Subagent 与子任务
3
+
description: "说明什么时候该用 `spawn`，什么时候该用 `bash.run_in_subtask`，以及运行时到底保证什么。"
4
+
---
5
+
6
+
# Subagent 与子任务
7
+
8
+
Mistermorph 现在有两种显式的子任务入口：
9
+
10
+
- `spawn`：启动一个带独立 LLM loop 的子 agent，并显式限制它能用的工具。
11
+
- `bash.run_in_subtask=true`：把一条 shell 命令放进 direct subtask 边界里执行，不会再起第二轮 LLM。
12
+
13
+
两条路径最后都会返回同一种 `SubtaskResult` envelope，也共用同一个深度限制。
14
+
15
+
## 什么时候用哪一种
16
+
17
+
- 子任务还需要自己做工具推理时，用 `spawn`。例如先 `url_fetch` 再抽取，或者组合 `read_file`、`url_fetch`、`bash` 这类步骤。
18
+
- 事情本身已经是一条明确 shell 命令时，用 `bash.run_in_subtask=true`。
19
+
- 很小的一步工作，父任务自己直接做完就行，不要硬拆子任务。
20
+
21
+
当前状态也要说清楚：这两条路径现在都是同步阻塞的。父任务会等子任务结束。它解决的是隔离和收敛，不是后台并发执行。
22
+
23
+
## `spawn`
24
+
25
+
`spawn` 是 engine 级工具。只有某次 agent engine 真正装配出来以后，它才会出现。
26
+
27
+
参数：
28
+
29
+
- `task`：必填，子任务提示词。
30
+
- `tools`：必填，非空字符串数组，表示子任务允许使用的工具名。
31
+
- `model`：可选，子任务模型覆盖；默认继承父任务模型。
32
+
- `output_schema`：可选，结构化输出的约定名。
33
+
- `observe_profile`：可选，观察提示。目前支持 `default`、`long_shell`、`web_extract`。
34
+
35
+
运行时行为：
36
+
37
+
- 子任务 registry 只会从你传入的 `tools` 里挑工具。未知工具名或父 registry 里没有的工具名会被忽略。
38
+
- 如果最后一个可用工具都没剩下，调用会失败。
39
+
- 即使你把 `spawn` 自己放进 `tools`，它也不会再暴露给子任务。
40
+
- 当前深度限制是 `1`，也就是子任务里不能继续起下一层子任务。
41
+
- 默认不会把子任务的原始 transcript 回灌给父 loop。
42
+
43
+
### `output_schema` 到底是什么
44
+
45
+
`output_schema` 只是一个结构化输出的标识，不是内建的 JSON Schema 注册中心。
46
+
47
+
如果你传了它：
48
+
49
+
- 子任务会被提示必须产出 JSON 最终输出；
50
+
- 运行时会要求最终输出是 JSON，或者至少是可解析的 JSON 字符串；
51
+
- 返回 envelope 时会把同一个标识原样放回 `output_schema`。
52
+
53
+
Mistermorph 现在不会替你拿真实 schema 去校验对象字段。
54
+
55
+
## 返回 Envelope
56
+
57
+
`spawn` 和 direct subtask 最后都会返回这种 JSON：
58
+
59
+
```json
60
+
{
61
+
"task_id": "sub_123",
62
+
"status": "done",
63
+
"summary": "subtask completed",
64
+
"output_kind": "text",
65
+
"output_schema": "",
66
+
"output": "child result",
67
+
"error": ""
68
+
}
69
+
```
70
+
71
+
字段含义：
72
+
73
+
- `status`：现在主要是 `done` 或 `failed`。
74
+
- `summary`：给父任务侧做进度预览或简短状态展示用的短文本。
75
+
- `output_kind`：`text` 或 `json`。
76
+
- `output_schema`：纯文本输出时为空；结构化输出时回显你传入的标识。
77
+
- `output`：子任务真正的结果。
78
+
- `error`：子任务失败时才会有内容。
79
+
80
+
## `bash.run_in_subtask=true`
81
+
82
+
这是更轻的一条子任务路径。
83
+
84
+
- 它直接走 subtask runner，不会再起第二轮 LLM。
85
+
- 它的 `output_schema` 固定是 `subtask.bash.result.v1`。
86
+
- 它的观察 profile 固定是 `long_shell`。
87
+
- 它的 `output` 里会带 `exit_code`、截断标记、`stdout` 和 `stderr`。
88
+
89
+
返回 payload 例子：
90
+
91
+
```json
92
+
{
93
+
"task_id": "sub_456",
94
+
"status": "done",
95
+
"summary": "bash exited with code 0",
96
+
"output_kind": "json",
97
+
"output_schema": "subtask.bash.result.v1",
98
+
"output": {
99
+
"exit_code": 0,
100
+
"stdout_truncated": false,
101
+
"stderr_truncated": false,
102
+
"stdout": "hello\n",
103
+
"stderr": ""
104
+
},
105
+
"error": ""
106
+
}
107
+
```
108
+
109
+
如果你只是想把一条长命令包进独立子任务边界里，但不需要子任务自己继续调用别的工具，就用这条路径。
110
+
111
+
## 配置与嵌入
112
+
113
+
- `tools.spawn.enabled` 只控制显式 `spawn` 工具入口。
114
+
- 即使 `tools.spawn.enabled=false`，像 `bash.run_in_subtask=true` 这种 direct subtask 仍然会走 subtask runtime。
115
+
- `integration.Config.BuiltinToolNames` 可以包含 `spawn`，也可以去掉它；它不只控制静态工具。
116
+
- 如果你直接用 `agent.New(...)` 组 engine，`spawn` 默认是开启的；需要关闭时用 `agent.WithSpawnToolEnabled(false)`。
117
+
118
+
示例：
119
+
120
+
```go
121
+
cfg := integration.DefaultConfig()
122
+
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
123
+
cfg.Set("tools.spawn.enabled", true)
124
+
```
125
+
126
+
如果你没把 `spawn` 放进 `BuiltinToolNames`，Agent 表面上就没有显式 child-agent 工具了；但底层 subtask runtime 仍然可以被 `bash.run_in_subtask=true` 这类内部入口使用。
127
+
128
+
延伸阅读：
129
+
130
+
- [内置工具](/zh/guide/built-in-tools)
131
+
- [创建自己的 AI Agent：进阶](/zh/guide/build-your-own-agent-advanced)
132
+
- [配置字段](/zh/guide/config-reference)