ag2 0.9.9__py3-none-any.whl → 0.10.0__py3-none-any.whl

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/group_tool_executor.py

@@ -7,6 +7,7 @@ from collections.abc import Callable
 from copy import deepcopy
 from typing import Annotated, Any
 
+from ...code_utils import content_str
 from ...oai import OpenAIWrapper
 from ...tools import Depends, Tool
 from ...tools.dependency_injection import inject_params, on
@@ -33,6 +34,9 @@ class GroupToolExecutor(ConversableAgent):
         # Store the next target from a tool call
         self._group_next_target: TransitionTarget | None = None
 
+        # Track the original agent that initiated the tool call (for safeguards)
+        self._tool_call_originator: str | None = None
+
         # Primary tool reply function for handling the tool reply and the ReplyResult and TransitionTarget returns
         self.register_reply([Agent, None], self._generate_group_tool_reply, remove_other_reply_funcs=True)
 
@@ -57,6 +61,18 @@ class GroupToolExecutor(ConversableAgent):
         """Clears the next target to transition to."""
         self._group_next_target = None
 
+    def set_tool_call_originator(self, agent_name: str) -> None:
+        """Sets the original agent that initiated the tool call (for safeguard transparency)."""
+        self._tool_call_originator = agent_name
+
+    def get_tool_call_originator(self) -> str | None:
+        """Gets the original agent that initiated the tool call."""
+        return self._tool_call_originator
+
+    def clear_tool_call_originator(self) -> None:
+        """Clears the tool call originator."""
+        self._tool_call_originator = None
+
     def _modify_context_variables_param(
         self, f: Callable[..., Any], context_variables: ContextVariables
     ) -> Callable[..., Any]:
@@ -71,6 +87,9 @@ class GroupToolExecutor(ConversableAgent):
         """
         sig = inspect.signature(f)
 
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return f(*args, **kwargs)
+
         # Check if context_variables parameter exists and update it if so
         if __CONTEXT_VARIABLES_PARAM_NAME__ in sig.parameters:
             new_params = []
@@ -84,13 +103,13 @@ class GroupToolExecutor(ConversableAgent):
 
             # Update signature
             new_sig = sig.replace(parameters=new_params)
-            f.__signature__ = new_sig  # type: ignore[attr-defined]
+            wrapper.__signature__ = new_sig  # type: ignore[attr-defined]
 
-        return f
+        return wrapper
 
-    def _change_tool_context_variables_to_depends(
-        self, agent: ConversableAgent, current_tool: Tool, context_variables: ContextVariables
-    ) -> None:
+    def make_tool_copy_with_context_variables(
+        self, current_tool: Tool, context_variables: ContextVariables
+    ) -> Tool | None:
         """Checks for the context_variables parameter in the tool and updates it to use dependency injection."""
         # If the tool has a context_variables parameter, remove the tool and reregister it without the parameter
         if __CONTEXT_VARIABLES_PARAM_NAME__ in current_tool.tool_schema["function"]["parameters"]["properties"]:
@@ -100,16 +119,19 @@ class GroupToolExecutor(ConversableAgent):
             # Remove the Tool from the agent
             name = current_tool._name
             description = current_tool._description
-            agent.remove_tool_for_llm(current_tool)
 
             # Recreate the tool without the context_variables parameter
-            tool_func = self._modify_context_variables_param(current_tool._func, context_variables)
+            tool_func = self._modify_context_variables_param(tool_func, context_variables)
             tool_func = inject_params(tool_func)
-            new_tool = ConversableAgent._create_tool_if_needed(
-                func_or_tool=tool_func, name=name, description=description
-            )
+            return ConversableAgent._create_tool_if_needed(func_or_tool=tool_func, name=name, description=description)
+        return None
 
-            # Re-register with the agent
+    def _change_tool_context_variables_to_depends(
+        self, agent: ConversableAgent, current_tool: Tool, context_variables: ContextVariables
+    ) -> None:
+        """Checks for the context_variables parameter in the tool and updates it to use dependency injection."""
+        if new_tool := self.make_tool_copy_with_context_variables(current_tool, context_variables):
+            agent.remove_tool_for_llm(current_tool)
             agent.register_for_llm()(new_tool)
 
     def register_agents_functions(self, agents: list[ConversableAgent], context_variables: ContextVariables) -> None:
@@ -140,15 +162,22 @@ class GroupToolExecutor(ConversableAgent):
         2. Generates the tool calls reply.
         3. Updates context_variables and next_agent based on the tool call response.
         """
+
         if config is None:
             config = agent  # type: ignore[assignment]
         if messages is None:
             messages = agent._oai_messages[sender]
 
         message = messages[-1]
-        if "tool_calls" in message:
+        # Track the original agent that initiated this tool call (for safeguard transparency)
+        # Use sender.name as fallback when message doesn't have a name field (e.g., for tool_calls messages)
+        agent_name = message.get("name", sender.name if sender else "unknown")
+        self.set_tool_call_originator(agent_name)
+
+        if message.get("tool_calls"):
             tool_call_count = len(message["tool_calls"])
 
+            tool_message = None
             # Loop through tool calls individually (so context can be updated after each function call)
             next_target: TransitionTarget | None = None
             tool_responses_inner = []
@@ -182,11 +211,13 @@ class GroupToolExecutor(ConversableAgent):
                         next_target = content
 
                     # Serialize the content to a string
-                    if content is not None:
-                        tool_response["content"] = str(content)
+                    normalized_content = (
+                        content_str(content) if isinstance(content, (str, list)) or content is None else str(content)
+                    )
+                    tool_response["content"] = normalized_content
 
                     tool_responses_inner.append(tool_response)
-                    contents.append(str(tool_response["content"]))
+                    contents.append(normalized_content)
 
             self._group_next_target = next_target  # type: ignore[attr-defined]
 

autogen/agentchat/group/guardrails.py

@@ -7,7 +7,7 @@ import re
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 from ...oai.client import OpenAIWrapper
 
@@ -16,32 +16,6 @@ if TYPE_CHECKING:
     from .targets.transition_target import TransitionTarget
 
 
-class GuardrailResult(BaseModel):
-    """Represents the outcome of a guardrail check."""
-
-    activated: bool
-    justification: str = Field(default="No justification provided")
-
-    def __str__(self) -> str:
-        return f"Guardrail Result: {self.activated}\nJustification: {self.justification}"
-
-    @staticmethod
-    def parse(text: str) -> "GuardrailResult":
-        """Parses a JSON string into a GuardrailResult object.
-
-        Args:
-            text (str): The JSON string to parse.
-
-        Returns:
-            GuardrailResult: The parsed GuardrailResult object.
-        """
-        try:
-            data = json.loads(text)
-            return GuardrailResult(**data)
-        except (json.JSONDecodeError, ValueError) as e:
-            raise ValueError(f"Failed to parse GuardrailResult from text: {text}") from e
-
-
 class Guardrail(ABC):
     """Abstract base class for guardrails."""
 
@@ -59,7 +33,7 @@ class Guardrail(ABC):
     def check(
         self,
         context: str | list[dict[str, Any]],
-    ) -> GuardrailResult:
+    ) -> "GuardrailResult":
         """Checks the text against the guardrail and returns a GuardrailResult.
 
         Args:
@@ -99,7 +73,7 @@ You will activate the guardrail only if the condition is met.
     def check(
         self,
         context: str | list[dict[str, Any]],
-    ) -> GuardrailResult:
+    ) -> "GuardrailResult":
         """Checks the context against the guardrail using an LLM.
 
         Args:
@@ -120,7 +94,7 @@ You will activate the guardrail only if the condition is met.
             raise ValueError("Context must be a string or a list of messages.")
         # Call the LLM with the check messages
         response = self.client.create(messages=check_messages)
-        return GuardrailResult.parse(response.choices[0].message.content)  # type: ignore
+        return GuardrailResult.parse(response.choices[0].message.content, guardrail=self)  # type: ignore
 
 
 class RegexGuardrail(Guardrail):
@@ -143,7 +117,7 @@ class RegexGuardrail(Guardrail):
     def check(
         self,
         context: str | list[dict[str, Any]],
-    ) -> GuardrailResult:
+    ) -> "GuardrailResult":
         """Checks the context against the guardrail using a regular expression.
 
         Args:
@@ -167,5 +141,39 @@ class RegexGuardrail(Guardrail):
             if match:
                 activated = True
                 justification = f"Match found -> {match.group(0)}"
-                return GuardrailResult(activated=activated, justification=justification)
-        return GuardrailResult(activated=False, justification="No match found in the context.")
+                return GuardrailResult(activated=activated, justification=justification, guardrail=self)
+        return GuardrailResult(activated=False, justification="No match found in the context.", guardrail=self)
+
+
+class GuardrailResult(BaseModel):
+    """Represents the outcome of a guardrail check."""
+
+    activated: bool
+    guardrail: Guardrail
+    justification: str = Field(default="No justification provided")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def __str__(self) -> str:
+        return f"Guardrail Result: {self.activated}\nJustification: {self.justification}"
+
+    @property
+    def reply(self) -> str:
+        return f"{self.guardrail.activation_message}\nJustification: {self.justification}"
+
+    @staticmethod
+    def parse(text: str, guardrail: "Guardrail") -> "GuardrailResult":
+        """Parses a JSON string into a GuardrailResult object.
+
+        Args:
+            text (str): The JSON string to parse.
+            guardrail (Guardrail): The guardrail that the result is for.
+
+        Returns:
+            GuardrailResult: The parsed GuardrailResult object.
+        """
+        try:
+            data = json.loads(text)
+            return GuardrailResult(**data, guardrail=guardrail)
+        except (json.JSONDecodeError, ValueError) as e:
+            raise ValueError(f"Failed to parse GuardrailResult from text: {text}") from e

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

@@ -11,6 +11,7 @@ from ...events.agent_events import ErrorEvent, RunCompletionEvent
 from ...io.base import IOStream
 from ...io.run_response import AsyncRunResponse, AsyncRunResponseProtocol, RunResponse, RunResponseProtocol
 from ...io.thread_io_stream import AsyncThreadIOStream, ThreadIOStream
+from ...llm_config import LLMConfig
 from ..chat import ChatResult
 from .context_variables import ContextVariables
 from .group_utils import cleanup_temp_user_messages
@@ -32,6 +33,9 @@ def initiate_group_chat(
     pattern: "Pattern",
     messages: list[dict[str, Any]] | str,
     max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
 ) -> tuple[ChatResult, ContextVariables, "Agent"]:
     """Initialize and run a group chat using a pattern for configuration.
 
@@ -39,6 +43,9 @@ def initiate_group_chat(
         pattern: Pattern object that encapsulates the chat configuration.
         messages: Initial message(s).
         max_rounds: Maximum number of conversation rounds.
+        safeguard_policy: Optional safeguard policy dict or path to JSON file.
+        safeguard_llm_config: Optional LLM configuration for safeguard checks.
+        mask_llm_config: Optional LLM configuration for masking.
 
     Returns:
         ChatResult:         Conversations chat history.
@@ -66,6 +73,17 @@ def initiate_group_chat(
         messages=messages,
     )
 
+    # Apply safeguards if provided
+    if safeguard_policy:
+        from .safeguards import apply_safeguard_policy
+
+        apply_safeguard_policy(
+            groupchat_manager=manager,
+            policy=safeguard_policy,
+            safeguard_llm_config=safeguard_llm_config,
+            mask_llm_config=mask_llm_config,
+        )
+
     # Start or resume the conversation
     if len(processed_messages) > 1:
         last_agent, last_message = manager.resume(messages=processed_messages)
@@ -94,6 +112,9 @@ async def a_initiate_group_chat(
     pattern: "Pattern",
     messages: list[dict[str, Any]] | str,
     max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
 ) -> tuple[ChatResult, ContextVariables, "Agent"]:
     """Initialize and run a group chat using a pattern for configuration, asynchronously.
 
@@ -101,6 +122,9 @@ async def a_initiate_group_chat(
         pattern: Pattern object that encapsulates the chat configuration.
         messages: Initial message(s).
         max_rounds: Maximum number of conversation rounds.
+        safeguard_policy: Optional safeguard policy dict or path to JSON file.
+        safeguard_llm_config: Optional LLM configuration for safeguard checks.
+        mask_llm_config: Optional LLM configuration for masking.
 
     Returns:
         ChatResult:         Conversations chat history.
@@ -128,6 +152,17 @@ async def a_initiate_group_chat(
         messages=messages,
     )
 
+    # Apply safeguards if provided
+    if safeguard_policy:
+        from .safeguards import apply_safeguard_policy
+
+        apply_safeguard_policy(
+            groupchat_manager=manager,
+            policy=safeguard_policy,
+            safeguard_llm_config=safeguard_llm_config,
+            mask_llm_config=mask_llm_config,
+        )
+
     # Start or resume the conversation
     if len(processed_messages) > 1:
         last_agent, last_message = await manager.a_resume(messages=processed_messages)
@@ -156,6 +191,9 @@ def run_group_chat(
     pattern: "Pattern",
     messages: list[dict[str, Any]] | str,
     max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
 ) -> RunResponseProtocol:
     iostream = ThreadIOStream()
     # todo: add agents
@@ -165,6 +203,9 @@ def run_group_chat(
         pattern: "Pattern" = pattern,
         messages: list[dict[str, Any]] | str = messages,
         max_rounds: int = max_rounds,
+        safeguard_policy: dict[str, Any] | str | None = safeguard_policy,
+        safeguard_llm_config: LLMConfig | None = safeguard_llm_config,
+        mask_llm_config: LLMConfig | None = mask_llm_config,
         iostream: ThreadIOStream = iostream,
         response: RunResponse = response,
     ) -> None:
@@ -174,6 +215,9 @@ def run_group_chat(
                     pattern=pattern,
                     messages=messages,
                     max_rounds=max_rounds,
+                    safeguard_policy=safeguard_policy,
+                    safeguard_llm_config=safeguard_llm_config,
+                    mask_llm_config=mask_llm_config,
                 )
 
                 IOStream.get_default().send(
@@ -200,6 +244,9 @@ async def a_run_group_chat(
     pattern: "Pattern",
     messages: list[dict[str, Any]] | str,
     max_rounds: int = 20,
+    safeguard_policy: dict[str, Any] | str | None = None,
+    safeguard_llm_config: LLMConfig | None = None,
+    mask_llm_config: LLMConfig | None = None,
 ) -> AsyncRunResponseProtocol:
     iostream = AsyncThreadIOStream()
     # todo: add agents
@@ -209,6 +256,9 @@ async def a_run_group_chat(
         pattern: "Pattern" = pattern,
         messages: list[dict[str, Any]] | str = messages,
         max_rounds: int = max_rounds,
+        safeguard_policy: dict[str, Any] | str | None = safeguard_policy,
+        safeguard_llm_config: LLMConfig | None = safeguard_llm_config,
+        mask_llm_config: LLMConfig | None = mask_llm_config,
         iostream: AsyncThreadIOStream = iostream,
         response: AsyncRunResponse = response,
     ) -> None:
@@ -218,6 +268,9 @@ async def a_run_group_chat(
                     pattern=pattern,
                     messages=messages,
                     max_rounds=max_rounds,
+                    safeguard_policy=safeguard_policy,
+                    safeguard_llm_config=safeguard_llm_config,
+                    mask_llm_config=mask_llm_config,
                 )
 
                 IOStream.get_default().send(
@@ -232,6 +285,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",
+]