Overview
The AI chat agent has access to a set of tools that let it interact with your workspace, execute code, and manage its own state. Tools run inside an isolated sandbox environment — a secure container that has access to your workspace files.File Tools
view
Read any file in your workspace. Supports two modes:| Mode | Description | Use Case |
|---|---|---|
| text | Returns file content as text/Markdown | Plaintext, parsed documents |
| visual | Returns rendered page images | PDFs with complex layouts, figures |
create_directory
Create new folders in your workspace hierarchy. The agent uses this to organize generated content or restructure your file tree.Code Execution
bash
Execute shell commands in the sandbox. Useful for:- File manipulation and processing
- Running command-line tools
- Data transformation scripts
python
Run Python snippets in the sandbox. The environment comes pre-installed with common data analysis libraries. Useful for:- Data analysis and statistics
- File format conversions
- Custom processing logic
Session State Tools
read_whiteboard / write_whiteboard
A shared scratchpad for the chat session. The agent uses this to:- Track its plans and progress on complex tasks
- Record intermediate findings
- Maintain a todo list across multiple turns
notify_user: true, you’ll receive a notification highlighting the update.
How the Sandbox Works
The sandbox is an isolated container that gets provisioned on the first tool call in a conversation turn:- Hydration — Your workspace files are copied into the sandbox at
/root/workspace - Execution — The agent runs tools against these files
- Sync — After the turn completes, any new or modified files are synced back to your staging workspace
- Cleanup — The sandbox is torn down
Parsed cache files (used for AI reading) are available in the sandbox but are never synced back or staged — they’re read-only derived content.