Tool output management

Production-ready tool output management system for LangGraph ReAct agents.

This module provides a comprehensive system for managing tool outputs in ReAct agents, including secure reference resolution, lifecycle management, and hybrid storage patterns.

Key Features: - Automatic and manual tool output storage with configurable lifecycle management - Secure reference resolution with validation and sanitization - LLM-friendly output summaries with data previews and tool context - Production-ready error handling with specialized exceptions - Memory management with automatic cleanup based on age and size limits

Authors

Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id) Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)

StoreOutputParams(call_id, tool_name, data, tool_args, thread_id, description=None, tags=None, agent_name=None) dataclass

Parameters for storing tool outputs.

Reduces the number of arguments passed to store_output method.

Attributes:

Name	Type	Description
call_id	str	Unique identifier for this tool call.
tool_name	str	Name of the tool that produced the output.
data	Any	The actual output data to store.
tool_args	dict[str, Any]	Input arguments used for the tool call.
thread_id	str	Thread/conversation ID to organize outputs by conversation.
description	str | None	Optional human-readable description of the output.
tags	list[str] | None	Optional list of tags for categorization.
agent_name	str | None	Name of the agent that created this output.

ToolOutput(call_id, tool_name, timestamp, size_bytes, tool_args, data=None, data_description=None, tags=None, agent_name=None) dataclass

Container for tool outputs with optional data payload.

This class represents tool output metadata and optionally the actual data. When used as metadata only, the data field is None and must be retrieved from storage. When loaded with data, it contains the complete output.

Attributes:

Name	Type	Description
call_id	str	Unique identifier for this tool call, used for reference resolution.
tool_name	str	Name of the tool that produced this output.
timestamp	datetime	When this output was created and stored.
size_bytes	int	Approximate size of the stored data in bytes for memory management.
tool_args	dict[str, Any]	Input arguments that were passed to the tool for this call.
data	Any | None	Optional actual output data. None when used as metadata only.
data_description	str | None	Optional human-readable description of the data content, typically provided by the tool itself.
tags	list[str] | None	Optional list of tags for categorization and filtering.
agent_name	str | None	Name of the agent that created this output, for multi-agent context.

is_metadata_only: bool property

Check if this instance contains only metadata without data.

get_data_preview(max_length=200, storage_provider=None, thread_id=None)

Get a truncated string representation of the stored data.

Parameters:

Name	Type	Description	Default
max_length	int	Maximum length of the preview string.	200
storage_provider	BaseStorageProvider | None	Required only if data is not loaded.	None
thread_id	str | None	Thread ID required for proper storage key generation.	None

Returns:

Type	Description
str | None	A string representation of the data, truncated if necessary. None if data is not found.

is_expired(max_age)

Check if this output has expired based on the given maximum age.

with_data(data)

Create a new instance with data populated.

Returns a new ToolOutput instance with the same metadata but with data field populated. Useful for converting metadata-only instances to complete instances.

ToolOutputConfig(max_stored_outputs=100, max_age_minutes=60, cleanup_interval=20, storage_provider=None) dataclass

Configuration for tool output management system.

This class defines the operational parameters for the tool output management system, including storage limits, cleanup intervals, and lifecycle policies.

Attributes:

Name	Type	Description
max_stored_outputs	int	Maximum number of tool outputs to store simultaneously. When this limit is reached, oldest outputs are evicted. Defaults to 100.
max_age_minutes	int	Maximum age in minutes for stored outputs before they become eligible for cleanup. Defaults to 60 minutes.
cleanup_interval	int	Number of tool calls between automatic cleanup operations. Set to 0 to disable automatic cleanup. Defaults to 20.
storage_provider	BaseStorageProvider | None	Optional storage provider for persistent storage. If None, uses in-memory storage (backward compatible). Defaults to None.

ToolOutputManager(config)

Production-ready tool output manager with comprehensive lifecycle management.

This class provides centralized management of tool outputs including storage, retrieval, lifecycle management, and LLM-friendly summarization. It handles memory management through configurable cleanup policies and provides secure access to stored outputs.

Key Features: - Automatic and manual storage of tool outputs with metadata - Configurable lifecycle management with age and size-based eviction - LLM-friendly summary generation with data previews and context - Memory management with size tracking and cleanup - Thread-safe operations with proper error handling and locking - Concurrent access support for multi-agent and parallel processing scenarios

Attributes:

Name	Type	Description
config		Configuration object defining operational parameters.

Initialize the ToolOutputManager with the given configuration.

Parameters:

Name	Type	Description	Default
config	ToolOutputConfig	Configuration object defining storage limits and cleanup policies.	required

clear_all()

Clear all stored outputs from both metadata and storage.

Warning

This operation is irreversible and will remove all stored tool outputs.

generate_summary(thread_id, max_entries=10)

Generate an LLM-friendly structured summary as JSON.

This method creates a comprehensive, structured summary of stored outputs that can be easily parsed by LLMs and other systems. The JSON format provides rich metadata and context about each tool output.

Thread-safe: This method uses internal locking to ensure safe concurrent access.

Parameters:

Name	Type	Description	Default
thread_id	str	Thread ID to generate summary for.	required
max_entries	int	Maximum number of entries to include in the summary. Defaults to 10.	10

Returns:

Type	Description
str	A JSON string containing structured data about tool outputs. Always returns
str	valid JSON, even when no outputs are stored (empty entries list).

get_output(call_id, thread_id)

Retrieve a stored tool output by its call ID and thread ID.

Thread-safe: This method uses internal locking to ensure safe concurrent access.

Parameters:

Name	Type	Description	Default
call_id	str	The unique identifier for the tool call.	required
thread_id	str	The thread/conversation ID to search in.	required

Returns:

Type	Description
ToolOutput | None	The ToolOutput object with data if found, None otherwise.

get_storage_stats()

Get storage statistics for monitoring and debugging.

Returns:

Type	Description
dict[str, Any]	Dictionary containing storage statistics.

has_outputs(thread_id=None)

Check if any outputs are currently stored.

Thread-safe: This method uses internal locking to ensure safe concurrent access.

Parameters:

Name	Type	Description	Default
thread_id	str | None	Optional thread ID to check for outputs in a specific thread. If None, checks across all threads.	None

Returns:

Type	Description
bool	True if there are stored outputs, False otherwise.

store_output(params)

Store a tool output with automatic cleanup and size management.

This method stores a tool output along with its metadata, automatically handling size limits, cleanup, and memory management. If the same call_id is used multiple times within the same thread, the previous output will be overwritten.

Thread-safe: This method uses internal locking to ensure safe concurrent access.

Parameters:

Name	Type	Description	Default
params	StoreOutputParams	StoreOutputParams containing all necessary parameters including thread_id.	required

Raises:

Type	Description
Exception	If storage operation fails for any reason.

ToolReferenceError(message, reference=None, call_id=None, details=None)

Bases: Exception

Specialized exception for tool output reference resolution errors.

This exception is raised when there are issues with resolving tool output references, such as invalid reference syntax, missing outputs, or security violations.

Attributes:

Name	Type	Description
reference		The original reference string that caused the error.
call_id		The call ID that was attempted to be resolved, if applicable.
details		Additional error details for debugging.

Initialize a ToolReferenceError.

Parameters:

Name	Type	Description	Default
message	str	Human-readable error message describing what went wrong.	required
reference	str | None	The original reference string that caused the error, if applicable.	None
call_id	str | None	The call ID that was attempted to be resolved, if applicable.	None
details	dict[str, Any] | None	Additional error details for debugging, if applicable.	None

__str__()

Return a detailed string representation of the error.

Returns:

Type	Description
str	A formatted error message with context information.

ToolReferenceResolver(config)

Secure and efficient tool output reference resolution system.

This class handles the resolution of tool output references in a secure manner, preventing injection attacks while providing simple and reliable access to stored tool outputs. It uses a whitelist approach with regex validation to ensure only safe references are processed.

Security Features: - Strict regex pattern matching for reference syntax - Whitelist-based validation to prevent injection attacks - Fail-fast error handling with detailed error messages - Input sanitization and validation at multiple levels

Supported Reference Syntax: - $tool_output. - Direct reference to a tool output by call ID

Attributes:

Name	Type	Description
config		Configuration object for operational parameters.

Initialize the ToolReferenceResolver with security configuration.

Parameters:

Name	Type	Description	Default
config	ToolOutputConfig	Configuration object defining operational parameters.	required

resolve_references(args, manager, thread_id=None)

Resolve all tool output references in the given arguments dictionary.

This method recursively processes a dictionary of tool arguments, finding and resolving any tool output references. It supports nested dictionaries and lists, providing comprehensive reference resolution.

Parameters:

Name	Type	Description	Default
args	dict[str, Any]	Dictionary of tool arguments that may contain references.	required
manager	ToolOutputManager	ToolOutputManager instance to resolve references against.	required
thread_id	str | None	Optional thread ID for context-aware resolution.	None

Returns:

Type	Description
dict[str, Any]	New dictionary with all references resolved to their actual values.

Raises:

Type	Description
ToolReferenceError	If any reference is invalid or cannot be resolved.