Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: add tool call caching for chatAgent (#3259)

Xiaotian Jin5a7c335ad266
diff --git a/camel/agents/chat_agent.py b/camel/agents/chat_agent.py
index 6ef16aecd..4b953dd9a 100644
--- a/camel/agents/chat_agent.py
+++ b/camel/agents/chat_agent.py
@@ -30,6 +30,7 @@ import threading
import time
import uuid
import warnings
+from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
from typing import (
@@ -159,6 +160,53 @@ SIMPLE_FORMAT_PROMPT = TextPrompt(
)
+@dataclass
+class _ToolOutputHistoryEntry:
+ tool_name: str
+ tool_call_id: str
+ result_text: str
+ record_uuids: List[str]
+ record_timestamps: List[float]
+ preview_text: str
+ cached: bool = False
+ cache_id: Optional[str] = None
+
+
+class _ToolOutputCacheManager:
+ r"""Minimal persistent store for caching verbose tool outputs."""
+
+ def __init__(self, base_dir: Union[str, Path]) -> None:
+ self.base_dir = Path(base_dir).expanduser().resolve()
+ self.base_dir.mkdir(parents=True, exist_ok=True)
+
+ def save(
+ self,
+ tool_name: str,
+ tool_call_id: str,
+ content: str,
+ ) -> Tuple[str, Path]:
+ cache_id = uuid.uuid4().hex
+ filename = f"{cache_id}.txt"
+ path = self.base_dir / filename
+ header = (
+ f"# Cached tool output\n"
+ f"tool_name: {tool_name}\n"
+ f"tool_call_id: {tool_call_id}\n"
+ f"cache_id: {cache_id}\n"
+ f"---\n"
+ )
+ path.write_text(f"{header}{content}", encoding="utf-8")
+ return cache_id, path
+
+ def load(self, cache_id: str) -> str:
+ path = self.base_dir / f"{cache_id}.txt"
+ if not path.exists():
+ raise FileNotFoundError(
+ f"Cached tool output {cache_id} not found at {path}"
+ )
+ return path.read_text(encoding="utf-8")
+
+
class StreamContentAccumulator:
r"""Manages content accumulation across streaming responses to ensure
all responses contain complete cumulative content."""
@@ -404,6 +452,19 @@ class ChatAgent(BaseAgent):
usage. When enabled, removes FUNCTION/TOOL role messages and
ASSISTANT messages with tool_calls after each step.
(default: :obj:`False`)
+ enable_tool_output_cache (bool, optional): Whether to offload verbose
+ historical tool outputs to a local cache and replace them with
+ lightweight references in memory. Only older tool results whose
+ payload length exceeds ``tool_output_cache_threshold`` are cached.
+ (default: :obj:`True`)
+ tool_output_cache_threshold (int, optional): Minimum character length
+ of a tool result before it becomes eligible for caching. Values
+ below or equal to zero disable caching regardless of the toggle.
+ (default: :obj:`2000`)
+ tool_output_cache_dir (Optional[Union[str, Path]], optional): Target
+ directory for cached tool outputs. When omitted, a ``tool_cache``
+ directory relative to the current working directory is used.
+ (default: :obj:`None`)
retry_attempts (int, optional): Maximum number of retry attempts for
rate limit errors. (default: :obj:`3`)
retry_delay (float, optional): Initial delay in seconds between
@@ -455,6 +516,9 @@ class ChatAgent(BaseAgent):
mask_tool_output: bool = False,
pause_event: Optional[Union[threading.Event, asyncio.Event]] = None,
prune_tool_calls_from_memory: bool = False,
+ enable_tool_output_cache: bool = True,
+ tool_output_cache_threshold: int = 2000,
+ tool_output_cache_dir: Optional[Union[str, Path]] = None,
retry_attempts: int = 3,
retry_delay: float = 1.0,
step_timeout: Optional[float] = None,
@@ -474,6 +538,28 @@ class ChatAgent(BaseAgent):
# Assign unique ID
self.agent_id = agent_id if agent_id else str(uuid.uuid4())
+ self._tool_output_cache_enabled = (
+ enable_tool_output_cache and tool_output_cache_threshold > 0
+ )
+ self._tool_output_cache_threshold = max(0, tool_output_cache_threshold)
+ self._tool_output_cache_dir: Optional[Path]
+ self._tool_output_cache_manager: Optional[_ToolOutputCacheManager]
+ if self._tool_output_cache_enabled:
+ cache_dir = (
+ Path(tool_output_cache_dir).expanduser()
+ if tool_output_cache_dir is not None
+ else Path("tool_cache")
+ )
+ self._tool_output_cache_dir = cache_dir
+ self._tool_output_cache_manager = _ToolOutputCacheManager(
+ cache_dir
+ )
+ else:
+ self._tool_output_cache_dir = None
+ self._tool_output_cache_manager = None
+ self._tool_output_history: List[_ToolOutputHistoryEntry] = []
+ self._cache_lookup_tool_name = "retrieve_cached_tool_output"
+
# Set up memory
context_creator = ScoreBasedContextCreator(
self.model_backend.token_counter,
@@ -520,6 +606,8 @@ class ChatAgent(BaseAgent):
convert_to_function_tool(tool) for tool in (tools or [])
]
}
+ if self._tool_output_cache_enabled:
+ self._ensure_tool_cache_lookup_tool()
# Register agent with toolkits that have RegisteredAgentToolkit mixin
if toolkits_to_register_agent:
@@ -556,6 +644,8 @@ class ChatAgent(BaseAgent):
r"""Resets the :obj:`ChatAgent` to its initial state."""
self.terminated = False
self.init_messages()
+ if self._tool_output_cache_enabled:
+ self._tool_output_history.clear()
for terminator in self.response_terminators:
terminator.reset()
@@ -776,6 +866,178 @@ class ChatAgent(BaseAgent):
for tool in tools:
self.add_tool(tool)
+ def retrieve_cached_tool_output(self, cache_id: str) -> str:
+ r"""Load a cached tool output by its cache identifier.
+
+ Args:
+ cache_id (str): Identifier provided in cached tool messages.
+
+ Returns:
+ str: The cached content or an explanatory error message.
+ """
+ if not self._tool_output_cache_manager:
+ return "Tool output caching is disabled for this agent instance."
+
+ normalized_cache_id = cache_id.strip()
+ if not normalized_cache_id:
+ return "Please provide a non-empty cache_id."
+
+ try:
+ return self._tool_output_cache_manager.load(normalized_cache_id)
+ except FileNotFoundError:
+ return (
+ f"Cache entry '{normalized_cache_id}' was not found. "
+ "Verify the identifier and try again."
+ )
+
+ def _ensure_tool_cache_lookup_tool(self) -> None:
+ if not self._tool_output_cache_enabled:
+ return
+ lookup_name = self._cache_lookup_tool_name
+ if lookup_name in self._internal_tools:
+ return
+ lookup_tool = convert_to_function_tool(
+ self.retrieve_cached_tool_output
+ )
+ self._internal_tools[lookup_tool.get_function_name()] = lookup_tool
+
+ def _serialize_tool_result(self, result: Any) -> str:
+ if isinstance(result, str):
+ return result
+ try:
+ return json.dumps(result, ensure_ascii=False)
+ except (TypeError, ValueError):
+ return str(result)
+
+ def _summarize_tool_result(self, text: str, limit: int = 160) -> str:
+ normalized = re.sub(r"\s+", " ", text).strip()
+ if len(normalized) <= limit:
+ return normalized
+ return normalized[: max(0, limit - 3)].rstrip() + "..."
+
+ def _register_tool_output_for_cache(
+ self,
+ func_name: str,
+ tool_call_id: str,
+ result_text: str,
+ records: List[MemoryRecord],
+ ) -> None:
+ if not records:
+ return
+
+ entry = _ToolOutputHistoryEntry(
+ tool_name=func_name,
+ tool_call_id=tool_call_id,
+ result_text=result_text,
+ record_uuids=[str(record.uuid) for record in records],
+ record_timestamps=[record.timestamp for record in records],
+ preview_text=self._summarize_tool_result(result_text),
+ )
+ self._tool_output_history.append(entry)
+ self._process_tool_output_cache()
+
+ def _process_tool_output_cache(self) -> None:
+ if (
+ not self._tool_output_cache_enabled
+ or not self._tool_output_history
+ or self._tool_output_cache_manager is None
+ ):
+ return
+
+ # Only cache older results; keep the latest expanded for immediate use.
+ for entry in self._tool_output_history[:-1]:
+ if entry.cached:
+ continue
+ if len(entry.result_text) < self._tool_output_cache_threshold:
+ continue
+ self._cache_tool_output_entry(entry)
+
+ def _cache_tool_output_entry(self, entry: _ToolOutputHistoryEntry) -> None:
+ if self._tool_output_cache_manager is None or not entry.record_uuids:
+ return
+
+ try:
+ cache_id, cache_path = self._tool_output_cache_manager.save(
+ entry.tool_name,
+ entry.tool_call_id,
+ entry.result_text,
+ )
+ except Exception as exc: # pragma: no cover - defensive
+ logger.warning(
+ "Failed to persist cached tool output for %s (%s): %s",
+ entry.tool_name,
+ entry.tool_call_id,
+ exc,
+ )
+ return
+
+ timestamp = (
+ entry.record_timestamps[0]
+ if entry.record_timestamps
+ else time.time_ns() / 1_000_000_000
+ )
+ reference_message = FunctionCallingMessage(
+ role_name=self.role_name,
+ role_type=self.role_type,
+ meta_dict={
+ "cache_id": cache_id,
+ "cached_preview": entry.preview_text,
+ "cached_tool_output_path": str(cache_path),
+ },
+ content="",
+ func_name=entry.tool_name,
+ result=self._build_cache_reference_text(entry, cache_id),
+ tool_call_id=entry.tool_call_id,
+ )
+
+ chat_history_block = getattr(self.memory, "_chat_history_block", None)
+ storage = getattr(chat_history_block, "storage", None)
+ if storage is None:
+ return
+
+ existing_records = storage.load()
+ updated_records = [
+ record
+ for record in existing_records
+ if record["uuid"] not in entry.record_uuids
+ ]
+ new_record = MemoryRecord(
+ message=reference_message,
+ role_at_backend=OpenAIBackendRole.FUNCTION,
+ timestamp=timestamp,
+ agent_id=self.agent_id,
+ )
+ updated_records.append(new_record.to_dict())
+ updated_records.sort(key=lambda record: record["timestamp"])
+ storage.clear()
+ storage.save(updated_records)
+
+ logger.info(
+ "Cached tool output '%s' (%s) to %s with cache_id=%s",
+ entry.tool_name,
+ entry.tool_call_id,
+ cache_path,
+ cache_id,
+ )
+
+ entry.cached = True
+ entry.cache_id = cache_id
+ entry.record_uuids = [str(new_record.uuid)]
+ entry.record_timestamps = [timestamp]
+
+ def _build_cache_reference_text(
+ self, entry: _ToolOutputHistoryEntry, cache_id: str
+ ) -> str:
+ preview = entry.preview_text or "[no preview available]"
+ return (
+ "[cached tool output]\n"
+ f"tool: {entry.tool_name}\n"
+ f"cache_id: {cache_id}\n"
+ f"preview: {preview}\n"
+ f"Use `{self._cache_lookup_tool_name}` with this cache_id to "
+ "retrieve the full content."
+ )
+
def add_external_tool(
self, tool: Union[FunctionTool, Callable, Dict[str, Any]]
) -> None:
@@ -820,7 +1082,8 @@ class ChatAgent(BaseAgent):
message: BaseMessage,
role: OpenAIBackendRole,
timestamp: Optional[float] = None,
- ) -> None:
+ return_records: bool = False,
+ ) -> Optional[List[MemoryRecord]]:
r"""Updates the agent memory with a new message.
If the single *message* exceeds the model's context window, it will
@@ -840,21 +1103,29 @@ class ChatAgent(BaseAgent):
timestamp (Optional[float], optional): Custom timestamp for the
memory record. If `None`, the current time will be used.
(default: :obj:`None`)
- (default: obj:`None`)
+ return_records (bool, optional): When ``True`` the method returns
+ the list of :class:`MemoryRecord` objects written to memory.
+ (default: :obj:`False`)
+
+ Returns:
+ Optional[List[MemoryRecord]]: The records that were written when
+ ``return_records`` is ``True``; otherwise ``None``.
"""
+ written_records: List[MemoryRecord] = []
+
# 1. Helper to write a record to memory
def _write_single_record(
message: BaseMessage, role: OpenAIBackendRole, timestamp: float
):
- self.memory.write_record(
- MemoryRecord(
- message=message,
- role_at_backend=role,
- timestamp=timestamp,
- agent_id=self.agent_id,
- )
+ record = MemoryRecord(
+ message=message,
+ role_at_backend=role,
+ timestamp=timestamp,
+ agent_id=self.agent_id,
)
+ written_records.append(record)
+ self.memory.write_record(record)
base_ts = (
timestamp
@@ -869,7 +1140,7 @@ class ChatAgent(BaseAgent):
token_limit = context_creator.token_limit
except AttributeError:
_write_single_record(message, role, base_ts)
- return
+ return written_records if return_records else None
# 3. Check if slicing is necessary
try:
@@ -885,14 +1156,14 @@ class ChatAgent(BaseAgent):
if current_tokens <= remaining_budget:
_write_single_record(message, role, base_ts)
- return
+ return written_records if return_records else None
except Exception as e:
logger.warning(
f"Token calculation failed before chunking, "
f"writing message as-is. Error: {e}"
)
_write_single_record(message, role, base_ts)
- return
+ return written_records if return_records else None
# 4. Perform slicing
logger.warning(
@@ -913,18 +1184,18 @@ class ChatAgent(BaseAgent):
if not text_to_chunk or not text_to_chunk.strip():
_write_single_record(message, role, base_ts)
- return
+ return written_records if return_records else None
# Encode the entire text to get a list of all token IDs
try:
all_token_ids = token_counter.encode(text_to_chunk)
except Exception as e:
logger.error(f"Failed to encode text for chunking: {e}")
_write_single_record(message, role, base_ts) # Fallback
- return
+ return written_records if return_records else None
if not all_token_ids:
_write_single_record(message, role, base_ts) # Nothing to chunk
- return
+ return written_records if return_records else None
# 1. Base chunk size: one-tenth of the smaller of (a) total token
# limit and (b) current remaining budget. This prevents us from
@@ -990,6 +1261,8 @@ class ChatAgent(BaseAgent):
# Increment timestamp slightly to maintain order
_write_single_record(new_msg, role, base_ts + i * 1e-6)
+ return written_records if return_records else None
+
def load_memory(self, memory: AgentMemory) -> None:
r"""Load the provided memory into the agent.
@@ -1310,6 +1583,8 @@ class ChatAgent(BaseAgent):
None
"""
self.memory.clear()
+ if self._tool_output_cache_enabled:
+ self._tool_output_history.clear()
if self.system_message is not None:
self.update_memory(self.system_message, OpenAIBackendRole.SYSTEM)
@@ -2740,14 +3015,18 @@ class ChatAgent(BaseAgent):
base_timestamp = current_time_ns / 1_000_000_000 # Convert to seconds
self.update_memory(
- assist_msg, OpenAIBackendRole.ASSISTANT, timestamp=base_timestamp
+ assist_msg,
+ OpenAIBackendRole.ASSISTANT,
+ timestamp=base_timestamp,
+ return_records=self._tool_output_cache_enabled,
)
# Add minimal increment to ensure function message comes after
- self.update_memory(
+ func_records = self.update_memory(
func_msg,
OpenAIBackendRole.FUNCTION,
timestamp=base_timestamp + 1e-6,
+ return_records=self._tool_output_cache_enabled,
)
# Record information about this tool call
@@ -2758,6 +3037,20 @@ class ChatAgent(BaseAgent):
tool_call_id=tool_call_id,
)
+ if (
+ self._tool_output_cache_enabled
+ and not mask_output
+ and func_records
+ and self._tool_output_cache_manager is not None
+ ):
+ serialized_result = self._serialize_tool_result(result)
+ self._register_tool_output_for_cache(
+ func_name,
+ tool_call_id,
+ serialized_result,
+ cast(List[MemoryRecord], func_records),
+ )
+
return tool_record
def _stream(
@@ -4109,6 +4402,9 @@ class ChatAgent(BaseAgent):
tool_execution_timeout=self.tool_execution_timeout,
pause_event=self.pause_event,
prune_tool_calls_from_memory=self.prune_tool_calls_from_memory,
+ enable_tool_output_cache=self._tool_output_cache_enabled,
+ tool_output_cache_threshold=self._tool_output_cache_threshold,
+ tool_output_cache_dir=self._tool_output_cache_dir,
stream_accumulate=self.stream_accumulate,
)
diff --git a/examples/agents/agent_tool_call_cache.py b/examples/agents/agent_tool_call_cache.py
new file mode 100644
index 000000000..d52164ce1
--- /dev/null
+++ b/examples/agents/agent_tool_call_cache.py
@@ -0,0 +1,247 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+"""Real-model example for ChatAgent tool-output caching.
+
+This demo uses a true LLM backend (configured via the default ``ModelFactory``)
+and a mock browser snapshot tool. The workflow is:
+
+1. Ask the agent to capture a very long snapshot (which will later be cached).
+2. Capture a concise update, triggering the caching of the earlier verbose
+ output.
+3. Ask the agent to retrieve the cached payload using the automatically
+ registered ``retrieve_cached_tool_output`` tool.
+
+Prerequisites:
+ - Set up the API credentials required by the default model backend
+ (for example, ``OPENAI_API_KEY`` if you're using OpenAI models).
+ - Optionally customize ``MODEL_PLATFORM`` / ``MODEL_TYPE`` via
+ environment variables to point to a different provider.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from camel.agents import ChatAgent
+from camel.messages import FunctionCallingMessage
+from camel.models import ModelFactory
+from camel.toolkits import FunctionTool
+from camel.types import (
+ ModelPlatformType,
+ ModelType,
+)
+
+# Mock payloads -------------------------------------------------------------
+SMARTPHONE_PAGE = """
+<html>
+ <body>
+ <header>
+ <h1>NovaPhone X Ultra Launch Event</h1>
+ <p>The flagship with HDR+ Pro display, titanium frame, and satellite SOS.</p>
+ <a class="cta-button" href="/buy">Pre-order now</a>
+ </header>
+ <section id="hero-carousel">
+ <article>
+ <h2>New Horizon Display</h2>
+ <p>6.9" adaptive 1-144Hz, peak brightness 4000 nits, Dolby Vision certified.</p>
+ </article>
+ <article>
+ <h2>Pro Camera Array</h2>
+ <p>Quad 50MP sensors, 200x adaptive zoom, neural night portrait, macro mode.</p>
+ </article>
+ <article>
+ <h2>Performance</h2>
+ <p>NovaCore G3 chip, 12GB LPDDR6, 1TB UFS 5.1 storage, Wi-Fi 7 ready.</p>
+ </article>
+ </section>
+ <section id="comparisons">
+ <table>
+ <tr><th>Model</th><th>Battery</th><th>Charging</th><th>Starting Price</th></tr>
+ <tr><td>NovaPhone X Ultra</td><td>5,500 mAh</td><td>120W wired / 80W wireless</td><td>$1099</td></tr>
+ <tr><td>NovaPhone X</td><td>5,000 mAh</td><td>80W wired / 50W wireless</td><td>$899</td></tr>
+ <tr><td>NovaPhone Air</td><td>4,700 mAh</td><td>45W wired / 25W wireless</td><td>$749</td></tr>
+ </table>
+ </section>
+ <section id="availability">
+ <p>Pre-orders open March 14, shipping starts March 28 in US, EU, and APAC.</p>
+ <ul>
+ <li>Colorways: Graphite Black, Aurora Blue, Sunset Copper, Alpine Ice.</li>
+ <li>Accessories: Smart Folio, 65W travel adapter, satellite communicator.</li>
+ <li>Trade-in bonus up to $450 for eligible devices.</li>
+ </ul>
+ </section>
+ <footer>
+ <p>Visit our Experience Labs for hands-on demos. Terms apply.</p>
+ </footer>
+ </body>
+</html>
+""" # noqa: E501
+
+WEATHER_DASHBOARD = """
+<div class="weather-widget">
+ <h1>City Weather</h1>
+ <p>Currently 68°F, partly cloudy.</p>
+ <p>Next hour: breezy with scattered clouds, no precipitation expected.</p>
+ <p>Sunset at 7:42 PM, UV index moderate.</p>
+</div>
+"""
+
+
+# Tool implementation -------------------------------------------------------
+def cache_browser_snapshot(snapshot: str) -> str:
+ """Return the provided snapshot verbatim so the cache can persist it."""
+ header = (
+ f"[browser_snapshot length={len(snapshot)} characters]\n"
+ "BEGIN_SNAPSHOT\n"
+ )
+ return header + snapshot + "\nEND_SNAPSHOT"
+
+
+# Utility functions ---------------------------------------------------------
+def _print_memory(agent: ChatAgent) -> None:
+ print("\n=== Memory after second step ===")
+ for idx, ctx_record in enumerate(agent.memory.retrieve(), start=1):
+ record = ctx_record.memory_record
+ message = record.message
+ role = record.role_at_backend.value
+ if isinstance(message, FunctionCallingMessage):
+ meta = message.meta_dict or {}
+ cache_id = meta.get("cache_id")
+ result = (
+ message.result
+ if isinstance(message.result, str)
+ else str(message.result)
+ )
+ preview = result.replace("\n", " ")[:140]
+ if cache_id:
+ print(
+ f"{idx:02d}. role={role} tool_call_id={message.tool_call_id} " # noqa:E501
+ f"(cached reference) cache_id={cache_id}"
+ )
+ print(f" preview: {preview}")
+ else:
+ print(
+ f"{idx:02d}. role={role} tool_call_id={message.tool_call_id} " # noqa:E501
+ f"(inline) preview={preview}"
+ )
+ else:
+ content = getattr(message, "content", "") or ""
+ print(f"{idx:02d}. role={role} content={content[:140]}")
+
+
+def _find_cached_entry(agent: ChatAgent):
+ for entry in agent._tool_output_history:
+ if entry.cached:
+ return entry
+ return None
+
+
+# Demo flow -----------------------------------------------------------------
+def main() -> None:
+ cache_dir = Path(__file__).resolve().parent / "tool_cache"
+ backend = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_4_1_MINI,
+ )
+ agent = ChatAgent(
+ system_message=("You are a browsing assistant."),
+ model=backend,
+ tools=[FunctionTool(cache_browser_snapshot)],
+ enable_tool_output_cache=True,
+ tool_output_cache_threshold=600,
+ tool_output_cache_dir=cache_dir,
+ prune_tool_calls_from_memory=False,
+ max_iteration=3,
+ )
+
+ print("\n>>> Step 1: Capture verbose snapshot")
+ prompt1 = (
+ "You just browsed the NovaPhone store."
+ "Store the current smartphone page exactly as-is "
+ "so we can reference it later. Here is the full markup:\n\n"
+ f"{SMARTPHONE_PAGE}"
+ )
+ response1 = agent.step(prompt1)
+ print(f"Assistant response: {response1.msg.content}")
+
+ print(
+ "\n>>> Step 2: Capture weather snapshot (triggers caching of step 1)"
+ )
+ prompt2 = (
+ "Now you are looking at a weather dashboard."
+ "Save the widget below as a new snapshot "
+ "without paraphrasing it:\n\n"
+ f"{WEATHER_DASHBOARD}"
+ )
+ response2 = agent.step(prompt2)
+ print(f"Assistant response: {response2.msg.content}")
+
+ _print_memory(agent)
+
+ cached_entry = _find_cached_entry(agent)
+ if not cached_entry or not cached_entry.cache_id:
+ print(
+ "\nNo cached entry detected. Ensure the tool was executed and the threshold is high enough." # noqa:E501
+ )
+ return
+
+ print("\n>>> Step 3: Ask about the smartphone page (trigger retrieval)")
+ prompt3 = (
+ "I need the details from the hero banner on the smartphone store "
+ "page—especially what it says about the display and core specs."
+ "Check whichever snapshots you recorded earlier before you answer."
+ )
+ response3 = agent.step(prompt3)
+ print(f"Assistant response:\n{response3.msg.content}")
+
+
+if __name__ == "__main__":
+ main()
+
+
+'''
+>>> Step 1: Capture verbose snapshot
+Assistant response: I have saved the current smartphone page from the NovaPhone store exactly as provided. You can reference it later as needed.
+
+>>> Step 2: Capture weather snapshot (triggers caching of step 1)
+Assistant response: The weather widget has been saved exactly as provided without any paraphrasing. Let me know if you'd like to do anything else with it.
+
+=== Memory after second step ===
+01. role=system content=You are a browsing assistant. Whenever you need to capture or recall a page, use the available tools to record or retrieve the exact text be
+02. role=user content=You just browsed the NovaPhone store. Store the current smartphone page exactly as-is so we can reference it later. Here is the full markup:
+03. role=assistant tool_call_id=call_iIILkyZtQvrfXHuLCMB2KWnM (inline) preview=None
+04. role=function tool_call_id=call_iIILkyZtQvrfXHuLCMB2KWnM (cached reference) cache_id=bd07770e0c0f461fbe31b4237f90ce2c
+ preview: [cached tool output] tool: cache_browser_snapshot cache_id: bd07770e0c0f461fbe31b4237f90ce2c preview: [browser_snapshot length=1724 characte
+05. role=assistant content=I have saved the current smartphone page from the NovaPhone store exactly as provided. You can reference it later as needed.
+06. role=user content=Now you are looking at a weather dashboard. Save the widget below as a new snapshot without paraphrasing it:
+
+
+<div class="weather-widget">
+
+07. role=assistant tool_call_id=call_wfl2szFZLV58kRhhRPsJPMnx (inline) preview=None
+08. role=function tool_call_id=call_wfl2szFZLV58kRhhRPsJPMnx (inline) preview=[browser_snapshot length=224 characters] BEGIN_SNAPSHOT <div class="weather-widget"> <h1>City Weather</h1> <p>Currently 686F, partly cl
+09. role=assistant content=The weather widget has been saved exactly as provided without any paraphrasing. Let me know if you'd like to do anything else with it.
+
+>>> Step 3: Ask about the smartphone page (should trigger retrieval)
+Assistant response:
+From the hero banner section of the smartphone store page the details about the display and core specs are:
+
+- Display (under "New Horizon Display"):
+ 6.9" adaptive 1-144Hz, peak brightness 4000 nits, Dolby Vision certified.
+
+- Performance (under "Performance"):
+ NovaCore G3 chip, 12GB LPDDR6, 1TB UFS 5.1 storage, Wi-Fi 7 ready.
+
+Let me know if you want more details from the page.
+''' # noqa: E501
diff --git a/pyproject.toml b/pyproject.toml
index d03ed0085..02ad86564 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -660,7 +660,7 @@ ignore_missing_imports = true
# Ref: https://github.com/codespell-project/codespell#using-a-config-file
# the .py file needs to be listed twice since pre-commit and codespell treat
# that path differently.
-skip = '.git*,*.pdf,*.svg,*.lock,*.css,examples/toolkits/semantic_scholar_toolkit.py,./examples/toolkits/semantic_scholar_toolkit.py,examples/usecases,./examples/usecases'
+skip = '.git*,*.pdf,*.svg,*.lock,*.css,examples/toolkits/semantic_scholar_toolkit.py,./examples/toolkits/semantic_scholar_toolkit.py,examples/usecases,./examples/usecases,examples/agents/agent_tool_call_cache.py,./examples/agents/agent_tool_call_cache.py'
check-hidden = true
# Ignore long lines as usually some kind of base64 encodings e.g. in ipynb
ignore-regex = '^\s*"image/\S+": ".*|^.{300,}|\b(NotIn|Unsupport)\b'
diff --git a/test/test_chat_agent_tool_cache.py b/test/test_chat_agent_tool_cache.py
new file mode 100644
index 000000000..9c26c24f1
--- /dev/null
+++ b/test/test_chat_agent_tool_cache.py
@@ -0,0 +1,117 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import pytest
+
+from camel.agents import ChatAgent
+from camel.messages import FunctionCallingMessage
+from camel.models.stub_model import StubModel
+from camel.types import ModelType
+
+
[email protected]("threshold", [20])
+def test_tool_output_caching(tmp_path, threshold):
+ agent = ChatAgent(
+ system_message="You are a tester.",
+ model=StubModel(model_type=ModelType.STUB),
+ enable_tool_output_cache=True,
+ tool_output_cache_threshold=threshold,
+ tool_output_cache_dir=tmp_path,
+ )
+
+ long_result = "A" * (threshold + 10)
+ short_result = "short"
+
+ agent._record_tool_calling(
+ "dummy_tool",
+ args={"value": 1},
+ result=long_result,
+ tool_call_id="call-1",
+ )
+
+ history = [
+ entry
+ for entry in agent._tool_output_history
+ if entry.tool_call_id == "call-1"
+ ]
+ assert history and not history[0].cached
+
+ agent._record_tool_calling(
+ "dummy_tool",
+ args={"value": 2},
+ result=short_result,
+ tool_call_id="call-2",
+ )
+
+ cached_entry = next(
+ entry
+ for entry in agent._tool_output_history
+ if entry.tool_call_id == "call-1"
+ )
+ assert cached_entry.cached
+ assert cached_entry.cache_id
+
+ cache_file = tmp_path / f"{cached_entry.cache_id}.txt"
+ assert cache_file.exists()
+ assert long_result in cache_file.read_text(encoding="utf-8")
+
+ records = agent.memory.retrieve()
+ cached_message = None
+ for record in records:
+ message = record.memory_record.message
+ if (
+ isinstance(message, FunctionCallingMessage)
+ and getattr(message, "tool_call_id", "") == "call-1"
+ ):
+ cached_message = message
+ break
+
+ assert cached_message is not None
+ assert cached_entry.cache_id in cached_message.result
+ assert agent._cache_lookup_tool_name in cached_message.result
+ assert long_result not in cached_message.result
+
+ retrieved = agent.retrieve_cached_tool_output(cached_entry.cache_id)
+ assert long_result in retrieved
+
+
+def test_tool_output_history_cleared_on_reset(tmp_path):
+ agent = ChatAgent(
+ system_message="Cache reset tester.",
+ model=StubModel(model_type=ModelType.STUB),
+ enable_tool_output_cache=True,
+ tool_output_cache_threshold=10,
+ tool_output_cache_dir=tmp_path,
+ )
+
+ agent._record_tool_calling(
+ "dummy_tool",
+ args={"value": "a"},
+ result="A" * 20,
+ tool_call_id="call-initial",
+ )
+ assert agent._tool_output_history
+
+ agent.clear_memory()
+ assert agent._tool_output_history == []
+
+ agent._record_tool_calling(
+ "dummy_tool",
+ args={"value": "b"},
+ result="B" * 20,
+ tool_call_id="call-after-clear",
+ )
+ assert len(agent._tool_output_history) == 1
+
+ agent.reset()
+ assert agent._tool_output_history == []