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

autogen/agentchat/conversable_agent.py

@@ -14,7 +14,7 @@ import re
 import threading
 import warnings
 from collections import defaultdict
-from collections.abc import Callable, Generator, Iterable
+from collections.abc import Callable, Container, Generator, Iterable
 from contextlib import contextmanager
 from dataclasses import dataclass
 from inspect import signature
@@ -77,7 +77,7 @@ from .chat import (
     initiate_chats,
 )
 from .group.context_variables import ContextVariables
-from .group.guardrails import Guardrail
+from .group.guardrails import Guardrail, GuardrailResult
 from .group.handoffs import Handoffs
 from .utils import consolidate_chat_info, gather_usage_summary
 
@@ -1044,7 +1044,11 @@ class ConversableAgent(LLMAgent):
         return name
 
     def _append_oai_message(
-        self, message: dict[str, Any] | str, role, conversation_id: Agent, is_sending: bool
+        self,
+        message: dict[str, Any] | str,
+        conversation_id: Agent,
+        role: str = "assistant",
+        name: str | None = None,
     ) -> bool:
         """Append a message to the ChatCompletion conversation.
 
@@ -1055,50 +1059,17 @@ class ConversableAgent(LLMAgent):
 
         Args:
             message (dict or str): message to be appended to the ChatCompletion conversation.
-            role (str): role of the message, can be "assistant" or "function".
             conversation_id (Agent): id of the conversation, should be the recipient or sender.
-            is_sending (bool): If the agent (aka self) is sending to the conversation_id agent, otherwise receiving.
+            role (str): role of the message, can be "assistant" or "function".
+            name (str | None): name of the message author, can be the name of the agent. If not provided, the name of the currentagent will be used.
 
         Returns:
             bool: whether the message is appended to the ChatCompletion conversation.
         """
-        message = self._message_to_dict(message)
-        # create oai message to be appended to the oai conversation that can be passed to oai directly.
-        oai_message = {
-            k: message[k]
-            for k in ("content", "function_call", "tool_calls", "tool_responses", "tool_call_id", "name", "context")
-            if k in message and message[k] is not None
-        }
-        if "content" not in oai_message:
-            if "function_call" in oai_message or "tool_calls" in oai_message:
-                oai_message["content"] = None  # if only function_call is provided, content will be set to None.
-            else:
-                return False
-
-        if message.get("role") in ["function", "tool"]:
-            oai_message["role"] = message.get("role")
-            if "tool_responses" in oai_message:
-                for tool_response in oai_message["tool_responses"]:
-                    tool_response["content"] = str(tool_response["content"])
-        elif "override_role" in message:
-            # If we have a direction to override the role then set the
-            # role accordingly. Used to customise the role for the
-            # select speaker prompt.
-            oai_message["role"] = message.get("override_role")
-        else:
-            oai_message["role"] = role
-
-        if oai_message.get("function_call", False) or oai_message.get("tool_calls", False):
-            oai_message["role"] = "assistant"  # only messages with role 'assistant' can have a function call.
-        elif "name" not in oai_message:
-            # If we don't have a name field, append it
-            if is_sending:
-                oai_message["name"] = self.name
-            else:
-                oai_message["name"] = conversation_id.name
-
+        valid, oai_message = normilize_message_to_oai(message, role=role, name=name or self.name)
+        if not valid:
+            return False
         self._oai_messages[conversation_id].append(oai_message)
-
         return True
 
     def _process_message_before_send(
@@ -1152,7 +1123,7 @@ class ConversableAgent(LLMAgent):
         message = self._process_message_before_send(message, recipient, ConversableAgent._is_silent(self, silent))
         # When the agent composes and sends the message, the role of the message is "assistant"
         # unless it's "function".
-        valid = self._append_oai_message(message, "assistant", recipient, is_sending=True)
+        valid = self._append_oai_message(message, recipient, role="assistant", name=self.name)
         if valid:
             recipient.receive(message, self, request_reply, silent)
         else:
@@ -1200,7 +1171,7 @@ class ConversableAgent(LLMAgent):
         message = self._process_message_before_send(message, recipient, ConversableAgent._is_silent(self, silent))
         # When the agent composes and sends the message, the role of the message is "assistant"
         # unless it's "function".
-        valid = self._append_oai_message(message, "assistant", recipient, is_sending=True)
+        valid = self._append_oai_message(message, recipient, role="assistant", name=self.name)
         if valid:
             await recipient.a_receive(message, self, request_reply, silent)
         else:
@@ -1209,7 +1180,7 @@ class ConversableAgent(LLMAgent):
             )
 
     def _print_received_message(self, message: dict[str, Any] | str, sender: Agent, skip_head: bool = False):
-        message = self._message_to_dict(message)
+        message = message_to_dict(message)
         message_model = create_received_event_model(event=message, sender=sender, recipient=self)
         iostream = IOStream.get_default()
         # message_model.print(iostream.print)
@@ -1217,7 +1188,7 @@ class ConversableAgent(LLMAgent):
 
     def _process_received_message(self, message: dict[str, Any] | str, sender: Agent, silent: bool):
         # When the agent receives a message, the role of the message is "user". (If 'role' exists and is 'function', it will remain unchanged.)
-        valid = self._append_oai_message(message, "user", sender, is_sending=False)
+        valid = self._append_oai_message(message, sender, role="user", name=sender.name)
         if logging_enabled():
             log_event(self, "received_message", message=message, sender=sender.name, valid=valid)
 
@@ -1349,9 +1320,10 @@ class ConversableAgent(LLMAgent):
         Returns:
             bool: True if the chat should be terminated, False otherwise.
         """
+        content = message.get("content")
         return (
             isinstance(recipient, ConversableAgent)
-            and isinstance(message.get("content"), str)
+            and content is not None
             and hasattr(recipient, "_is_termination_msg")
             and recipient._is_termination_msg(message)
         )
@@ -2175,6 +2147,7 @@ class ConversableAgent(LLMAgent):
         messages: list[dict[str, Any]] | None = None,
         sender: Agent | None = None,
         config: OpenAIWrapper | None = None,
+        **kwargs: Any,
     ) -> tuple[bool, str | dict[str, Any] | None]:
         """Generate a reply using autogen.oai."""
         client = self.client if config is None else config
@@ -2188,7 +2161,12 @@ class ConversableAgent(LLMAgent):
         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)
+        extracted_response = self._generate_oai_reply_from_client(
+            client,
+            self._oai_system_message + messages,
+            self.client_cache,
+            **kwargs,
+        )
 
         # Process LLM response
         if extracted_response is not None:
@@ -2198,7 +2176,13 @@ class ConversableAgent(LLMAgent):
 
         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:
+    def _generate_oai_reply_from_client(
+        self,
+        llm_client,
+        messages,
+        cache,
+        **kwargs: Any,
+    ) -> str | dict[str, Any] | None:
         # unroll tool_responses
         all_messages = []
         for message in messages:
@@ -2217,6 +2201,7 @@ class ConversableAgent(LLMAgent):
             messages=all_messages,
             cache=cache,
             agent=self,
+            **kwargs,
         )
         extracted_response = llm_client.extract_text_or_completion_object(response)[0]
 
@@ -2246,20 +2231,27 @@ class ConversableAgent(LLMAgent):
         messages: list[dict[str, Any]] | None = None,
         sender: Agent | None = None,
         config: Any | None = None,
+        **kwargs: Any,
     ) -> tuple[bool, str | dict[str, Any] | None]:
         """Generate a reply using autogen.oai asynchronously."""
         iostream = IOStream.get_default()
 
         def _generate_oai_reply(
-            self, iostream: IOStream, *args: Any, **kwargs: Any
+            self, iostream: IOStream, *args: Any, **kw: Any
         ) -> tuple[bool, str | dict[str, Any] | None]:
             with IOStream.set_default(iostream):
-                return self.generate_oai_reply(*args, **kwargs)
+                return self.generate_oai_reply(*args, **kw)
 
         return await asyncio.get_event_loop().run_in_executor(
             None,
             functools.partial(
-                _generate_oai_reply, self=self, iostream=iostream, messages=messages, sender=sender, config=config
+                _generate_oai_reply,
+                self=self,
+                iostream=iostream,
+                messages=messages,
+                sender=sender,
+                config=config,
+                **kwargs,
             ),
         )
 
@@ -2423,7 +2415,7 @@ class ConversableAgent(LLMAgent):
         if messages is None:
             messages = self._oai_messages[sender]
         message = messages[-1]
-        if "function_call" in message:
+        if message.get("function_call"):
             call_id = message.get("id", None)
             func_call = message["function_call"]
             func_name = func_call.get("name", "")
@@ -2822,7 +2814,7 @@ class ConversableAgent(LLMAgent):
         self,
         messages: list[dict[str, Any]] | None = None,
         sender: Optional["Agent"] = None,
-        **kwargs: Any,
+        exclude: Container[Any] = (),
     ) -> str | dict[str, Any] | None:
         """Reply based on the conversation history and the sender.
 
@@ -2844,8 +2836,7 @@ class ConversableAgent(LLMAgent):
         Args:
             messages: a list of messages in the conversation history.
             sender: sender of an Agent instance.
-            **kwargs (Any): Additional arguments to customize reply generation. Supported kwargs:
-                - exclude (List[Callable[..., Any]]): A list of reply functions to exclude from
+            exclude: A list of reply functions to exclude from
                 the reply generation process. Functions in this list will be skipped even if
                 they would normally be triggered.
 
@@ -2873,7 +2864,7 @@ class ConversableAgent(LLMAgent):
 
         for reply_func_tuple in self._reply_func_list:
             reply_func = reply_func_tuple["reply_func"]
-            if "exclude" in kwargs and reply_func in kwargs["exclude"]:
+            if reply_func in exclude:
                 continue
             if inspect.iscoroutinefunction(reply_func):
                 continue
@@ -2896,7 +2887,7 @@ class ConversableAgent(LLMAgent):
         self,
         messages: list[dict[str, Any]] | None = None,
         sender: Optional["Agent"] = None,
-        **kwargs: Any,
+        exclude: Container[Any] = (),
     ) -> str | dict[str, Any] | None:
         """(async) Reply based on the conversation history and the sender.
 
@@ -2918,8 +2909,7 @@ class ConversableAgent(LLMAgent):
         Args:
             messages: a list of messages in the conversation history.
             sender: sender of an Agent instance.
-            **kwargs (Any): Additional arguments to customize reply generation. Supported kwargs:
-                - exclude (List[Callable[..., Any]]): A list of reply functions to exclude from
+            exclude: A list of reply functions to exclude from
                 the reply generation process. Functions in this list will be skipped even if
                 they would normally be triggered.
 
@@ -2947,13 +2937,16 @@ class ConversableAgent(LLMAgent):
 
         for reply_func_tuple in self._reply_func_list:
             reply_func = reply_func_tuple["reply_func"]
-            if "exclude" in kwargs and reply_func in kwargs["exclude"]:
+            if reply_func in exclude:
                 continue
 
             if self._match_trigger(reply_func_tuple["trigger"], sender):
                 if inspect.iscoroutinefunction(reply_func):
                     final, reply = await reply_func(
-                        self, messages=messages, sender=sender, config=reply_func_tuple["config"]
+                        self,
+                        messages=messages,
+                        sender=sender,
+                        config=reply_func_tuple["config"],
                     )
                 else:
                     final, reply = reply_func(self, messages=messages, sender=sender, config=reply_func_tuple["config"])
@@ -3448,13 +3441,30 @@ class ConversableAgent(LLMAgent):
             logger.error(error_msg)
             raise AssertionError(error_msg)
 
+        self.llm_config = self._update_tool_config(
+            self.llm_config,
+            tool_sig=tool_sig,
+            is_remove=is_remove,
+            silent_override=silent_override,
+        )
+
+        self.client = OpenAIWrapper(**self.llm_config)
+
+    def _update_tool_config(
+        self,
+        llm_config: dict[str, Any] | LLMConfig,
+        tool_sig: str | dict[str, Any],
+        is_remove: bool,
+        silent_override: bool = False,
+    ) -> dict[str, Any]:
         if is_remove:
-            if "tools" not in self.llm_config or len(self.llm_config["tools"]) == 0:
+            if "tools" not in llm_config or len(llm_config["tools"]) == 0:
                 error_msg = f"The agent config doesn't have tool {tool_sig}."
                 logger.error(error_msg)
                 raise AssertionError(error_msg)
+
             else:
-                current_tools = self.llm_config["tools"]
+                current_tools = llm_config["tools"]
                 filtered_tools = []
 
                 # Loop through and rebuild tools list without the tool to remove
@@ -3467,31 +3477,34 @@ class ConversableAgent(LLMAgent):
                     if is_different:
                         filtered_tools.append(tool)
 
-                self.llm_config["tools"] = filtered_tools
+                llm_config["tools"] = filtered_tools
+
         else:
             if not isinstance(tool_sig, dict):
                 raise ValueError(
                     f"The tool signature must be of the type dict. Received tool signature type {type(tool_sig)}"
                 )
+
             self._assert_valid_name(tool_sig["function"]["name"])
-            if "tools" in self.llm_config and len(self.llm_config["tools"]) > 0:
+            if "tools" in llm_config and len(llm_config["tools"]) > 0:
                 if not silent_override and any(
-                    tool["function"]["name"] == tool_sig["function"]["name"] for tool in self.llm_config["tools"]
+                    tool["function"]["name"] == tool_sig["function"]["name"] for tool in llm_config["tools"]
                 ):
                     warnings.warn(f"Function '{tool_sig['function']['name']}' is being overridden.", UserWarning)
-                self.llm_config["tools"] = [
+
+                llm_config["tools"] = [
                     tool
-                    for tool in self.llm_config["tools"]
+                    for tool in llm_config["tools"]
                     if tool.get("function", {}).get("name") != tool_sig["function"]["name"]
                 ] + [tool_sig]
             else:
-                self.llm_config["tools"] = [tool_sig]
+                llm_config["tools"] = [tool_sig]
 
         # Do this only if llm_config is a dict. If llm_config is LLMConfig, LLMConfig will handle this.
-        if len(self.llm_config["tools"]) == 0 and isinstance(self.llm_config, dict):
-            del self.llm_config["tools"]
+        if len(llm_config["tools"]) == 0 and isinstance(llm_config, dict):
+            del llm_config["tools"]
 
-        self.client = OpenAIWrapper(**self.llm_config)
+        return llm_config
 
     def can_execute_function(self, name: list[str] | str) -> bool:
         """Whether the agent can execute the function."""
@@ -3975,7 +3988,11 @@ class ConversableAgent(LLMAgent):
         if executor_kwargs is None:
             executor_kwargs = {}
         if "is_termination_msg" not in executor_kwargs:
-            executor_kwargs["is_termination_msg"] = lambda x: (x["content"] is not None) and "TERMINATE" in x["content"]
+            executor_kwargs["is_termination_msg"] = lambda x: "TERMINATE" in (
+                content_str(x.get("content"))
+                if isinstance(x.get("content"), (str, list)) or x.get("content") is None
+                else str(x.get("content"))
+            )
 
         try:
             if not self.run_executor:
@@ -4160,6 +4177,32 @@ class ConversableAgent(LLMAgent):
         """
         self.output_guardrails.extend(guardrails)
 
+    def run_input_guardrails(self, messages: list[dict[str, Any]] | None = None) -> GuardrailResult | None:
+        """Run input guardrails for an agent before the reply is generated.
+
+        Args:
+            messages (Optional[list[dict[str, Any]]]): The messages to check against the guardrails.
+        """
+        for guardrail in self.input_guardrails:
+            guardrail_result = guardrail.check(context=messages)
+
+            if guardrail_result.activated:
+                return guardrail_result
+        return None
+
+    def run_output_guardrails(self, reply: str | dict[str, Any]) -> GuardrailResult | None:
+        """Run output guardrails for an agent after the reply is generated.
+
+        Args:
+            reply (str | dict[str, Any]): The reply generated by the agent.
+        """
+        for guardrail in self.output_guardrails:
+            guardrail_result = guardrail.check(context=reply)
+
+            if guardrail_result.activated:
+                return guardrail_result
+        return None
+
 
 @export_module("autogen")
 def register_function(
@@ -4187,3 +4230,65 @@ def register_function(
     """
     f = caller.register_for_llm(name=name, description=description)(f)
     executor.register_for_execution(name=name)(f)
+
+
+def normilize_message_to_oai(
+    message: dict[str, Any] | str,
+    name: str,
+    role: str = "assistant",
+) -> tuple[bool, dict[str, Any]]:
+    message = message_to_dict(message)
+    # create oai message to be appended to the oai conversation that can be passed to oai directly.
+    oai_message = {
+        k: message[k]
+        for k in ("content", "function_call", "tool_responses", "tool_call_id", "name", "context")
+        if k in message and message[k] is not None
+    }
+
+    if tools := message.get("tool_calls"):  # check for [], None and missed key
+        oai_message["tool_calls"] = tools
+
+    if "content" not in oai_message:
+        if "function_call" in oai_message or "tool_calls" in oai_message:
+            oai_message["content"] = None  # if only function_call is provided, content will be set to None.
+        else:
+            return False, oai_message
+
+    if message.get("role") in ["function", "tool"]:
+        oai_message["role"] = message.get("role")
+        if "tool_responses" in oai_message:
+            for tool_response in oai_message["tool_responses"]:
+                content_value = tool_response.get("content")
+                tool_response["content"] = (
+                    content_str(content_value)
+                    if isinstance(content_value, (str, list)) or content_value is None
+                    else str(content_value)
+                )
+    elif "override_role" in message:
+        # If we have a direction to override the role then set the
+        # role accordingly. Used to customise the role for the
+        # select speaker prompt.
+        oai_message["role"] = message.get("override_role")
+    else:
+        oai_message["role"] = role
+
+    if oai_message.get("function_call", False) or oai_message.get("tool_calls", False):
+        oai_message["role"] = "assistant"  # only messages with role 'assistant' can have a function call.
+    elif "name" not in oai_message:
+        # If we don't have a name field, append it
+        oai_message["name"] = name
+
+    return True, oai_message
+
+
+def message_to_dict(message: dict[str, Any] | str) -> dict:
+    """Convert a message to a dictionary.
+
+    The message can be a string or a dictionary. The string will be put in the "content" field of the new dictionary.
+    """
+    if isinstance(message, str):
+        return {"content": message}
+    elif isinstance(message, dict):
+        return message
+    else:
+        return dict(message)

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]