# Disk Tools



Pre-built tools for LLMs to read, write, and search files on disks through function calling.

## Available Tools [#available-tools]

| Tool                  | Description                    |
| --------------------- | ------------------------------ |
| `write_file_disk`     | Create or overwrite text files |
| `read_file_disk`      | Read file contents             |
| `replace_string_disk` | Find and replace text          |
| `list_disk`           | List files and directories     |
| `download_file_disk`  | Get public download URL        |
| `grep_disk`           | Search contents with regex     |
| `glob_disk`           | Find files by path pattern     |

## Quick Start [#quick-start]

<CodeGroup>
  ```python title="Python"
  import json
  import os
  from acontext import AcontextClient
  from acontext.agent.disk import DISK_TOOLS
  from openai import OpenAI

  client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))
  openai_client = OpenAI()

  # Create disk and context
  disk = client.disks.create()
  ctx = DISK_TOOLS.format_context(client, disk.id)

  tools = DISK_TOOLS.to_openai_tool_schema()
  context_prompt = ctx.get_context_prompt()

  messages = [
      {"role": "system", "content": f"You have disk access.\n\n{context_prompt}"},
      {"role": "user", "content": "Create a todo.md file with 3 tasks"}
  ]

  # Agent loop
  while True:
      response = openai_client.chat.completions.create(
          model="gpt-4.1", messages=messages, tools=tools
      )
      message = response.choices[0].message
      messages.append(message)

      if not message.tool_calls:
          print(f"Assistant: {message.content}")
          break

      for tc in message.tool_calls:
          result = DISK_TOOLS.execute_tool(ctx, tc.function.name, json.loads(tc.function.arguments))
          messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
  ```

  ```typescript title="TypeScript"
  import { AcontextClient, DISK_TOOLS } from '@acontext/acontext';
  import OpenAI from 'openai';

  const client = new AcontextClient({
      apiKey: process.env.ACONTEXT_API_KEY,
  });
  const openai = new OpenAI();

  // Create disk and context
  const disk = await client.disks.create();
  const ctx = DISK_TOOLS.formatContext(client, disk.id);

  const tools = DISK_TOOLS.toOpenAIToolSchema();
  const contextPrompt = ctx.getContextPrompt();

  const messages: OpenAI.ChatCompletionMessageParam[] = [
      { role: "system", content: `You have disk access.\n\n${contextPrompt}` },
      { role: "user", content: "Create a todo.md file with 3 tasks" },
  ];

  // Agent loop
  while (true) {
      const response = await openai.chat.completions.create({
          model: "gpt-4.1",
          messages,
          tools,
      });
      const message = response.choices[0].message;
      messages.push(message);

      if (!message.tool_calls) {
          console.log(`Assistant: ${message.content}`);
          break;
      }

      for (const tc of message.tool_calls) {
          const result = await DISK_TOOLS.executeTool(ctx, tc.function.name, JSON.parse(tc.function.arguments));
          messages.push({ role: "tool", tool_call_id: tc.id, content: result });
      }
  }
  ```
</CodeGroup>

## Tool Reference [#tool-reference]

### write\_file\_disk [#write_file_disk]

```json
{"filename": "notes.md", "content": "# Notes", "file_path": "/docs/"}
```

### read\_file\_disk [#read_file_disk]

```json
{"filename": "notes.md", "file_path": "/docs/", "line_offset": 0, "line_limit": 100}
```

### replace\_string\_disk [#replace_string_disk]

```json
{"filename": "notes.md", "old_string": "TODO", "new_string": "DONE", "file_path": "/"}
```

### list\_disk [#list_disk]

```json
{"file_path": "/docs/"}
```

### download\_file\_disk [#download_file_disk]

```json
{"filename": "report.pdf", "file_path": "/", "expire": 3600}
```

### grep\_disk [#grep_disk]

Search file contents with regex:

```json
{"query": "TODO.*", "limit": 100}
```

<Warning>
  Uses **regex** syntax: `.*` means any characters, `*` alone means zero or more of preceding character.
</Warning>

### glob\_disk [#glob_disk]

Find files by path pattern:

```json
{"query": "**/*.md", "limit": 100}
```

## Next Steps [#next-steps]

<CardGroup cols="2">
  <Card title="Disk API" icon="hard-drive" href="/store/disk">
    Low-level disk API
  </Card>

  <Card title="Sandbox Tools" icon="terminal" href="/tool/bash_tools">
    Execute code in sandbox
  </Card>
</CardGroup>