Agent Filesystem

Give agents a real filesystem during execution. Agents can read, write, edit, and search files — and large tool outputs are automatically saved so they never overflow the context window.

For local SDK execution, filesystem is enabled by default and uses a local-disk backend unless you override it. For remote deployment, you can still choose backend type (InMemoryConfig or LocalDiskConfig), but path management is platform-managed. When LocalDiskConfig is used remotely, base_directory is ignored and a platform-managed path is used. Recommended: set filesystem=True explicitly in your agent definition so intent is clear.

---

Overview

When filesystem is enabled, the agent receives five file-operation tools and an isolated storage backend scoped to its run (identified by thread_id):

Tool	What it does
read_file	Read a file's contents, with optional offset and limit for large files
write_file	Create a new file (errors if the file already exists)
edit_file	Perform exact string replacement in an existing file
ls	List files in a directory
grep	Search for text within files

Files are stored in an isolated namespace per thread_id, so concurrent runs never interfere with each other.

---

Enabling the Filesystem

In-Memory (explicit override)

Files live in memory for the duration of the run. Nothing is written to disk; files are lost when the process exits.

Use this when you want ephemeral storage behavior explicitly.

from glaip_sdk import Agent
from glaip_sdk.models.filesystem import InMemoryConfig

agent = Agent(
    name="file-agent",
    instruction="You can work with files.",
    filesystem=InMemoryConfig(),
)

response = agent.run("Write a summary to /reports/summary.txt then read it back.")

Local Disk (default for local SDK runs)

Files are written to a directory on disk and survive process restarts.

In local SDK runs, filesystem=True resolves to a local-disk backend by default. You can also set an explicit base directory.

Recommended default:

from glaip_sdk import Agent

agent = Agent(
    name="file-agent",
    instruction="You can work with files.",
    filesystem=True,
)

Custom local disk path:

from glaip_sdk import Agent
from glaip_sdk.models.filesystem import LocalDiskConfig

agent = Agent(
    name="file-agent",
    instruction="You can work with files.",
    filesystem=LocalDiskConfig(base_directory="/tmp/agent_files"),
)

LocalDiskConfig works in remote mode for backend selection, but base_directory is ignored remotely.

Sandbox (coming soon)

A SandboxBackend is planned for isolated execution environments where file operations run inside a sandboxed container. See the roadmap for details.

Explicit Backend (advanced)

Pass a BackendProtocol instance directly when you need custom sharing or pre-populated state.

from aip_agents.middleware.backends.in_memory import InMemoryBackend
from aip_agents import LangGraphReactAgent

shared_backend = InMemoryBackend()

agent = LangGraphReactAgent(
    name="file-agent",
    instruction="...",
    filesystem=shared_backend,
)

---

File Operation Tools

The tools are automatically added to the agent's tool list when filesystem is enabled. The agent receives system prompt guidance explaining all five tools and their paths.

read_file

Reads file contents. Use offset and limit to page through large files without loading everything into context.

# Agent call examples:
read_file(path="/reports/summary.txt")
read_file(path="/data/large_dataset.csv", offset=100, limit=50)

write_file

Creates a new file at the given path. If the file already exists, the tool returns an error.

write_file(path="/reports/summary.txt", content="Q2 revenue grew 12%...")

edit_file

Performs an exact string replacement in an existing file. Fails if the target string is not found.

edit_file(file_path="/reports/summary.txt", old_string="12%", new_string="14%")

# Replace all occurrences:
edit_file(file_path="/config.json", old_string="staging", new_string="production", replace_all=True)

ls

Lists files in a directory. Paths must be absolute.

ls(path="/reports/")
ls(path="/")

grep

Searches for a pattern inside files.

grep(pattern="revenue", path="/reports/")
grep(pattern="ERROR", path="/logs/run.log")

---

Auto-Save for Large Tool Outputs

When a tool (not one of the five filesystem tools) returns an output larger than 20,000 tokens (approximately 80,000 characters using the middleware's 4 chars/token heuristic), the middleware automatically:

1. Saves the full content to /tool_outputs/ on the filesystem.

2. Replaces the in-context message with a head + tail preview and the saved file path.

The agent can always recover the full output with read_file.

# What the agent sees instead of a huge response:
Output saved to: /tool_outputs/web_search_call_abc123.txt
Preview (first 500 chars): ...
Preview (last 500 chars): ...
Use read_file(path, offset, limit) to access specific sections.

This prevents context overflow without losing data. The system prompt reminds the agent that /tool_outputs/ holds saved outputs and that ls can be used to browse them.

---

Multi-Agent Behavior

In coordinator/delegation workflows, the coordinator's filesystem backend is automatically shared with delegated sub-agents.

• Sub-agents with existing filesystem middleware have their backend replaced with the coordinator backend.

• Sub-agents without filesystem middleware receive an injected middleware using the coordinator backend.

• This enables direct shared access to files across delegated agents in the same workflow.

---

Backend Reference

Backend	Created by	Modes	Storage	Persistence	Best for
InMemoryBackend	filesystem=InMemoryConfig()	Local + Remote	RAM	Session only	Ephemeral runs, tests, sandbox-like behavior
LocalDiskBackend	filesystem=True (local default) or filesystem=LocalDiskConfig(base_directory=...)	Local + Remote	Disk	Survives restarts	Durable storage; remote path is platform-managed
SandboxBackend	—	TBD	Sandboxed container	—	Coming soon

All backends isolate files by thread_id, so the same agent running in two concurrent sessions never sees each other's files.

---

Best Practices

• Use / as the root — all file paths must be absolute (start with /).

• Structure your workspace — organize agent output under named subdirectories (e.g., /reports/, /data/, /scratch/). The /tool_outputs/ directory is reserved for auto-saved tool outputs.

• Page large files — use read_file(path, offset, limit) rather than reading an entire large file at once.

• Prefer edit_file for updates — it performs precise in-place changes and avoids overwriting the whole file by accident.

• Use LocalDiskConfig when you need durable storage — InMemoryBackend is lost when the process exits. In remote mode, LocalDiskConfig still selects local-disk behavior, but base_directory is ignored and managed by the platform.

• Multi-agent workflows — when using delegation, coordinator and sub-agents share the coordinator backend automatically.

---

Related Documentation

• Local vs Remote — runtime behavior differences between local and remote execution.

• Agents guide — agent lifecycle and multi-agent patterns.

• Multi-Agent System Patterns — coordinator/sub-agent topologies.

• File processing guide — attach files to remote runs and retrieve artifacts.