> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Read and write files with agents

Agents can work with files - read documents, write outputs, and manage data.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "File Operations"
        A[👤 User] --> B[🤖 Agent]
        B --> C[📄 Read]
        B --> D[✏️ Write]
        B --> E[📁 Manage]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    class B agent
    class A,C,D,E tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

```

## Quick Start

**1. Simple Usage**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You analyze documents',
  tools: ['read_file']
});

await agent.chat('Summarize the contents of report.pdf');
// Agent reads and summarizes the file
```

**2. With Configuration**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const agent = new Agent({
  tools: ['read_file', 'write_file']
});

await agent.chat('Create a summary.txt with key points');
// Agent creates the file
```

***

## User Interaction Flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant FileSystem
    
    User->>Agent: "Read config.json"
    Agent->>FileSystem: read_file('config.json')
    FileSystem-->>Agent: File contents
    Agent-->>User: "The config contains..."
```

***

## Configuration Levels

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Level 1: Array - Enable file tools
const agent = new Agent({
  tools: ['read_file', 'write_file']
});

// Level 2: String - Allow directory access
const agent = new Agent({
  tools: ['read_file'],
  allowedPaths: './docs/'
});

// Level 3: Dict - Full control
const agent = new Agent({
  files: {
    read: true,
    write: true,
    delete: false,
    allowedPaths: ['./docs/', './output/'],
    maxFileSize: '10MB'
  }
});
```

***

## File Tools

| Tool | Description |
| - | - |
| `read_file` | Read file contents |
| `write_file` | Create or update files |
| `list_files` | List directory contents |
| `delete_file` | Remove files (use carefully) |

***

## API Reference

> [card] [Tools Module](https://praison.ai/docs/sdk/reference/typescript/modules/tools.md)
>
> Tools including file operations

***

## Best Practices

> [accordion] Limit allowed paths
>
> Restrict file access to specific directories.

> [accordion] Disable delete by default
>
> Only enable delete\_file when absolutely needed.

> [accordion] Use approval for writes
>
> Combine with approval for production safety.

***

## Related

> [card] [Tools](https://praison.ai/docs/js/tools.md)
>
> Agent tools

> [card] [Approval](https://praison.ai/docs/js/approval.md)
>
> Human oversight


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.