DeepSeek SuperAgent Architecture Explained: Design, Code & Our Flock Practice

Introduction

This article is excerpted from the Alibaba Cloud AI Agent Handbook (GitHub: https://github.com/aliyun/ai-agent-handbook). It introduces DeepSeek SuperAgent's design and the author's similar technical and product exploration.

1. The Problem: Human Attention Is the Bottleneck

A typical developer afternoon: using an agent to fix bugs, write specs, and run data simultaneously. The problem isn't that individual agents aren't strong—each window's agent performs well. The issue is that scheduling falls on the human : who is waiting, which message relates to which task, where decisions were made—all rely on human memory. The DSH team observed that a person can typically track only 3 to 5 active sessions . Their summary is precise: single-task ceiling depends on the model; multi-task ceiling depends on human attention .

Therefore, SuperAgent's goal in one sentence: make the human feel there is only one agent, yet it can do many things at once . To achieve this it must satisfy four requirements:

Continuous : a mention in chat about approach A, later changed to approach B in code review—the agent connects them without the user hunting for context.

Efficient : no need to wait for the previous task to finish before accepting the next.

Proactive : observes the environment, acts when worthwhile, stays silent otherwise.

Persistent : always online, self-recovers from failures, doesn't stop when the laptop closes.

2. DeepSeek SuperAgent Architecture Deep Dive

2.1 Dual-Layer Architecture: Why Separate Router and Worker

Designing agent systems faces an inherent tension: continuity vs. throughput . Putting everything in one session gives maximum context continuity but forces serial execution via a single ReAct loop—tasks queue and interrupt each other. Spawning a new session per task enables concurrency but loses cross-task awareness and floods the user with multiple conversations.

The solution: decouple the two concerns.

Router handles continuity : all human communication and inter-task coordination go through it; it is the system's global sequence point and memory.

Worker handles concurrency : each task gets an isolated session. To avoid blocking the Router, it does no actual work—DSH even withholds Bash tools from it, and a lighter model often suffices. Workers use the strongest model; reasoning and tool calls stay inside their session, reporting conclusions back to the Router for unified external replies.

A common question: how does this differ from a Team Lead in an Agent Team? The Team Lead dives into a task to decompose it, while the Router only manages task-to-task relationships. Workers may internally use Subagents or Teams—transparent to the Router. The original text notes: if a prompt constrains the Team's main session to not do hands-on work, "it can also be viewed as this dual-layer architecture." Thus dual-layer is about responsibility separation, not a specific component.

2.2 Event-Driven: Most Messages Don't Need the Model

To eliminate the "human must initiate" bottleneck, agents must be woken by the environment: group messages, code comments, CI results—these are Triggers . Real-world event streams are high-noise, low-trigger-rate; sending every event to the model is slow and expensive.

DeepSeek SuperAgent splits into a Fast Path (rules) and a Slow Path (model) . Rules prioritize certain groups or users (e.g., product managers or bosses). In DSH's experimental load, ~300 messages yielded only ~20 actual work requests.

The clever part is routing. A sequence of events under the same PR or group topic is a Thread . Once a Worker receives a task, it subscribes to that Thread; subsequent events are delivered directly to it, bypassing the Router—called subscription pass-through . Workers and Threads are many-to-many: two Workers subscribing to the same PR see each other's actions, answering "won't Workers clash without communication?"

DeepSeek ran ablation experiments showing pass-through's value: removing it barely changed task completion time, but the Router made ~30% more decisions and read ~37% more cached tokens. It saves Router load, not task time.

2.3 Context Organization: Inline, Spill, and Chain-of-Recall

Events enter the session; the next question is how much to stuff into the context window. Too much crowds the window and dilutes model attention; too little forces repeated tool calls, increasing steps. DSH treats the window as a cache, borrowing two terms from compiler optimization:

Inline : recent, likely-needed info placed directly in the window, saving a tool call.

Spill : content exceeding budget or low-frequency kept outside, with only a summary or reference.

Placement follows locality: e.g., adjacent IM messages around a message, adjacent comments around a code review comment.

Applying this rule consistently across Trigger, Thread, Worker Session objects builds a reference graph: each object inlines the ID of the next hop. The model can start from the current event and hop along references—this is Chain-of-Recall . The Router doesn't need all history in its window; when an old task is mentioned, it can traverse the chain to retrieve it.

The original admits its boundary: this mainly solves recent tasks; cross-month long-term memory remains a bottleneck.

2.4 Full-Duplex: Is It Just Codex's Interrupt?

Codex's steer injects a message into a running turn, visible at the next reasoning step. DSH's docs also use steer. But the model loop is "reason, call tool, wait result, reason again." If currently waiting on a synchronous tool, the next reasoning step arrives only after the tool returns. So even with interrupt, saying "stop" might wait 20 minutes for a test to finish.

DSH's "full-duplex" targets this blocking. It turns long-running commands and subtasks into async start / stop: call returns "started" immediately, loop continues; tool runs in background, result delivered as a new event; model can also actively stop. Reasoning steps stay short, new messages processed after the current step ends. The model still runs step-by-step—no true parallelism.

In the prototype, any foreground command exceeding 5 seconds automatically moves to background, explicitly to allow the next step to receive new messages.

2.5 Compute, State, and Environment Separation: A Concrete Example

Local agents bind compute (Agent Loop), session state, and real work environment to one machine. Separating them changes everything:

Two layers of decoupling:

Compute and state separated : Agent Loop in stateless cloud containers, Session in database; container restart/replacement doesn't lose progress.

Compute and environment separated : local machine has uncommitted changes, private credentials, intranet dependencies—rebuilding in cloud is costly and leaky. Since the environment itself is hard to sync, leave it in place, install only a lightweight stateless daemon to execute commands and return results. When the device comes back online, the cloud agent continues the steps needing that machine. This is the general BYOM (Bring Your Own Machine) solution. Instead of rebuilding the environment, push operations that need local interaction to the local machine , keeping the overall environment lightweight. (Trade-off: depends on device being online. When offline, that step pauses, resumes on reconnect—progress safe because state is in cloud. Cursor Background Agents and Codex cloud tasks take the other route: rebuild environment in cloud. Pros: no dependency on your machine, parallelizable, good isolation. Cons: replication cost. Different trade-offs, no absolute better.)

An often-overlooked failure mode: agent process alive but model spinning in place. Liveness probes won't detect this. DSH adds an independent Watchdog session that periodically judges whether each Worker makes substantive progress or has drifted.

2.6 Interpreting Experimental Results

The headline number is "nearly 2x faster," but the full table needs careful reading. P50 = median completion time; P95 = near-worst-case, reflecting the slowest tasks.

Super Agent : P50 12.4 min, P95 15.7 min, Read Cache Tokens 23.23M (3.8x baseline)

Single session, prompt prefers delegation : P50 13.8 min, P95 29.0 min, Read Cache Tokens 10.82M (1.8x)

Single session, neutral prompt : P50 20.4 min, P95 29.5 min, Read Cache Tokens 6.05M (baseline)

Changing just one prompt sentence makes median time only 11% slower than Super Agent, with less than half the tokens. What does the architecture buy? Stability : models occasionally judge "this task is small, I'll do it myself," dragging the slowest task to 29 minutes—randomness prompts can't eliminate. Cost: tokens more than doubled. Also, this is synthetic load (coding work simulated with a time-only tool), measuring scheduling ability, not directly extrapolatable to real teams.

3. SuperAgent Prototype Code Analysis

DSH open-sourced a prototype (~16k lines, GitHub: https://github.com/deepseek-ai/dsh-superagent-prototype). Below is source-level analysis.

3.1 Core Concepts

Trigger & Thread : what happened in the world, which events belong together.

Ticket : authorized work unit. Most stable thing—sessions can break, executors can change, Ticket persists.

Policy : team rules (who can initiate work, when proactive action allowed). Rules change, so versioned.

Mandate : credential proving "why this Ticket can proceed"—who requested, scope, policy version.

Why separate Ticket and Mandate? Scenario: a fix merged, Ticket closed. Week later someone comments on the PR "there's another issue." Re-evaluating from scratch is slow; jumping straight in risks overreach. With independent Mandate, reuse the old Mandate to resume work, but validate against latest Policy first. Whether work can continue and its current state are two separate questions.

3.2 From Message to Work: The Full Pipeline

Check-in : persist every message, deduplicate. Append-only engineering pattern—restart won't replay messages, audit trail exists.

Owner lookup : if a human's follow-up lands on a Thread tracked by a Ticket, that Ticket is the owner; route directly to its Worker, Router bypassed.

Gate (code) : check sender's permission.

Model call (only step using LLM).

Ticket creation : Ticket, Mandate, subscription, confirmation reply generated atomically—no intermediate "ticket opened but nobody knows" state.

3.3 Design Decision 1: Model Proposes, Code Decides

This is the prototype's core architectural decision. A deterministic core is the sole writer of Ticket state. Router model "accepts order" by submitting a proposal; core validates permissions, rules, parameters, current state—rejects if invalid.

Benefit: model errors or injection worst-case submit a rejected proposal. Aligns with experimental conclusion: since models think "task is small," don't rely on self-restraint. Router forbidden from doing work is enforced in code, not just prompt—long-wait operations rejected at code level.

3.4 Design Decision 2: Write-Ahead Logging (Outbox Pattern)

Long-running systems fear mid-execution crashes. Example: state set to "accepted" but confirmation message not sent; restart leaves ambiguity. Prototype treats external actions as data, logs them with state changes in same transaction, commits, then background worker executes each. Classic Outbox pattern. DeepSeek applies it thoroughly: Worker startup, message delivery, IM sending all go through this. Model work can't be fully replayed, so on restart Worker gets a hint to inspect code directory and PR actual state before deciding to redo.

3.5 Design Decision 3: External Text Is Always Data

Super Agent reads group chats and comments constantly—these may carry malicious instructions. Prototype enforces explicit priority hierarchy; the defense line is in that diagram.

Detail: when Router delegates, notes limited to 30 words, no implementation plans or acceptance criteria; Worker must read original messages. Prevents "telephone game" distortion—more retellings, more drift.

3.6 Design Decision 4: Proactive Capability Must Be Canary-Released

Proactivity is easiest to blow up—an agent spamming PRs gets shut down fast. Prototype separates "judgment" from "execution": new rules default to dry-run. Model judges normally but only logs "if enabled I would take this ticket," doesn't actually start. Team reviews logs, if judgment accurate, enables execution. Judgment must cite specific rule and reference original message as evidence. Same principle as canary release—interesting design in current prototype.

3.7 Design Decision 5: Human Priority Highest

DSH paper says save human attention; code implements three concrete points:

Status sorted by "waiting for whom"—tasks waiting on humans shown first, instantly see who's blocking.

Concurrency slot reserved for humans: when all Workers busy, human messages still wake existing work; new work cannot displace humans.

Distinguish "delivered" from "read": message entering Worker session doesn't count; only entering model history counts. Unread human messages at Ticket closure trigger re-evaluation. Human saying "wait, don't merge, spec changed" at last moment must be handled correctly. Router may reopen task, create new Ticket, or reply directly.

3.8 Current Prototype Boundaries

Clear simplifications: state in single-node DB, one deployment = one repo + one account set; Worker runs as operator system identity—docs explicitly say command wrapping is not a security boundary; Watchdog and speculative execution mentioned in paper not found in prototype code, docs, or prompts. Completion relies on external facts (e.g., PR merged)—natural for R&D, insufficient for business work. These are exactly the gaps we aim to fill.

4. Author's Reflections: From Digital Employee Perspective

4.1 "Digital Employee" Term Overused

Many products call themselves digital employees but are just chat + knowledge base + tools. You ask, it answers; close window, session ends; next time re-explain context. Useful, but "employee" is a stretch.

I judge by four questions:

Must you re-explain context every time? Real colleagues don't; so no "new session" concept.

Does it keep working after you walk away? Must persist, wait for others, pick up context.

Does it act when nobody nudges? Upstream done, CI failed, time triggered—must wake on these events.

When it errs, can you trace who/why? Enterprise can't use employees without accountability and audit.

True digital employees are Always-on; SuperAgent's "continuous, efficient, proactive, persistent" are exactly a good colleague's basic qualities.

4.2 Router Not Mandatory—Can Be Replaced by Coordinator

Reading the original, attention fixates on Router component. But it bundles three jobs: human front-end interaction, routing judgment, global memory. These need not live in one resident session; original admits "part of Router logic may not need LLM."

Our approach: front-end is the Channel itself—humans and agents share one timeline; who to wake computed programmatically from task state; judgment delegated to Coordinator (a regular Channel member with clear duty: "decompose, assign, track, summarize—no direct business ops"); memory stored in Quest and files.

Trade-offs: gain—Coordinator not resident, context doesn't bloat infinitely, wake-on-demand, clearer permission boundaries. Lose—resident Router's continuity feel and batch-processing dividend (accumulated events processed together next round). We currently wake once per trigger; this is exactly what we need to learn from DSH.

4.3 Centralized Router's Design Rationale: Agent Bandwidth vs. Human

Management veterans wary of centralization: everything through one person, that person gets crushed. True, but premise is human bandwidth is narrow . A manager tracks few things; human orgs add layers to compress info.

Agents lack this constraint. They read fast, don't tire, don't need sync meetings. DSH stress test shows counter-intuitive result: event rate from 1/min to 40/min, average reasoning time per decision dropped from 6.4s to 1.6s . Because Router's pending events get batched next round. Humans degrade under load; models in range get cheaper via batching.

Insight: don't transplant human org structures onto agents . Hierarchies, weekly meetings, upward reporting invented for human bandwidth. Many multi-agent systems mirror company org charts—may be learning the wrong lesson. Centralization is bottleneck for humans; for agents, likely simplest effective structure.

4.4 Bottlenecks Remain, Just Shifted

Stress test used fake Workers, rate only 40/min—can't extrapolate to arbitrary scale. Four centralization bottlenecks:

Context capacity : Everything passes through, window eventually overflows. DSH mitigation: pass-through to Workers, chain-of-recall; admits cross-month bottleneck. Our mitigation: Coordinator non-resident, sharded by Channel, query on demand.

Judgment quality : One round judges too many things, error blast radius large. DSH mitigation: only route when message explicitly targets a Ticket. Our mitigation: @ counts as communication only; formal Ticket creation = delegation.

Cost : Re-reads large context every time. DSH mitigation: accepts 3.8x read cache tokens. Our mitigation: model invoked only when needed; batch wake not yet done.

Blast radius : All events & permissions converge; injection affects globally. DSH mitigation: external text only data, permissions enforced in code. Our mitigation: isolation by Channel; cross-Channel requires mutual auth.

DSH says finer sharding increases throughput but reduces continuity; "until global memory solved, this trade-off persists." We shard by Channel from start—equivalent to pre-splitting by business boundary. Cost: user must know which Channel. Both imperfect; in enterprise I prefer boundaries first.

4.5 Center Should Care About Outcomes, Not How

Most agreed point, converged independently. Once center cares about "how," it reads details, plans, immediately degrades into heavy Team Lead—bottleneck returns. To keep center thin, it must only see results.

In our collaboration space, tasks define goal, acceptance criteria, owner, dependencies—no "implementation plan." Assignee agent decides how: read docs, use sub-agents, run workflows, even re-delegate—Coordinator doesn't interrogate. Coordinator finishes after decomposition; no polling; platform wakes it when all subtasks done. DSH goes further: Router not allowed to write acceptance criteria; Worker must return to original request to judge; even "Router accepted ticket doesn't prove task should be done."

Difference: DSH can skip acceptance criteria because R&D has PR, CI as objective facts; we must write them because many business tasks lack objective completion signals—acceptance criteria become task interface.

"Outcomes only" has a precondition—touches a famous 2025 debate. June 2025: Anthropic published multi-agent Research system (main agent decomposes, sub-agents parallel search). Simultaneously Cognition posted "Don't Build Multi-Agents," citing Flappy Bird example: one sub-agent made Mario-style background, another made mismatched bird—each action carries implicit decisions invisible to others.

Both have merit: research can be split; a game's art style cannot. Answer isn't whether to use multi-agent, but where the split boundary lies: only independently verifiable work can be delegated out .

5. Our Practice: Collaboration Space Flock

Above views not formed after reading DSH paper; many from building Flock. Flock answers a slightly different question. DSH: "how can one agent do many things at once." We: "how can a group of humans and a group of agents be accountable for one thing end-to-end."

5.1 Overall Architecture

Four layers; follow numbered flow for a complete work item. Most important: control plane and execution plane separation . Control plane = business facts (who owns, progress, which result version). Execution plane = run this round (model calls, tool execution, checkpoint recovery). Execution can fail, retry, swap people; responsibility and progress stay in control plane, never lost. Same idea as DSH's "Ticket doesn't follow session," but we made it a product humans directly see and operate.

5.2 Product Form: A Network of Channels

Unlike DSH's "single center," we have many Channels. Each Channel maps to a project or business scenario, containing humans, Coordinators, various agents, even local Qoder on user's machine. They share one timeline; context and permissions default to stay within the space.

Isolation demands cross-boundary collaboration. DSH leaves it open; we have v1 implementation. Dev agent needs biz side to take over—not by pulling them in, but by creating a task in the other Channel, executed in their space. Nice design: same interaction line exceeding round-trip limit (default 6) gets rejected with suggestion to merge spaces. If they need that many rounds, boundary likely drawn wrong.

Local Qoder corresponds to DSH's "bring daily machine in." Difference: we make it a Channel member, same task/acceptance as platform agents, but it actively pulls tasks and executes on user's machine.

5.3 Sessionless: How Sessions Are Hidden

You don't "create a new colleague" every time you talk to one. That's Sessionless—not that sessions don't exist underneath, but session no longer represents identity or task; it's disposable execution material. One work round in system:

Chat session continues for continuity.

Task execution prefers new session each round—inheriting old session "causes cross-round context accumulation"; only sub-task returning to parent or human breakpoint restart continue.

Acceptance always new session—acceptor shouldn't carry executor's context, has no execution rights.

Chat session best illustrates. User has no "new session" button; system computes a key from several facts; same key = continue chat.

"Who can see" is an easily overlooked privacy boundary: Channel membership change auto-cuts to new session; newcomers can't read prior context. Single-instance DSH doesn't face this; multi-human multi-agent Channels must.

After hiding sessions, new problem: how to debug when things break? Added lineage table in Sept—nodes can be sessions or tasks, every edge records trigger. One query shows what grew from a human @.

5.4 Quest: The Thing That Outlives Sessions

Sessions become disposable; what's stable? Quest . Table comment: three characters "责任状" (letter of responsibility). It's an assignable, trackable, verifiable work unit with goal, acceptance criteria, unique owner. Similar to DSH's Ticket—structured task.

Key design: "Pending Acceptance" state : Agent succeeds ≠ task done . It only means a version submitted; human or designated acceptance agent must approve. Reject → re-execute, previous version retained. In enterprise, "done" requires human sign-off.

5.5 Task Chains: DAG Emerges, Not Planned

Many orchestration systems demand flowchart upfront. Complex tasks often can't be pre-drawn. We reverse: each action only records its own dependencies ; graph grows naturally during execution .

Three simple rules:

Agent executing a task creates sub-task—default child of current task.

On creation, declare dependencies—upstream completion wakes downstream.

All children done → platform wakes parent, brings accepted results for summary.

"Failed order review" in diagram was created mid-execution by executor; Coordinator didn't know initially.

Manager's "execution panorama" expands these relations into a DAG—system maintains no separate flowchart. "Grown" isn't laissez-faire: if Agent can't clarify new task ownership, platform rejects creation—otherwise orphan tasks stall parent forever.

5.6 Quest Chain Context Recall

DSH uses event references for chain-of-recall; our task chain itself is a reference graph —edges are work relations, more stable than event relations. Example: answer scattered across three places—clue in v2 annotation, evidence in upstream failure details, reason in biz person's reply. Agent doesn't remember two weeks ago; just walks the work relations.

5.7 Proactive Execution: Why It Moves When Nobody Pushes

Many think proactive = background process constantly pondering "what should I do." Our implementation is simpler: task state in ledger; state change computes who to wake; model invoked only when something happens . One execution's output becomes next execution's trigger; work advances autonomously.

Biggest pitfall we hit: mutual wake-ups —a single-agent non-issue. Staging had "organize headcount" task; ideal 3 executions: Coordinator @ two agents, each replies, then summary. Actual 10+ executions, same task spawned 8 instances, agent @'d itself. Root cause not model stupidity: platform put "being @'d" and "task assigned" in same pipeline. @'d agent received instruction "must submit deliverable on completion," so it diligently decomposed tasks, sent notifications.

Fix: separate semantics: @ is communication, Quest is delegation . @ only triggers reply, no execution rights; to work, must create task first. Add: CC doesn't wake; agent-to-agent consecutive wakes default max 3, human intervention resets. Same as DSH conclusion: platform hard constraints > prompts.

5.8 Cross-Session Memory: Remembering Everything

Hardest problem; DSH admits cross-month long-term memory bottleneck. We pivoted once. Early approach: every wake, stuff member list, today's messages, recent activity—fear it wouldn't know. Result: context bloated, full of noise. Later we slimmed: deleted all that.

Tool detail: long messages no longer truncated; keep head/tail, fold middle with retrieval hint. Because every wake is brand-new, retrieval is only way to learn past; truncation lets agent treat fragment as whole.

Further: MDC (Meta-Dance-Context) idea: don't make agent remember; make agent able to find . Memory not in model brain, not in infinite session, but behind a file interface agent can browse. Each wake compiles a clean window; fetch what's needed.

Conclusion: Two Trends

First, agent architectures are converging. After SuperAgent, I quickly saw DSH and us solving identical problems, community feedback echoing similar designs. Source code review confirmed. Among similar solutions, we're nearly identical to DSH—even Ticket objects, call-chain organization highly similar. Not coincidence or copying; constraints narrowed solution space:

Models can complete single tasks; bottleneck shifted to human attention → need unified external entry point.

Tasks longer, more numerous → need isolated execution units.

Tasks must outlive sessions → need persistable, traceable task objects.

Once problem defined clearly, answers converge—like databases converging to WAL, OSes to processes and schedulers.

Second, agents are returning to traditional engineering. When agents shift from "one conversation" to "long-running process," they face classic distributed systems problems: processes crash, machines go offline, messages duplicate, side-effects must not run twice. In DSH and our code we see more and more classic database/distributed systems techniques: write-ahead logging (log before act), Outbox for exactly-once side-effects, leases to prevent duplicate pickup, replayable event logs.

Model is the only non-deterministic component; engineering's job is to wrap it in a deterministic shell. Model can err; system must converge. Reliability no longer depends solely on model correctness, but on system recovery when model fails or interrupts.

Agents increasingly resemble systems engineering : model = CPU, Harness = OS + database.