deepagents-patterns

name	DeepAgents Patterns
description	This skill should be used when the user asks about "agent prompts", "system prompt design", "tool patterns", "anti-patterns", "agent best practices", "subagent prompts", or needs guidance on implementing effective prompts, tools, and avoiding common mistakes in DeepAgents.

DeepAgents Implementation Patterns

Effective patterns for system prompts, tools, and common anti-patterns to avoid.

System Prompt Structure

Every agent prompt should include:

[Role Definition]
[Context & Vocabulary]
[Workflow/Process]
[Decision Criteria]
[Tool Usage Guidance]
[Escalation/Stopping Criteria]

system_prompt= parameter vs AGENTS.md memory

Both provide instructions/context to the agent, but serve different purposes:

Use system_prompt= parameter for	Use AGENTS.md memory for
Core role definition	Subagent capabilities & descriptions
Hardcoded behavior	Auto-summarized context from past work
Static workflows	Cross-session knowledge persistence
Decision criteria	Capability awareness for delegation

system_prompt= vs runtime context

Use system_prompt= for	Use context_schema / ToolRuntime for
Core role definition	Per-request dynamic context
Hardcoded behavior	User-specific data (IDs, keys)
Subagent-specific logic	Session-specific settings
Static workflows	Runtime-injected variables

Context-driven approach (recommended for production):

from deepagents import create_deep_agent
from langchain.tools import tool, ToolRuntime
from dataclasses import dataclass

@dataclass
class AgentContext:
    tenant_id: str
    preferences: dict

@tool
def get_tenant_config(
    runtime: ToolRuntime[AgentContext],  # Invisible to LLM
) -> dict:
    """Get tenant-specific configuration from runtime context."""
    return load_config(runtime.context.tenant_id)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    tools=[get_tenant_config],
    system_prompt="You are a support coordinator.",  # Static role
    context_schema=AgentContext,                     # Dynamic context
)

result = agent.invoke(
    {"messages": [...]},
    context=AgentContext(tenant_id="t_123", preferences={"lang": "en"}),
)

The system_prompt= parameter defines the agent's static role and behavior. The context_schema injects per-request dynamic context accessible via ToolRuntime in tools.

Security Note: Runtime context via context_schema is injected server-side and never exposed to the LLM as tool parameters. For customer-facing agents, see Security for Customer-Facing Agents to prevent prompt injection attacks.

Prompt Patterns by Agent Type

Note: The system_prompt key in the example config dicts below maps to the system_prompt= parameter when calling create_deep_agent.

Platform Subagent

Self-service, minimal context, reusable.

{
    "name": "data-platform",
    "system_prompt": """You provide data access services.

## Available Services
- Query databases (SQL)
- Load files (CSV, JSON)
- Statistical analysis

## Service Standards
- Respond within 30 seconds
- Return data in JSON format
- Include data quality metrics

## When to Escalate
- Query requires > 1GB processing
- Data quality issues detected"""
}

Domain Specialist

Deep expertise, specific vocabulary.

{
    "name": "risk-analyst",
    "system_prompt": """You assess portfolio risk.

## Domain Context
- 'VaR' = potential loss at confidence level
- 'Volatility' = standard deviation of returns
- 'Beta' = correlation with market

## Workflow
1. Fetch portfolio data
2. Calculate risk metrics (VaR, Volatility, Beta)
3. Compare against benchmarks
4. Generate assessment with recommendations

## Risk Classification
- Low: VaR < 5%, Volatility < 15%
- Medium: VaR 5-15%, Volatility 15-30%
- High: VaR > 15%, Volatility > 30%

## When to Stop
- All metrics calculated
- Risk assessment complete"""
}

Coordinator/Orchestrator

Delegates, doesn't execute. Uses subagent dicts — the native pattern for create_deep_agent:

from deepagents import create_deep_agent

# Coordinator uses subagent dicts for delegation
coordinator = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    system_prompt="""You coordinate support operations.

## You Do NOT
- Answer questions directly (delegate to inquiry-handler)
- Resolve issues yourself (delegate to issue-resolver)
- Process orders yourself (delegate to order-specialist)

## You DO
- Understand full context
- Choose right specialist
- Synthesize results
- Recognize when to escalate

## Escalation Criteria
- Customer requests human
- Issue unresolved after 3 attempts
- Refund > $500""",
    tools=[],
    subagents=[
        {
            "name": "inquiry-handler",
            "tools": [kb_search, get_faq],
            "system_prompt": "You answer customer questions using the knowledge base.",
        },
        {
            "name": "issue-resolver",
            "tools": [lookup_issue, create_ticket],
            "system_prompt": "You resolve customer issues and create support tickets.",
        },
        {
            "name": "order-specialist",
            "tools": [track_order, process_return],
            "system_prompt": "You handle order tracking and returns.",
        },
    ],
)

Checkpointer & Human-in-the-Loop

Enable Persistence

Use MemorySaver for conversation persistence and HITL:

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    system_prompt="You are a support agent.",
    tools=[...],
    checkpointer=MemorySaver(),  # Required for interrupt_on
)

# Use thread_id for conversation persistence
config = {"configurable": {"thread_id": "session-1"}}
result = agent.invoke({"messages": [...]}, config)

Human-in-the-Loop for Sensitive Tools

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    system_prompt="You are a database administrator.",
    tools=[delete_database, read_database],
    checkpointer=MemorySaver(),
    interrupt_on={
        # Keyed by tool name. Valid decisions: approve, edit, reject, respond
        "delete_database": {"allowed_decisions": ["approve", "reject"]},
        "read_database": False,  # no pause for reads
    },
)

# Agent pauses before sensitive tools, awaits human decision
config = {"configurable": {"thread_id": "session-1"}}
for event in agent.stream({"messages": [...]}, config, stream_mode="values"):
    if "__interrupt__" in event:
        # Review and approve or reject
        decision = input("Approve? (approve/reject): ")
        agent.invoke(None, config)  # Resume execution

Completion Signals

For task tracking, add an explicit signal tool:

@tool
def signal_task_complete(task_id: str, summary: str) -> dict:
    """Explicitly signal task completion with summary."""
    return {"status": "completed", "task_id": task_id, "summary": summary}

Avoid heuristic completion detection (checking for "done" in responses). Explicit signals are reliable; pattern matching is fragile.

Tool Design Patterns

Naming Convention

Use snake_case for tool names:

@tool
def search_knowledge_base(query: str) -> list[dict]:
    """Search customer support knowledge base."""
    pass

Secure Tools with ToolRuntime (Recommended)

Never pass user identifiers as parameters. Use ToolRuntime for context injection:

import os
from dataclasses import dataclass
from typing import Annotated
from langchain.tools import tool, ToolRuntime
from deepagents import create_deep_agent

@dataclass
class SecureContext:
    user_id: str
    api_key: str

# Bad: user_id as parameter (security risk)
@tool
def get_account_bad(user_id: str) -> str:
    """Insecure: user_id exposed to LLM."""
    pass

# Good: user_id from ToolRuntime context
@tool
def get_account_info(
    runtime: ToolRuntime[SecureContext],  # Invisible to LLM
) -> str:
    """Get account info using secure runtime context."""
    user_id = runtime.context.user_id
    return fetch_from_db(user_id)

# Create agent with context schema
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    system_prompt="You are an account assistant.",
    tools=[get_account_info],
    context_schema=SecureContext,
)

# Invoke with context (not visible to LLM)
result = agent.invoke(
    {"messages": [...]},
    context=SecureContext(user_id="user_123", api_key=os.environ["SERVICE_API_KEY"]),
)

Parameter Design

@tool
def process_refund(
    amount: float,                    # Required, with units implied
    reason: str = "customer_request"  # Optional with default
) -> dict:
    """Process customer refund.

    Args:
        amount: Refund amount in USD
        reason: Reason for refund

    Returns:
        Refund confirmation with processing time
    """
    pass

Return Values

Always return structured data:

return {
    "status": "success",
    "data": {...},
    "metadata": {"processing_time": 0.5}
}

Tool Granularity Principle

Custom tools should be atomic primitives, not workflow bundles. Let the agent compose them.

Bad: Workflow-Shaped Tool

@tool
def handle_customer_request(request: str) -> str:
    """Analyzes request, routes to department, executes action, sends response."""
    # Decision logic buried in tool—agent can't adapt
    category = analyze(request)
    if category == "billing":
        return billing_workflow(request)
    elif category == "support":
        return support_workflow(request)
    # Agent has no visibility or control

Good: Atomic Primitives

@tool
def classify_request(request: str) -> dict:
    """Classify customer request type and extract key details."""

@tool
def get_relevant_articles(category: str, keywords: list[str]) -> list[dict]:
    """Fetch knowledge base articles for category."""

@tool
def send_response(message: str, channel: str) -> bool:
    """Send response through specified channel."""

# Agent composes: classify -> get_articles -> formulate answer -> send
# Agent can skip steps, retry failures, or handle edge cases creatively

Domain Tools as Shortcuts, Not Gates

Preserve atomic tools alongside domain-specific conveniences:

tools = [
    query_database,           # Atomic: any query
    insert_record,            # Atomic: any table
    update_record,            # Atomic: any update
    # PLUS domain shortcuts
    get_customer_orders,      # Convenience: common query
    create_support_ticket,    # Convenience: common workflow
]
# Agent can use shortcuts for speed OR compose primitives for novel tasks

Security Model

DeepAgents uses a secure-by-default model. Implement security at tool/context level:

• Never expose user IDs, API keys, or credentials as tool parameters
• Always use ToolRuntime for secure context injection
• Configure interrupt_on for destructive operations
• Sandbox agent execution for untrusted tasks

Security for Customer-Facing Agents

When deploying agents to end users, the key risk is Prompt Injection -- a malicious user tricks the agent into performing unintended actions or leaking sensitive data.

Recommended mitigation: Use context_schema for per-user isolation and ToolRuntime to keep sensitive data out of LLM-visible parameters. Combine with interrupt_on for destructive operations.

from deepagents import create_deep_agent
from langchain.tools import tool, ToolRuntime
from langgraph.checkpoint.memory import MemorySaver
from dataclasses import dataclass

@dataclass
class UserContext:
    user_id: str
    permissions: list[str]

@tool
def get_user_data(
    runtime: ToolRuntime[UserContext],
) -> dict:
    """Get user data using runtime context — user_id never exposed to LLM."""
    return fetch_user_data(runtime.context.user_id)

@tool
def delete_user_data(
    runtime: ToolRuntime[UserContext],
    confirmation: str,
) -> dict:
    """Delete user data — requires human approval via interrupt."""
    if "admin" not in runtime.context.permissions:
        return {"error": "insufficient permissions"}
    return perform_deletion(runtime.context.user_id)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    system_prompt="You are a user account assistant.",
    tools=[get_user_data, delete_user_data],
    context_schema=UserContext,
    checkpointer=MemorySaver(),
    interrupt_on={
        "delete_user_data": {"allowed_decisions": ["approve", "reject"]},  # keyed by tool name
    },
)

# Each user gets isolated context
result = agent.invoke(
    {"messages": [...]},
    context=UserContext(user_id="user_456", permissions=["read"]),
    config={"configurable": {"thread_id": "user_456_session"}},
)

Security Checklist for Production

• Sensitive data injected via context_schema + ToolRuntime, never as tool parameters
• User context is isolated per-user (not shared)
• interrupt_on configured for destructive operations
• Rate limiting on agent invocations
• Tool permissions scoped per user role

For complete mitigation strategies (4 strategies), content validation, rate limiting, and audit logging implementations, see references/security-patterns.md.

Anti-Patterns to Avoid

The most common mistakes: God Agent (> 30 tools in one agent), Unclear Boundaries (overlapping subagent responsibilities), Parallel Decision-Making (conflicting choices), Vocabulary Collision (same term means different things), and Premature Decomposition (over-splitting simple tasks).

For the complete catalog of 19 anti-patterns with code examples and fixes, see references/anti-patterns.md.

Prompt Checklist

Before finalizing a prompt:

• Role clearly defined
• Domain vocabulary specified
• Workflow/process outlined
• Decision criteria explicit
• Tool usage guided
• Stopping criteria clear
• Escalation conditions defined

Tool Checklist

Before finalizing tools:

• snake_case naming
• Clear docstring with Args/Returns
• Explicit required parameters
• Sensible defaults for optional params
• Structured return values
• Error handling included

Additional Resources

Reference Files

For comprehensive patterns and examples:

• API Cheatsheet — Current DeepAgents API quick reference
• Prompt Patterns — 5 prompt patterns with templates
• Tool Patterns — Complete tool design guide with ToolRuntime
• Anti-Patterns — 19 anti-patterns with fixes
• Security Patterns — Security strategies for customer-facing agents

Related Skills

• Quickstart — Getting started with DeepAgents
• Architecture — Agent topologies and bounded contexts
• Tool Design — AI-friendly tool design principles
• Evolution — Maturity model and refactoring
• Evals — Evals-Driven Development — test interrupt_on flows, signal_task_complete assertions, escalation boundary scenarios

Validation

Use /validate-agent to check for anti-patterns in your agent code.