Unified Agent + reusable Go agent core.
docs: refresh subagents docs across locales
+335
-222
+4
-5
web/vitepress/docs/guide/built-in-tools.md
+4
-5
web/vitepress/docs/guide/built-in-tools.md
···
40
40
Executes local `bash` commands to call existing CLIs, run one-off conversions, execute scripts, or inspect the local environment.
41
41
42
42
- Key limits: can be disabled via `tools.bash.enabled`; restricted by `deny_paths` and internal deny-token rules; child processes inherit only an allowlisted environment.
43
-
- Current subtask behavior: accepts `run_in_subtask=true` for an explicit direct subtask boundary; when the current runtime exposes a stream sink, stdout/stderr chunks can be previewed before the command exits.
43
+
- Current isolated-execution behavior: accepts `run_in_subtask=true` and runs the command inside one direct boundary; when the current runtime exposes a stream sink, stdout/stderr chunks can appear in the preview stream before the command exits.
44
44
45
45
### `url_fetch`
46
46
···
66
66
67
67
### `spawn`
68
68
69
-
Starts a subtask with its own context and an explicit tool whitelist. The parent agent blocks until the child finishes and receives a structured result envelope.
69
+
Starts a subagent with its own context and an explicit tool whitelist. The parent agent waits synchronously until the inner run finishes, then receives a structured JSON envelope.
70
70
71
-
- Key limits: can be disabled via `tools.spawn.enabled`; the child can use only the tool names passed in `tools`; raw child transcript is not returned to the parent loop by default.
72
-
- Current depth limit: the built-in subtask mechanism currently allows only one child layer. A child task cannot spawn another child task.
71
+
- Key limits: can be disabled via `tools.spawn.enabled`; the inner agent can use only the tool names passed in `tools`; raw transcript is not returned to the parent loop by default.
73
72
- 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
73
75
-
For parameter details, result envelope fields, and the difference between `spawn` and `bash.run_in_subtask=true`, see [Subagents and Subtasks](/guide/subagents).
74
+
For parameter details, result envelope fields, test prompts, and the difference from `bash.run_in_subtask=true`, see [Subagents](/guide/subagents).
76
75
77
76
## Runtime Tools
78
77
+1
-1
web/vitepress/docs/guide/overview.md
+1
-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
+
- To delegate isolated work: read [Subagents](/guide/subagents)
23
23
- For pre-production governance: read [Security and Guard](/guide/security-and-guard)
+109
-64
web/vitepress/docs/guide/subagents.md
+109
-64
web/vitepress/docs/guide/subagents.md
···
1
1
---
2
-
title: Subagents and Subtasks
3
-
description: "When to use `spawn`, when to use `bash.run_in_subtask`, and what the runtime guarantees."
2
+
title: Subagents
3
+
description: "Typical scenarios first, then a high-level overview, then the current implementation details and test prompts."
4
4
---
5
5
6
-
# Subagents and Subtasks
6
+
# Subagents
7
7
8
-
Mistermorph currently has two explicit ways to put work behind a child-task boundary:
8
+
## Common Scenarios
9
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.
10
+
Use a subagent boundary mainly in these cases:
12
11
13
-
Both paths return the same `SubtaskResult` envelope shape and share the same depth limit.
12
+
- A shell command is slow or noisy, and you want its output isolated from the parent loop.
13
+
- The work is still multi-step, but you want the inner execution to operate with a narrower tool set.
14
+
- You want one compact final result instead of leaking raw intermediate output back to the parent.
14
15
15
-
## Which entry to use
16
+
Choose the entry like this:
16
17
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.
18
+
- Use `bash.run_in_subtask=true` for one concrete shell command.
19
+
- Use `spawn` when the inner execution still needs agent-style tool use such as `read_file`, `url_fetch`, or `bash`.
20
+
- Do not add an isolated layer for trivial one-step work the parent can finish directly.
20
21
21
-
Current status: both paths are synchronous. The parent waits until the child finishes. This is isolation, not background execution.
22
+
## Overview
23
+
24
+
Mistermorph currently exposes two explicit subagent entries:
25
+
26
+
| Entry | Starts another LLM loop | Best for | Returns |
27
+
|---|---|---|---|
28
+
| `spawn` | Yes | an inner agent that still needs tools and reasoning | `SubtaskResult` JSON envelope |
29
+
| `bash.run_in_subtask=true` | No | one shell command with isolated execution/output | `SubtaskResult` JSON envelope |
22
30
23
-
## `spawn`
31
+
Shared behavior:
32
+
33
+
- Both are synchronous. The parent waits until the inner run finishes.
34
+
- Both share the same depth limit.
35
+
- Both return the same top-level envelope shape.
36
+
- Neither path sends the raw inner transcript back into the parent loop by default.
37
+
38
+
This feature is about isolation and result collection. It is not a background job system yet.
39
+
40
+
## Current Implementation
41
+
42
+
### `spawn`
24
43
25
-
`spawn` is an engine-scoped tool. It appears when an agent engine is assembled for a run.
44
+
`spawn` is an engine-scoped tool. It appears only after an agent engine is assembled for a run.
26
45
27
46
Parameters:
28
47
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.
48
+
- `task`: required prompt for the inner agent.
49
+
- `tools`: required non-empty tool-name array.
50
+
- `model`: optional model override for the inner agent.
51
+
- `output_schema`: optional structured-output label.
33
52
- `observe_profile`: optional observer hint. Supported values are `default`, `long_shell`, and `web_extract`.
34
53
35
-
Runtime behavior:
54
+
Current behavior:
55
+
56
+
- The inner registry is built from the tool names passed in `tools`.
57
+
- Unknown or unavailable tool names are ignored.
58
+
- If no usable tool remains, the call fails.
59
+
- `spawn` is never re-exposed inside the inner agent, even if listed in `tools`.
60
+
61
+
### `bash.run_in_subtask=true`
62
+
63
+
This is the lighter isolated-execution path.
64
+
65
+
- It uses the direct isolated path behind `bash`.
66
+
- It does not start a second LLM loop.
67
+
- Its `output_schema` is fixed to `subtask.bash.result.v1`.
68
+
- Its observer profile is fixed to `long_shell`.
69
+
70
+
Use it when the inner work is already one concrete shell step and does not need more tool decisions.
71
+
72
+
### Depth Limit
73
+
74
+
The current depth limit is `1`.
36
75
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.
76
+
- A root run can enter one isolated extra layer.
77
+
- A run that is already inside that layer cannot enter another one.
42
78
43
-
### About `output_schema`
79
+
### `output_schema`
44
80
45
-
`output_schema` is a schema identifier, not a built-in JSON Schema registry.
81
+
`output_schema` is only a contract label. It is not a built-in JSON Schema registry.
46
82
47
-
If you set it:
83
+
If you set it for `spawn`:
48
84
49
-
- the child is told to produce JSON final output;
85
+
- the inner agent is told to produce JSON final output;
50
86
- the runtime requires the final output to be JSON or JSON-parsable text;
51
-
- the same identifier is echoed back in `output_schema`.
87
+
- the same identifier is echoed back in the result envelope.
52
88
53
-
Mistermorph does not validate the returned object against a real schema definition for you.
89
+
Mistermorph does not validate the returned object against a real schema definition.
54
90
55
-
## Result Envelope
91
+
### Result Envelope
56
92
57
-
Both `spawn` and direct subtasks return JSON in this shape:
93
+
Both entries return JSON in this shape:
58
94
59
95
```json
60
96
{
···
68
104
}
69
105
```
70
106
71
-
Field meanings:
107
+
Meaning of the fields:
72
108
73
109
- `status`: currently `done` or `failed`.
74
-
- `summary`: short status text suitable for parent-side progress or preview.
110
+
- `summary`: short status text for the isolated run.
75
111
- `output_kind`: `text` or `json`.
76
112
- `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.
113
+
- `output`: the result payload.
114
+
- `error`: set only when the run fails.
115
+
116
+
For `bash.run_in_subtask=true`, `output` is structured JSON with `exit_code`, truncation flags, `stdout`, and `stderr`.
117
+
118
+
### Test Prompts
79
119
80
-
## `bash.run_in_subtask=true`
120
+
These are good smoke tests when `spawn` and `bash` are enabled.
121
+
122
+
#### Prompt 1: `spawn` + `bash`, return one line
81
123
82
-
This is the lighter child-task path.
124
+
```text
125
+
You must call the spawn tool. Do not answer directly. Allow the inner agent to use only bash. Have it run `printf 'alpha\nbeta\ngamma\n' | sed -n '2p'`. Return only the second line.
126
+
```
83
127
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`.
128
+
Expected result: `beta`
88
129
89
-
Example payload:
130
+
#### Prompt 2: `spawn` + `bash`, return structured JSON
131
+
132
+
```text
133
+
You must call the spawn tool and set output_schema to `subagent.demo.echo.v1`. Allow the inner agent to use only bash. Have it run `echo '{"ok":true,"value":42}'`. Return structured JSON only, with no explanation.
134
+
```
135
+
136
+
Expected result:
90
137
91
138
```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
-
}
139
+
{"ok":true,"value":42}
140
+
```
141
+
142
+
#### Prompt 3: `bash.run_in_subtask=true`
143
+
144
+
```text
145
+
Call the bash tool and set `run_in_subtask` to true. Run `printf 'one\ntwo\nthree\n' | tail -n 1`. Do not explain anything. Return only the last line.
146
+
```
147
+
148
+
Expected result: `three`
149
+
150
+
#### Prompt 4: longer isolated shell run
151
+
152
+
```text
153
+
Call the bash tool and set `run_in_subtask` to true. Run `sleep 1; echo SUBAGENT_BASH_OK`. Reply with stdout only.
107
154
```
108
155
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.
156
+
Expected result: `SUBAGENT_BASH_OK`
110
157
111
-
## Config and Embedding
158
+
### Config and Embedding
112
159
113
160
- `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.
161
+
- Direct isolated runs such as `bash.run_in_subtask=true` still work even if `tools.spawn.enabled=false`.
162
+
- `integration.Config.BuiltinToolNames` can include or omit `spawn`.
116
163
- If you build an engine directly with `agent.New(...)`, `spawn` is enabled by default. Disable it with `agent.WithSpawnToolEnabled(false)`.
117
164
118
165
Example:
···
122
169
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
123
170
cfg.Set("tools.spawn.enabled", true)
124
171
```
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
172
128
173
See also:
129
174
+4
-5
web/vitepress/docs/ja/guide/built-in-tools.md
+4
-5
web/vitepress/docs/ja/guide/built-in-tools.md
···
40
40
ローカルの `bash` コマンドを実行します。既存 CLI の利用、一時的な変換処理、スクリプト実行、環境確認に使います。
41
41
42
42
- 主な制約: `tools.bash.enabled` で無効化できます。`deny_paths` と内部 deny-token ルールの制約を受け、子プロセスには許可済み環境変数だけが渡されます。
43
-
- 現在の子タスク挙動: `run_in_subtask=true` を明示すると direct subtask 境界で実行されます。runtime が stream sink を持つ場合、stdout/stderr はコマンド終了前にプレビューへ流れます。
43
+
- 現在の分離実行挙動: `run_in_subtask=true` を明示すると、コマンドは 1 層の direct boundary で実行されます。runtime が stream sink を持つ場合、stdout/stderr はコマンド終了前にプレビューへ流れます。
44
44
45
45
### `url_fetch`
46
46
···
66
66
67
67
### `spawn`
68
68
69
-
独立した文脈と明示的なツールホワイトリストを持つ子タスクを起動します。親 agent は子タスク終了まで同期で待ち、統一された構造化 envelope を受け取ります。
69
+
独立した文脈と明示的なツールホワイトリストを持つ Subagent を起動します。親 agent は内側の実行終了まで同期で待ち、構造化された JSON envelope を受け取ります。
70
70
71
-
- 主な制約: `tools.spawn.enabled` で無効化できます。子タスクが使えるのは引数 `tools` で明示したツールだけです。子タスクの生 transcript はデフォルトで親 loop に戻しません。
72
-
- 現在の深さ制限: 組み込み subtask 機構は今のところ 1 層までです。子タスクの中からさらに子タスクを起動することはできません。
71
+
- 主な制約: `tools.spawn.enabled` で無効化できます。内側の agent が使えるのは引数 `tools` で明示したツールだけです。生 transcript はデフォルトで親 loop に戻しません。
73
72
- 現在の観測ヒント: `spawn` は任意で `observe_profile` を受け取れます。`default` は実行中プレビューを保守的に扱い、`long_shell` は長いシェル出力やログ向き、`web_extract` は生の高ノイズ出力をいったん抑えます。
74
73
75
-
引数の詳細、返り値 envelope の各フィールド、`bash.run_in_subtask=true` との違いは [Subagent と子タスク](/ja/guide/subagents) を参照してください。
74
+
引数の詳細、返り値 envelope の各フィールド、test prompt、`bash.run_in_subtask=true` との違いは [Subagents](/ja/guide/subagents) を参照してください。
76
75
77
76
## ランタイムツール
78
77
+1
-1
web/vitepress/docs/ja/guide/docs-map.md
+1
-1
web/vitepress/docs/ja/guide/docs-map.md
+1
-1
web/vitepress/docs/ja/guide/overview.md
+1
-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
+
- Subagent への委譲を理解したい: [Subagents](/ja/guide/subagents)
23
23
- 本番前のガバナンスを確認したい: [セキュリティと Guard](/ja/guide/security-and-guard)
+108
-63
web/vitepress/docs/ja/guide/subagents.md
+108
-63
web/vitepress/docs/ja/guide/subagents.md
···
1
1
---
2
-
title: Subagent と子タスク
3
-
description: "`spawn` を使う場面、`bash.run_in_subtask` を使う場面、そして runtime が何を保証するかをまとめる。"
2
+
title: Subagents
3
+
description: "まず典型場面、その次に全体像、最後に現在の実装 details と test prompts をまとめる。"
4
4
---
5
5
6
-
# Subagent と子タスク
6
+
# Subagents
7
+
8
+
## 典型的な場面
7
9
8
-
Mistermorph には現在、子タスク境界を明示的に作る方法が二つあります。
10
+
Subagent は主に次のような場面で使います。
9
11
10
-
- `spawn`: 独立した LLM loop を持つ子 agent を起動し、使えるツールを明示的に制限する。
11
-
- `bash.run_in_subtask=true`: 1 本の shell コマンドを direct subtask 境界で実行し、2 回目の LLM loop は起動しない。
12
+
- shell コマンドが長く、出力も多いので、親 loop から切り離したい。
13
+
- 処理自体は複数ステップだが、内側の実行に許すツールを絞りたい。
14
+
- 中間の生出力ではなく、最後に短い結果だけを親へ返したい。
15
+
16
+
入口の選び方は次の通りです。
17
+
18
+
- 1 本の明確な shell コマンドなら `bash.run_in_subtask=true`。
19
+
- 内側の実行でもツール推論が必要なら `spawn`。
20
+
- 親がそのまま終えられる小さな 1 ステップ作業なら、無理に 1 層増やさない。
21
+
22
+
## Overview
12
23
13
-
どちらも最後は同じ `SubtaskResult` envelope を返し、深さ制限も共有します。
24
+
Mistermorph には現在、明示的な Subagent 入口が二つあります。
14
25
15
-
## どちらを使うか
26
+
| 入口 | もう一度 LLM loop を起こすか | 向いている場面 | 返り値 |
27
+
|---|---|---|---|
28
+
| `spawn` | 起こす | 内側の agent 側でもツール利用と推論が必要 | `SubtaskResult` JSON envelope |
29
+
| `bash.run_in_subtask=true` | 起こさない | 1 本の shell コマンドを隔離して実行したい | `SubtaskResult` JSON envelope |
16
30
17
-
- 子タスク側でもツール推論が必要なら `spawn` を使います。たとえば `url_fetch` のあとに抽出する、`read_file` と `bash` を組み合わせる、といった流れです。
18
-
- 仕事の中身がすでに 1 本の shell コマンドなら `bash.run_in_subtask=true` を使います。
19
-
- 親がそのまま実行できる小さな 1 ステップ作業なら、わざわざ子タスクに分けない方がよいです。
31
+
共通点:
20
32
21
-
現状も重要です。どちらも同期実行で、親は子タスク終了まで待ちます。解決しているのは隔離と結果の収束であり、バックグラウンド実行ではありません。
33
+
- どちらも現状は同期実行で、親は内側の実行終了まで待ちます。
34
+
- どちらも同じ深さ制限を共有します。
35
+
- どちらも同じトップレベル envelope を返します。
36
+
- 内側の生 transcript はデフォルトで親 loop に戻しません。
22
37
23
-
## `spawn`
38
+
これは隔離と結果回収の仕組みであって、まだバックグラウンド job システムではありません。
24
39
25
-
`spawn` は engine スコープのツールです。1 回の agent engine が組み上がったときにだけ現れます。
40
+
## 現在の実装
41
+
42
+
### `spawn`
43
+
44
+
`spawn` は engine スコープのツールです。agent engine が 1 回組み上がったときにだけ現れます。
26
45
27
46
引数:
28
47
29
-
- `task`: 必須。子タスクのプロンプト。
30
-
- `tools`: 必須。子タスクが使えるツール名の非空配列。
31
-
- `model`: 任意。子タスク用モデル上書き。省略時は親モデルを使います。
32
-
- `output_schema`: 任意。構造化出力の契約名。
48
+
- `task`: 必須。内側の agent へのプロンプト。
49
+
- `tools`: 必須。非空のツール名配列。
50
+
- `model`: 任意。内側の agent 用モデル上書き。
51
+
- `output_schema`: 任意。構造化出力ラベル。
33
52
- `observe_profile`: 任意。観測ヒント。現在は `default`、`long_shell`、`web_extract` をサポートします。
34
53
35
-
実行時の挙動:
54
+
現在の挙動:
55
+
56
+
- 内側の registry は `tools` からだけ作られます。
57
+
- 未知のツール名や親 registry に存在しない名前は無視されます。
58
+
- 最終的に使えるツールが 1 つも残らなければ失敗します。
59
+
- `tools` に `spawn` を入れても、内側の agent には再公開されません。
60
+
61
+
### `bash.run_in_subtask=true`
62
+
63
+
こちらはより軽い分離実行経路です。
64
+
65
+
- `bash` の direct path を使います。
66
+
- 2 回目の LLM loop は起動しません。
67
+
- `output_schema` は `subtask.bash.result.v1` に固定です。
68
+
- 観測 profile は `long_shell` に固定です。
69
+
70
+
内側の仕事が 1 本の shell ステップで、追加のツール判断が不要ならこちらを使います。
71
+
72
+
### 深さ制限
73
+
74
+
現在の深さ制限は `1` です。
36
75
37
-
- 子タスク registry は渡した `tools` だけから作られます。未知の名前や親 registry に存在しない名前は無視されます。
38
-
- 最終的に使えるツールが 1 つも残らなければ呼び出しは失敗します。
39
-
- `tools` に `spawn` 自身を入れても、子タスクには再公開されません。
40
-
- 現在の深さ制限は `1` です。つまり子タスクの中からさらに子タスクは起動できません。
41
-
- 子タスクの生 transcript はデフォルトで親 loop に戻しません。
76
+
- ルート run は 1 層だけ分離実行に入れます。
77
+
- すでにその層にいる run は次の層へ進めません。
42
78
43
-
### `output_schema` とは何か
79
+
### `output_schema`
44
80
45
-
`output_schema` は構造化出力の識別子であって、組み込み JSON Schema レジストリではありません。
81
+
`output_schema` は契約ラベルであり、組み込み JSON Schema レジストリではありません。
46
82
47
-
これを指定すると:
83
+
`spawn` でこれを指定すると:
48
84
49
-
- 子タスクには JSON の最終出力を求めます。
85
+
- 内側の agent には JSON の最終出力を要求します。
50
86
- runtime は最終出力が JSON、または JSON として解釈できる文字列であることを要求します。
51
-
- 返り値の envelope では同じ識別子が `output_schema` にそのまま入ります。
87
+
- 結果 envelope には同じ識別子が `output_schema` として返ります。
52
88
53
-
ただし Mistermorph 自体が実在する schema 定義でオブジェクト検証までは行いません。
89
+
ただし Mistermorph 自体は実在する schema 定義でオブジェクト検証までは行いません。
54
90
55
-
## 返り値 Envelope
91
+
### 返り値 Envelope
56
92
57
-
`spawn` と direct subtask はどちらも次の形の JSON を返します。
93
+
どちらの入口も最後は次の形の JSON を返します。
58
94
59
95
```json
60
96
{
···
71
107
各フィールド:
72
108
73
109
- `status`: 現状は主に `done` または `failed`。
74
-
- `summary`: 親側の進捗表示や短い要約に使う短文。
110
+
- `summary`: この分離実行の短い状態文。
75
111
- `output_kind`: `text` または `json`。
76
112
- `output_schema`: テキスト出力なら空、構造化出力なら渡した識別子。
77
-
- `output`: 子タスクの本体結果。
78
-
- `error`: 失敗時だけ非空になります。
113
+
- `output`: 結果本体。
114
+
- `error`: 失敗時だけ入ります。
115
+
116
+
`bash.run_in_subtask=true` の場合、`output` は `exit_code`、切り捨てフラグ、`stdout`、`stderr` を含む構造化 JSON です。
117
+
118
+
### Test Prompts
119
+
120
+
最小の smoke test として使いやすい例です。前提は `spawn` と `bash` が有効なことです。
121
+
122
+
#### Prompt 1: `spawn` + `bash`, 1 行だけ返す
123
+
124
+
```text
125
+
You must call the spawn tool. Do not answer directly. Allow the inner agent to use only bash. Have it run `printf 'alpha\nbeta\ngamma\n' | sed -n '2p'`. Return only the second line.
126
+
```
79
127
80
-
## `bash.run_in_subtask=true`
128
+
期待結果: `beta`
81
129
82
-
こちらはより軽い子タスク経路です。
130
+
#### Prompt 2: `spawn` + `bash`, 構造化 JSON を返す
83
131
84
-
- subtask runner を直接使い、2 回目の LLM loop は起動しません。
85
-
- `output_schema` は `subtask.bash.result.v1` に固定です。
86
-
- 観測 profile は `long_shell` に固定です。
87
-
- `output` には `exit_code`、切り捨てフラグ、`stdout`、`stderr` が入ります。
132
+
```text
133
+
You must call the spawn tool and set output_schema to `subagent.demo.echo.v1`. Allow the inner agent to use only bash. Have it run `echo '{"ok":true,"value":42}'`. Return structured JSON only, with no explanation.
134
+
```
88
135
89
-
payload 例:
136
+
期待結果:
90
137
91
138
```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
-
}
139
+
{"ok":true,"value":42}
107
140
```
108
141
109
-
長い shell 実行を独立 envelope で包みたいが、子タスク側で追加のツール判断までは不要、という場面で使います。
142
+
#### Prompt 3: `bash.run_in_subtask=true`
110
143
111
-
## 設定と組み込み
144
+
```text
145
+
Call the bash tool and set `run_in_subtask` to true. Run `printf 'one\ntwo\nthree\n' | tail -n 1`. Do not explain anything. Return only the last line.
146
+
```
147
+
148
+
期待結果: `three`
149
+
150
+
#### Prompt 4: 少し長い shell 実行
151
+
152
+
```text
153
+
Call the bash tool and set `run_in_subtask` to true. Run `sleep 1; echo SUBAGENT_BASH_OK`. Reply with stdout only.
154
+
```
155
+
156
+
期待結果: `SUBAGENT_BASH_OK`
157
+
158
+
### 設定と組み込み
112
159
113
160
- `tools.spawn.enabled` が制御するのは明示的な `spawn` ツール入口だけです。
114
-
- `tools.spawn.enabled=false` でも、`bash.run_in_subtask=true` のような direct subtask は subtask runtime を使います。
115
-
- `integration.Config.BuiltinToolNames` には `spawn` を含めることも外すこともできます。対象は静的ツールだけではありません。
161
+
- `tools.spawn.enabled=false` でも、`bash.run_in_subtask=true` のような direct path は動きます。
162
+
- `integration.Config.BuiltinToolNames` には `spawn` を含めることも外すこともできます。
116
163
- `agent.New(...)` で直接 engine を作る場合、`spawn` はデフォルトで有効です。無効化したいなら `agent.WithSpawnToolEnabled(false)` を使います。
117
164
118
165
例:
···
122
169
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
123
170
cfg.Set("tools.spawn.enabled", true)
124
171
```
125
-
126
-
`BuiltinToolNames` から `spawn` を外すと、agent 表面からは明示的な child-agent ツールが消えます。ただし基盤の subtask runtime 自体は残るため、`bash.run_in_subtask=true` のような内部入口は引き続き利用できます。
127
172
128
173
あわせて読む:
129
174
+6
-6
web/vitepress/docs/zh/guide/built-in-tools.md
+6
-6
web/vitepress/docs/zh/guide/built-in-tools.md
···
40
40
执行本地 `bash` 命令，调用已有 CLI、做一次性格式转换、跑脚本或查询系统信息。
41
41
42
42
关键限制：可通过 `tools.bash.enabled` 关闭；会受 `deny_paths` 和内部 deny-token 规则限制；`bash` 启动的子进程只继承白名单环境变量。
43
-
当前子任务行为：支持显式 `run_in_subtask=true`，把命令放进 direct subtask 边界里执行；如果当前 runtime 暴露了流式 sink，stdout/stderr 会在命令结束前先出现在预览流里。
43
+
当前隔离执行行为：支持显式 `run_in_subtask=true`，把命令放进一层 direct boundary 里执行；如果当前 runtime 暴露了流式 sink，stdout/stderr 会在命令结束前先出现在预览流里。
44
44
45
45
### `url_fetch`
46
46
···
66
66
67
67
### `spawn`
68
68
69
-
启动一个拥有独立上下文和显式工具白名单的子任务。父 agent 会同步等待子任务结束，并收到统一的结构化 envelope。
69
+
启动一个拥有独立上下文和显式工具白名单的 Subagent。父 agent 会同步等待内部执行结束，并收到统一的结构化 JSON envelope。
70
70
71
-
关键限制：可通过 `tools.spawn.enabled` 关闭；子任务只能使用参数 `tools` 里显式列出的工具；默认不会把子任务原始 transcript 回灌给父 loop。
72
-
当前深度限制：内置 subtask 机制现在只允许一层子任务，子任务里不能再继续启动下一层子任务。
73
-
当前观察提示：`spawn` 支持可选 `observe_profile` 参数。`default` 会保守处理运行中预览，`long_shell` 适合长命令和日志，`web_extract` 会先压制原始高噪声输出，等后续阶段信号或更高层摘要。
71
+
关键限制：可通过 `tools.spawn.enabled` 关闭；内部 agent 只能使用参数 `tools` 里显式列出的工具；默认不会把原始 transcript 回灌给父 loop。
72
+
73
+
`spawn` 支持可选 `observe_profile` 参数。`default` 会保守处理运行中预览，`long_shell` 适合长命令和日志，`web_extract` 会先压制原始高噪声输出，等后续阶段信号或更高层摘要。
74
74
75
-
参数细节、返回 envelope 字段，以及它和 `bash.run_in_subtask=true` 的差别，见 [Subagent 与子任务](/zh/guide/subagents)。
75
+
参数细节、返回 envelope 字段、测试 prompt，以及它和 `bash.run_in_subtask=true` 的差别，见 [Subagents](/zh/guide/subagents)。
76
76
77
77
## 运行时工具
78
78
+1
-1
web/vitepress/docs/zh/guide/docs-map.md
+1
-1
web/vitepress/docs/zh/guide/docs-map.md
+1
-1
web/vitepress/docs/zh/guide/overview.md
+1
-1
web/vitepress/docs/zh/guide/overview.md
···
19
19
- 先快速跑通：看 [快速开始](/zh/guide/quickstart-cli)
20
20
- 嵌入到 Go 项目：看 [把 Agent 嵌到自己的程序里](/zh/guide/build-your-own-agent)
21
21
- 了解长期运行入口：看 [Runtime 模式](/zh/guide/runtime-modes)
22
-
- 了解子任务委托：看 [Subagent 与子任务](/zh/guide/subagents)
22
+
- 了解 Subagent 委托：看 [Subagents](/zh/guide/subagents)
23
23
- 上线前治理：看 [安全与 Guard](/zh/guide/security-and-guard)
+99
-74
web/vitepress/docs/zh/guide/subagents.md
+99
-74
web/vitepress/docs/zh/guide/subagents.md
···
1
1
---
2
-
title: Subagent 与子任务
3
-
description: "说明什么时候该用 `spawn`，什么时候该用 `bash.run_in_subtask`，以及运行时到底保证什么。"
2
+
title: Subagents
3
+
description: "分而治之"
4
4
---
5
5
6
-
# Subagent 与子任务
6
+
# Subagents
7
7
8
-
Mistermorph 现在有两种显式的子任务入口：
8
+
## 典型场景
9
9
10
-
- `spawn`：启动一个带独立 LLM loop 的子 agent，并显式限制它能用的工具。
11
-
- `bash.run_in_subtask=true`：把一条 shell 命令放进 direct subtask 边界里执行，不会再起第二轮 LLM。
10
+
Subagent 适合这几类事情：
12
11
13
-
两条路径最后都会返回同一种 `SubtaskResult` envelope，也共用同一个深度限制。
12
+
- 一条 shell 命令很慢、输出很多，想把它和父 Loop 隔开。
13
+
- 一段工作还是多步的，但依然想要用内置工具和配套的体系。
14
+
- 希望任务只返回一个结果，而不是把中间噪声都回灌给父 Loop。
14
15
15
-
## 什么时候用哪一种
16
+
## Overview
16
17
17
-
- 子任务还需要自己做工具推理时，用 `spawn`。例如先 `url_fetch` 再抽取，或者组合 `read_file`、`url_fetch`、`bash` 这类步骤。
18
-
- 事情本身已经是一条明确 shell 命令时，用 `bash.run_in_subtask=true`。
19
-
- 很小的一步工作，父任务自己直接做完就行，不要硬拆子任务。
18
+
Mister Morph 现在对外有两个显式 Subagent 入口：
20
19
21
-
当前状态也要说清楚：这两条路径现在都是同步阻塞的。父任务会等子任务结束。它解决的是隔离和收敛，不是后台并发执行。
20
+
| 入口 | 会不会使用 LLM | 更适合什么 | 返回什么 |
21
+
|---|---|---|---|
22
+
| `spawn` | 会 | 内部 subagent 还要自己调用工具和做推理 | JSON |
23
+
| `bash.run_in_subtask=true` | 不会 | 单条 shell 命令，想隔离执行和输出 | JSON |
22
24
23
-
## `spawn`
25
+
共同点：
24
26
25
-
`spawn` 是 engine 级工具。只有某次 agent engine 真正装配出来以后，它才会出现。
27
+
- 两条路径现在都是同步阻塞，父 Loop 会等内部执行结束。
28
+
- 两条路径返回同一种 JSON envelope。
29
+
- 都不会把内部执行的原始 transcript 发给父 Loop。
30
+
31
+
Subagent 解决隔离、收敛和结果回传的问题，不是完整的后台任务系统
32
+
33
+
## `spawn` 工具
34
+
35
+
`spawn` 是 engine 级工具。
26
36
27
37
参数：
28
38
29
-
- `task`：必填，子任务提示词。
30
-
- `tools`：必填，非空字符串数组，表示子任务允许使用的工具名。
31
-
- `model`：可选，子任务模型覆盖；默认继承父任务模型。
32
-
- `output_schema`：可选，结构化输出的约定名。
39
+
- `task`：必填，给内部 agent 的提示词。
40
+
- `tools`：必填，非空工具名数组。
41
+
- `model`：可选，内部 agent 的模型覆盖。
42
+
- `output_schema`：可选，结构化输出标识。
33
43
- `observe_profile`：可选，观察提示。目前支持 `default`、`long_shell`、`web_extract`。
34
44
35
-
运行时行为：
45
+
当前行为：
46
+
47
+
- 未知工具名或父 registry 里不存在的工具名会被忽略。
48
+
- 如果没有可用工具，调用会失败。
49
+
- `tools` 会忽略 `spawn`。
36
50
37
-
- 子任务 registry 只会从你传入的 `tools` 里挑工具。未知工具名或父 registry 里没有的工具名会被忽略。
38
-
- 如果最后一个可用工具都没剩下，调用会失败。
39
-
- 即使你把 `spawn` 自己放进 `tools`，它也不会再暴露给子任务。
40
-
- 当前深度限制是 `1`，也就是子任务里不能继续起下一层子任务。
41
-
- 默认不会把子任务的原始 transcript 回灌给父 loop。
51
+
## `bash.run_in_subtask=true`
52
+
53
+
更轻的一条隔离执行路径
54
+
55
+
- 不会内置调用 LLM。
56
+
- 内部 `output_schema` 固定为 `subtask.bash.result.v1`。
57
+
- 内部 `observe_profile` 固定为 `long_shell`。
58
+
59
+
## 限制
60
+
61
+
当前 subagent 深度限制是 `1`。即根任务最多进入一层隔离执行。已经在这一层里的 run 不能再继续进入下一层。
42
62
43
-
### `output_schema` 到底是什么
63
+
## 输出
44
64
45
-
`output_schema` 只是一个结构化输出的标识，不是内建的 JSON Schema 注册中心。
65
+
### `output_schema`
46
66
47
-
如果你传了它：
67
+
`output_schema` 只是一个约定名，不是内建的 JSON Schema 注册中心。
48
68
49
-
- 子任务会被提示必须产出 JSON 最终输出；
50
-
- 运行时会要求最终输出是 JSON，或者至少是可解析的 JSON 字符串；
51
-
- 返回 envelope 时会把同一个标识原样放回 `output_schema`。
69
+
给 `spawn` 传了它以后：
52
70
53
-
Mistermorph 现在不会替你拿真实 schema 去校验对象字段。
71
+
- 内部 agent 会被提示产出 JSON 最终输出；
72
+
- 运行时会要求最终输出是 JSON，或者至少是可解析 JSON 的字符串；
54
73
55
-
## 返回 Envelope
74
+
Mistermorph 现在不会按真实 schema 校验对象字段。
56
75
57
-
`spawn` 和 direct subtask 最后都会返回这种 JSON：
76
+
### 返回的 JSON Envelope
58
77
59
78
```json
60
79
{
···
68
87
}
69
88
```
70
89
71
-
字段含义：
90
+
其中，
72
91
73
-
- `status`：现在主要是 `done` 或 `failed`。
74
-
- `summary`：给父任务侧做进度预览或简短状态展示用的短文本。
92
+
- `status`：现在是 `done` 或 `failed`。
93
+
- `summary`：这次 subagent 执行的摘要。
75
94
- `output_kind`：`text` 或 `json`。
76
-
- `output_schema`：纯文本输出时为空；结构化输出时回显你传入的标识。
77
-
- `output`：子任务真正的结果。
78
-
- `error`：子任务失败时才会有内容。
95
+
- `output_schema`：纯文本输出时为空；结构化输出时回显传入的标识。
96
+
- `output`：结果本体，可能是文本或者 JSON
97
+
- `error`：只在失败时有内容。
79
98
80
-
## `bash.run_in_subtask=true`
99
+
对 `bash.run_in_subtask=true` 来说，`output` 会是结构化 JSON，里面包含 `exit_code`、截断标记、`stdout`、`stderr`。
100
+
101
+
## 测试 Prompt
102
+
103
+
**Prompt 1** - `spawn + bash`，只返回一行：
104
+
105
+
```text
106
+
必须调用 spawn tool，不要直接回答。只允许内部 agent 使用 bash。
107
+
让它执行 `printf 'alpha\nbeta\ngamma\n' | sed -n '2p'`。最后只返回第二行。
108
+
```
109
+
110
+
预期结果：`beta`
81
111
82
-
这是更轻的一条子任务路径。
112
+
**Prompt 2** - `spawn + bash`，返回结构化 JSON：
83
113
84
-
- 它直接走 subtask runner，不会再起第二轮 LLM。
85
-
- 它的 `output_schema` 固定是 `subtask.bash.result.v1`。
86
-
- 它的观察 profile 固定是 `long_shell`。
87
-
- 它的 `output` 里会带 `exit_code`、截断标记、`stdout` 和 `stderr`。
114
+
```text
115
+
必须调用 spawn tool，并把 output_schema 设为 `subagent.demo.echo.v1`。
116
+
只允许内部 agent 使用 bash。让它执行 `echo '{"ok":true,"value":42}'`。最终只返回结构化 JSON，不要解释。
117
+
```
88
118
89
-
返回 payload 例子：
119
+
预期结果：
90
120
91
121
```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
-
}
122
+
{"ok":true,"value":42}
123
+
```
124
+
125
+
**Prompt 3** - `bash.run_in_subtask=true`：
126
+
127
+
```text
128
+
请调用 bash tool，并把 `run_in_subtask` 设为 true。执行 `printf 'one\ntwo\nthree\n' | tail -n 1`。不要解释，只返回最后一行。
129
+
```
130
+
131
+
预期结果：`three`
132
+
133
+
**Prompt 4** - 更长一点的隔离 shell 执行：
134
+
135
+
```text
136
+
请调用 bash tool，并把 `run_in_subtask` 设为 true。执行 `sleep 1; echo SUBAGENT_BASH_OK`。最后只回复 stdout。
107
137
```
108
138
109
-
如果你只是想把一条长命令包进独立子任务边界里，但不需要子任务自己继续调用别的工具，就用这条路径。
139
+
预期结果：`SUBAGENT_BASH_OK`
110
140
111
-
## 配置与嵌入
141
+
## 配置
112
142
113
143
- `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)`。
144
+
- 即使 `tools.spawn.enabled=false`，`bash.run_in_subtask=true` 这种 direct path 仍然可以工作。
145
+
146
+
## Integration 开发
147
+
148
+
- `integration.Config.BuiltinToolNames` 可以包含 `spawn`，也可以不包含。
149
+
- 如果你直接用 `agent.New(...)` 组 engine，`spawn` 默认开启；关闭时用 `agent.WithSpawnToolEnabled(false)`。
117
150
118
151
示例：
119
152
···
122
155
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "spawn"}
123
156
cfg.Set("tools.spawn.enabled", true)
124
157
```
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)