@deepseek-ai/dsh-research-runtime-subagent

@deepseek-ai/dsh-research-runtime-subagent

English | 中文

The research subagent runtime: turns one evidence duty into a delegated subagent run with a fixed contract and authority, validates the structured output (schema + authority + reference checks), and records the outcome as an immutable research/* event on the lead agent's session.

The pipeline

Six roles, each with a fixed authority (enforced in code, never only by prompt):

role	authority	task kind	output schema
scout	discovery	literature_screening	candidate paper
bibliographic-verifier	bibliographic_verification	bibliographic_verification	BibliographicVerdict
extractor	evidence_extraction	evidence_extraction	claim or experiment
claim-verifier	claim_verification	claim_verification	ClaimVerdict
citation-auditor	review	citation_audit	citation audit verdict
adjudicator	adjudication	adjudication	AdjudicationVerdict

processRoleOutput classifies the output kind, refuses it through assertOutputAllowed when the assignment's authority may not emit it, validates the shape, runs reference checks (every cited paper must be in the contract's inputRefs), and builds the immutable event. A citation audit that is unsound or needs revision raises an objection (blocking human approval); a sound one records an audit-only review verdict. An adjudication verdict names a decision, not an inputRef, so no reference check applies; an approved adjudication dismisses every still-open objection against that decision so it can proceed to human approval, a revised one folds the decision back to under_review, and a rejected one is terminal.

Data flow

lead → delegate() → research/assignment-created + research/route-decided logged first → subagent transport starts a child with the role's outputSchema → the role processor validates + enforces the fixed authority → the resulting research/* event is appended → consumers fold the ledger.

The subagent transport is optional: it is resolved with ctx.get('subagents') inside delegate(), so headless compositions can route and log assignments without a real transport, and a missing transport fails loudly. The child run is always disposed (try/finally), on success and on every error path.

Partial blind review

buildContract produces a ResearchContract that carries the research question, the assignment's own objective, criteria, and input references — never the lead's conclusions or other reviewers' verdicts.

Model Experience

Child subagent prompt and structured output

What the model sees

A delegated child receives a role prompt (the research question, the assignment's own objective, and the input references — never the lead's conclusions) and the role's outputSchema from the routed profile's provider/model. The child is expected to produce exactly the role's structured output: the runtime classifies the output kind, refuses anything the assignment's fixed authority may not emit, validates the shape against the schema, runs reference checks, and appends the resulting research/* events.

Token effect

Each delegation starts a child conversation on the routed tier; the role prompt and the structured outputSchema are part of that start request, and the child's output is retained in the lead's session as event data.

KV Cache effect

Children start fresh conversations per assignment, so there is no shared request prefix across delegations; the lead's session history grows with the appended research/* events.

Known Limitations and Deferred Work

• Usage is a size-based estimate — after a structured result, delegate() appends research/usage-observed charging child-prompt bytes plus produced-result bytes to the routed tier (a strong-tier run charges strong-model tokens; anything else charges agent tokens), not real provider token counts; exact counts are unreachable because the settled SubagentResult carries no usage — the minimal upstream change is a usage field on SubagentResult populated by readResult in @deepseek-ai/dsh-subagent-in-process-driver from the child session's usage fold.
• A refused or malformed child output rejects without a retry — delegate() throws a typed error and appends no result event: only the run's seeded budgets (from createRun) and the already-recorded assignment/route stay on the ledger; there is no automatic retry or re-prompt of the child.
• The subagent transport is optional — without a composed ctx.subagents provider, delegation fails loudly; headless compositions can route and log assignments but cannot run a real child.

Source: packages/research/dsh-research-runtime-subagent/src/index.ts