Subagents: Delegate Specialized Tasks

Lesson updated November 2, 2026. Example agent files now use keys documented by Vibe: instructions (not system_prompt), active_model (not model), [tools.<tool>] blocks for approvals (the auto_approve key does not exist in an agent file), and real tool names (edit, not edit_file; no list_dir tool). Reminder from Lesson 3: safety is a visual indicator, not a permission. Source: Configuration reference.

The Delegation Principle

In complex projects, certain tasks are independent of one another: analyzing a file’s security while another process generates tests. Instead of handling everything sequentially, Mistral Vibe lets you delegate tasks to subagents. A subagent is an agent that runs independently, completes its mission, and returns a text result to the main agent. It cannot ask the user questions: it must be fully autonomous.

This constraint is the key to everything that follows, and it deserves detail. A subagent runs in its own context, with no access to the current conversation—it knows nothing of what you explained to the main agent five minutes ago. It cannot use ask_user_question and must handle ambiguity on its own. It returns text that the main agent then integrates into its response. Because it is cut off from the exchange, it only makes sense when designed for a specific, well-defined task.

Configuring a Subagent

To turn an agent into a subagent, add the field agent_type = "subagent" to the .toml file. The rest of the configuration follows the usual rules for custom agents.

# ~/.vibe/agents/test-generator.toml
display_name = "Test Generator"
description = "Generates unit tests for given functions."
agent_type = "subagent"
safety = "neutral"
active_model = "codestral"  # alias declared in config.toml (Lesson 2)

instructions = """
You receive source code. Generate comprehensive unit tests:
- Nominal case tests
- Edge case tests (null, undefined, empty strings)
- Expected error tests
Framework: Use the project's test framework (Jest, Vitest, Pytest...).
Return only the test code, ready to copy.
"""

enabled_tools = [
  "read_file",
  "grep",
]

Notice the absence of ask_user_question in the tools: this is not an oversight. A subagent cannot ask for clarification, and the system prompt compensates for this impossibility by specifying the test framework to use and the exact response format in advance.

Concrete Use Cases

The first benefit is parallel work. The main agent can assign multiple tasks simultaneously to different subagents, each working on its own before returning its result.

Main Agent
├── Subagent "test-generator" → generates tests
├── Subagent "doc-writer" → generates documentation
└── Subagent "security-checker" → analyzes vulnerabilities

The second benefit concerns highly specialized tasks. Some require a system prompt radically different from that of the main agent; rather than overloading a single agent with contradictory instructions, you delegate. The SQL optimizer below is a good example: its prompt talks only about indexes, execution plans, and N+1 queries, which would make no sense in a generalist agent.

# ~/.vibe/agents/sql-optimizer.toml
display_name = "SQL Optimizer"
description = "Analyzes and optimizes SQL queries."
agent_type = "subagent"
safety = "safe"
active_model = "mistral-medium-3.5"  # model built into Vibe

instructions = """
Analyze the provided SQL queries:
1. Identify performance issues (N+1, full scan, missing index)
2. Propose optimized queries
3. Suggest indexes to create
Return a structured report with before/after for each query.
"""

enabled_tools = ["read_file", "grep"]

The third benefit, less obvious, is security isolation. A subagent with safety = "safe" cannot modify files, even if the main agent runs in destructive mode: permissions do not inherit downward. You can therefore work in a permissive mode while entrusting analyses to restricted subagents that have no way to act on the repository.

# Subagent that can ONLY read
agent_type = "subagent"
safety = "safe"
enabled_tools = ["read_file", "grep"]

[tools.read_file]
permission = "always"

[tools.grep]
permission = "always"

Vibe also provides a built-in explore subagent, which it uses automatically when it needs to traverse your codebase to answer a question. It operates in read-only mode and returns a summary of what it found—exactly the pattern you replicate with your own subagents.

Designing a Good Subagent

Everything hinges on the autonomy of the system prompt: it must contain all instructions necessary for the subagent to reach the end without ever asking a question. This requires anticipating cases where things go wrong and writing down exactly what the agent must do in those situations, as in the following example.

instructions = """
Analyze ALL TypeScript files in the project.
If a file is not found, move to the next one.
If the test framework is not identifiable, use Vitest by default.
Always return a result, even if partial.
"""

Two reflexes complete this work. Give the subagent strictly the tools it needs—an analysis subagent does not need write_file—and specify the expected output format in the system prompt. The main agent must be able to exploit the result without ambiguity: it, not you, will read this text first.

Rules Set by Vibe

Vibe’s documentation specifies several rules worth knowing before designing your subagents:

• a subagent returns text only to the main agent and cannot ask the user questions;
• it can use only the built-in tools its file authorizes, never MCP tools, connectors, or plugins, and never with broader permissions than the parent agent: its [tools.<tool>] blocks can restrict it further, not expand it;
• its description is mandatory: this indicates to the agent when to use it; a file without a description is flagged rather than loaded;
• it runs on its active_model, or on the session model if none is set;
• the main agent launches it via delegation, using the task tool; it is not selected with --agent;
• by default, up to 32 subagents can exist and run simultaneously (max_subagents, max_concurrent_subagents), and enable_subagents = false in config.toml forbids all delegation.

Without a custom subagent, the agent can still launch a generic subagent equipped with its own instructions and tools.

Key Takeaways

• A subagent is an independent agent that cannot interact with the user
• Configure it with agent_type = "subagent" in the .toml file
• Subagents are ideal for parallel work and specialized tasks
• They offer natural security isolation
• instructions must be fully autonomous: no questions allowed
• Always specify a clear output format in the prompt