Tool Output Store

When a tool output is too large for context, the full result is saved to disk so the agent can read it back on demand.

from praisonaiagents import Agent, tool

@tool
def fetch_large_report(query: str) -> str:
    """Return a very large text blob."""
    return "x" * 100_000

agent = Agent(
    name="Researcher",
    instructions="If output is truncated, read the full file from the stored path.",
    tools=[fetch_large_report],
)
agent.start("Fetch the latest report")

The user asks for a large tool result; oversized output is stored on disk and the agent gets a preview plus a path to read the full file.

Quick Start

Zero-config (default retention)

from praisonaiagents import Agent, tool

@tool
def fetch_large_report(query: str) -> str:
    """Return a very large text blob."""
    return "x" * 100_000

agent = Agent(
    name="Researcher",
    instructions="If output is truncated, read the full file from the stored path.",
    tools=[fetch_large_report],
)
agent.start("Fetch the latest report")

No setup required — overflow outputs are stored automatically under ~/.praisonai/cache/tool_outputs/.

Custom retention

export PRAISONAI_TOOL_OUTPUT_RETENTION_HOURS=72

Or programmatically:

from praisonaiagents.runtime.tool_output_store import ToolOutputStore

store = ToolOutputStore(retention_hours=72)

How It Works

Step	What happens
1	Tool returns output exceeding the context budget
2	Full text is written to `~/.praisonai/cache/tool_outputs/{run_id}/{call_id}.txt` — `run_id` is auto-threaded from the current agent run
3	Inline preview keeps head/tail with `Full output stored at: <path>`
4	Agent uses `read_file` (or similar) to fetch omitted content

What the Agent Sees

First part of output...
...[50,000 chars, showing first/last portions | Full output stored at: ~/.praisonai/cache/tool_outputs/<run>/<call>.txt]...
Last part of output...

The agent can then read the full file from the path in the marker.

Configuration

Option	Type	Default	Description
`run_id`	`Optional[str]`	auto UUID	Scopes outputs to one run
`retention_hours`	`Optional[int]`	`24`	TTL for old run directories
`PRAISONAI_TOOL_OUTPUT_RETENTION_HOURS`	env	`24`	Same as `retention_hours` default

Storage Layout

~/.praisonai/cache/
└── tool_outputs/
    └── {run_id}/
        ├── {call_id_1}.txt
        └── {tool}.{field}_{uuid}.txt

When no run_id is supplied — i.e. get_tool_output_store() is called with no argument outside of an agent run — the store returns a fresh, un-cached instance scoped to a new auto-generated UUID. It does not adopt whichever store happens to be live process-wide, so outputs from unrelated runs never share a directory.

Retrieve Programmatically

from praisonaiagents.runtime.tool_output_store import get_tool_output_store

store = get_tool_output_store()
full_text = store.retrieve("/path/from/the/preview/marker.txt")

Common Patterns

Long-running research agents — web search bodies are stored when truncated; the agent reads them back in a follow-up turn. Pair with per-tool budgets — combine with Context Per-Tool Budgets for fine-grained limits. Short retention on CI — set PRAISONAI_TOOL_OUTPUT_RETENTION_HOURS=1 on shared runners.

Best Practices

Keep retention short on shared/CI machines

Old run directories are removed when older than the retention window on the next store initialisation.

Don't store secrets

Outputs are plaintext on disk — avoid tools that return credentials or tokens into the store.

Use stable run_id when chaining runs

Pass a consistent run_id to get_tool_output_store(run_id=...) when multiple agents share one session.

Isolation is automatic inside agents

Inside an agent run, run_id is threaded through automatically from the agent’s internal run context. You do not need to pass it yourself — overflow outputs go under ~/.praisonai/cache/tool_outputs/<run_id>/ scoped to that run. If you build a workflow that shares outputs across agents, pass a stable run_id explicitly to get_tool_output_store(run_id=...) so they land in the same directory.

Combine with per-tool budgets

Use per-tool budgets to control inline size; the store handles anything that still overflows.

Not the same as Tool Output Spill. This store handles arbitrary large tool return values with time-based retention under ~/.praisonai/cache/ (PRAISONAI_TOOL_OUTPUT_RETENTION_HOURS). Tool Output Spill is specific to execute_command and uses a different dir (PRAISONAI_TOOL_OUTPUT_DIR) with process-exit cleanup.

Tool Output Spill

Save large execute_command output to a retrievable artifact

Context Per-Tool Budgets

Per-tool truncation limits

Context Window Management

Overflow and compaction strategies

Context Management

Agent context lifecycle

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

What the Agent Sees

Configuration

Storage Layout

Retrieve Programmatically

Common Patterns

Best Practices

Tool Output Spill

Context Per-Tool Budgets

Context Window Management

Context Management

​Quick Start

​How It Works

​What the Agent Sees

​Configuration

​Storage Layout

​Retrieve Programmatically

​Common Patterns

​Best Practices

​Related

Tool Output Spill

Context Per-Tool Budgets

Context Window Management

Context Management

Quick Start

How It Works

What the Agent Sees

Configuration

Storage Layout

Retrieve Programmatically

Common Patterns

Best Practices

Related