How to Configure Artifact Storage for Agent Output in AISuite

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, 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. 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 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 (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 (lines 86-88) and normalized to an absolute path before storage initialization.

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.

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.

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:

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.

Embedded Python Script Configuration

For production deployments requiring specific storage locations:

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:

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, 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 (storage backends) and 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 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 (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. 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 and app.py respectively.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}