Skip to main content
Acontext provides pre-built filesystem tools that allow LLMs to read, write, and manage files on disks through function calling. You can integrate these tools with OpenAI or Anthropic APIs to create agents that persist data autonomously.

​
Available Tools

The SDK includes four disk operation tools:
  • write_file - Create or overwrite text files
  • read_file - Read file contents with optional line offset and limit
  • replace_string - Find and replace text in files
  • list_artifacts - List files and directories in a path
These tools handle path normalization automatically and support nested directory structures like /notes/, /documents/2024/, etc.

​
Building an Agent with Filesystem

You can build an agentic loop where the LLM autonomously calls disk tools to complete file-related tasks. Here’s a complete example: 
import json
from acontext import AcontextClient
from acontext.agent.disk import DISK_TOOLS
from openai import OpenAI

# Initialize clients
acontext_client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token", base_url="http://localhost:8029/api/v1"
)
openai_client = OpenAI()

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

# Get tool schemas for OpenAI
tools = DISK_TOOLS.to_openai_tool_schema()
print(tools)
# Simple agentic loop
messages = [
    {
        "role": "user",
        "content": "Create a todo.md file with 3 tasks. Then check the content in this file",
    }
]

while True:
    response = openai_client.chat.completions.create(
        model="gpt-4.1",
        messages=messages,
        tools=tools,
    )

    message = response.choices[0].message
    messages.append(message)

    # Break if no tool calls
    if not message.tool_calls:
        print(f"🤖 Assistant: {message.content}")
        break

    # Execute each tool call
    for tool_call in message.tool_calls:
        print(f"⚙️ Called {tool_call.function.name}")
        result = DISK_TOOLS.execute_tool(
            ctx, tool_call.function.name, json.loads(tool_call.function.arguments)
        )
        print(f"🔍 Result: {result}")
        messages.append(
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        )
The agent will automatically call the appropriate tools (write_file, read_file, etc.) to complete your request, creating a fully autonomous file management system.

​
How It Works

1

Initialize clients and create a disk

Set up both the Acontext client and your LLM client (OpenAI or Anthropic). Create a disk to store files.
from acontext import AcontextClient
from acontext.agent.disk import DISK_TOOLS

client = AcontextClient(
    api_key="sk-ac-your-token",
    base_url="http://localhost:8029/api/v1"
)
disk = client.disks.create()
ctx = DISK_TOOLS.format_context(client, disk.id)
2

Get tool schemas for your LLM

Convert the disk tools to the schema format your LLM provider expects.
# For OpenAI
tools = DISK_TOOLS.to_openai_tool_schema()

# For Anthropic
tools = DISK_TOOLS.to_anthropic_tool_schema()
3

Implement the agentic loop

Create a loop that sends messages to the LLM, executes tool calls, and feeds results back until the task is complete.Executing Tools After LLM Response:When the LLM responds with tool calls, iterate through each one and execute them using DISK_TOOLS.execute_tool() (Python) or DISK_TOOLS.executeTool() (TypeScript):
# Execute each tool call from the LLM response
for tool_call in message.tool_calls:
    result = DISK_TOOLS.execute_tool(
        ctx,                                      # Tool context with disk ID
        tool_call.function.name,                  # Tool name (e.g., "write_file")
        json.loads(tool_call.function.arguments)  # Parse arguments
    )
    # Add tool result back to message history
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": result
    })
The loop continues until the LLM returns a message without tool calls, indicating the task is complete.

​
Tool Reference

​
write_file

Create or overwrite a text file on the disk. Parameters:
  • filename (required) - Name of the file, e.g., "report.md"
  • content (required) - Text content to write to the file
  • file_path (optional) - Directory path, e.g., "/notes/" (defaults to "/")
Returns: Success message with file path

​
read_file

Read the contents of a text file from the disk. Parameters:
  • filename (required) - Name of the file to read
  • file_path (optional) - Directory path where the file is located (defaults to "/")
  • line_offset (optional) - Starting line number (defaults to 0)
  • line_limit (optional) - Maximum number of lines to return (defaults to 100)
Returns: File content with line range information

​
replace_string

Replace all occurrences of a string in a file. Parameters:
  • filename (required) - Name of the file to modify
  • old_string (required) - String to be replaced
  • new_string (required) - Replacement string
  • file_path (optional) - Directory path where the file is located (defaults to "/")
Returns: Number of replacements made

​
list_artifacts

List all files and directories at a specified path. Parameters:
  • file_path (required) - Directory path to list, e.g., "/notes/" or "/"
Returns: List of files and directories
All file operations are scoped to the specific disk. Ensure you create and configure the disk context correctly before executing tools.