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

Auto-update documentation after merge [skip ci]

camel-docs-bot1999dc0a27cd
diff --git a/docs/mintlify/reference/camel.agents._utils.mdx b/docs/mintlify/reference/camel.agents._utils.mdx
index 402999b35..9559f236d 100644
--- a/docs/mintlify/reference/camel.agents._utils.mdx
+++ b/docs/mintlify/reference/camel.agents._utils.mdx
@@ -1,5 +1,24 @@
<a id="camel.agents._utils"></a>
+<a id="camel.agents._utils.build_default_summary_prompt"></a>
+
+## build_default_summary_prompt
+
+```python
+def build_default_summary_prompt(conversation_text: str):
+```
+
+Create the default prompt used for conversation summarization.
+
+**Parameters:**
+
+- **conversation_text** (str): The conversation to be summarized.
+
+**Returns:**
+
+ str: A formatted prompt instructing the model to produce a structured
+markdown summary.
+
<a id="camel.agents._utils.generate_tool_prompt"></a>
## generate_tool_prompt
diff --git a/docs/mintlify/reference/camel.agents.chat_agent.mdx b/docs/mintlify/reference/camel.agents.chat_agent.mdx
index 7503096b0..cc0319970 100644
--- a/docs/mintlify/reference/camel.agents.chat_agent.mdx
+++ b/docs/mintlify/reference/camel.agents.chat_agent.mdx
@@ -237,7 +237,7 @@ Class for managing conversations of CAMEL Chat Agents.
- **system_message** (Union[BaseMessage, str], optional): The system message for the chat agent. (default: :obj:`None`) model (Union[BaseModelBackend, Tuple[str, str], str, ModelType, Tuple[ModelPlatformType, ModelType], List[BaseModelBackend], List[str], List[ModelType], List[Tuple[str, str]], List[Tuple[ModelPlatformType, ModelType]]], optional): The model backend(s) to use. Can be a single instance, a specification (string, enum, tuple), or a list of instances or specifications to be managed by `ModelManager`. If a list of specifications (not `BaseModelBackend` instances) is provided, they will be instantiated using `ModelFactory`. (default: :obj:`ModelPlatformType.DEFAULT` with `ModelType.DEFAULT`)
- **memory** (AgentMemory, optional): The agent memory for managing chat messages. If `None`, a :obj:`ChatHistoryMemory` will be used. (default: :obj:`None`)
- **message_window_size** (int, optional): The maximum number of previous messages to include in the context window. If `None`, no windowing is performed. (default: :obj:`None`)
-- **token_limit** (int, optional): The maximum number of tokens in a context. The context will be automatically pruned to fulfill the limitation. If `None`, it will be set according to the backend model. (default: :obj:`None`)
+- **summarize_threshold** (int, optional): The percentage of the context window that triggers summarization. If `None`, will trigger summarization when the context window is full. (default: :obj:`None`)
- **output_language** (str, optional): The language to be output by the agent. (default: :obj:`None`)
- **tools** (Optional[List[Union[FunctionTool, Callable]]], optional): List of available :obj:`FunctionTool` or :obj:`Callable`. (default: :obj:`None`) toolkits_to_register_agent (Optional[List[RegisteredAgentToolkit]], optional): List of toolkit instances that inherit from :obj:`RegisteredAgentToolkit`. The agent will register itself with these toolkits, allowing them to access the agent instance. Note: This does NOT add the toolkit's tools to the agent. To use tools from these toolkits, pass them explicitly via the `tools` parameter. (default: :obj:`None`) external_tools (Optional[List[Union[FunctionTool, Callable, Dict[str, Any]]]], optional): List of external tools (:obj:`FunctionTool` or :obj:`Callable` or :obj:`Dict[str, Any]`) bind to one chat agent. When these tools are called, the agent will directly return the request instead of processing it. (default: :obj:`None`)
- **response_terminators** (List[ResponseTerminator], optional): List of :obj:`ResponseTerminator` bind to one chat agent. (default: :obj:`None`)
@@ -253,6 +253,7 @@ Class for managing conversations of CAMEL Chat Agents.
- **retry_delay** (float, optional): Initial delay in seconds between retries. Uses exponential backoff. (default: :obj:`1.0`)
- **step_timeout** (Optional[float], optional): Timeout in seconds for the entire step operation. If None, no timeout is applied. (default: :obj:`None`)
- **stream_accumulate** (bool, optional): When True, partial streaming updates return accumulated content (current behavior). When False, partial updates return only the incremental delta. (default: :obj:`True`)
+- **summary_window_ratio** (float, optional): Maximum fraction of the total context window that can be occupied by summary information. Used to limit how much of the model's context is reserved for summarization results. (default: :obj:`0.6`)
<a id="camel.agents.chat_agent.ChatAgent.__init__"></a>
@@ -265,6 +266,7 @@ def __init__(
model: Optional[Union[BaseModelBackend, ModelManager, Tuple[str, str], str, ModelType, Tuple[ModelPlatformType, ModelType], List[BaseModelBackend], List[str], List[ModelType], List[Tuple[str, str]], List[Tuple[ModelPlatformType, ModelType]]]] = None,
memory: Optional[AgentMemory] = None,
message_window_size: Optional[int] = None,
+ summarize_threshold: Optional[int] = 50,
token_limit: Optional[int] = None,
output_language: Optional[str] = None,
tools: Optional[List[Union[FunctionTool, Callable]]] = None,
@@ -282,7 +284,8 @@ def __init__(
retry_attempts: int = 3,
retry_delay: float = 1.0,
step_timeout: Optional[float] = None,
- stream_accumulate: bool = True
+ stream_accumulate: bool = True,
+ summary_window_ratio: float = 0.6
):
```
@@ -438,6 +441,122 @@ def _get_full_tool_schemas(self):
Returns a list of tool schemas of all tools, including internal
and external tools.
+<a id="camel.agents.chat_agent.ChatAgent._is_token_limit_error"></a>
+
+### _is_token_limit_error
+
+```python
+def _is_token_limit_error(error: Exception):
+```
+
+Return True when the exception message indicates a token limit.
+
+<a id="camel.agents.chat_agent.ChatAgent._is_tool_related_record"></a>
+
+### _is_tool_related_record
+
+```python
+def _is_tool_related_record(record: MemoryRecord):
+```
+
+Determine whether the given memory record
+belongs to a tool call.
+
+<a id="camel.agents.chat_agent.ChatAgent._find_indices_to_remove_for_last_tool_pair"></a>
+
+### _find_indices_to_remove_for_last_tool_pair
+
+```python
+def _find_indices_to_remove_for_last_tool_pair(self, recent_records: List[ContextRecord]):
+```
+
+**Returns:**
+
+ List[int]: Indices to remove (may be non-contiguous).
+
+<a id="camel.agents.chat_agent.ChatAgent._serialize_tool_args"></a>
+
+### _serialize_tool_args
+
+```python
+def _serialize_tool_args(args: Dict[str, Any]):
+```
+
+<a id="camel.agents.chat_agent.ChatAgent._build_tool_signature"></a>
+
+### _build_tool_signature
+
+```python
+def _build_tool_signature(cls, func_name: str, args: Dict[str, Any]):
+```
+
+<a id="camel.agents.chat_agent.ChatAgent._describe_tool_call"></a>
+
+### _describe_tool_call
+
+```python
+def _describe_tool_call(self, record: Optional[ToolCallingRecord]):
+```
+
+<a id="camel.agents.chat_agent.ChatAgent._update_last_tool_call_state"></a>
+
+### _update_last_tool_call_state
+
+```python
+def _update_last_tool_call_state(self, record: Optional[ToolCallingRecord]):
+```
+
+Track the most recent tool call and its identifying signature.
+
+<a id="camel.agents.chat_agent.ChatAgent._format_tool_limit_notice"></a>
+
+### _format_tool_limit_notice
+
+```python
+def _format_tool_limit_notice(self):
+```
+
+<a id="camel.agents.chat_agent.ChatAgent._append_user_messages_section"></a>
+
+### _append_user_messages_section
+
+```python
+def _append_user_messages_section(summary_content: str, user_messages: List[str]):
+```
+
+<a id="camel.agents.chat_agent.ChatAgent._reset_summary_state"></a>
+
+### _reset_summary_state
+
+```python
+def _reset_summary_state(self):
+```
+
+<a id="camel.agents.chat_agent.ChatAgent._calculate_next_summary_threshold"></a>
+
+### _calculate_next_summary_threshold
+
+```python
+def _calculate_next_summary_threshold(self):
+```
+
+**Returns:**
+
+ int: The token count threshold for next summarization.
+
+<a id="camel.agents.chat_agent.ChatAgent._update_memory_with_summary"></a>
+
+### _update_memory_with_summary
+
+```python
+def _update_memory_with_summary(self, summary: str, include_summaries: bool = False):
+```
+
+Update memory with summary result.
+
+This method handles memory clearing and restoration of summaries based
+on whether it's a progressive or full compression.
+
<a id="camel.agents.chat_agent.ChatAgent._get_external_tool_names"></a>
### _get_external_tool_names
@@ -537,16 +656,6 @@ def update_memory(
Updates the agent memory with a new message.
-If the single *message* exceeds the model's context window, it will
-be **automatically split into multiple smaller chunks** before being
-written into memory. This prevents later failures in
-`ScoreBasedContextCreator` where an over-sized message cannot fit
-into the available token budget at all.
-
-This slicing logic handles both regular text messages (in the
-`content` field) and long tool call results (in the `result` field of
-a `FunctionCallingMessage`).
-
**Parameters:**
- **message** (BaseMessage): The new message to add to the stored messages.
@@ -610,7 +719,9 @@ def summarize(
filename: Optional[str] = None,
summary_prompt: Optional[str] = None,
response_format: Optional[Type[BaseModel]] = None,
- working_directory: Optional[Union[str, Path]] = None
+ working_directory: Optional[Union[str, Path]] = None,
+ include_summaries: bool = False,
+ add_user_messages: bool = True
):
```
@@ -626,7 +737,9 @@ performance in parallel summarization workflows.
- **filename** (Optional[str]): The base filename (without extension) to use for the markdown file. Defaults to a timestamped name when not provided.
- **summary_prompt** (Optional[str]): Custom prompt for the summarizer. When omitted, a default prompt highlighting key decisions, action items, and open questions is used.
- **response_format** (Optional[Type[BaseModel]]): A Pydantic model defining the expected structure of the response. If provided, the summary will be generated as structured output and included in the result.
+- **include_summaries** (bool): Whether to include previously generated summaries in the content to be summarized. If False (default), only non-summary messages will be summarized. If True, all messages including previous summaries will be summarized (full compression). (default: :obj:`False`)
- **working_directory** (Optional[str|Path]): Optional directory to save the markdown summary file. If provided, overrides the default directory used by ContextUtility.
+- **add_user_messages** (bool): Whether add user messages to summary. (default: :obj:`True`)
**Returns:**
diff --git a/docs/mintlify/reference/camel.memories.agent_memories.mdx b/docs/mintlify/reference/camel.memories.agent_memories.mdx
index 0259c2901..56bc36552 100644
--- a/docs/mintlify/reference/camel.memories.agent_memories.mdx
+++ b/docs/mintlify/reference/camel.memories.agent_memories.mdx
@@ -92,6 +92,26 @@ This method removes all FUNCTION/TOOL role messages and any ASSISTANT
messages that contain tool_calls in their meta_dict to save token
usage.
+<a id="camel.memories.agent_memories.ChatHistoryMemory.pop_records"></a>
+
+### pop_records
+
+```python
+def pop_records(self, count: int):
+```
+
+Removes the most recent records from chat history memory.
+
+<a id="camel.memories.agent_memories.ChatHistoryMemory.remove_records_by_indices"></a>
+
+### remove_records_by_indices
+
+```python
+def remove_records_by_indices(self, indices: List[int]):
+```
+
+Removes records at specified indices from chat history memory.
+
<a id="camel.memories.agent_memories.VectorDBMemory"></a>
## VectorDBMemory
@@ -175,6 +195,26 @@ def clear(self):
Removes all records from the vector database memory.
+<a id="camel.memories.agent_memories.VectorDBMemory.pop_records"></a>
+
+### pop_records
+
+```python
+def pop_records(self, count: int):
+```
+
+Rolling back is unsupported for vector database memory.
+
+<a id="camel.memories.agent_memories.VectorDBMemory.remove_records_by_indices"></a>
+
+### remove_records_by_indices
+
+```python
+def remove_records_by_indices(self, indices: List[int]):
+```
+
+Removing by indices is unsupported for vector database memory.
+
<a id="camel.memories.agent_memories.LongtermAgentMemory"></a>
## LongtermAgentMemory
@@ -274,3 +314,23 @@ def clear(self):
```
Removes all records from the memory.
+
+<a id="camel.memories.agent_memories.LongtermAgentMemory.pop_records"></a>
+
+### pop_records
+
+```python
+def pop_records(self, count: int):
+```
+
+Removes recent chat history records while leaving vector memory.
+
+<a id="camel.memories.agent_memories.LongtermAgentMemory.remove_records_by_indices"></a>
+
+### remove_records_by_indices
+
+```python
+def remove_records_by_indices(self, indices: List[int]):
+```
+
+Removes records at specified indices from chat history.
diff --git a/docs/mintlify/reference/camel.memories.base.mdx b/docs/mintlify/reference/camel.memories.base.mdx
index dde6766dd..653910887 100644
--- a/docs/mintlify/reference/camel.memories.base.mdx
+++ b/docs/mintlify/reference/camel.memories.base.mdx
@@ -42,6 +42,43 @@ Writes a record to the memory, appending it to existing ones.
- **record** (MemoryRecord): Record to be added to the memory.
+<a id="camel.memories.base.MemoryBlock.pop_records"></a>
+
+### pop_records
+
+```python
+def pop_records(self, count: int):
+```
+
+Removes records from the memory and returns the removed records.
+
+**Parameters:**
+
+- **count** (int): Number of records to remove.
+
+**Returns:**
+
+ List[MemoryRecord]: The records that were removed from the memory
+in their original order.
+
+<a id="camel.memories.base.MemoryBlock.remove_records_by_indices"></a>
+
+### remove_records_by_indices
+
+```python
+def remove_records_by_indices(self, indices: List[int]):
+```
+
+Removes records at specified indices from the memory.
+
+**Parameters:**
+
+- **indices** (List[int]): List of indices to remove. Indices should be valid positions in the current record list.
+
+**Returns:**
+
+ List[MemoryRecord]: The removed records in their original order.
+
<a id="camel.memories.base.MemoryBlock.clear"></a>
### clear
diff --git a/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx b/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx
index ca7a70115..e8547a850 100644
--- a/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx
+++ b/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx
@@ -78,3 +78,39 @@ def clear(self):
```
Clears all chat messages from the memory.
+
+<a id="camel.memories.blocks.chat_history_block.ChatHistoryBlock.pop_records"></a>
+
+### pop_records
+
+```python
+def pop_records(self, count: int):
+```
+
+Removes the most recent records from the memory.
+
+**Parameters:**
+
+- **count** (int): Number of records to remove from the end of the conversation history. A value of 0 results in no changes.
+
+**Returns:**
+
+ List[MemoryRecord]: The removed records in chronological order.
+
+<a id="camel.memories.blocks.chat_history_block.ChatHistoryBlock.remove_records_by_indices"></a>
+
+### remove_records_by_indices
+
+```python
+def remove_records_by_indices(self, indices: List[int]):
+```
+
+Removes records at specified indices from the memory.
+
+**Parameters:**
+
+- **indices** (List[int]): List of indices to remove. Indices are positions in the current record list (0-based). System/developer messages at index 0 are protected and will not be removed.
+
+**Returns:**
+
+ List[MemoryRecord]: The removed records in their original order.
diff --git a/docs/mintlify/reference/camel.memories.context_creators.score_based.mdx b/docs/mintlify/reference/camel.memories.context_creators.score_based.mdx
index 15fea7e99..af210c169 100644
--- a/docs/mintlify/reference/camel.memories.context_creators.score_based.mdx
+++ b/docs/mintlify/reference/camel.memories.context_creators.score_based.mdx
@@ -8,18 +8,12 @@
class ScoreBasedContextCreator(BaseContextCreator):
```
-A default implementation of context creation strategy, which inherits
-from :obj:`BaseContextCreator`.
-
-This class provides a strategy to generate a conversational context from
-a list of chat history records while ensuring the total token count of
-the context does not exceed a specified limit. It prunes messages based
-on their score if the total token count exceeds the limit.
+A context creation strategy that orders records chronologically.
**Parameters:**
-- **token_counter** (BaseTokenCounter): An instance responsible for counting tokens in a message.
-- **token_limit** (int): The maximum number of tokens allowed in the generated context.
+- **token_counter** (BaseTokenCounter): Token counter instance used to compute the combined token count of the returned messages.
+- **token_limit** (int): Retained for API compatibility. No longer used to filter records.
<a id="camel.memories.context_creators.score_based.ScoreBasedContextCreator.__init__"></a>
@@ -53,151 +47,4 @@ def token_limit(self):
def create_context(self, records: List[ContextRecord]):
```
-Constructs conversation context from chat history while respecting
-token limits.
-
-Key strategies:
-1. System message is always prioritized and preserved
-2. Truncation removes low-score messages first
-3. Final output maintains chronological order and in history memory,
-the score of each message decreases according to keep_rate. The
-newer the message, the higher the score.
-4. Tool calls and their responses are kept together to maintain
-API compatibility
-
-**Parameters:**
-
-- **records** (List[ContextRecord]): List of context records with scores and timestamps.
-
-**Returns:**
-
- Tuple[List[OpenAIMessage], int]:
-- Ordered list of OpenAI messages
-- Total token count of the final context
-
-<a id="camel.memories.context_creators.score_based.ScoreBasedContextCreator._group_tool_calls_and_responses"></a>
-
-### _group_tool_calls_and_responses
-
-```python
-def _group_tool_calls_and_responses(self, units: List[_ContextUnit]):
-```
-
-Groups tool calls with their corresponding responses based on
-`tool_call_id`.
-
-This improved logic robustly gathers all messages (assistant requests
-and tool responses, including chunks) that share a `tool_call_id`.
-
-**Parameters:**
-
-- **units** (List[_ContextUnit]): List of context units to analyze.
-
-**Returns:**
-
- Dict[str, List[_ContextUnit]]: Mapping from `tool_call_id` to a
-list of related units.
-
-<a id="camel.memories.context_creators.score_based.ScoreBasedContextCreator._truncate_with_tool_call_awareness"></a>
-
-### _truncate_with_tool_call_awareness
-
-```python
-def _truncate_with_tool_call_awareness(
- self,
- regular_units: List[_ContextUnit],
- tool_call_groups: Dict[str, List[_ContextUnit]],
- system_tokens: int
-):
-```
-
-Truncates messages while preserving tool call-response pairs.
-This method implements a more sophisticated truncation strategy:
-1. It treats tool call groups (request + responses) and standalone
-messages as individual items to be included.
-2. It sorts all items by score and greedily adds them to the context.
-3. **Partial Truncation**: If a complete tool group is too large to
-fit,it attempts to add the request message and as many of the most
-recent response chunks as the token budget allows.
-
-**Parameters:**
-
-- **regular_units** (List[_ContextUnit]): All regular message units.
-- **tool_call_groups** (Dict[str, List[_ContextUnit]]): Grouped tool calls.
-- **system_tokens** (int): Tokens used by the system message.
-
-**Returns:**
-
- List[_ContextUnit]: A list of units that fit within the token
-limit.
-
-<a id="camel.memories.context_creators.score_based.ScoreBasedContextCreator._extract_system_message"></a>
-
-### _extract_system_message
-
-```python
-def _extract_system_message(self, records: List[ContextRecord]):
-```
-
-Extracts the system message from records and validates it.
-
-**Parameters:**
-
-- **records** (List[ContextRecord]): List of context records representing conversation history.
-
-**Returns:**
-
- Tuple[Optional[_ContextUnit], List[_ContextUnit]]: containing:
-- The system message as a `_ContextUnit`, if valid; otherwise,
-`None`.
-- An empty list, serving as the initial container for regular
-messages.
-
-<a id="camel.memories.context_creators.score_based.ScoreBasedContextCreator._conversation_sort_key"></a>
-
-### _conversation_sort_key
-
-```python
-def _conversation_sort_key(self, unit: _ContextUnit):
-```
-
-Defines the sorting key for assembling the final output.
-
-Sorting priority:
-- Primary: Sort by timestamp in ascending order (chronological order).
-- Secondary: Sort by score in descending order (higher scores first
-when timestamps are equal).
-
-**Parameters:**
-
-- **unit** (_ContextUnit): A `_ContextUnit` representing a conversation record.
-
-**Returns:**
-
- Tuple[float, float]:
-- Timestamp for chronological sorting.
-- Negative score for descending order sorting.
-
-<a id="camel.memories.context_creators.score_based.ScoreBasedContextCreator._assemble_output"></a>
-
-### _assemble_output
-
-```python
-def _assemble_output(
- self,
- context_units: List[_ContextUnit],
- system_unit: Optional[_ContextUnit]
-):
-```
-
-Assembles final message list with proper ordering and token count.
-
-**Parameters:**
-
-- **context_units** (List[_ContextUnit]): Sorted list of regular message units.
-- **system_unit** (Optional[_ContextUnit]): System message unit (if present).
-
-**Returns:**
-
- Tuple[List[OpenAIMessage], int]: Tuple of (ordered messages, total
-tokens)
+Returns messages sorted by timestamp and their total token count.