Skip to main content

​
Usage

DeepAgent provides an isolated virtual filesystem. Files persist across the task execution and can be stored in memory (ephemeral) or persistent storage.

​
Filesystem Tools

​
ls

List directory contents. 
ls(path: str = "/") -> str

​
read_file

Read file content with pagination. 
read_file(file_path: str, offset: int = None, limit: int = 500) -> str

​
write_file

Create or overwrite a file. 
write_file(file_path: str, content: str) -> str

​
edit_file

Perform exact string replacement. 
edit_file(file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> str
Important: You must read a file before editing it.

​
glob

Find files matching a pattern. 
glob(pattern: str) -> str
Pattern Examples:
  • "*.txt" - All text files in root
  • "/docs/**/*.md" - All markdown files under /docs/
  • "/**/*.py" - All Python files recursively

​
grep

Search for text within files. 
grep(
    pattern: str,
    path: str = "/",
    glob_pattern: str = None,
    output_mode: str = "files_with_matches",
    max_results: int = 100
) -> str

​
Example

import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Task

async def main():
    agent = DeepAgent(model="openai/gpt-4o")
    
    task = Task(description="""
    Create a file /workspace/notes.txt with content "Initial notes"
    Then read the file
    Then edit it to change "Initial" to "Updated"
    List all files in /workspace/
    """)
    
    result = await agent.do_async(task)
    print(result)
    
    # Verify file exists
    exists = await agent.filesystem_backend.exists("/workspace/notes.txt")
    print(f"\nFile exists: {exists}")
    
    if exists:
        content = await agent.filesystem_backend.read("/workspace/notes.txt")
        print(f"File content: {content}")

asyncio.run(main())

​
Advanced Example

import asyncio
from upsonic.agent.deepagent import DeepAgent
from upsonic import Task

async def main():
    agent = DeepAgent(model="openai/gpt-4o")
    
    task = Task(description="""
    Create multiple files:
    1. /docs/python.md with content about Python
    2. /docs/javascript.md with content about JavaScript
    3. /scripts/helper.py with Python code
    
    Then:
    4. Find all .md files
    5. Find all files under /docs/
    6. Search for "Python" in all files
    7. Show matching lines with content output mode
    """)
    
    result = await agent.do_async(task)
    print(result)
    
    # List all files
    all_files = await agent.filesystem_backend.glob("/**/*")
    print(f"\nAll files: {all_files}")

asyncio.run(main())