mouadja02 Deep Agents Harness
Design long-running agents as a harness with explicit state, bounded delegation, durable artifacts, and reviewable tool calls. Use a higher-level harness when the work needs more than one ReAct loop.
Use When
- The agent must plan, delegate, write files, run tools, and resume after interruption.
- Tool output is too large for the context window and needs filesystem offload.
- Subagents need separate context windows or specialist instructions.
- Humans must approve, edit, or reject high-risk actions.
- You need production traces, checkpoints, evals, or deployment hooks.
Harness Design
- Define the persistent state object: task, plan, artifacts, decisions, approvals, and final output.
- Split capabilities into tools, subagents, filesystem, memory, shell, and human review.
- Give each subagent a narrow contract: inputs, allowed tools, expected artifacts, and stop condition.
- Store bulky observations as files and pass summaries plus paths through the state.
- Add approval gates for network calls, shell commands, writes outside workspace, credential access, deletes, and external side effects.
- Trace every step with state diffs, tool inputs, tool outputs, and handoff reasons.
- Evaluate the trajectory, not just the final answer.
Decision Table
| Need | Pattern |
|---|---|
| Short single-step assistant | Plain tool-calling agent |
| Stateful workflow with branches | LangGraph-style graph |
| Long-horizon work with files and subagents | Deep agent harness |
| Tool execution can affect users or infrastructure | Human-in-the-loop gate |
| Agent needs learned project practices | Durable memory plus context evolution |
Handoff Contract
Every subagent handoff should include:
- Goal and non-goals.
- Allowed files and tools.
- Evidence to collect.
- Output artifact path.
- Review criteria.
- Failure status vocabulary:
DONE,DONE_WITH_CONCERNS,NEEDS_CONTEXT,BLOCKED.
See harness-contracts.md for reusable templates.
Common Mistakes
| Mistake | Fix |
|---|---|
| Letting subagents explore the whole repo | Give exact files, commands, and output contracts |
| Passing huge tool outputs through chat | Store them as artifacts and pass summaries |
| Treating checkpoints as logs only | Resume from checkpoints and test recovery |
| Adding memory without invalidation | Version memory and attach evidence |
| Evaluating only pass/fail | Inspect trajectory quality, retries, dead ends, and repair behavior |
References
- GitHub: langchain-ai/deepagents - https://github.com/langchain-ai/deepagents
- GitHub: langchain-ai/langgraph - https://github.com/langchain-ai/langgraph
- LangGraph documentation - https://docs.langchain.com/oss/python/langgraph/
- LangSmith documentation - https://docs.smith.langchain.com/