AgentFS Documentation

To get started, import AgentFS and AgentFSOptions, open an agent filesystem with a unique ID, and use the kv, fs, and tools interfaces. Remember to close the database using await agent.close() or use an async context manager.

import asyncio
from agentfs_sdk import AgentFS, AgentFSOptions

async def main():
    # Open an agent filesystem
    agent = await AgentFS.open(AgentFSOptions(id='my-agent'))

    # Use key-value store
    await agent.kv.set('config', {'debug': True, 'version': '1.0'})
    config = await agent.kv.get('config')
    print(f"Config: {config}")

    # Use filesystem
    await agent.fs.write_file('/data/notes.txt', 'Hello, AgentFS!')
    content = await agent.fs.read_file('/data/notes.txt')
    print(f"Content: {content}")

    # Track tool calls
    call_id = await agent.tools.start('search', {'query': 'Python'})
    await agent.tools.success(call_id, {'results': ['result1', 'result2']})

    # Get statistics
    stats = await agent.tools.get_stats()
    for stat in stats:
        print(f"{stat.name}: {stat.total_calls} calls, {stat.avg_duration_ms:.2f}ms avg")

    # Close the database
    await agent.close()

if __name__ == '__main__':
    asyncio.run(main())

This example demonstrates how to initialize an AgentFS database, perform filesystem operations (write/read), use the Key-Value store, and track tool calls.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	agentfs "github.com/tursodatabase/agentfs/sdk/go"
)

func main() {
	ctx := context.Background()

	// Open or create an AgentFS database
	afs, err := agentfs.Open(ctx, agentfs.AgentFSOptions{
		ID: "my-agent", // Creates ~/.agentfs/my-agent.db
	})
	if err != nil {
		log.Fatal(err)
	}
	defer afs.Close()

	// === Filesystem Operations ===

	// Write a file
	err = afs.FS.WriteFile(ctx, "/hello.txt", []byte("Hello, World!"), 0o644)
	if err != nil {
		log.Fatal(err)
	}

	// Read a file
	data, err := afs.FS.ReadFile(ctx, "/hello.txt")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(data)) // "Hello, World!"

	// Create directories
	err = afs.FS.MkdirAll(ctx, "/path/to/dir", 0o755)

	// List directory
	names, err := afs.FS.Readdir(ctx, "/")
	for _, name := range names {
		fmt.Printf("File name: %s\n", name)
	}

	// Get file stats
	stats, err := afs.FS.Stat(ctx, "/hello.txt")
	fmt.Printf("Size: %d, IsDir: %v\n", stats.Size, stats.IsDir())

	// === Key-Value Store ===

	// Store values (JSON-serialized)
	err = afs.KV.Set(ctx, "config:version", "1.0.0")

	type Settings struct {
		Theme    string `json:"theme"`
		FontSize int    `json:"font_size"`
	}
	err = afs.KV.Set(ctx, "user:settings", Settings{Theme: "dark", FontSize: 14})

	// Retrieve values
	var version string
	err = afs.KV.Get(ctx, "config:version", &version)

	var settings Settings
	err = afs.KV.Get(ctx, "user:settings", &settings)

	// List keys by prefix
	keys, err := afs.KV.Keys(ctx, "config:")
	for _, key := range keys {
		fmt.Printf("Key: %s\n", key)
	}

	// === Tool Call Tracking ===

	// Start/Success pattern
	pending, err := afs.Tools.Start(ctx, "web_search", map[string]string{
		"query": "golang sqlite",
	})

	// ... perform operation ...

	call, err := pending.Success(ctx, map[string]any{
		"results": []string{"result1", "result2"},
	})
	fmt.Printf("Tool call %d completed in %dms\n", call.ID, call.DurationMs)

	// Or record directly
	now := time.Now().Unix()
	call, err = afs.Tools.Record(ctx, "read_file",
		map[string]string{"path": "/test.txt"},
		"file contents",
		nil, // no error
		now-1, now,
	)

	// Query tool calls
	calls, err := afs.Tools.GetByName(ctx, "web_search", 10)
	stats, err := afs.Tools.GetStats(ctx)
}