Tool Output Spill

Save large execute_command output to disk so the agent keeps a preview plus a path to the full log

Large execute_command output is saved to disk so nothing is lost, and the agent gets a preview plus a path to read the full log.

Quick Start

1. Default (spill is already on)

   No code change is required — spill is enabled by default.

   from praisonaiagents import Agent
   from praisonaiagents.tools import execute_command
   
   agent = Agent(
       name="BuildRunner",
       instructions="Run the test suite and read the saved log if output is truncated.",
       tools=[execute_command],
   )
   
   agent.start("Run pytest and report which tests failed")

   When the test log overflows, the tool result includes a stdout_artifact path — the agent reads that file for the failing traceback that used to be truncated away.

2. Pin artifacts to a workspace dir

   Set PRAISONAI_TOOL_OUTPUT_DIR for cross-session retrieval.

   export PRAISONAI_TOOL_OUTPUT_DIR=./.praisonai/logs

3. Override per call or opt out

   Pass spill_dir explicitly, or spill=False for the legacy middle-truncated preview.

   result = execute_command("very-noisy-command", spill_dir="./logs")
   
   result = execute_command("very-noisy-command", spill=False)

How It Works

Configuration Options

The directory resolves in this order: spill_dir argument, then PRAISONAI_TOOL_OUTPUT_DIR, then <system temp>/praisonai_tool_output/.

What the Agent Sees

When spill fires, the preview keeps the head and tail with a pointer line in the middle:

<head bytes...>
...[52,318 chars / 894 lines truncated in preview]...
Full output saved to: /tmp/praisonai_tool_output/stdout_xxxxx.txt
Use read_file/grep on that path to inspect the omitted region (do NOT re-run the command through head/tail).
<tail bytes...>

Retrieval

The agent reads the omitted region straight from the artifact path.

from praisonaiagents.tools import read_file

read_file("/tmp/praisonai_tool_output/stdout_xxxxx.txt")

Best Practices

Related