Workspace Files
Workspace files give agents durable file-style storage for notes, scratchpads, logs, todos, task progress, generated code, and research files.
The workspace has two clear areas:
files/ — agent-managed files for scratchpads, todos, progress, preferences, notes, subagent outputs, and generated work.artifacts/ — runtime-managed tool output artifacts created by tool offloading and read back with artifact tools.
There is no separate workspace-files backend: choose the workspace backend once, and both areas use that same local, S3, or R2 workspace.
Workspace Backends
| Backend | Use Case | Benefits |
|---|
local | Development, single-server | Zero config, instant setup |
s3 | Production, AWS infrastructure | Scalable, durable, global access |
r2 | Production, edge computing | Zero egress fees, Cloudflare ecosystem |
Quick Setup
Workspace files default to local disk. Choose S3 or R2 only when the whole workspace should live in cloud storage.
export OMNICOREAGENT_WORKSPACE_BACKEND=local
export OMNICOREAGENT_WORKSPACE_DIR=./workspace
import asyncio
from omnicoreagent import OmniCoreAgent
async def main():
agent = OmniCoreAgent(
name="workspace_agent",
system_instruction=(
"Use workspace files for notes, progress, and final artifacts."
),
model_config={"provider": "openai", "model": "gpt-4o"},
agent_config={"enable_workspace_files": True},
)
result = await agent.run(
"Create a project note at notes/plan.md with three checklist items, "
"then read it back."
)
print(result["response"])
await agent.cleanup()
asyncio.run(main())
./workspace/files/notes/plan.md.
Cloud workspace storage uses the S3/R2 extra:
pip install "omnicoreagent[s3]"
Environment Variables
Local
OMNICOREAGENT_WORKSPACE_BACKEND=local
OMNICOREAGENT_WORKSPACE_DIR=./workspace
OMNICOREAGENT_WORKSPACE_BACKEND=s3
OMNICOREAGENT_WORKSPACE_PREFIX=workspace
AWS_S3_BUCKET=my-agent-workspace
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1 # optional
OMNICOREAGENT_WORKSPACE_BACKEND=r2
OMNICOREAGENT_WORKSPACE_PREFIX=workspace
R2_BUCKET_NAME=my-agent-workspace
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-key
R2_SECRET_ACCESS_KEY=your-r2-secret
OmniCoreAgent exposes these tools for the files/ area:
| Tool | Purpose |
|---|
ls | List files and directories |
read_file | Read file contents, like workspace-scoped cat |
write_file | Create, append, or overwrite files |
edit_file | Find and replace text within files |
insert_file | Insert text at specific line numbers |
delete_file | Delete files or directories |
move_file | Rename or move files |
clear_files | Clear the workspace files area |
glob | Find files by glob pattern |
grep | Search text inside workspace files |
Backend Behavior
| Feature | Local | S3 | R2 |
|---|
| Persists across process restarts | Yes | Yes | Yes |
| Works without cloud credentials | Yes | No | No |
| Shared across multiple machines | No | Yes | Yes |
| Fits single-server development | Yes | Yes | Yes |
| Fits distributed deployments | Limited | Yes | Yes |
| Uses the same workspace tools | Yes | Yes | Yes |
Use Cases
| Use Case | Recommended Backend |
|---|
| Local development | local |
| Single-server production | local or s3 |
| Multi-server / Kubernetes | s3 or r2 |
| Edge computing / Workers | r2 |
| Cost-sensitive workloads | r2 (zero egress) |
Example: Research Agent with Cloud Workspace
import os
# Set environment for S3
os.environ["OMNICOREAGENT_WORKSPACE_BACKEND"] = "s3"
os.environ["AWS_S3_BUCKET"] = "research-agent-workspace"
os.environ["AWS_ACCESS_KEY_ID"] = "AKIA..."
os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
os.environ["AWS_REGION"] = "us-east-1"
os.environ["AWS_ENDPOINT_URL"] = "https://s3.amazonaws.com" # Optional
agent = OmniCoreAgent(
name="workspace_agent",
system_instruction="Save durable notes, logs, task progress, and final output to workspace files.",
model_config={"provider": "openai", "model": "gpt-4o"},
agent_config={
"max_steps": 50,
}
)
# Agent can now save research notes that persist across:
# - Server restarts
# - Multiple instances
# - Different geographic locations
result = await agent.run(
"Research recent AI developments and save a summary to /notes/ai_trends.md"
)
Use local for development. Use s3 or r2 when the whole workspace should persist across server restarts, multiple agent instances, or production deployments.