deepagents-setup-configuration

name

deepagents-setup-configuration

description

Initialize, validate, and troubleshoot Deep Agents projects in Python or JavaScript using the `deepagents` package. Use when users need to create agents with built-in planning/filesystem/subagents, configure middleware/backends/checkpointing/HITL, migrate from `create_react_agent` or `create_agent`, scaffold projects with repo scripts, validate agent config files, and confirm compatibility with current LangChain/LangGraph/LangSmith docs.

Deep Agents Setup and Configuration

Deep Agents are an agent harness on top of LangChain + LangGraph with built-in planning, filesystem context management, and subagent delegation.

Use This Skill When

• You need a Deep Agent quickly (Python or JavaScript).
• You need subagents, filesystem-backed context, planning (write_todos), or long-term memory patterns.
• You need migration guidance from older create_react_agent flows.
• You need to scaffold a starter project with repository scripts.
• You need to statically validate an agent.py / agent.js / agent.ts config.
• You need safety checks before open-sourcing Deep Agents examples/templates.

Tooling In This Skill

• scripts/init_deep_agent_project.py: scaffolds Python/JS projects with templates.
• scripts/validate_deep_agent_config.py: static checks for Deep Agent config quality.
• references/deep-agents-reference.md: detailed API, middleware, backends, migration, troubleshooting.
• assets/templates/deep-agent-simple/: minimal Python starter template.
• assets/examples/basic-deep-agent/: richer Python example.

Recommended Workflow

1. Decide if Deep Agents is the right abstraction.
2. Scaffold with init_deep_agent_project.py (Python or JS).
3. Customize tools, prompt, backend, subagents, and persistence.
4. Run validate_deep_agent_config.py.
5. Use references/deep-agents-reference.md for advanced configuration.
6. Run the generated project and verify traces/behavior.

Choose The Right Abstraction

Need	Deep Agents	LangChain create_agent	LangGraph
Built-in planning/filesystem/subagents	✅ Best fit	⚠️ Manual middleware setup	❌ Manual graph design
Fast path for complex multi-step tasks	✅	⚠️	⚠️
Fully custom graph topology	❌	❌	✅ Best fit
Minimal/simple agent (1-3 steps)	⚠️ Overhead	✅ Best fit	⚠️

Initialize A Project

Use repo-local scripts and prefer uv run.

# Python simple template
uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template simple --path skills/

# Python with subagents
uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template with-subagents --path skills/

# Python CLI-config template (memory/checkpointer toggles)
uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template cli-config --path skills/

# JavaScript template
uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language javascript --template simple --path skills/

Templates currently supported by the script:

• simple
• with-subagents
• cli-config

Generated outputs include:

• agent.py or agent.js
• tools/example_tools.py or tools/example_tools.js
• .env.example
• README.md
• .gitignore
• pyproject.toml (Python) or package.json (JavaScript)

Validate Agent Configuration

Run static validation before shipping examples/templates:

uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.py
uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.js
uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.ts

Validator behavior:

• Errors on missing agent calls or invalid file types.
• Warns on risky/weak configs (missing prompt, odd backend usage, deprecated models).
• Supports dynamic config patterns (create_deep_agent(**kwargs), createDeepAgent(config)), with warning that some static checks are skipped.
• Validates HITL style: interrupt_on / interruptOn should be mapping/object, and requires checkpointer.

Current Deep Agents Defaults (Verified)

Default middleware includes:

1. TodoListMiddleware
2. FilesystemMiddleware
3. SubAgentMiddleware
4. SummarizationMiddleware
5. AnthropicPromptCachingMiddleware
6. PatchToolCallsMiddleware

Conditionally added middleware:

• MemoryMiddleware when memory is set
• SkillsMiddleware when skills is set
• HumanInTheLoopMiddleware when interrupt_on / interruptOn is set

Core Configuration Patterns

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",  # string or model object
    tools=[...],
    system_prompt="...",
    subagents=[...],          # optional delegation specialists
    middleware=[...],         # optional custom middleware
    store=store,              # needed for StoreBackend patterns
    backend=backend_factory,  # State/Store/Filesystem/Composite
    checkpointer=checkpointer # required for HITL interrupts
)

Backend guidance:

• StateBackend (default): thread-scoped, ephemeral.
• StoreBackend: persistent files via LangGraph store (requires store=).
• CompositeBackend: route prefixes (common /memories/ -> StoreBackend).
• FilesystemBackend: direct disk access; use carefully, prefer virtual_mode=True with root_dir.

HITL And Persistence

If using human approval interrupts:

• Python: use interrupt_on={...}
• JavaScript: use interruptOn={...}
• Always provide a checkpointer (InMemorySaver, MemorySaver, Sqlite/Postgres saver, etc.)

Migration Guidance

• langgraph.prebuilt.create_react_agent is deprecated in LangGraph v1.
• For standard agents, prefer langchain.agents.create_agent.
• For harness capabilities (planning/filesystem/subagents), use deepagents.create_deep_agent / createDeepAgent.

Versioning Note

• deepagents is currently a pre-1.0 package, so minor-version upgrades may include API changes.
• Re-validate generated templates and examples when bumping deepagents versions.

Open-Source Safety Checklist

Before publishing this skill:

• Ensure no real secrets are committed (.env.example must stay placeholder-only).
• Remove generated artifacts like __pycache__/ and *.pyc from skill folders.
• Avoid absolute local paths in code/examples.
• Keep provider credentials in environment variables only.
• Re-run validator on all shipped agent.py / agent.js templates.

Troubleshooting Quick Hits

• Model/tool-call errors: verify tool-calling model and provider credentials.
• Files not persisting: confirm StoreBackend route + store= wiring.
• HITL not interrupting: verify interrupt mapping/object and checkpointer.
• Too much overhead for simple tasks: use create_agent or plain LangGraph.

Resources

• references/deep-agents-reference.md for detailed API and migration patterns.
• assets/templates/deep-agent-simple/ for minimal template files.
• assets/examples/basic-deep-agent/ for a fuller runnable example.
• Python docs: https://docs.langchain.com/oss/python/deepagents/overview
• JavaScript docs: https://docs.langchain.com/oss/javascript/deepagents/overview
• LangGraph v1 migration: https://docs.langchain.com/oss/python/migrate/langgraph-v1