deepagents-setup-configuration — Claude Code skill: setup
The deepagents-setup-configuration Claude Code skill scaffolds and checks Deep Agents projects in Python or JavaScript. It helps configure subagents, persistence, and human approval.
MIT ★ 106 updated 2026-11-11
npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a claude-codeWhat deepagents-setup-configuration does
The skill creates a Deep Agents project skeleton and checks agent configuration. Its repository includes init_deep_agent_project.py and validate_deep_agent_config.py, Python templates, and a reference covering APIs, middleware, backends, and migration. It can help configure tools, prompts, persistence, and delegation to subagents.
The validator catches missing agent calls and unsupported file types; it also warns about risky configuration choices. Human approval requires interrupt_on or interruptOn together with a checkpointer. deepagents is pre-1.0, so a minor-version upgrade may change its API.
What it helps with
- scaffold a Python or JavaScript Deep Agents project
- check an
agent.py,agent.js, oragent.tsconfiguration - configure middleware, backends, and subagent delegation
- move an agent from
create_react_agentorcreate_agent
Example prompts for the agent
- Create a simple Python Deep Agents project under
skills/. - Check the agent configuration in
path/to/agent.py. - Move my agent from
create_react_agentto Deep Agents and add a checkpointer for human approval.
How to install deepagents-setup-configuration
1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a claude-code2Manually: put the files in place
~/.claude/skills/deepagents-setup-configuration/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/deepagents-setup-configuration/
1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a codex2Manually: put the files in place
.agents/skills/deepagents-setup-configuration/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a cursor2Manually: put the files in place
.cursor/skills/deepagents-setup-configuration/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install soba-labs/langchain-agent-skills skills/deepagents-setup-configuration2Manually: put the files in place
.github/skills/deepagents-setup-configuration/SKILL.md1Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a gemini-cli2Platform CLI
gemini skills install https://github.com/soba-labs/langchain-agent-skills --path skills/deepagents-setup-configurationManually: put the files in place
.devin/skills/deepagents-setup-configuration/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about deepagents-setup-configuration
How do I install deepagents-setup-configuration in Claude Code?
Run npx skills add soba-labs/langchain-agent-skills --skill deepagents-setup-configuration -a claude-code. The skill file will be available at ~/.claude/skills/deepagents-setup-configuration/SKILL.md.
What does deepagents-setup-configuration do?
It scaffolds Deep Agents projects in Python or JavaScript and statically checks agent configuration. It also covers backend and middleware setup, subagents, and migration.
What is required for human approval in Deep Agents?
Set interrupt_on in Python or interruptOn in JavaScript, and provide a checkpointer. Examples include InMemorySaver, MemorySaver, and Sqlite or Postgres savers.
Source text
SKILL.md · MIT
---
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`.
```bash
# 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:
```bash
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
```python
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
© soba-labs · MIT · soba-labs/langchain-agent-skills