Skip to main content

DeepAgents Workspace

DeepAgents Workspace is an advanced feature that gives AI agents the ability to manage tasks and files, creating a persistent workspace for complex, multi-step operations. This enables agents to break down complex problems, track progress, and maintain context across conversations.

What is DeepAgents?

DeepAgents is a specialized mode where your AI expert operates with:
  • Todo Management: Create, track, and complete tasks
  • File System: Read, write, and manage files
  • State Persistence: Maintain workspace across sessions
  • HITL Mode: Human-in-the-Loop for approvals
  • Autonomous Operation: Self-directed problem solving
DeepAgents Workspace

Enabling DeepAgents Mode

1

Open Chat Settings

In the chat interface, click the settings icon in the top bar
2

Enable Deep Mode

Toggle “Deep Mode” or “Todo Mode” to activate the workspace
3

View Workspace

The workspace drawer appears on the right side of the chat
4

Configure HITL

Choose between:
  • Auto Mode: Agent works independently
  • HITL Mode: Agent asks for approval before actions

Workspace Overview

The workspace consists of two main sections:

Tasks Tab

Manage todos with hierarchical structure, statuses, and dependencies

Files Tab

Virtual file system for documents, code, data, and outputs

Tasks Management

Task Structure

Tasks in DeepAgents follow a hierarchical structure:
📋 Main Task (parent_id: null)
├── 🔹 Subtask 1 (parent_id: main_task_id)
│   ├── 🔸 Sub-subtask 1.1
│   └── 🔸 Sub-subtask 1.2
└── 🔹 Subtask 2
    └── 🔸 Sub-subtask 2.1

Task Statuses

  • Pending
  • In Progress
  • Completed
  • Failed
  • Cancelled
Status: pending Color: Gray Meaning: Task created but not startedWhen to use:
  • Task is planned
  • Waiting for dependencies
  • Scheduled for later

Creating Tasks

Agent-Created: Agents automatically create tasks when working on complex problems:
User: "Build a landing page for my product"

Agent creates:
1. Research product information
2. Design page layout
3. Write HTML structure
4. Add CSS styling
5. Create JavaScript interactions
6. Test responsiveness
7. Generate final files
User-Created: You can manually create tasks for the agent:
1

Open Workspace

Ensure DeepAgents mode is enabled
2

Click Add Task

In the Tasks tab, click Add Todo
3

Fill Details

  • Task Name: Short, descriptive title
  • Description: Detailed instructions
  • Status: Usually “pending”
4

Save

Task appears in the workspace

Task Operations

View Details

Click a task to see full description and metadata

Update Status

Change status manually or let agent update

Add Subtasks

Break tasks into smaller steps

Edit Task

Modify name, description, or details

Delete Task

Remove completed or unnecessary tasks

Mark Complete

Quick-complete with one click

Files System

Virtual File System

DeepAgents maintains a virtual file system where agents can:
  • Create and edit files
  • Store outputs and data
  • Read and process files
  • Organize by type and purpose

File Types

Extensions: .js, .py, .html, .css, .tsx, .java, etc.Features:
  • Syntax highlighting
  • Code editing
  • Download as files
  • Direct execution (some types)
Use cases:
  • Generated code
  • Scripts
  • Web pages
  • Applications
Extensions: .md, .txt, .json, .xml, .csv, etc.Features:
  • Text editing
  • Formatting support
  • Search within file
  • Export options
Use cases:
  • Documentation
  • Data files
  • Configuration
  • Reports
Extensions: .json, .csv, .yaml, .sql, etc.Features:
  • Structured data editing
  • Validation
  • Import/export
  • Transformation
Use cases:
  • Datasets
  • API responses
  • Database queries
  • Analysis results

File Operations

1

View Files

Switch to the Files tab in the workspace drawer
2

Open File

Click a file name to view its contents in a modal
3

Edit File

Click the Edit button to modify file content with syntax highlighting
4

Download

Use the Download button to save files to your computer
5

Delete

Remove files that are no longer needed

Adding Files

Agent-Created:
User: "Create a React component for a login form"

Agent creates files:
├── LoginForm.tsx (React component)
├── LoginForm.module.css (Styles)
├── types.ts (TypeScript types)
└── README.md (Documentation)
User-Created:
1

Add File

Click Add File in the Files tab
2

Enter Details

  • File Name: Include extension (e.g., script.py)
  • Content: Paste or type file content
3

Upload (Optional)

Or upload a file from your computer
4

Save

File is added to the workspace

State Persistence

Important: Workspace state persists across chat sessions!

What Persists

  • ✅ All todos and their statuses
  • ✅ Complete file system
  • ✅ Task hierarchy and relationships
  • ✅ Current task ID (what agent is working on)
  • ✅ Conversation context

State Restoration

When you:
  1. Close and reopen chat: Workspace restored automatically
  2. Switch to different conversation: Each has its own workspace
  3. Refresh browser: State loaded from checkpoint
  4. Continue next day: Everything right where you left it

State Management

// Workspace state structure
{
  todos: [
    {
      id: "todo_123",
      task: "Complete analysis",
      description: "Analyze dataset and generate report",
      status: "in_progress",
      parent_id: null,
      created_at: "2025-11-25T10:00:00Z"
    }
  ],
  files: {
    "analysis.py": "import pandas as pd\n...",
    "results.json": "{\"findings\": [...]}",
    "report.md": "# Analysis Report\n..."
  },
  current_todo_id: "todo_123"
}

HITL (Human-in-the-Loop) Mode

What is HITL?

HITL mode requires the agent to ask for human approval before executing actions. This provides:
  • Control: You decide what happens
  • Safety: Prevent unwanted actions
  • Learning: Understand agent’s reasoning
  • Flexibility: Modify or reject proposals

Auto vs HITL Mode

  • Auto Mode
  • HITL Mode
Agent autonomy: HighWorkflow:
  1. Agent analyzes problem
  2. Creates tasks automatically
  3. Executes tasks independently
  4. Updates you on progress
  5. Completes entire workflow
Best for:
  • Trusted operations
  • Well-defined tasks
  • Time-sensitive work
  • Routine processes
Example:
User: "Analyze this CSV and create a report"

Agent: [Auto Mode]
✓ Created task: Load and validate CSV
✓ Created task: Perform statistical analysis
✓ Created task: Generate visualizations
✓ Created task: Write comprehensive report
⚙️ Executing tasks...
✅ Complete! Report saved to workspace.

Toggling HITL Mode

Chat Settings → HITL Mode → Toggle On/Off
During conversation:
User: "Switch to HITL mode"
Agent: "Switched to Human-in-the-Loop mode. I'll ask for approval before actions."

User: "Go back to auto mode"
Agent: "Switched to Auto mode. I'll work independently."

Use Cases

Software Development

Scenario: Build a complete web application
User: "Create a todo app with React and Firebase"

Workspace:
📋 Tasks:
├── ✅ Plan application structure
├── ✅ Set up React project
├── ⏳ Create components
│   ├── ✅ App.tsx
│   ├── ✅ TodoList.tsx
│   ├── ⏳ TodoItem.tsx
│   └── ⏳ AddTodo.tsx
├── ⏳ Implement Firebase integration
└── ⏳ Add styling and deploy

📁 Files:
├── App.tsx
├── TodoList.tsx
├── TodoItem.tsx
├── firebase.config.ts
├── styles.css
└── README.md

Data Analysis

Scenario: Analyze large dataset and generate insights
User: "Analyze sales data and find trends"

Workspace:
📋 Tasks:
├── ✅ Load and validate dataset
├── ✅ Clean and preprocess data
├── ✅ Exploratory data analysis
├── ⏳ Statistical analysis
├── ⏳ Generate visualizations
└── ⏳ Write comprehensive report

📁 Files:
├── sales_data_cleaned.csv
├── analysis.py
├── statistics.json
├── plot_sales_trend.png
├── plot_regional_breakdown.png
└── analysis_report.md

Content Creation

Scenario: Create comprehensive documentation
User: "Write documentation for our API"

Workspace:
📋 Tasks:
├── ✅ Analyze API endpoints
├── ✅ Draft introduction
├── ⏳ Document authentication
├── ⏳ Write endpoint references
├── ⏳ Add code examples
└── ⏳ Create getting started guide

📁 Files:
├── introduction.md
├── authentication.md
├── endpoints.md
├── examples.md
├── getting-started.md
└── full-documentation.md

Research & Planning

Scenario: Research and plan a project
User: "Research best practices for microservices architecture"

Workspace:
📋 Tasks:
├── ✅ Research microservices patterns
├── ✅ Analyze pros and cons
├── ✅ Review case studies
├── ⏳ Compare technologies
└── ⏳ Create implementation plan

📁 Files:
├── research-notes.md
├── architecture-patterns.md
├── technology-comparison.md
├── case-studies.md
└── implementation-plan.md

Advanced Features

Task Dependencies

Tasks can depend on other tasks:
{
  id: "task_2",
  task: "Write tests",
  depends_on: ["task_1"], // Must complete task_1 first
  status: "pending"
}

Task Priorities

Set priorities for agent focus:
{
  id: "task_3",
  task: "Fix critical bug",
  priority: "high", // high, medium, low
  status: "in_progress"
}

File Templates

Agents can use templates for common file types:
Template: React Component
├── Component.tsx
├── Component.module.css
├── Component.test.tsx
└── index.ts

Best Practices

Clear Instructions

Do:
  • Be specific about end goals
  • Provide context and requirements
  • Set expectations
Example: ✅ “Create a REST API with user auth, CRUD for posts, and proper error handling” ❌ “Make an API”

Monitor Progress

Do:
  • Check workspace regularly
  • Review completed tasks
  • Verify file outputs
  • Provide feedback
Example: “Review the generated code and suggest improvements”

Use HITL Wisely

Do:
  • HITL for critical tasks
  • Auto for routine work
  • Switch modes as needed
Example: HITL: Database modifications Auto: Data analysis

Organize Files

Do:
  • Use clear file names
  • Organize by purpose
  • Clean up old files
  • Download important outputs
Example:user-auth-component.tsxcomponent1.tsx

Troubleshooting

Check:
  1. Deep Mode enabled in settings?
  2. Using DeepAgents-compatible expert?
  3. Workspace drawer not collapsed?
Solution:
  • Toggle Deep Mode off and on
  • Click expand button on drawer
  • Refresh and check settings
Possible causes:
  • Agent stuck or waiting
  • Error in task execution
  • HITL mode waiting for approval
Solution:
  • Check for pending approvals
  • Review error messages
  • Provide additional guidance
  • Restart task if stuck
Check:
  • File name valid?
  • Content not too large?
  • No special characters?
Solution:
  • Use standard file names
  • Check file size limits
  • Download critical files locally
  • Contact support if persists
If state is lost:
  1. Check conversation ID (state per conversation)
  2. Verify DeepAgents mode active
  3. Review last checkpoint
Prevention:
  • Don’t clear browser data
  • Save important files externally
  • Regular downloads of outputs

Next Steps