Artifact Storage

Persist large tool outputs to disk so agents can page through them on demand

When a tool returns more data than fits in context, Artifact Storage saves the overflow to disk and gives the agent tools to page through it — so nothing is silently lost.

from praisonaiagents import Agent
from praisonaiagents.config import ToolConfig

agent = Agent(
    name="Researcher",
    instructions="Research topics deeply.",
    tool_config=ToolConfig(enable_artifacts=True),
)
agent.start("Download and summarise the full release notes.")

The user asks for a large result; the agent stores the overflow as an artifact and pages through it with artifact tools instead of truncating silently.

Quick Start

1. Enable with one line

   from praisonaiagents import Agent
   from praisonaiagents.config import ToolConfig
   
   agent = Agent(
       name="Researcher",
       instructions="Research topics deeply",
       tools=[web_search],
       tool_config=ToolConfig(enable_artifacts=True)
   )
   
   agent.start("Summarise the latest LangChain release notes")
   # Large results are now saved to ~/.praisonai/artifacts/
   # instead of being silently truncated.

   The user asks for a summary; the agent reads artefacts from storage and replies.

2. With configuration

   from praisonaiagents import Agent
   from praisonaiagents.config import ToolConfig
   
   agent = Agent(
       name="Log Analyst",
       instructions="Analyse application logs",
       tools=[read_file],
       tool_config=ToolConfig(
           output_limit=32000,           # raise threshold to 32 KB
           enable_artifacts=True,
           artifact_retention_days=14,   # keep artifacts for 2 weeks
           redact_secrets=True,          # strip API keys / tokens before writing
       )
   )
   
   agent.start("Find errors in app.log from the last hour")

3. With a custom artifact store

   from praisonaiagents import Agent
   from praisonaiagents.config import ToolConfig
   from praisonaiagents.context import FileSystemArtifactStore
   
   store = FileSystemArtifactStore(base_dir="/data/my-artifacts")
   
   agent = Agent(
       name="Data Analyst",
       instructions="Analyse large datasets",
       tools=[query_database],
       tool_config=ToolConfig(
           enable_artifacts=True,
           artifact_store=store,
       )
   )

How It Works

When a tool returns output larger than output_limit, the agent:

1. Writes the full content to ~/.praisonai/artifacts/{agent_id}/{run_id}/
2. Replaces the oversize output with a short preview and an [ArtifactRef ...] line
3. Gains six new tools (auto-registered) to page through the stored content

The agent picks these up autonomously — you do not call them manually.

Configuration Options

Validation rules:

• output_limit must be > 0
• output_max_lines, if set, must be > 0
• output_direction must be one of "head", "tail", or "both"
• artifact_retention_days must be >= 0

Retrieval Tools the Agent Gains

These tools are auto-registered on first overflow — you do not add them manually.

When a tool output is too large, the agent sees a truncated preview with a line like:

[Artifact from web_search: /home/user/.praisonai/artifacts/agent1/run1/abc123.artifact (204.8 KB) - First 200 chars of content...]

The agent then calls artifact_grep, artifact_chunk, or other tools autonomously to retrieve the parts it needs.

Storage Layout

Artifacts are stored under ~/.praisonai/artifacts/ by default:

~/.praisonai/artifacts/
└── {agent_id}/
    └── {run_id}/
        ├── {sha256[:12]}_{uuid8}.artifact       # raw content
        └── {sha256[:12]}_{uuid8}.meta.json      # metadata

The .meta.json file contains size, mime type, checksum (SHA256), tool name, and turn number.

Security: The store rejects any retrieval path outside base_dir and any extension other than .artifact. Keep this in mind when writing custom store implementations.

Cleanup: Artifacts older than artifact_retention_days are removed when the agent is finalized (garbage collected). Set artifact_retention_days=0 to disable retention-based cleanup.

Which Option Should I Use?

Common Patterns

Long web scrapes

An agent scrapes a 200 KB page. The preview shows head and tail, and the agent uses artifact_grep to find “pricing” without re-scraping:

from praisonaiagents import Agent
from praisonaiagents.config import ToolConfig

agent = Agent(
    name="Web Researcher",
    instructions="Research pricing information from websites",
    tools=[web_scrape],
    tool_config=ToolConfig(
        enable_artifacts=True,
        output_limit=8000,
    )
)

agent.start("Find pricing tiers on stripe.com")
# Agent scrapes page → overflow stored → uses artifact_grep("pricing") autonomously

Log file analysis

read_file over a 5 MB log spills to disk. The agent uses artifact_chunk to inspect around an error timestamp:

from praisonaiagents import Agent
from praisonaiagents.config import ToolConfig

agent = Agent(
    name="Log Analyst",
    instructions="Find errors in application logs",
    tools=[read_file],
    tool_config=ToolConfig(
        enable_artifacts=True,
        output_limit=16000,
        artifact_retention_days=1,  # logs don't need long retention
    )
)

agent.start("Find what caused the 503 errors at 14:32 UTC in /var/log/app.log")
# Agent reads file → overflow stored → uses artifact_chunk(start_line=4500, end_line=4600)

Custom store backend

Power users can supply their own store instead of the filesystem default:

from praisonaiagents import Agent
from praisonaiagents.config import ToolConfig
from praisonaiagents.context import ArtifactStoreProtocol

class S3ArtifactStore:
    """Custom store that writes artifacts to S3."""
    def store(self, content, metadata): ...
    def load(self, ref): ...
    def head(self, ref, lines=50): ...
    def tail(self, ref, lines=50): ...
    def grep(self, ref, pattern, context_lines=2, max_matches=50): ...
    def chunk(self, ref, start_line=1, end_line=None): ...
    def list_artifacts(self, run_id=None, agent_id=None, tool_name=None): ...

agent = Agent(
    name="Cloud Analyst",
    instructions="Analyse cloud resources",
    tools=[fetch_cloud_data],
    tool_config=ToolConfig(
        enable_artifacts=True,
        artifact_store=S3ArtifactStore(bucket="my-artifacts"),
    )
)

Best Practices

Related