Workspace Files

Every agent has a workspace: a folder where it writes notes, plans and finished work with file tools, and where you can put files for it to work on. It is on local disk by default (./workspace/files/), or in S3 or R2 when several machines need the same files.

The agent writes a file

Workspace files are on by default; there is nothing to switch on.

import asyncio
from pathlib import Path
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="planner",
        system_instruction="Keep notes and plans in workspace files. Answer in plain text.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    )
    result = await agent.run(
        "Create notes/plan.md with a three-item checklist for launching a blog, "
        "then read it back and tell me the three items in one line."
    )
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print("step", step["step"], "->", call["tool_name"], call["arguments"].get("path"), call["outcome"])

    print(Path("workspace/files/notes/plan.md").read_text())
    await agent.cleanup()

asyncio.run(main())

Choose a blog niche and target audience; set up the blogging platform and domain; draft and publish the first three posts.
step 1 -> write_file notes/plan.md success
step 2 -> read_file notes/plan.md success
- [ ] Choose a blog niche and target audience
- [ ] Set up the blogging platform and domain
- [ ] Draft and publish the first three posts

The agent’s notes/plan.md is ./workspace/files/notes/plan.md on your disk. What it writes will differ on your run; where it lands will not.

Give the agent your files

To give the agent existing files — a project to review, data to analyze — put them under the workspace’s files/ folder before the run. This example also moves the workspace to ./review-ws:

import asyncio
from pathlib import Path
from omnicoreagent import OmniCoreAgent

# Seed the workspace with a file before the run.
seed = Path("review-ws/files/project/app.py")
seed.parent.mkdir(parents=True, exist_ok=True)
seed.write_text(
    "def average(numbers):\n"
    "    return sum(numbers) / len(numbers)\n"
)

async def main():
    agent = OmniCoreAgent(
        name="reviewer",
        system_instruction="You review code. Answer in plain text, in two sentences at most.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={"workspace_config": {"workspace_dir": "./review-ws"}},
    )
    result = await agent.run("Review project/app.py. What input breaks it?")
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print("step", step["step"], "->", call["tool_name"], call["arguments"], call["outcome"])
    await agent.cleanup()

asyncio.run(main())

`average([])` breaks it with a `ZeroDivisionError` because `len(numbers)` is 0.
step 1 -> ls {'path': '.'} success
step 2 -> read_file {'path': 'project/app.py'} success

review-ws/files/project/app.py on disk is project/app.py to the agent’s tools. When the agent runs commands in a sandbox, its workspace files are copied in too.

Work in a directory you already have

To have the file tools work in an existing directory instead of copying files in, name it files_dir. The runtime’s own files (traces, offloaded results) stay in workspace_dir, out of your directory. The example reviews myproject/app.py; create it first:

mkdir -p myproject
printf 'def average(numbers):\n    return sum(numbers) / len(numbers)\n' > myproject/app.py

Then:

import asyncio
from pathlib import Path
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="reviewer",
        system_instruction="You review code. Answer in plain text, in two sentences at most.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        agent_config={
            "workspace_config": {
                "workspace_dir": "./agent-ws",  # the runtime's own files
                "files_dir": "./myproject",     # where the file tools work
            }
        },
    )
    result = await agent.run("Review app.py. What input breaks it?")
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print("step", step["step"], "->", call["tool_name"], call["arguments"], call["outcome"])
    await agent.cleanup()
    print(sorted(p.name for p in Path("myproject").iterdir()))

asyncio.run(main())

`average([])` breaks it with a `ZeroDivisionError` because `len(numbers)` is 0.
step 1 -> ls {'path': '.'} success
step 2 -> read_file {'path': 'app.py'} success
['app.py']

myproject/app.py is app.py to the tools, and nothing of the runtime’s was written into myproject. files_dir is for a local workspace; with S3 or R2 it is refused. The Harbor integration uses it to put the agent’s files in the task’s own directory.

How it works

The workspace has three areas:

Folder	Holds	Written by
`files/`	The agent’s files, and the ones you seed	The agent’s file tools, and you
`artifacts/`	Tool results too large for the model’s context, saved for the agent to read back in parts (context engineering)	The runtime
`telemetry/`	The record of every run (observability)	The runtime

The agent works in files/ with these tools:

Tool	Arguments	What it does
`ls`	`path` (optional)	List a folder
`read_file`	`path`	Read a file
`write_file`	`path`, `content`, `mode`	`create` (default; refuses to replace an existing file), `append`, or `overwrite`
`edit_file`	`path`, `old_str`, `new_str`	Replace every occurrence of a string
`insert_file`	`path`, `insert_line`, `insert_text`	Insert text at a line (1-based)
`delete_file`	`path`	Delete a file or folder
`move_file`	`old_path`, `new_path`	Rename or move
`clear_files`	—	Delete everything in `files/`
`glob`	`pattern`, `path` (optional)	Find files by pattern, such as `*/.md`
`grep`	`pattern`, `path`, `include`, `case_sensitive`, `max_matches`	Search inside files; returns `path:line:content`

These are workspace tools, not a shell: every path is relative to files/, and a path that leads outside it is refused (an absolute path too, unless it is under the files directory), and so is a path that goes through a link on local disk. Under governance, grep, glob and ls show only files the policy lets the agent read, and a folder is deleted, moved or cleared only if the policy would allow that for each file in it: with deletes denied on prod/*, delete_file("prod") is refused. If a file in the folder is under an ask rule instead, the operation asks a person once, listing those files (covered_files on the pending approval, the first ten and “and N more”); if the person approves, the operation runs and those files count as approved for that operation only, and if they deny, nothing changes. They work the same on local disk, S3 and R2. Their names are reserved while workspace files are on, so give your own tools other names. Under governance each is a capability — workspace.files.read, .write, .delete, .move, .clear — that a policy can allow, ask about or deny (security model).

Where the workspace lives

Local disk (default)
S3
R2

agent_config = {"workspace_config": {"workspace_dir": "./workspace"}}

One machine. Files survive restarts; other machines cannot see them.

pip install "omnicoreagent[s3]"

agent_config = {
    "workspace_config": {
        "workspace_backend": "s3",
        "s3_bucket": "my-agent-workspace",
        "aws_region": "us-east-1",
        "prefix": "workspace",  # files go under workspace/files/ in the bucket
    }
}

Credentials: aws_access_key_id and aws_secret_access_key, or, when those are not given, boto3’s usual chain (environment, profile, role). aws_endpoint_url points it at any S3-compatible store.

pip install "omnicoreagent[s3]"

import os

agent_config = {
    "workspace_config": {
        "workspace_backend": "r2",
        "r2_bucket_name": "my-agent-workspace",
        "r2_account_id": os.environ["R2_ACCOUNT_ID"],
        "r2_access_key_id": os.environ["R2_ACCESS_KEY_ID"],
        "r2_secret_access_key": os.environ["R2_SECRET_ACCESS_KEY"],
    }
}

All four R2 settings are required.

Or from the environment

With no workspace_config at all, the workspace is read from environment variables, so a deployment can choose it without code changes:

Variable	Default	For
`OMNICOREAGENT_WORKSPACE_BACKEND`	`local`	`local`, `s3` or `r2`
`OMNICOREAGENT_WORKSPACE_DIR`	`./workspace`	local
`OMNICOREAGENT_WORKSPACE_PREFIX`	`workspace`	S3 and R2: the key prefix in the bucket
`AWS_S3_BUCKET`, `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL`	—	S3
`R2_BUCKET_NAME`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`	—	R2

A workspace_config you pass replaces these variables entirely: none of them is read, so {"workspace_backend": "s3"} alone fails for want of a bucket even when AWS_S3_BUCKET is set. Pass everything the backend needs in the dictionary, or pass no workspace_config and set it all in the environment. (For S3, boto3 still finds credentials its own way when none are given.)

	Local	S3	R2
Survives a restart	Yes	Yes	Yes
Needs cloud credentials	No	Yes	Yes
Shared by several machines	No	Yes	Yes

Options

Setting (in `agent_config`)	Default	What it does
`enable_workspace_files`	`True`	Give the agent the file tools above. `False` removes them; the workspace still holds artifacts and telemetry
`workspace_config`	`None` (from the environment, else `./workspace`)	Where the workspace lives: `workspace_backend`, `workspace_dir`, `files_dir` (where the file tools work, if not `<workspace_dir>/files`), `prefix`, and the S3 / R2 settings above

Every setting is in the agent settings reference.

When things go wrong

ValueError: Tool name conflict: built-in workspace tools reserve these names

One of your tools has the name of a workspace tool. Raised by run:

ValueError: Tool name conflict: built-in workspace tools reserve these names when enable_workspace_files=True: read_file. Rename the app tool or disable workspace files for this agent.

Rename your tool (read_app_file), or set enable_workspace_files to False.

ValueError: S3 workspace backend requires AWS_S3_BUCKET

Raised by run when the S3 or R2 settings are incomplete:

ValueError: S3 workspace backend requires AWS_S3_BUCKET
ValueError: R2 workspace backend requires environment variables: R2_BUCKET_NAME, R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY
ValueError: workspace_backend must be one of: local, s3, r2

With a workspace_config dictionary, the settings must be in it (s3_bucket, r2_bucket_name, …): the environment is not read.

The agent cannot find the file I put there

Seeded files belong under files/: ./workspace/files/project/app.py, not ./workspace/project/app.py. And the workspace is relative to the working directory the agent runs in unless workspace_dir is absolute.

What the model sees when a file call fails

A failed file call is an answer to the model, not an exception; it usually corrects itself. It is recorded as the tool call’s error (outcome error in the trajectory), with the same text. For example:

File not found: project/missing.py
Invalid path '../../../etc/passwd' resolved outside workspace namespace.

write_file in create mode on an existing file answers with a preview of it and Use mode='append' or mode='overwrite'.

Context engineering

Large tool results saved as artifacts, and context kept under the limit.

Execution

Commands in a sandbox, with the workspace copied in and out.

Memory

The conversation, kept across restarts.

Agent Skills

Instructions and scripts the agent uses when a task calls for them.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Workspace Files

Workspace Files

The agent writes a file

Give the agent your files

Work in a directory you already have

How it works

Where the workspace lives

Or from the environment

Options

When things go wrong

Next

Context engineering

Execution

Memory

Agent Skills

​Workspace Files

​The agent writes a file

​Give the agent your files

​Work in a directory you already have

​How it works

​Where the workspace lives

​Or from the environment

​Options

​When things go wrong

​Next

Context engineering

Execution

Memory

Agent Skills

Workspace Files

The agent writes a file

Give the agent your files

Work in a directory you already have

How it works

Where the workspace lives

Or from the environment

Options

When things go wrong

Next