Customizing Deep Agents
A decision-first guide to customizing Deep Agents: when to add custom tools, which filesystem backend fits your persistence needs, how to stack middleware correctly, and how to configure subagents without paying for a Sonnet when Haiku will do.
Quick Reference
- →Start with defaults — add customization only when a specific task requirement fails
- →Custom tools inject into the agent alongside built-ins; descriptions are how the model decides which to call
- →BackendProtocol requires: ls, read, write, edit, grep, glob — not read_file/write_file
- →CompositeBackend(default=StateBackend(), routes={'/data/': S3Backend()}) — not a plain dict
- →Middleware imports from langchain.agents.middleware — PIIMiddleware requires pii_type as first arg
- →PII middleware must run before summarization middleware or PII leaks into summaries
- →Haiku is 3× cheaper than Sonnet per token — assign models per subagent based on task complexity
Before You Customize Anything
The default `create_deep_agent()` — no custom tools, StateBackend, no middleware — handles most single-session, single-domain tasks. Every customization axis you add is maintenance surface. Before writing a custom backend or wiring up middleware, check whether the defaults already fail a specific requirement you can name.
Each axis is independent — you may need all four, one, or none
| Signal that defaults aren't enough | What to add |
|---|---|
| Agent can't take an action — no built-in tool covers querying your DB, posting to Slack, or calling your internal API | Custom tools |
| Files must survive agent restarts, be shared across sessions, or live in S3 / a database | Custom filesystem backend |
| PII must be redacted before it reaches the model, all invocations must be audit-logged, or token spend must be rate-limited | Middleware |
| Task has clearly separated sub-problems with different expertise or cost profiles — research vs. analysis, fast retrieval vs. deep reasoning | Subagents |
Add `create_deep_agent(model='anthropic:claude-sonnet-4-6', tools=[])` to a test harness and run your target task before adding anything. If it completes correctly, you're done. If a specific step fails for a specific reason, that reason tells you exactly which customization to add.