Reviews Deep Agents code for bugs, anti-patterns, and improvements. Use when reviewing code that uses create_deep_agent, backends, subagents, middleware, or human-in-the-loop patterns. Catches common configuration and usage mistakes.
Reviews Deep Agents code for bugs, anti-patterns, and configuration mistakes. Triggers on code using create_deep_agent, backends, subagents, middleware, or human-in-the-loop patterns. Catches critical issues like missing checkpointer/store, backend misuse, and subagent configuration errors.
/plugin marketplace add existential-birds/beagle/plugin install beagle@existential-birdsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
When reviewing Deep Agents code, check for these categories of issues.
# BAD - interrupt_on without checkpointer
agent = create_deep_agent(
tools=[send_email],
interrupt_on={"send_email": True},
# No checkpointer! Interrupts will fail
)
# GOOD - checkpointer required for interrupts
from langgraph.checkpoint.memory import InMemorySaver
agent = create_deep_agent(
tools=[send_email],
interrupt_on={"send_email": True},
checkpointer=InMemorySaver(),
)
# BAD - StoreBackend without store
from deepagents.backends import StoreBackend
agent = create_deep_agent(
backend=lambda rt: StoreBackend(rt),
# No store! Will raise ValueError at runtime
)
# GOOD - provide store
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()
agent = create_deep_agent(
backend=lambda rt: StoreBackend(rt),
store=store,
)
# BAD - no thread_id when using checkpointer
agent = create_deep_agent(checkpointer=InMemorySaver())
agent.invoke({"messages": [...]}) # Error!
# GOOD - always provide thread_id
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config)
# BAD - relative paths not supported
read_file(path="src/main.py")
read_file(path="./config.json")
# GOOD - absolute paths required
read_file(path="/workspace/src/main.py")
read_file(path="/config.json")
# BAD - Windows paths rejected
read_file(path="C:\\Users\\file.txt")
write_file(path="D:/projects/code.py", content="...")
# GOOD - Unix-style virtual paths
read_file(path="/workspace/file.txt")
write_file(path="/projects/code.py", content="...")
# BAD - expecting files to persist across threads
agent = create_deep_agent() # Uses StateBackend by default
# Thread 1
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "a"}})
# Agent writes to /data/report.txt
# Thread 2 - file won't exist!
agent.invoke({"messages": [...]}, {"configurable": {"thread_id": "b"}})
# Agent tries to read /data/report.txt - NOT FOUND
# GOOD - use StoreBackend or CompositeBackend for cross-thread persistence
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={"/data/": StoreBackend(store=store)},
),
store=store,
)
# BAD - unrestricted filesystem access
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/"), # Full system access!
)
# GOOD - scope to project directory
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/home/user/project"),
)
# BAD - shorter prefix shadows longer prefix
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={
"/mem/": backend_a, # This catches /mem/long-term/ too!
"/mem/long-term/": backend_b, # Never reached
},
),
)
# GOOD - CompositeBackend sorts by length automatically
# But be explicit about your intent:
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(),
routes={
"/memories/": persistent_backend,
"/workspace/": ephemeral_backend,
},
),
)
# BAD - execute tool won't work with StateBackend
agent = create_deep_agent() # Default StateBackend
# Agent calls execute("ls -la") → Error: not supported
# GOOD - use FilesystemBackend for shell execution
agent = create_deep_agent(
backend=FilesystemBackend(root_dir="/project"),
)
# Agent calls execute("ls -la") → Works
# BAD - missing required fields
agent = create_deep_agent(
subagents=[{
"name": "helper",
# Missing: description, system_prompt, tools
}]
)
# GOOD - all required fields present
agent = create_deep_agent(
subagents=[{
"name": "helper",
"description": "General helper for misc tasks",
"system_prompt": "You are a helpful assistant.",
"tools": [], # Can be empty but must be present
}]
)
# BAD - duplicate subagent names
agent = create_deep_agent(
subagents=[
{"name": "research", "description": "A", ...},
{"name": "research", "description": "B", ...}, # Collision!
]
)
# GOOD - unique names
agent = create_deep_agent(
subagents=[
{"name": "web-research", "description": "Web-based research", ...},
{"name": "doc-research", "description": "Document research", ...},
]
)
# BAD - subagent overhead for trivial task
# In system prompt or agent behavior:
"Use the task tool to check the current time"
"Delegate file reading to a subagent"
# GOOD - use subagents for complex, isolated work
"Use the task tool for multi-step research that requires many searches"
"Delegate the full analysis workflow to a subagent"
# BAD - subgraph with incompatible state schema
from langgraph.graph import StateGraph
class CustomState(TypedDict):
custom_field: str # No messages field!
sub_builder = StateGraph(CustomState)
# ... build graph
subgraph = sub_builder.compile()
agent = create_deep_agent(
subagents=[CompiledSubAgent(
name="custom",
description="Custom workflow",
runnable=subgraph, # State mismatch!
)]
)
# GOOD - ensure compatible state or use message-based interface
class CompatibleState(TypedDict):
messages: Annotated[list, add_messages]
custom_field: str
# BAD - expecting custom middleware to run first
class PreProcessMiddleware(AgentMiddleware):
def transform_request(self, request):
# Expecting this runs before built-in middleware
return request
agent = create_deep_agent(middleware=[PreProcessMiddleware()])
# Actually runs AFTER TodoList, Filesystem, SubAgent, etc.
# GOOD - understand middleware runs after built-in stack
# Built-in order:
# 1. TodoListMiddleware
# 2. FilesystemMiddleware
# 3. SubAgentMiddleware
# 4. SummarizationMiddleware
# 5. AnthropicPromptCachingMiddleware
# 6. PatchToolCallsMiddleware
# 7. YOUR MIDDLEWARE HERE
# 8. HumanInTheLoopMiddleware (if interrupt_on set)
# BAD - mutating instead of returning new object
class BadMiddleware(AgentMiddleware):
def transform_request(self, request):
request.messages.append(extra_message) # Mutation!
return request
# GOOD - return modified copy
class GoodMiddleware(AgentMiddleware):
def transform_request(self, request):
return ModelRequest(
messages=[*request.messages, extra_message],
**other_fields
)
# BAD - tool without docstring
@tool
def my_tool(arg: str) -> str:
return process(arg)
class MyMiddleware(AgentMiddleware):
tools = [my_tool] # LLM won't know how to use it!
# GOOD - descriptive docstring
@tool
def my_tool(arg: str) -> str:
"""Process the input string and return formatted result.
Args:
arg: The string to process
Returns:
Formatted result string
"""
return process(arg)
# BAD - re-explaining what middleware already covers
agent = create_deep_agent(
system_prompt="""You have access to these tools:
- write_todos: Create task lists
- read_file: Read files from the filesystem
- task: Delegate to subagents
When using files, always use absolute paths..."""
)
# This duplicates what FilesystemMiddleware and TodoListMiddleware inject!
# GOOD - focus on domain-specific guidance
agent = create_deep_agent(
system_prompt="""You are a code review assistant.
Workflow:
1. Read the files to review
2. Create a todo list of issues found
3. Delegate deep analysis to subagents if needed
4. Compile findings into a report"""
)
# BAD - contradicting default behavior
agent = create_deep_agent(
system_prompt="""Never use the task tool.
Always process everything in the main thread.
Don't use todos, just remember everything."""
)
# Fighting against the framework!
# GOOD - work with the framework
agent = create_deep_agent(
system_prompt="""For simple tasks, handle directly.
For complex multi-step research, use subagents.
Track progress with todos for tasks with 3+ steps."""
)
# BAD - no guidance on when to stop
agent = create_deep_agent(
system_prompt="Research everything about the topic thoroughly."
)
# Agent may run indefinitely!
# GOOD - define completion criteria
agent = create_deep_agent(
system_prompt="""Research the topic with these constraints:
- Maximum 5 web searches
- Stop when you have 3 reliable sources
- Limit subagent delegations to 2 parallel tasks
- Summarize findings within 500 words"""
)
# BAD - sequential subagent calls (in agent behavior)
# Agent calls: task(research topic A) → wait → task(research topic B) → wait
# GOOD - parallel subagent calls
# Agent calls in single turn:
# task(research topic A)
# task(research topic B)
# task(research topic C)
# All run concurrently!
# Guide via system prompt:
agent = create_deep_agent(
system_prompt="""When researching multiple topics,
launch all research subagents in parallel in a single response."""
)
# BAD - writing large files to StateBackend
# Agent writes 10MB log file to /output/full_log.txt
# This bloats every checkpoint!
# GOOD - use FilesystemBackend for large files or paginate
agent = create_deep_agent(
backend=CompositeBackend(
default=StateBackend(), # Small files
routes={
"/large_files/": FilesystemBackend(root_dir="/tmp/agent"),
},
),
)
# BAD - ephemeral checkpointer in production
agent = create_deep_agent(
checkpointer=InMemorySaver(), # Lost on restart!
)
# GOOD - persistent checkpointer
from langgraph.checkpoint.postgres import PostgresSaver
agent = create_deep_agent(
checkpointer=PostgresSaver.from_conn_string(DATABASE_URL),
)
# BAD - no guard against long-running loops
agent = create_deep_agent(
system_prompt="Keep improving the solution until it's perfect."
)
# May hit recursion limit (default 1000)
# GOOD - explicit iteration limits
agent = create_deep_agent(
system_prompt="""Improve the solution iteratively:
- Maximum 3 revision cycles
- Stop if quality score > 90%
- Stop if no improvement after 2 iterations"""
)
interrupt_onStoreBackendroot_dirstore parameterUse when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.