Document subagent model and reasoning effort (#65505)

## Summary

I came across this gap while trying to understand how choosing a model
for subagents affects their reasoning effort. The agent settings guide
mentions `agent.subagent_model`, but does not explain that relationship.

This PR adds a configuration example and a model selection table
covering reasoning and speed settings, explains how to find supported
effort values, keeps the settings reference and Rust field documentation
aligned, and links the explanation from the agent settings and tool
guides.

## Self-review

- [x] I’ve reviewed my diff for quality, security, reliability, and
performance.
- [x] UI changes follow the
[checklist](https://zed.dev/docs/development/ui-checklist).
- [x] Tests cover the new or changed behavior.

---

Release Notes:

- N/A

---------

Co-authored-by: Smit Barmase <heysmitbarmase@gmail.com>
This commit is contained in:
Dom Porada
2026-10-13 15:28:45 +00:00
committed by GitHub
parent d3267a39ff
commit 05d5e10362
4 changed files with 54 additions and 1 deletions
+3 -1
View File
@@ -282,7 +282,9 @@ pub struct AgentSettingsContent {
pub max_content_width: Option<crate::PixelSetting>,
/// The default model to use when creating new chats and for other features when a specific model is not specified.
pub default_model: Option<LanguageModelSelection>,
/// The model to use for subagents spawned via the `spawn_agent` tool. Defaults to the parent agent's model when not specified.
/// Model to use for subagents. Defaults to the parent thread's model and its
/// thinking, effort, and speed settings when not specified. If the configured
/// model is unavailable, the parent thread's model is used instead.
pub subagent_model: Option<LanguageModelSelection>,
/// Favorite models to show at the top of the model selector.
#[serde(default)]
+44
View File
@@ -156,6 +156,50 @@ Zed supports feature-specific model settings for Inline Assistant, Git commit ge
See [LLM Providers](./llm-providers.md) for model access, and [All Settings](../reference/all-settings.md) for the complete settings reference.
### Subagent Models {#subagent-models}
By default, Zed Agent's subagents inherit the parent thread's model, thinking setting, reasoning effort, and speed. Set `agent.subagent_model` in `settings.json` to choose separate model, reasoning, and speed settings. You can override the model by asking the agent to use a specific model for a subagent. When that model matches the provider and model in `agent.subagent_model`, its `enable_thinking`, `effort`, and `speed` settings are preserved. This setting does not configure [External Agents](./external-agents.md).
Configure this setting with a `provider` and `model`. To choose a reasoning effort for a model that supports it, also set `enable_thinking` and `effort`:
```json [settings]
{
"agent": {
"subagent_model": {
"effort": "low",
"enable_thinking": true,
"model": "claude-opus-4-6",
"provider": "anthropic"
}
}
}
```
Choose an `effort` value supported by the selected model. Omitting `effort` from this object does not inherit the parent's effort. It leaves effort to the selected provider and model's default behavior. Omitting `enable_thinking` defaults to `false`, although models that cannot disable thinking still use it.
To find supported effort values:
1. Choose the target provider and model from the model selector in a native Zed Agent thread, even if it is already selected, to save it as `agent.default_model`.
2. Enable thinking if it is off, then open the thinking effort menu. The "Change Thinking Effort" menu lists the model's supported levels. If the model offers no effort choices, omit `effort`.
3. Choose a level and read `agent.default_model.effort` in `settings.json` for the exact value to use in `agent.subagent_model.effort`.
These controls change the current thread and saved default model settings, and can update a matching favorite model. Restore your previous selections afterward if needed.
The optional `speed` field accepts `"fast"` or `"standard"`. It applies only to models that support fast mode. Omitting it from `agent.subagent_model` leaves speed unspecified rather than inheriting the parent's speed.
| Model Selection | Settings Applied |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No specific model requested, and `agent.subagent_model` is unset | Inherits the parent thread's current thinking, effort, and speed settings. |
| No specific model requested, and `agent.subagent_model` is configured | Uses `enable_thinking`, `effort`, and `speed` from `agent.subagent_model`. |
| Requested model matches the provider and model in `agent.subagent_model` | Uses `enable_thinking`, `effort`, and `speed` from `agent.subagent_model`. |
| Requested model differs from `agent.subagent_model`, or `agent.subagent_model` is unset | Uses matching `agent.default_model` settings. Without a match, enables thinking if supported, uses the model's default effort when available, and leaves speed unspecified. |
When using matching `agent.default_model` settings, unsupported or omitted `effort` falls back to the selected model's default effort, when available.
If the configured model is unavailable, subagents use the parent thread's model and its thinking, effort, and speed settings.
The agent can only request a model for a subagent, not a separate effort or speed. Requesting the parent's own model is not the same as requesting no specific model: the table's rules for requested models apply instead of inheriting the parent's current settings. Subagents with a requested or configured model do not follow later changes to the parent's model, reasoning, or speed settings. Resuming a subagent keeps its existing model, reasoning, and speed settings.
## Model Temperature {#model-temperature}
Most Zed AI features use the selected model's default generation behavior.
+2
View File
@@ -109,4 +109,6 @@ Loads instructions from an available [Skill](./skills.md) so the agent can follo
Spawns a subagent with its own context window to perform a delegated task. Useful for running parallel investigations, completing self-contained tasks, or performing research where only the outcome matters. Each subagent has access to the same tools as the parent agent.
To configure a subagent's model, reasoning effort, and speed, see [Subagent Models](./agent-settings.md#subagent-models).
**Example:** While refactoring the authentication module, spawn a subagent to investigate how session tokens are validated elsewhere in the codebase. The parent agent continues its work and reviews the subagent's findings when it completes — keeping both context windows focused on a single task.
+5
View File
@@ -6062,6 +6062,11 @@ Visit [AI Quick Start](../ai/quick-start.md) under the AI section to learn more
`boolean` values
### Subagent Model {#agent-subagent-model}
- Description: The model, reasoning, and speed settings for new Zed Agent subagents. This setting does not configure external agents. See [Subagent Models](../ai/agent-settings.md#subagent-models).
- Setting: `agent.subagent_model`
## Collaboration Panel
- Description: Customizations for the collaboration panel.