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
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: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: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
Code Files
Code Files
Extensions:
.js, .py, .html, .css, .tsx, .java, etc.Features:- Syntax highlighting
- Code editing
- Download as files
- Direct execution (some types)
- Generated code
- Scripts
- Web pages
- Applications
Document Files
Document Files
Extensions:
.md, .txt, .json, .xml, .csv, etc.Features:- Text editing
- Formatting support
- Search within file
- Export options
- Documentation
- Data files
- Configuration
- Reports
Data Files
Data Files
Extensions:
.json, .csv, .yaml, .sql, etc.Features:- Structured data editing
- Validation
- Import/export
- Transformation
- 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: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:- Close and reopen chat: Workspace restored automatically
- Switch to different conversation: Each has its own workspace
- Refresh browser: State loaded from checkpoint
- Continue next day: Everything right where you left it
State Management
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:
- Agent analyzes problem
- Creates tasks automatically
- Executes tasks independently
- Updates you on progress
- Completes entire workflow
- Trusted operations
- Well-defined tasks
- Time-sensitive work
- Routine processes
Toggling HITL Mode
Use Cases
Software Development
Scenario: Build a complete web applicationData Analysis
Scenario: Analyze large dataset and generate insightsContent Creation
Scenario: Create comprehensive documentationResearch & Planning
Scenario: Research and plan a projectAdvanced Features
Task Dependencies
Tasks can depend on other tasks:Task Priorities
Set priorities for agent focus:File Templates
Agents can use templates for common file types:Best Practices
Clear Instructions
Do:
- Be specific about end goals
- Provide context and requirements
- Set expectations
Monitor Progress
Do:
- Check workspace regularly
- Review completed tasks
- Verify file outputs
- Provide feedback
Use HITL Wisely
Do:
- HITL for critical tasks
- Auto for routine work
- Switch modes as needed
Organize Files
Do:
- Use clear file names
- Organize by purpose
- Clean up old files
- Download important outputs
user-auth-component.tsx
❌ component1.tsxTroubleshooting
Workspace Not Showing
Workspace Not Showing
Check:
- Deep Mode enabled in settings?
- Using DeepAgents-compatible expert?
- Workspace drawer not collapsed?
- Toggle Deep Mode off and on
- Click expand button on drawer
- Refresh and check settings
Tasks Not Updating
Tasks Not Updating
Possible causes:
- Agent stuck or waiting
- Error in task execution
- HITL mode waiting for approval
- Check for pending approvals
- Review error messages
- Provide additional guidance
- Restart task if stuck
Files Not Saving
Files Not Saving
Check:
- File name valid?
- Content not too large?
- No special characters?
- Use standard file names
- Check file size limits
- Download critical files locally
- Contact support if persists
Lost Workspace State
Lost Workspace State
If state is lost:
- Check conversation ID (state per conversation)
- Verify DeepAgents mode active
- Review last checkpoint
- Don’t clear browser data
- Save important files externally
- Regular downloads of outputs