Agents, subagents and teams in DeepSeek Harness

Agents, subagents, and teams are three layers, not three synonyms. The main agent decides, subagents split work, and teams coordinate; mixing them usually produces excessive concurrency and tasks waiting on each other.

Three layers

Identify responsibilities before configuring.

The main agent is the decision center, the subagent is the execution unit, and the team is the organization. The main agent decides whether to delegate, how many, and when to collect results (source). A subagent takes a clear subtask, runs in its own context, and returns results; isolation enables parallelism and adds merge cost. A team defines roles, tasks, and sequencing for work with dependencies (source).

Subagents: split and isolate

The value is parallelism and isolation, not smarter output.

1. Split into independent subtasks: retrieval, review, generation, verification.
2. Write input, output, and completion criteria for each.
3. Let the main agent dispatch and collect results.
4. Check whether a subagent overstepped: edited the wrong files or called the wrong tools.
5. Resolve conflicts in the main agent, not between subagents.

Isolation cuts both ways, and strong dependencies do not suit subagents. A subagent does not see the whole session, reducing interference but possibly missing constraints; the task brief must carry its own premises. If step two needs step one, serial is faster; parallel only adds waiting and merge work.

Teams: roles, concurrency, coordination

Teams solve "how multiple roles work together," centered on division and order.

1. Define roles: planning, implementation, review.
2. Define tasks and dependencies: what can parallelize and what must wait.
3. Set a concurrency cap based on quota and machine capacity.
4. Define handoff artifacts so the next role can continue.
5. Define termination: when to stop, roll back, or hand to a human.

The cost of a team is coordination, and concurrency is not free. More roles mean more handoffs and waiting; two or three roles usually suffice. High concurrency queues, times out, and deadlocks; get serial working first.

Agent presets: fix the configuration

Presets solve "configuration differs every run."

1. Choose a stable working configuration as the baseline.
2. Fix model and key parameters.
3. Document when the preset applies and when it does not.
4. Give it a recognizable name and reference it from teams and subagents.
5. Record versions when changing it.

A preset is "how to configure," a team is "how to collaborate," and presets should not change often. Changing one alters behavior for every task referencing it; create a new preset for experiments instead of editing the baseline.

Comparison

Choose by task shape, not habit.

If the main agent can solve it, do not split; teams are heavier, not "more advanced." Splitting adds context isolation, merging, and coordination costs. Use a team only when division and dependencies truly exist.

Configuration entry points

The three layers are configured in different places.

1. Main agent: session-level model, tools, and prompts.
2. Subagents: dispatched by the main agent with task scope and tools.
3. Team: a team plugin or configuration defining roles, tasks, and concurrency.
4. Preset: the agent preset management entry.
5. Concurrency: set in the team or runtime configuration, not hard-coded per task.

Draw the relationships before changing configuration, and record the effective version. Otherwise one place changes while another keeps the old value, and multiple versions make diagnosis ambiguous.

Common failures

Four failures dominate multi-agent work.

1. Too much concurrency: queueing, timeouts, exhausted quota; reduce first.
2. Mutual waiting: circular dependencies; draw the graph and break the cycle.
3. Subagent lacks context: missing premises; put constraints in the dispatch brief.
4. Lost results: no handoff artifact; standardize output shape.

All four are coordination design issues, not model capability. Fix the structure before changing models.

Selection advice

Start light and upgrade by need.

1. Try the main agent first.
2. Add subagents when independent parallel work exists.
3. Add a team when roles and dependencies exist.
4. Extract a preset when a task repeats.
5. Keep a rollback path at each step.

The upgrade criterion is "benefit exceeds coordination cost"; do not use multi-agent for its own sake. Parallel time saved must exceed splitting and merging cost. Tools serve goals; keep simple work simple.

Next steps

Identify the layer, then choose by task shape. For team orchestration, read How to use multi-agent teams. For presets, read What dsh agent presets are. To separate workflow, schedule, and subagents, read Workflow vs schedule vs subagent.

Sources: DeepSeek Harness docs, dsh-agent-teams plugin page, dsh CLI README