How to Configure Sub-Agents in DeepSeek-TUI: A Complete Guide

DeepSeek-TUI supports sub-agents through the agent_spawn, agent_wait, agent_result, and agent_cancel lifecycle tools, configured via the [sub_agents] table in ~/.deepseek/config.toml.

DeepSeek-TUI is a terminal-based AI coding assistant that enables complex, multi-step workflows through child processes called sub-agents. According to the deepseek-ai/awesome-deepseek-agent repository, configuring these sub-agents requires editing your local configuration file and leveraging a deterministic four-tool lifecycle that governs parent-child agent interactions.

What Are Sub-Agents in DeepSeek-TUI?

Sub-agents are specialized child agents that the main model spawns to perform isolated tasks—such as repository analysis, code generation, or file processing—while keeping the overall workflow deterministic. As documented in docs/deepseek-tui.md (lines 81-83) and its Chinese translation docs/deepseek-tui.zh-CN.md, these agents operate as separate contexts that return structured results to the parent session, preventing context overflow and improving task isolation.

Enable Agent or YOLO Mode

Before you can configure sub-agents, you must activate the appropriate runtime mode. Launch DeepSeek-TUI and press Tab until the status indicator shows Agent mode (for manual tool approval) or YOLO mode (for automatic approval of tool calls). Only these modes expose the agent_* lifecycle tools to the model.

Configuring Sub-Agents in ~/.deepseek/config.toml

Sub-agent definitions reside in the user's DeepSeek configuration file, located at ~/.deepseek/config.toml. The configuration follows the layout established in the upstream config.example.toml, using a dedicated [sub_agents] table where each nested key represents a unique agent profile.

Add a sub-agent configuration by creating a table entry with your desired parameters:

# ~/.deepseek/config.toml

[sub_agents.my_helper]
model = "deepseek-v4-pro"
temperature = 0.2
max_output_tokens = 1024

You can define multiple sub-agents by creating additional tables (e.g., [sub_agents.summary], [sub_agents.coder]). Each entry can specify model selection, temperature, token limits, and optional tool-access permissions to restrict what the child agent is allowed to execute.

The Sub-Agent Tool Lifecycle

DeepSeek-TUI exposes four lifecycle tools that manage the creation, execution, and termination of child agents:

• agent_spawn – Creates a new child agent based on a named configuration profile and returns a unique agent_id.
• agent_wait – Blocks the parent agent until the specified child finishes its current turn or task.
• agent_result – Retrieves the final output (text, JSON, or files) produced by the child agent.
• agent_cancel – Terminates a running child agent if it is no longer needed or becomes unresponsive.

These tools are invoked automatically by the model when processing prompts that require delegated work, or they can be referenced explicitly in your instructions.

Spawning and Managing Sub-Agents in Practice

To use a configured sub-agent, reference it by name in your prompt. The model translates your request into a structured tool call. For example, if you configured [sub_agents.summary], you might prompt:

Please analyze the following repository and produce a summary.
Use a sub-agent named "summary" to do the heavy lifting.

The model generates an agent_spawn call:

{
  "name": "agent_spawn",
  "arguments": {
    "agent_name": "summary",
    "prompt": "Read the repository README and list its main features."
  }
}

After spawning, the model typically sequences agent_wait and agent_result calls to retrieve the output:

{
  "name": "agent_wait",
  "arguments": { "agent_id": "xyz789" }
}

{
  "name": "agent_result",
  "arguments": { "agent_id": "xyz789" }
}

The final result appears in the TUI as standard model output, ready for further processing or human review. If the task stalls or becomes irrelevant, the parent can issue an agent_cancel call using the same agent_id.

Summary

• Sub-agents in DeepSeek-TUI are configured via the [sub_agents] table in ~/.deepseek/config.toml, following the schema documented in docs/deepseek-tui.md (lines 81-83).
• You must run the TUI in Agent or YOLO mode to enable the agent_spawn, agent_wait, agent_result, and agent_cancel tools.
• Each sub-agent profile supports custom model, temperature, and max_output_tokens settings.
• The lifecycle follows a strict sequence: spawn the child, optionally wait for completion, retrieve results, and cancel if necessary.

Frequently Asked Questions

Where is the sub-agent configuration file located?

The configuration file is located at ~/.deepseek/config.toml. You must create or edit this file to add [sub_agents] tables that define your child agent profiles, as verified in the repository's documentation at docs/deepseek-tui.md.

Which DeepSeek-TUI modes support sub-agent spawning?

Sub-agent tools are only available when the TUI is running in Agent mode (manual tool approval) or YOLO mode (automatic approval). You can cycle between modes by pressing Tab until the desired mode appears in the status bar.

How do I stop a sub-agent that is taking too long?

Use the agent_cancel tool with the child's agent_id. The parent agent can issue this call to immediately terminate the child process if it becomes unresponsive or if the task is no longer required.

Can different sub-agents use different AI models?

Yes. Each [sub_agents.<name>] table in ~/.deepseek/config.toml supports independent model assignments. This allows you to delegate specific tasks to specialized models—for example, using a lightweight model for quick summaries and a more powerful model for complex code generation within the same session.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}