Tool Output Store

Recover full tool outputs after truncation via persistent on-disk storage

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

1. 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/.

2. 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

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

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

Related