Harness Engineering Practices
P4. Contract Subagents as Distillers
🎯 Point
If a subagent returns raw logs from 50 files to the parent, the parent's context is instantly dead. Return conclusions, not transcripts.
📝 Overview
Define the subagent's contract as "return conclusions, not minutes." Explore 50 files, return 5 lines of findings. This isn't courtesy — it's memory management discipline for context hierarchies.
🔍 Explanation
The primary purpose of using subagents is to protect the parent agent's context window. But if subagents return raw exploration results as-is, that purpose is entirely defeated. Subagents should function as "distillers" — consuming large volumes of information and returning only the essence. By explicitly defining this contract in the prompt and constraining the response format, you maintain efficiency across the entire context hierarchy. This also aligns with token economics: use cheap models for broad exploration, expensive models for deep judgment.
🛠 How to Practice
- Explicitly state "return conclusions, not transcripts" in subagent prompts and constrain response format (line limits, structure)
- Design token economics: use cheap models for exploration tasks, expensive models for parent agent judgment
- Monitor subagent response sizes and add guards that request re-distillation when thresholds are exceeded
- Adjust distillation granularity per task (3 lines for classification, 10 lines for analysis, etc.)
💼 Use Cases
- Large codebase investigation: multiple subagents explore different file groups, each returning only summaries
- Migration: subagents investigating each unit return only a 3-way classification: "ready / needs manual work / unclear"
- Incident response: separate subagents investigate logs, metrics, and traces, returning only correlated anomaly summaries
⚠ Pitfalls
If distillation quality is poor, critical information can be lost. Even with "return only conclusions" instructions, judging what qualifies as a conclusion depends on model capability. Over-distillation can strip away context the parent agent needs for correct decisions. The granularity of distillation must be tuned to the task.
#
HarnessEngineering# #
AIAgent#