> ## 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.
# File
> Read and write files
## Overview
File tool allows you to read, write, and manage files from your AI agents.
The user asks to read or write a file; the agent performs the operation and returns the result.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "FileTool Flow"
User[👤 User] --> Agent[🤖 Agent]
Agent --> Tool[🔧 FileTool]
Tool --> Result[✅ Result]
Result --> Agent
end
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class User,Agent agent
class Tool tool
class Result output
```
## Installation
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install "praisonai[tools]"
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import FileTool
# Initialize
file = FileTool()
# Read file
content = file.read("document.txt")
print(content)
```
Use the same tool with an agent — see **Usage with Agent** below, or pass env vars and options from the sections above.
## Usage with Agent
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonai_tools import FileTool
agent = Agent(
name="FileManager",
instructions="You help manage files.",
tools=[FileTool()]
)
response = agent.chat("Read the contents of config.json")
print(response)
```
## Available Methods
### read(path)
Read file contents.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_tools import FileTool
file = FileTool()
content = file.read("data.txt")
```
### write(path, content)
Write content to a file.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
file.write("output.txt", "Hello World!")
```
### list\_dir(path)
List directory contents.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
files = file.list_dir("./documents")
```
## Common Errors
| Error | Cause | Solution |
| ------------------- | ------------ | ----------------- |
| `File not found` | Invalid path | Check file path |
| `Permission denied` | No access | Check permissions |
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Tool as Tool
participant Svc as File system
User->>Agent: Request
Agent->>Tool: Call tool
Tool->>Svc: Query
Svc-->>Tool: Data
Tool-->>Agent: Result
Agent-->>User: Response
```
***
## Best Practices
Pass absolute paths so file operations are predictable regardless of the working directory.
Check for existing files before `write` to avoid data loss.
Limit file operations to a known workspace so the agent can't touch sensitive paths.
***
## Related Tools
JSON files
CSV files
Shell commands