# How to Configure Artifact Storage for Agent Output in AISuite

> Learn how to configure artifact storage for agent output in AISuite using CLI flags or the FileArtifactStore. Customize your agent output location easily.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-07-30

---

**You configure artifact storage in AISuite by supplying a custom path via the `--artifact-root` CLI flag or by instantiating a `FileArtifactStore` and passing it to the `Runner`, with the default location being `.aisuite/artifacts` relative to the current working directory.**

The **aisuite** repository provides a flexible framework for running AI agents that generate large data outputs through tool executions. When agents run shell commands or write files, the results are stored as **artifacts** to keep execution traces lightweight while preserving full output on disk. Understanding how to configure artifact storage ensures you maintain control over data persistence and access patterns.

## Understanding the Artifact Storage Architecture

### CliConfig.artifact_root

In [`cli/py/aisuite-code-cli/aisuite_code_cli/config.py`](https://github.com/andrewyng/aisuite/blob/main/cli/py/aisuite-code-cli/aisuite_code_cli/config.py), the `CliConfig` class defines the **artifact_root** attribute that specifies the directory path for artifact persistence. The default value is set to `".aisuite/artifacts"` (lines 29-33), which resolves relative to the current working directory where the CLI is launched.

### FileArtifactStore Implementation

The concrete storage backend resides in [`aisuite/agents/artifact_store.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/agents/artifact_store.py). The **`FileArtifactStore`** class (lines 11-15) writes each artifact to a sub-directory within the supplied root path, storing both the raw data and a [`metadata.json`](https://github.com/andrewyng/aisuite/blob/main/metadata.json) file indexed by artifact ID.

### CLI Wiring and Runner Integration

The CLI instantiates the storage backend in [`cli/py/aisuite-code-cli/aisuite_code_cli/app.py`](https://github.com/andrewyng/aisuite/blob/main/cli/py/aisuite-code-cli/aisuite_code_cli/app.py) (lines 31-32). Here, the application creates a `FileArtifactStore` from the parsed `CliConfig.artifact_root` and injects it into the runner. This allows every tool invocation during agent execution to persist results via the `artifact_store.put` method.

## Methods to Configure Artifact Storage

### Using the CLI Flag (--artifact-root)

The simplest method to configure artifact storage is via the command line. The **`--artifact-root`** flag is parsed in [`config.py`](https://github.com/andrewyng/aisuite/blob/main/config.py) (lines 86-88) and normalized to an absolute path before storage initialization.

```bash
aisuite-code --model=gpt-4o-mini --artifact-root=/tmp/my_artifacts

```

### Programmatic Configuration with FileArtifactStore

When embedding AISuite in Python applications, construct a `FileArtifactStore` directly with any `Path` object and pass it to `Runner.run_sync`.

```python
from pathlib import Path
import aisuite as ai

artifact_store = ai.FileArtifactStore(Path("/var/aisuite/artifacts"))
result = ai.Runner.run_sync(
    agent=my_agent,
    user_input="List all Python files in this repo.",
    artifact_store=artifact_store,
)

```

### In-Memory Storage for Testing

For unit tests or temporary runs where disk I/O is undesirable, use **`InMemoryArtifactStore`**. This backend keeps artifacts in RAM and is the default choice in many test suites.

```python
import aisuite as ai

store = ai.InMemoryArtifactStore()
result = ai.Runner.run_sync(agent, user_input, artifact_store=store)

```

## Practical Code Examples

### Custom Artifact Directory via CLI

To redirect all agent outputs to a specific directory without modifying code:

```bash
aisuite-code --model=openai:gpt-4o-mini \
    --artifact-root=/home/user/custom_artifacts

```

When executed, `CliConfig` resolves the path to `/home/user/custom_artifacts`, and the CLI creates the `FileArtifactStore` instance. All tool-generated artifacts—such as large shell outputs or files written by the agent—are saved under that directory in sub-folders structured as `artifact_id/data` and [`artifact_id/metadata.json`](https://github.com/andrewyng/aisuite/blob/main/artifact_id/metadata.json).

### Embedded Python Script Configuration

For production deployments requiring specific storage locations:

```python
from pathlib import Path
import aisuite as ai

# Build a custom artifact store

artifact_root = Path("/opt/aisuite/artifacts")
store = ai.FileArtifactStore(artifact_root)

# Run an agent with the custom store

result = ai.Runner.run_sync(
    agent=my_agent,
    user_input="Analyze the codebase structure.",
    artifact_store=store,
)
print("Trace ID:", result.trace_id)

```

### Unit Testing with InMemoryArtifactStore

To test agent logic without filesystem side effects:

```python
import aisuite as ai

store = ai.InMemoryArtifactStore()   # No filesystem writes

result = ai.Runner.run_sync(
    agent=my_agent,
    user_input="Show me the first 10 lines of README.md.",
    artifact_store=store,
)

# Retrieve the artifact directly from memory

artifact_ref = result.steps[0].data["result_artifacts"][0]["artifact_ref"]
artifact = store.get(ai.ArtifactRef.from_dict(artifact_ref))
print(artifact.text())

```

## Summary

- **Default Location**: Without configuration, artifacts are stored in `.aisuite/artifacts` relative to the working directory as defined in `CliConfig` ([`config.py`](https://github.com/andrewyng/aisuite/blob/main/config.py), lines 29-33).
- **CLI Configuration**: Use the `--artifact-root` flag to specify a custom directory path when launching the CLI tool.
- **Programmatic Control**: Instantiate `FileArtifactStore` with a `Path` object and pass it to `Runner.run_sync` for embedded use cases.
- **Testing Alternative**: Use `InMemoryArtifactStore` to avoid disk writes during unit tests or temporary executions.
- **Core Files**: Key implementations reside in [`aisuite/agents/artifact_store.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/agents/artifact_store.py) (storage backends) and [`cli/py/aisuite-code-cli/aisuite_code_cli/app.py`](https://github.com/andrewyng/aisuite/blob/main/cli/py/aisuite-code-cli/aisuite_code_cli/app.py) (CLI wiring).

## Frequently Asked Questions

### What is the default artifact storage location in AISuite?

The default artifact storage location is `.aisuite/artifacts` relative to the current working directory. This path is defined in the `CliConfig` class within [`cli/py/aisuite-code-cli/aisuite_code_cli/config.py`](https://github.com/andrewyng/aisuite/blob/main/cli/py/aisuite-code-cli/aisuite_code_cli/config.py) at lines 29-33.

### How do I change the artifact storage path when using the CLI?

Pass the `--artifact-root` flag followed by your desired path when launching the CLI. For example: `aisuite-code --artifact-root=/tmp/artifacts`. The CLI parses this flag in [`config.py`](https://github.com/andrewyng/aisuite/blob/main/config.py) (lines 86-88) and resolves it to an absolute path before creating the `FileArtifactStore`.

### Can I disable disk storage for artifacts in AISuite?

Yes, you can avoid writing to disk by using `InMemoryArtifactStore` instead of `FileArtifactStore`. This is particularly useful for unit testing or when running agents in ephemeral environments where persistent storage is unnecessary.

### Where are artifact storage classes defined in the source code?

The storage classes are defined in [`aisuite/agents/artifact_store.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/agents/artifact_store.py). This file contains `ArtifactRef`, `Artifact`, `InMemoryArtifactStore`, and `FileArtifactStore` implementations. The CLI-specific configuration and instantiation logic resides in [`cli/py/aisuite-code-cli/aisuite_code_cli/config.py`](https://github.com/andrewyng/aisuite/blob/main/cli/py/aisuite-code-cli/aisuite_code_cli/config.py) and [`app.py`](https://github.com/andrewyng/aisuite/blob/main/app.py) respectively.