🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
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.mdxindex 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_promptdiff --git a/docs/mintlify/reference/camel.agents.chat_agent.mdx b/docs/mintlify/reference/camel.agents.chat_agent.mdxindex 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 internaland 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.mdxindex 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 ASSISTANTmessages that contain tool_calls in their meta_dict to save tokenusage.+<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.mdxindex 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>### cleardiff --git a/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdx b/docs/mintlify/reference/camel.memories.blocks.chat_history_block.mdxindex 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.mdxindex 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.