ag2 0.9.8.post1__py3-none-any.whl → 0.9.10__py3-none-any.whl

autogen/agentchat/conversable_agent.py

@@ -132,11 +132,11 @@ class ConversableAgent(LLMAgent):
     For example, AssistantAgent and UserProxyAgent are subclasses of this class,
     configured with different default settings.
 
-    To modify auto reply, override `generate_reply` method.
-    To disable/enable human response in every turn, set `human_input_mode` to "NEVER" or "ALWAYS".
-    To modify the way to get human input, override `get_human_input` method.
-    To modify the way to execute code blocks, single code block, or function call, override `execute_code_blocks`,
-    `run_code`, and `execute_function` methods respectively.
+    To modify auto reply, override `generate_reply` method. \n
+    To disable/enable human response in every turn, set `human_input_mode` to "NEVER" or "ALWAYS". \n
+    To modify the way to get human input, override `get_human_input` method. \n
+    To modify the way to execute code blocks, single code block, or function call, override `execute_code_blocks`, \n
+    `run_code`, and `execute_function` methods respectively. \n
     """
 
     DEFAULT_CONFIG = False  # False or dict, the default config for llm inference
@@ -144,7 +144,7 @@ class ConversableAgent(LLMAgent):
 
     DEFAULT_SUMMARY_PROMPT = "Summarize the takeaway from the conversation. Do not add any introductory phrases."
     DEFAULT_SUMMARY_METHOD = "last_msg"
-    llm_config: dict[str, Any] | Literal[False]
+    llm_config: LLMConfig | Literal[False]
 
     def __init__(
         self,
@@ -168,60 +168,60 @@ class ConversableAgent(LLMAgent):
         | None = None,
         handoffs: Handoffs | None = None,
     ):
-        """Args:
-        name (str): name of the agent.
-        system_message (str or list): system message for the ChatCompletion inference.
-        is_termination_msg (function): a function that takes a message in the form of a dictionary
+        """Args:\n
+        1) name (str): name of the agent.\n
+        2) system_message (str or list): system message for the ChatCompletion inference.\n
+        3) is_termination_msg (function): a function that takes a message in the form of a dictionary
             and returns a boolean value indicating if this received message is a termination message.
-            The dict can contain the following keys: "content", "role", "name", "function_call".
-        max_consecutive_auto_reply (int): the maximum number of consecutive auto replies.
+            The dict can contain the following keys: "content", "role", "name", "function_call".\n
+        4) max_consecutive_auto_reply (int): the maximum number of consecutive auto replies.
             default to None (no limit provided, class attribute MAX_CONSECUTIVE_AUTO_REPLY will be used as the limit in this case).
-            When set to 0, no auto reply will be generated.
-        human_input_mode (str): whether to ask for human inputs every time a message is received.
-            Possible values are "ALWAYS", "TERMINATE", "NEVER".
+            When set to 0, no auto reply will be generated.\n
+        5) human_input_mode (str): whether to ask for human inputs every time a message is received.\n
+            Possible values are "ALWAYS", "TERMINATE", "NEVER".\n
             (1) When "ALWAYS", the agent prompts for human input every time a message is received.
                 Under this mode, the conversation stops when the human input is "exit",
-                or when is_termination_msg is True and there is no human input.
+                or when is_termination_msg is True and there is no human input.\n
             (2) When "TERMINATE", the agent only prompts for human input only when a termination message is received or
-                the number of auto reply reaches the max_consecutive_auto_reply.
+                the number of auto reply reaches the max_consecutive_auto_reply.\n
             (3) When "NEVER", the agent will never prompt for human input. Under this mode, the conversation stops
-                when the number of auto reply reaches the max_consecutive_auto_reply or when is_termination_msg is True.
-        function_map (dict[str, callable]): Mapping function names (passed to openai) to callable functions, also used for tool calls.
-        code_execution_config (dict or False): config for the code execution.
-            To disable code execution, set to False. Otherwise, set to a dictionary with the following keys:
-            - work_dir (Optional, str): The working directory for the code execution.
-                If None, a default working directory will be used.
+                when the number of auto reply reaches the max_consecutive_auto_reply or when is_termination_msg is True. \n
+        6) function_map (dict[str, callable]): Mapping function names (passed to openai) to callable functions, also used for tool calls. \n
+        7) code_execution_config (dict or False): config for the code execution.\n
+            To disable code execution, set to False. Otherwise, set to a dictionary with the following keys:\n
+            - work_dir (Optional, str): The working directory for the code execution.\n
+                If None, a default working directory will be used.\n
                 The default working directory is the "extensions" directory under
-                "path_to_autogen".
-            - use_docker (Optional, list, str or bool): The docker image to use for code execution.
-                Default is True, which means the code will be executed in a docker container. A default list of images will be used.
-                If a list or a str of image name(s) is provided, the code will be executed in a docker container
-                with the first image successfully pulled.
-                If False, the code will be executed in the current environment.
-                We strongly recommend using docker for code execution.
-            - timeout (Optional, int): The maximum execution time in seconds.
+                "path_to_autogen".\n
+            - use_docker (Optional, list, str or bool): The docker image to use for code execution.\n
+                Default is True, which means the code will be executed in a docker container. A default list of images will be used.\n
+                If a list or a str of image name(s) is provided, the code will be executed in a docker container\n
+                with the first image successfully pulled.\n
+                If False, the code will be executed in the current environment.\n
+                We strongly recommend using docker for code execution.\n
+            - timeout (Optional, int): The maximum execution time in seconds.\n
             - last_n_messages (Experimental, int or str): The number of messages to look back for code execution.
-                If set to 'auto', it will scan backwards through all messages arriving since the agent last spoke, which is typically the last time execution was attempted. (Default: auto)
-        llm_config (LLMConfig or dict or False or None): llm inference configuration.
-            Please refer to [OpenAIWrapper.create](https://docs.ag2.ai/latest/docs/api-reference/autogen/OpenAIWrapper/#autogen.OpenAIWrapper.create)
-            for available options.
-            When using OpenAI or Azure OpenAI endpoints, please specify a non-empty 'model' either in `llm_config` or in each config of 'config_list' in `llm_config`.
-            To disable llm-based auto reply, set to False.
-            When set to None, will use self.DEFAULT_CONFIG, which defaults to False.
-        default_auto_reply (str or dict): default auto reply when no code execution or llm-based reply is generated.
-        description (str): a short description of the agent. This description is used by other agents
-            (e.g. the GroupChatManager) to decide when to call upon this agent. (Default: system_message)
-        chat_messages (dict or None): the previous chat messages that this agent had in the past with other agents.
+                If set to 'auto', it will scan backwards through all messages arriving since the agent last spoke, which is typically the last time execution was attempted. (Default: auto)\n
+        8) llm_config (LLMConfig or dict or False or None): llm inference configuration.\n
+            Please refer to [OpenAIWrapper.create](https://docs.ag2.ai/latest/docs/api-reference/autogen/OpenAIWrapper/#autogen.OpenAIWrapper.create)\n
+            for available options.\n
+            When using OpenAI or Azure OpenAI endpoints, please specify a non-empty 'model' either in `llm_config` or in each config of 'config_list' in `llm_config`.\n
+            To disable llm-based auto reply, set to False.\n
+            When set to None, will use self.DEFAULT_CONFIG, which defaults to False.\n
+        9) default_auto_reply (str or dict): default auto reply when no code execution or llm-based reply is generated.\n
+        10) description (str): a short description of the agent. This description is used by other agents
+            (e.g. the GroupChatManager) to decide when to call upon this agent. (Default: system_message)\n
+        11) chat_messages (dict or None): the previous chat messages that this agent had in the past with other agents.
             Can be used to give the agent a memory by providing the chat history. This will allow the agent to
-            resume previous had conversations. Defaults to an empty chat history.
-        silent (bool or None): (Experimental) whether to print the message sent. If None, will use the value of
-            silent in each function.
-        context_variables (ContextVariables or None): Context variables that provide a persistent context for the agent.
-            Note: This will be a reference to a shared context for multi-agent chats.
-            Behaves like a dictionary with keys and values (akin to dict[str, Any]).
-        functions (List[Callable[..., Any]]): A list of functions to register with the agent, these will be wrapped up as tools and registered for LLM (not execution).
-        update_agent_state_before_reply (List[Callable[..., Any]]): A list of functions, including UpdateSystemMessage's, called to update the agent before it replies.
-        handoffs (Handoffs): Handoffs object containing all handoff transition conditions.
+            resume previous had conversations. Defaults to an empty chat history.\n
+        12) silent (bool or None): (Experimental) whether to print the message sent. If None, will use the value of
+            silent in each function.\n
+        13) context_variables (ContextVariables or None): Context variables that provide a persistent context for the agent.
+            Note: This will be a reference to a shared context for multi-agent chats.\n
+            Behaves like a dictionary with keys and values (akin to dict[str, Any]).\n
+        14) functions (List[Callable[..., Any]]): A list of functions to register with the agent, these will be wrapped up as tools and registered for LLM (not execution).\n
+        15) update_agent_state_before_reply (List[Callable[..., Any]]): A list of functions, including UpdateSystemMessage's, called to update the agent before it replies.\n
+        16) handoffs (Handoffs): Handoffs object containing all handoff transition conditions.\n
         """
         self.handoffs = handoffs if handoffs is not None else Handoffs()
         self.input_guardrails: list[Guardrail] = []
@@ -370,6 +370,12 @@ class ConversableAgent(LLMAgent):
             "process_all_messages_before_reply": [],
             "process_message_before_send": [],
             "update_agent_state": [],
+            # Safeguard hooks for monitoring agent interactions
+            "safeguard_tool_inputs": [],  # Hook for processing tool inputs before execution
+            "safeguard_tool_outputs": [],  # Hook for processing tool outputs after execution
+            "safeguard_llm_inputs": [],  # Hook for processing LLM inputs before sending
+            "safeguard_llm_outputs": [],  # Hook for processing LLM outputs after receiving
+            "safeguard_human_inputs": [],  # Hook for processing human inputs
         }
 
         # Associate agent update state hooks
@@ -379,9 +385,7 @@ class ConversableAgent(LLMAgent):
         if not self.llm_config:
             return
 
-        if any([
-            entry for entry in self.llm_config.config_list if entry.api_type == "openai" and re.search(r"\s", name)
-        ]):
+        if any(entry for entry in self.llm_config.config_list if entry.api_type == "openai" and re.search(r"\s", name)):
             raise ValueError(f"The name of the agent cannot contain any whitespace. The name provided is: '{name}'")
 
     def _get_display_name(self):
@@ -485,25 +489,15 @@ class ConversableAgent(LLMAgent):
     def _validate_llm_config(
         cls, llm_config: LLMConfig | dict[str, Any] | Literal[False] | None
     ) -> LLMConfig | Literal[False]:
-        # if not(llm_config in (None, False) or isinstance(llm_config, [dict, LLMConfig])):
-        #     raise ValueError(
-        #         "llm_config must be a dict or False or None."
-        #     )
-
         if llm_config is None:
             llm_config = LLMConfig.get_current_llm_config()
             if llm_config is None:
-                llm_config = cls.DEFAULT_CONFIG
-        elif isinstance(llm_config, dict):
-            llm_config = LLMConfig(**llm_config)
-        elif isinstance(llm_config, LLMConfig):
-            llm_config = llm_config.copy()
+                return cls.DEFAULT_CONFIG
+
         elif llm_config is False:
-            pass
-        else:
-            raise ValueError("llm_config must be a LLMConfig, dict or False or None.")
+            return False
 
-        return llm_config
+        return LLMConfig.ensure_config(llm_config)
 
     @classmethod
     def _create_client(cls, llm_config: LLMConfig | Literal[False]) -> OpenAIWrapper | None:
@@ -2188,9 +2182,20 @@ class ConversableAgent(LLMAgent):
             return False, None
         if messages is None:
             messages = self._oai_messages[sender]
-        extracted_response = self._generate_oai_reply_from_client(
-            client, self._oai_system_message + messages, self.client_cache
-        )
+
+        # Process messages before sending to LLM, hook point for llm input monitoring
+        processed_messages = self._process_llm_input(self._oai_system_message + messages)
+        if processed_messages is None:
+            return True, {"content": "LLM call blocked by safeguard", "role": "assistant"}
+
+        extracted_response = self._generate_oai_reply_from_client(client, processed_messages, self.client_cache)
+
+        # Process LLM response
+        if extracted_response is not None:
+            processed_extracted_response = self._process_llm_output(extracted_response)
+            if processed_extracted_response is None:
+                raise ValueError("safeguard_llm_outputs hook returned None")
+
         return (False, None) if extracted_response is None else (True, extracted_response)
 
     def _generate_oai_reply_from_client(self, llm_client, messages, cache) -> str | dict[str, Any] | None:
@@ -2449,14 +2454,26 @@ class ConversableAgent(LLMAgent):
         tool_returns = []
         for tool_call in message.get("tool_calls", []):
             function_call = tool_call.get("function", {})
+
+            # Hook: Process tool input before execution
+            processed_call = self._process_tool_input(function_call)
+            if processed_call is None:
+                raise ValueError("safeguard_tool_inputs hook returned None")
+
             tool_call_id = tool_call.get("id", None)
-            func = self._function_map.get(function_call.get("name", None), None)
-            if inspect.iscoroutinefunction(func):
-                coro = self.a_execute_function(function_call, call_id=tool_call_id)
+            func = self._function_map.get(processed_call.get("name", None), None)
+            if is_coroutine_callable(func):
+                coro = self.a_execute_function(processed_call, call_id=tool_call_id)
                 _, func_return = self._run_async_in_thread(coro)
             else:
-                _, func_return = self.execute_function(function_call, call_id=tool_call_id)
-            content = func_return.get("content", "")
+                _, func_return = self.execute_function(processed_call, call_id=tool_call_id)
+
+            # Hook: Process tool output before returning
+            processed_return = self._process_tool_output(func_return)
+            if processed_return is None:
+                raise ValueError("safeguard_tool_outputs hook returned None")
+
+            content = processed_return.get("content", "")
             if content is None:
                 content = ""
 
@@ -2992,8 +3009,14 @@ class ConversableAgent(LLMAgent):
         iostream = IOStream.get_default()
 
         reply = iostream.input(prompt)
-        self._human_input.append(reply)
-        return reply
+
+        # Process the human input through hooks
+        processed_reply = self._process_human_input(reply)
+        if processed_reply is None:
+            raise ValueError("safeguard_human_inputs hook returned None")
+
+        self._human_input.append(processed_reply)
+        return processed_reply
 
     async def a_get_human_input(self, prompt: str) -> str:
         """(Async) Get human input.
@@ -3473,7 +3496,7 @@ class ConversableAgent(LLMAgent):
     def can_execute_function(self, name: list[str] | str) -> bool:
         """Whether the agent can execute the function."""
         names = name if isinstance(name, list) else [name]
-        return all([n in self._function_map for n in names])
+        return all(n in self._function_map for n in names)
 
     @property
     def function_map(self) -> dict[str, Callable[..., Any]]:
@@ -3727,7 +3750,7 @@ class ConversableAgent(LLMAgent):
             """
             tool = self._create_tool_if_needed(func_or_tool, name, description)
             chat_context = ChatContext(self)
-            chat_context_params = {param: chat_context for param in tool._chat_context_param_names}
+            chat_context_params = dict.fromkeys(tool._chat_context_param_names, chat_context)
 
             self.register_function(
                 {tool.name: self._wrap_function(tool.func, chat_context_params, serialize=serialize)},
@@ -3825,6 +3848,87 @@ class ConversableAgent(LLMAgent):
         messages[-1]["content"] = processed_user_content
         return messages
 
+    def _process_tool_input(self, tool_input: dict[str, Any]) -> dict[str, Any] | None:
+        """Process tool input through registered hooks."""
+        hook_list = self.hook_lists["safeguard_tool_inputs"]
+
+        # If no hooks are registered, allow the tool input
+        if len(hook_list) == 0:
+            return tool_input
+
+        # Process through each hook
+        processed_input = tool_input
+        for hook in hook_list:
+            processed_input = hook(processed_input)
+            if processed_input is None:
+                return None
+
+        return processed_input
+
+    def _process_tool_output(self, response: dict[str, Any]) -> dict[str, Any]:
+        """Process tool output through registered hooks"""
+        hook_list = self.hook_lists["safeguard_tool_outputs"]
+
+        # If no hooks are registered, return original response
+        if len(hook_list) == 0:
+            return response
+
+        # Process through each hook
+        processed_response = response
+        for hook in hook_list:
+            processed_response = hook(processed_response)
+
+        return processed_response
+
+    def _process_llm_input(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]] | None:
+        """Process messages before sending to LLM through registered hooks."""
+        hook_list = self.hook_lists["safeguard_llm_inputs"]
+
+        # If no hooks registered, allow the messages through
+        if len(hook_list) == 0:
+            return messages
+
+        # Process through each hook
+        processed_messages = messages
+        for hook in hook_list:
+            processed_messages = hook(processed_messages)
+            if processed_messages is None:
+                return None
+
+        return processed_messages
+
+    def _process_llm_output(self, response: str | dict[str, Any]) -> str | dict[str, Any]:
+        """Process LLM response through registered hooks"""
+        hook_list = self.hook_lists["safeguard_llm_outputs"]
+
+        # If no hooks registered, return original response
+        if len(hook_list) == 0:
+            return response
+
+        # Process through each hook
+        processed_response = response
+        for hook in hook_list:
+            processed_response = hook(processed_response)
+
+        return processed_response
+
+    def _process_human_input(self, human_input: str) -> str | None:
+        """Process human input through registered hooks."""
+        hook_list = self.hook_lists["safeguard_human_inputs"]
+
+        # If no hooks registered, allow the input through
+        if len(hook_list) == 0:
+            return human_input
+
+        # Process through each hook
+        processed_input = human_input
+        for hook in hook_list:
+            processed_input = hook(processed_input)
+            if processed_input is None:
+                return None
+
+        return processed_input
+
     def print_usage_summary(self, mode: str | list[str] = ["actual", "total"]) -> None:
         """Print the usage summary."""
         iostream = IOStream.get_default()

autogen/agentchat/group/context_expression.py

@@ -13,27 +13,27 @@ from .context_variables import ContextVariables
 @dataclass
 @export_module("autogen")
 class ContextExpression:
-    """A class to evaluate logical expressions using context variables.
-
-    Args:
-        expression (str): A string containing a logical expression with context variable references.
-            - Variable references use ${var_name} syntax: ${logged_in}, ${attempts}
-            - String literals can use normal quotes: 'hello', "world"
-            - Supported operators:
-                - Logical: not/!, and/&, or/|
-                - Comparison: >, <, >=, <=, ==, !=
-            - Supported functions:
-                - len(${var_name}): Gets the length of a list, string, or other collection
-            - Parentheses can be used for grouping
-            - Examples:
-                - "not ${logged_in} and ${is_admin} or ${guest_checkout}"
-                - "!${logged_in} & ${is_admin} | ${guest_checkout}"
-                - "len(${orders}) > 0 & ${user_active}"
-                - "len(${cart_items}) == 0 | ${checkout_started}"
-
-    Raises:
-        SyntaxError: If the expression cannot be parsed
-        ValueError: If the expression contains disallowed operations
+    """A class to evaluate logical expressions using context variables.\n
+    \n
+        Args:\n
+            expression (str): A string containing a logical expression with context variable references.\n
+                - Variable references use ${var_name} syntax: ${logged_in}, ${attempts}\n
+                - String literals can use normal quotes: 'hello', "world"\n
+                - Supported operators:\n
+                    - Logical: not/!, and/&, or/|\n
+                    - Comparison: >, <, >=, <=, ==, !=\n
+                - Supported functions:\n
+                    - len(${var_name}): Gets the length of a list, string, or other collection\n
+                - Parentheses can be used for grouping\n
+                - Examples:\n
+                    - "not ${logged_in} and ${is_admin} or ${guest_checkout}"\n
+                    - "!${logged_in} & ${is_admin} | ${guest_checkout}"\n
+                    - "len(${orders}) > 0 & ${user_active}"\n
+                    - "len(${cart_items}) == 0 | ${checkout_started}"\n
+    \n
+        Raises:\n
+            SyntaxError: If the expression cannot be parsed\n
+            ValueError: If the expression contains disallowed operations\n
     """
 
     expression: str

autogen/agentchat/group/handoffs.py

@@ -14,17 +14,17 @@ __all__ = ["Handoffs"]
 
 
 class Handoffs(BaseModel):
-    """Container for all handoff transition conditions of a ConversableAgent.
-
-    Three types of conditions can be added, each with a different order and time of use:
-    1. OnContextConditions (evaluated without an LLM)
-    2. OnConditions (evaluated with an LLM)
-    3. After work TransitionTarget (if no other transition is triggered)
-
-    Supports method chaining:
-    agent.handoffs.add_context_conditions([condition1]) \
-                   .add_llm_condition(condition2) \
-                   .set_after_work(after_work)
+    """Container for all handoff transition conditions of a ConversableAgent.\n
+    \n
+        Three types of conditions can be added, each with a different order and time of use:\n
+        1. OnContextConditions (evaluated without an LLM)\n
+        2. OnConditions (evaluated with an LLM)\n
+        3. After work TransitionTarget (if no other transition is triggered)\n
+    \n
+        Supports method chaining:\n
+        agent.handoffs.add_context_conditions([condition1])\n
+                       .add_llm_condition(condition2)\n
+                       .set_after_work(after_work)\n
     """
 
     context_conditions: list[OnContextCondition] = Field(default_factory=list)

autogen/agentchat/group/multi_agent_chat.py

@@ -232,6 +232,7 @@ async def a_run_group_chat(
             except Exception as e:
                 response.iostream.send(ErrorEvent(error=e))  # type: ignore[call-arg]
 
-    asyncio.create_task(_initiate_group_chat())
-
+    task = asyncio.create_task(_initiate_group_chat())
+    # prevent the task from being garbage collected
+    response._task_ref = task  # type: ignore[attr-defined]
     return response

autogen/agentchat/group/on_condition.py

@@ -17,17 +17,17 @@ __all__ = [
 
 @export_module("autogen")
 class OnCondition(BaseModel):  # noqa: N801
-    """Defines a condition for transitioning to another agent or nested chats.
-
-    This is for LLM-based condition evaluation where these conditions are translated into tools and attached to the agent.
-
-    These are evaluated after the OnCondition conditions but before the after work condition.
-
-    Args:
-        target (TransitionTarget): The transition (essentially an agent) to hand off to.
-        condition (LLMCondition): The condition for transitioning to the target agent, evaluated by the LLM.
-        available (AvailableCondition): Optional condition to determine if this OnCondition is included for the LLM to evaluate based on context variables using classes like StringAvailableCondition and ContextExpressionAvailableCondition.
-        llm_function_name (Optional[str]): The name of the LLM function to use for this condition.
+    """Defines a condition for transitioning to another agent or nested chats.\n
+    \n
+        This is for LLM-based condition evaluation where these conditions are translated into tools and attached to the agent.\n
+    \n
+        These are evaluated after the OnCondition conditions but before the after work condition.\n
+    \n
+        Args:\n
+            target (TransitionTarget): The transition (essentially an agent) to hand off to.\n
+            condition (LLMCondition): The condition for transitioning to the target agent, evaluated by the LLM.\n
+            available (AvailableCondition): Optional condition to determine if this OnCondition is included for the LLM to evaluate based on context variables using classes like StringAvailableCondition and ContextExpressionAvailableCondition.\n
+            llm_function_name (Optional[str]): The name of the LLM function to use for this condition.\n
     """
 
     target: TransitionTarget

autogen/agentchat/group/safeguards/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Safeguards module for agent safety and compliance.
+
+This module provides functionality for applying, managing, and enforcing
+safeguards on agent interactions including inter-agent communication,
+tool interactions, LLM interactions, and user interactions.
+"""
+
+from .api import apply_safeguard_policy, reset_safeguard_policy
+from .enforcer import SafeguardEnforcer
+from .events import SafeguardEvent
+
+__all__ = [
+    "SafeguardEnforcer",
+    "SafeguardEvent",
+    "apply_safeguard_policy",
+    "reset_safeguard_policy",
+]