TelegramAgent

def send(
    self,
    message: Union[dict[str, Any], str],
    recipient: Agent,
    request_reply: Optional[bool] = None,
    silent: Optional[bool] = False,
):
    """Send a message to another agent.

    Args:
        message (dict or str): message to be sent.
            The message could contain the following fields:
            - content (str or List): Required, the content of the message. (Can be None)
            - function_call (str): the name of the function to be called.
            - name (str): the name of the function to be called.
            - role (str): the role of the message, any role that is not "function"
                will be modified to "assistant".
            - context (dict): the context of the message, which will be passed to
                [OpenAIWrapper.create](https://docs.ag2.ai/latest/docs/api-reference/autogen/OpenAIWrapper/#autogen.OpenAIWrapper.create).
                For example, one agent can send a message A as:
    ```python
    {
        "content": lambda context: context["use_tool_msg"],
        "context": {"use_tool_msg": "Use tool X if they are relevant."},
    }
    ```
                Next time, one agent can send a message B with a different "use_tool_msg".
                Then the content of message A will be refreshed to the new "use_tool_msg".
                So effectively, this provides a way for an agent to send a "link" and modify
                the content of the "link" later.
        recipient (Agent): the recipient of the message.
        request_reply (bool or None): whether to request a reply from the recipient.
        silent (bool or None): (Experimental) whether to print the message sent.

    Raises:
        ValueError: if the message can't be converted into a valid ChatCompletion message.
    """
    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)
    if valid:
        recipient.receive(message, self, request_reply, silent)
    else:
        raise ValueError(
            "Message can't be converted into a valid ChatCompletion message. Either content or function_call must be provided."
        )

async def a_send(
    self,
    message: Union[dict[str, Any], str],
    recipient: Agent,
    request_reply: Optional[bool] = None,
    silent: Optional[bool] = False,
):
    """(async) Send a message to another agent.

    Args:
        message (dict or str): message to be sent.
            The message could contain the following fields:
            - content (str or List): Required, the content of the message. (Can be None)
            - function_call (str): the name of the function to be called.
            - name (str): the name of the function to be called.
            - role (str): the role of the message, any role that is not "function"
                will be modified to "assistant".
            - context (dict): the context of the message, which will be passed to
                [OpenAIWrapper.create](https://docs.ag2.ai/latest/docs/api-reference/autogen/OpenAIWrapper/#autogen.OpenAIWrapper.create).
                For example, one agent can send a message A as:
    ```python
    {
        "content": lambda context: context["use_tool_msg"],
        "context": {"use_tool_msg": "Use tool X if they are relevant."},
    }
    ```
                Next time, one agent can send a message B with a different "use_tool_msg".
                Then the content of message A will be refreshed to the new "use_tool_msg".
                So effectively, this provides a way for an agent to send a "link" and modify
                the content of the "link" later.
        recipient (Agent): the recipient of the message.
        request_reply (bool or None): whether to request a reply from the recipient.
        silent (bool or None): (Experimental) whether to print the message sent.

    Raises:
        ValueError: if the message can't be converted into a valid ChatCompletion message.
    """
    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)
    if valid:
        await recipient.a_receive(message, self, request_reply, silent)
    else:
        raise ValueError(
            "Message can't be converted into a valid ChatCompletion message. Either content or function_call must be provided."
        )

def receive(
    self,
    message: Union[dict[str, Any], str],
    sender: Agent,
    request_reply: Optional[bool] = None,
    silent: Optional[bool] = False,
):
    """Receive a message from another agent.

    Once a message is received, this function sends a reply to the sender or stop.
    The reply can be generated automatically or entered manually by a human.

    Args:
        message (dict or str): message from the sender. If the type is dict, it may contain the following reserved fields (either content or function_call need to be provided).
            1. "content": content of the message, can be None.
            2. "function_call": a dictionary containing the function name and arguments. (deprecated in favor of "tool_calls")
            3. "tool_calls": a list of dictionaries containing the function name and arguments.
            4. "role": role of the message, can be "assistant", "user", "function", "tool".
                This field is only needed to distinguish between "function" or "assistant"/"user".
            5. "name": In most cases, this field is not needed. When the role is "function", this field is needed to indicate the function name.
            6. "context" (dict): the context of the message, which will be passed to
                [OpenAIWrapper.create](https://docs.ag2.ai/latest/docs/api-reference/autogen/OpenAIWrapper/#autogen.OpenAIWrapper.create).
        sender: sender of an Agent instance.
        request_reply (bool or None): whether a reply is requested from the sender.
            If None, the value is determined by `self.reply_at_receive[sender]`.
        silent (bool or None): (Experimental) whether to print the message received.

    Raises:
        ValueError: if the message can't be converted into a valid ChatCompletion message.
    """
    self._process_received_message(message, sender, silent)
    if request_reply is False or (request_reply is None and self.reply_at_receive[sender] is False):
        return
    reply = self.generate_reply(messages=self.chat_messages[sender], sender=sender)
    if reply is not None:
        self.send(reply, sender, silent=silent)

async def a_receive(
    self,
    message: Union[dict[str, Any], str],
    sender: Agent,
    request_reply: Optional[bool] = None,
    silent: Optional[bool] = False,
):
    """(async) Receive a message from another agent.

    Once a message is received, this function sends a reply to the sender or stop.
    The reply can be generated automatically or entered manually by a human.

    Args:
        message (dict or str): message from the sender. If the type is dict, it may contain the following reserved fields (either content or function_call need to be provided).
            1. "content": content of the message, can be None.
            2. "function_call": a dictionary containing the function name and arguments. (deprecated in favor of "tool_calls")
            3. "tool_calls": a list of dictionaries containing the function name and arguments.
            4. "role": role of the message, can be "assistant", "user", "function".
                This field is only needed to distinguish between "function" or "assistant"/"user".
            5. "name": In most cases, this field is not needed. When the role is "function", this field is needed to indicate the function name.
            6. "context" (dict): the context of the message, which will be passed to
                [OpenAIWrapper.create](https://docs.ag2.ai/latest/docs/api-reference/autogen/OpenAIWrapper/#autogen.OpenAIWrapper.create).
        sender: sender of an Agent instance.
        request_reply (bool or None): whether a reply is requested from the sender.
            If None, the value is determined by `self.reply_at_receive[sender]`.
        silent (bool or None): (Experimental) whether to print the message received.

    Raises:
        ValueError: if the message can't be converted into a valid ChatCompletion message.
    """
    self._process_received_message(message, sender, silent)
    if request_reply is False or (request_reply is None and self.reply_at_receive[sender] is False):
        return
    reply = await self.a_generate_reply(messages=self.chat_messages[sender], sender=sender)
    if reply is not None:
        await self.a_send(reply, sender, silent=silent)

def generate_reply(
    self,
    messages: Optional[list[dict[str, Any]]] = None,
    sender: Optional["Agent"] = None,
    **kwargs: Any,
) -> Optional[Union[str, dict[str, Any]]]:
    """Reply based on the conversation history and the sender.

    Either messages or sender must be provided.
    Register a reply_func with `None` as one trigger for it to be activated when `messages` is non-empty and `sender` is `None`.
    Use registered auto reply functions to generate replies.
    By default, the following functions are checked in order:
    1. check_termination_and_human_reply
    2. generate_function_call_reply (deprecated in favor of tool_calls)
    3. generate_tool_calls_reply
    4. generate_code_execution_reply
    5. generate_oai_reply
    Every function returns a tuple (final, reply).
    When a function returns final=False, the next function will be checked.
    So by default, termination and human reply will be checked first.
    If not terminating and human reply is skipped, execute function or code and return the result.
    AI replies are generated only when no code execution is performed.

    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
            the reply generation process. Functions in this list will be skipped even if
            they would normally be triggered.

    Returns:
        str or dict or None: reply. None if no reply is generated.
    """
    if all((messages is None, sender is None)):
        error_msg = f"Either {messages=} or {sender=} must be provided."
        logger.error(error_msg)
        raise AssertionError(error_msg)

    if messages is None:
        messages = self._oai_messages[sender]

    # Call the hookable method that gives registered hooks a chance to update agent state, used for their context variables.
    self.update_agent_state_before_reply(messages)

    # Call the hookable method that gives registered hooks a chance to process the last message.
    # Message modifications do not affect the incoming messages or self._oai_messages.
    messages = self.process_last_received_message(messages)

    # Call the hookable method that gives registered hooks a chance to process all messages.
    # Message modifications do not affect the incoming messages or self._oai_messages.
    messages = self.process_all_messages_before_reply(messages)

    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"]:
            continue
        if inspect.iscoroutinefunction(reply_func):
            continue
        if self._match_trigger(reply_func_tuple["trigger"], sender):
            final, reply = reply_func(self, messages=messages, sender=sender, config=reply_func_tuple["config"])
            if logging_enabled():
                log_event(
                    self,
                    "reply_func_executed",
                    reply_func_module=reply_func.__module__,
                    reply_func_name=reply_func.__name__,
                    final=final,
                    reply=reply,
                )
            if final:
                return reply
    return self._default_auto_reply

async def a_generate_reply(
    self,
    messages: Optional[list[dict[str, Any]]] = None,
    sender: Optional["Agent"] = None,
    **kwargs: Any,
) -> Union[str, dict[str, Any], None]:
    """(async) Reply based on the conversation history and the sender.

    Either messages or sender must be provided.
    Register a reply_func with `None` as one trigger for it to be activated when `messages` is non-empty and `sender` is `None`.
    Use registered auto reply functions to generate replies.
    By default, the following functions are checked in order:
    1. check_termination_and_human_reply
    2. generate_function_call_reply
    3. generate_tool_calls_reply
    4. generate_code_execution_reply
    5. generate_oai_reply
    Every function returns a tuple (final, reply).
    When a function returns final=False, the next function will be checked.
    So by default, termination and human reply will be checked first.
    If not terminating and human reply is skipped, execute function or code and return the result.
    AI replies are generated only when no code execution is performed.

    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
            the reply generation process. Functions in this list will be skipped even if
            they would normally be triggered.

    Returns:
        str or dict or None: reply. None if no reply is generated.
    """
    if all((messages is None, sender is None)):
        error_msg = f"Either {messages=} or {sender=} must be provided."
        logger.error(error_msg)
        raise AssertionError(error_msg)

    if messages is None:
        messages = self._oai_messages[sender]

    # Call the hookable method that gives registered hooks a chance to update agent state, used for their context variables.
    self.update_agent_state_before_reply(messages)

    # Call the hookable method that gives registered hooks a chance to process the last message.
    # Message modifications do not affect the incoming messages or self._oai_messages.
    messages = self.process_last_received_message(messages)

    # Call the hookable method that gives registered hooks a chance to process all messages.
    # Message modifications do not affect the incoming messages or self._oai_messages.
    messages = self.process_all_messages_before_reply(messages)

    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"]:
            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"]
                )
            else:
                final, reply = reply_func(self, messages=messages, sender=sender, config=reply_func_tuple["config"])
            if final:
                return reply
    return self._default_auto_reply

def update_system_message(self, system_message: str) -> None:
    """Update the system message.

    Args:
        system_message (str): system message for the ChatCompletion inference.
    """
    self._oai_system_message[0]["content"] = system_message

def register_reply(
    self,
    trigger: Union[type[Agent], str, Agent, Callable[[Agent], bool], list],
    reply_func: Callable,
    position: int = 0,
    config: Optional[Any] = None,
    reset_config: Optional[Callable[..., Any]] = None,
    *,
    ignore_async_in_sync_chat: bool = False,
    remove_other_reply_funcs: bool = False,
):
    """Register a reply function.

    The reply function will be called when the trigger matches the sender.
    The function registered later will be checked earlier by default.
    To change the order, set the position to a positive integer.

    Both sync and async reply functions can be registered. The sync reply function will be triggered
    from both sync and async chats. However, an async reply function will only be triggered from async
    chats (initiated with `ConversableAgent.a_initiate_chat`). If an `async` reply function is registered
    and a chat is initialized with a sync function, `ignore_async_in_sync_chat` determines the behaviour as follows:
        if `ignore_async_in_sync_chat` is set to `False` (default value), an exception will be raised, and
        if `ignore_async_in_sync_chat` is set to `True`, the reply function will be ignored.

    Args:
        trigger (Agent class, str, Agent instance, callable, or list): the trigger.
            If a class is provided, the reply function will be called when the sender is an instance of the class.
            If a string is provided, the reply function will be called when the sender's name matches the string.
            If an agent instance is provided, the reply function will be called when the sender is the agent instance.
            If a callable is provided, the reply function will be called when the callable returns True.
            If a list is provided, the reply function will be called when any of the triggers in the list is activated.
            If None is provided, the reply function will be called only when the sender is None.
            Note: Be sure to register `None` as a trigger if you would like to trigger an auto-reply function with non-empty messages and `sender=None`.
        reply_func (Callable): the reply function.
            The function takes a recipient agent, a list of messages, a sender agent and a config as input and returns a reply message.

            ```python
            def reply_func(
                recipient: ConversableAgent,
                messages: Optional[List[Dict]] = None,
                sender: Optional[Agent] = None,
                config: Optional[Any] = None,
            ) -> Tuple[bool, Union[str, Dict, None]]:
            ```
        position (int): the position of the reply function in the reply function list.
            The function registered later will be checked earlier by default.
            To change the order, set the position to a positive integer.
        config (Any): the config to be passed to the reply function.
            When an agent is reset, the config will be reset to the original value.
        reset_config (Callable): the function to reset the config.
            The function returns None. Signature: ```def reset_config(config: Any)```
        ignore_async_in_sync_chat (bool): whether to ignore the async reply function in sync chats. If `False`, an exception
            will be raised if an async reply function is registered and a chat is initialized with a sync
            function.
        remove_other_reply_funcs (bool): whether to remove other reply functions when registering this reply function.
    """
    if not isinstance(trigger, (type, str, Agent, Callable, list)):
        raise ValueError("trigger must be a class, a string, an agent, a callable or a list.")
    if remove_other_reply_funcs:
        self._reply_func_list.clear()
    self._reply_func_list.insert(
        position,
        {
            "trigger": trigger,
            "reply_func": reply_func,
            "config": copy.copy(config),
            "init_config": config,
            "reset_config": reset_config,
            "ignore_async_in_sync_chat": ignore_async_in_sync_chat and inspect.iscoroutinefunction(reply_func),
        },
    )

def replace_reply_func(self, old_reply_func: Callable, new_reply_func: Callable):
    """Replace a registered reply function with a new one.

    Args:
        old_reply_func (Callable): the old reply function to be replaced.
        new_reply_func (Callable): the new reply function to replace the old one.
    """
    for f in self._reply_func_list:
        if f["reply_func"] == old_reply_func:
            f["reply_func"] = new_reply_func

def register_nested_chats(
    self,
    chat_queue: list[dict[str, Any]],
    trigger: Union[type[Agent], str, Agent, Callable[[Agent], bool], list],
    reply_func_from_nested_chats: Union[str, Callable[..., Any]] = "summary_from_nested_chats",
    position: int = 2,
    use_async: Union[bool, None] = None,
    **kwargs: Any,
) -> None:
    """Register a nested chat reply function.

    Args:
        chat_queue (list): a list of chat objects to be initiated. If use_async is used, then all messages in chat_queue must have a chat-id associated with them.
        trigger (Agent class, str, Agent instance, callable, or list): refer to `register_reply` for details.
        reply_func_from_nested_chats (Callable, str): the reply function for the nested chat.
            The function takes a chat_queue for nested chat, recipient agent, a list of messages, a sender agent and a config as input and returns a reply message.
            Default to "summary_from_nested_chats", which corresponds to a built-in reply function that get summary from the nested chat_queue.
            ```python
            def reply_func_from_nested_chats(
                chat_queue: List[Dict],
                recipient: ConversableAgent,
                messages: Optional[List[Dict]] = None,
                sender: Optional[Agent] = None,
                config: Optional[Any] = None,
            ) -> Tuple[bool, Union[str, Dict, None]]:
            ```
        position (int): Ref to `register_reply` for details. Default to 2. It means we first check the termination and human reply, then check the registered nested chat reply.
        use_async: Uses a_initiate_chats internally to start nested chats. If the original chat is initiated with a_initiate_chats, you may set this to true so nested chats do not run in sync.
        kwargs: Ref to `register_reply` for details.
    """
    if use_async:
        for chat in chat_queue:
            if chat.get("chat_id") is None:
                raise ValueError("chat_id is required for async nested chats")

    if use_async:
        if reply_func_from_nested_chats == "summary_from_nested_chats":
            reply_func_from_nested_chats = self._a_summary_from_nested_chats
        if not callable(reply_func_from_nested_chats) or not inspect.iscoroutinefunction(
            reply_func_from_nested_chats
        ):
            raise ValueError("reply_func_from_nested_chats must be a callable and a coroutine")

        async def wrapped_reply_func(recipient, messages=None, sender=None, config=None):
            return await reply_func_from_nested_chats(chat_queue, recipient, messages, sender, config)

    else:
        if reply_func_from_nested_chats == "summary_from_nested_chats":
            reply_func_from_nested_chats = self._summary_from_nested_chats
        if not callable(reply_func_from_nested_chats):
            raise ValueError("reply_func_from_nested_chats must be a callable")

        def wrapped_reply_func(recipient, messages=None, sender=None, config=None):
            return reply_func_from_nested_chats(chat_queue, recipient, messages, sender, config)

    functools.update_wrapper(wrapped_reply_func, reply_func_from_nested_chats)

    self.register_reply(
        trigger,
        wrapped_reply_func,
        position,
        kwargs.get("config"),
        kwargs.get("reset_config"),
        ignore_async_in_sync_chat=(
            not use_async if use_async is not None else kwargs.get("ignore_async_in_sync_chat")
        ),
    )

def get_context(self, key: str, default: Any = None) -> Any:
    """Get a context variable by key.

    Args:
        key: The key to look up
        default: Value to return if key doesn't exist
    Returns:
        The value associated with the key, or default if not found
    """
    return self._context_variables.get(key, default)

def set_context(self, key: str, value: Any) -> None:
    """Set a context variable.

    Args:
        key: The key to set
        value: The value to associate with the key
    """
    self._context_variables[key] = value

def update_context(self, context_variables: dict[str, Any]) -> None:
    """Update multiple context variables at once.

    Args:
        context_variables: Dictionary of variables to update/add
    """
    self._context_variables.update(context_variables)

def pop_context(self, key: str, default: Any = None) -> Any:
    """Remove and return a context variable.

    Args:
        key: The key to remove
        default: Value to return if key doesn't exist
    Returns:
        The value that was removed, or default if key not found
    """
    return self._context_variables.pop(key, default)

def update_max_consecutive_auto_reply(self, value: int, sender: Optional[Agent] = None):
    """Update the maximum number of consecutive auto replies.

    Args:
        value (int): the maximum number of consecutive auto replies.
        sender (Agent): when the sender is provided, only update the max_consecutive_auto_reply for that sender.
    """
    if sender is None:
        self._max_consecutive_auto_reply = value
        for k in self._max_consecutive_auto_reply_dict:
            self._max_consecutive_auto_reply_dict[k] = value
    else:
        self._max_consecutive_auto_reply_dict[sender] = value

def max_consecutive_auto_reply(self, sender: Optional[Agent] = None) -> int:
    """The maximum number of consecutive auto replies."""
    return self._max_consecutive_auto_reply if sender is None else self._max_consecutive_auto_reply_dict[sender]

def chat_messages_for_summary(self, agent: Agent) -> list[dict[str, Any]]:
    """A list of messages as a conversation to summarize."""
    return self._oai_messages[agent]

def last_message(self, agent: Optional[Agent] = None) -> Optional[dict[str, Any]]:
    """The last message exchanged with the agent.

    Args:
        agent (Agent): The agent in the conversation.
            If None and more than one agent's conversations are found, an error will be raised.
            If None and only one conversation is found, the last message of the only conversation will be returned.

    Returns:
        The last message exchanged with the agent.
    """
    if agent is None:
        n_conversations = len(self._oai_messages)
        if n_conversations == 0:
            return None
        if n_conversations == 1:
            for conversation in self._oai_messages.values():
                return conversation[-1]
        raise ValueError("More than one conversation is found. Please specify the sender to get the last message.")
    if agent not in self._oai_messages:
        raise KeyError(
            f"The agent '{agent.name}' is not present in any conversation. No history available for this agent."
        )
    return self._oai_messages[agent][-1]

def initiate_chat(
    self,
    recipient: "ConversableAgent",
    clear_history: bool = True,
    silent: Optional[bool] = False,
    cache: Optional[AbstractCache] = None,
    max_turns: Optional[int] = None,
    summary_method: Optional[Union[str, Callable[..., Any]]] = DEFAULT_SUMMARY_METHOD,
    summary_args: Optional[dict[str, Any]] = {},
    message: Optional[Union[dict[str, Any], str, Callable[..., Any]]] = None,
    **kwargs: Any,
) -> ChatResult:
    """Initiate a chat with the recipient agent.

    Reset the consecutive auto reply counter.
    If `clear_history` is True, the chat history with the recipient agent will be cleared.


    Args:
        recipient: the recipient agent.
        clear_history (bool): whether to clear the chat history with the agent. Default is True.
        silent (bool or None): (Experimental) whether to print the messages for this conversation. Default is False.
        cache (AbstractCache or None): the cache client to be used for this conversation. Default is None.
        max_turns (int or None): the maximum number of turns for the chat between the two agents. One turn means one conversation round trip. Note that this is different from
            `max_consecutive_auto_reply` which is the maximum number of consecutive auto replies; and it is also different from `max_rounds` in GroupChat which is the maximum number of rounds in a group chat session.
            If max_turns is set to None, the chat will continue until a termination condition is met. Default is None.
        summary_method (str or callable): a method to get a summary from the chat. Default is DEFAULT_SUMMARY_METHOD, i.e., "last_msg".
            Supported strings are "last_msg" and "reflection_with_llm":
                - when set to "last_msg", it returns the last message of the dialog as the summary.
                - when set to "reflection_with_llm", it returns a summary extracted using an llm client.
                    `llm_config` must be set in either the recipient or sender.

            A callable summary_method should take the recipient and sender agent in a chat as input and return a string of summary. E.g.,

            ```python
            def my_summary_method(
                sender: ConversableAgent,
                recipient: ConversableAgent,
                summary_args: dict,
            ):
                return recipient.last_message(sender)["content"]
            ```
        summary_args (dict): a dictionary of arguments to be passed to the summary_method.
            One example key is "summary_prompt", and value is a string of text used to prompt a LLM-based agent (the sender or recipient agent) to reflect
            on the conversation and extract a summary when summary_method is "reflection_with_llm".
            The default summary_prompt is DEFAULT_SUMMARY_PROMPT, i.e., "Summarize takeaway from the conversation. Do not add any introductory phrases. If the intended request is NOT properly addressed, please point it out."
            Another available key is "summary_role", which is the role of the message sent to the agent in charge of summarizing. Default is "system".
        message (str, dict or Callable): the initial message to be sent to the recipient. Needs to be provided. Otherwise, input() will be called to get the initial message.
            - If a string or a dict is provided, it will be used as the initial message.        `generate_init_message` is called to generate the initial message for the agent based on this string and the context.
                If dict, it may contain the following reserved fields (either content or tool_calls need to be provided).

                    1. "content": content of the message, can be None.
                    2. "function_call": a dictionary containing the function name and arguments. (deprecated in favor of "tool_calls")
                    3. "tool_calls": a list of dictionaries containing the function name and arguments.
                    4. "role": role of the message, can be "assistant", "user", "function".
                        This field is only needed to distinguish between "function" or "assistant"/"user".
                    5. "name": In most cases, this field is not needed. When the role is "function", this field is needed to indicate the function name.
                    6. "context" (dict): the context of the message, which will be passed to
                        `OpenAIWrapper.create`.

            - If a callable is provided, it will be called to get the initial message in the form of a string or a dict.
                If the returned type is dict, it may contain the reserved fields mentioned above.

                Example of a callable message (returning a string):

                ```python
                def my_message(
                    sender: ConversableAgent, recipient: ConversableAgent, context: dict
                ) -> Union[str, Dict]:
                    carryover = context.get("carryover", "")
                    if isinstance(message, list):
                        carryover = carryover[-1]
                    final_msg = "Write a blogpost." + "\\nContext: \\n" + carryover
                    return final_msg
                ```

                Example of a callable message (returning a dict):

                ```python
                def my_message(
                    sender: ConversableAgent, recipient: ConversableAgent, context: dict
                ) -> Union[str, Dict]:
                    final_msg = {}
                    carryover = context.get("carryover", "")
                    if isinstance(message, list):
                        carryover = carryover[-1]
                    final_msg["content"] = "Write a blogpost." + "\\nContext: \\n" + carryover
                    final_msg["context"] = {"prefix": "Today I feel"}
                    return final_msg
                ```
        **kwargs: any additional information. It has the following reserved fields:
            - "carryover": a string or a list of string to specify the carryover information to be passed to this chat.
                If provided, we will combine this carryover (by attaching a "context: " string and the carryover content after the message content) with the "message" content when generating the initial chat
                message in `generate_init_message`.
            - "verbose": a boolean to specify whether to print the message and carryover in a chat. Default is False.

    Raises:
        RuntimeError: if any async reply functions are registered and not ignored in sync chat.

    Returns:
        ChatResult: an ChatResult object.
    """
    iostream = IOStream.get_default()

    _chat_info = locals().copy()
    _chat_info["sender"] = self
    consolidate_chat_info(_chat_info, uniform_sender=self)
    for agent in [self, recipient]:
        agent._raise_exception_on_async_reply_functions()
        agent.previous_cache = agent.client_cache
        agent.client_cache = cache
    if isinstance(max_turns, int):
        self._prepare_chat(recipient, clear_history, reply_at_receive=False)
        for i in range(max_turns):
            # check recipient max consecutive auto reply limit
            if self._consecutive_auto_reply_counter[recipient] >= recipient._max_consecutive_auto_reply:
                break
            if i == 0:
                if isinstance(message, Callable):
                    msg2send = message(_chat_info["sender"], _chat_info["recipient"], kwargs)
                else:
                    msg2send = self.generate_init_message(message, **kwargs)
            else:
                msg2send = self.generate_reply(messages=self.chat_messages[recipient], sender=recipient)
            if msg2send is None:
                break
            self.send(msg2send, recipient, request_reply=True, silent=silent)

        else:  # No breaks in the for loop, so we have reached max turns
            iostream.send(TerminationEvent(termination_reason=f"Maximum turns ({max_turns}) reached"))
    else:
        self._prepare_chat(recipient, clear_history)
        if isinstance(message, Callable):
            msg2send = message(_chat_info["sender"], _chat_info["recipient"], kwargs)
        else:
            msg2send = self.generate_init_message(message, **kwargs)
        self.send(msg2send, recipient, silent=silent)
    summary = self._summarize_chat(
        summary_method,
        summary_args,
        recipient,
        cache=cache,
    )
    for agent in [self, recipient]:
        agent.client_cache = agent.previous_cache
        agent.previous_cache = None
    chat_result = ChatResult(
        chat_history=self.chat_messages[recipient],
        summary=summary,
        cost=gather_usage_summary([self, recipient]),
        human_input=self._human_input,
    )
    return chat_result

def run(
    self,
    recipient: Optional["ConversableAgent"] = None,
    clear_history: bool = True,
    silent: Optional[bool] = False,
    cache: Optional[AbstractCache] = None,
    max_turns: Optional[int] = None,
    summary_method: Optional[Union[str, Callable[..., Any]]] = DEFAULT_SUMMARY_METHOD,
    summary_args: Optional[dict[str, Any]] = {},
    message: Optional[Union[dict[str, Any], str, Callable[..., Any]]] = None,
    executor_kwargs: Optional[dict[str, Any]] = None,
    tools: Optional[Union[Tool, Iterable[Tool]]] = None,
    user_input: Optional[bool] = False,
    msg_to: Optional[str] = "agent",
    **kwargs: Any,
) -> RunResponseProtocol:
    iostream = ThreadIOStream()
    response = RunResponse(iostream)

    if recipient is None:

        def initiate_chat(
            self=self,
            iostream: ThreadIOStream = iostream,
            response: RunResponse = response,
        ) -> None:
            with (
                IOStream.set_default(iostream),
                self._create_or_get_executor(
                    executor_kwargs=executor_kwargs,
                    tools=tools,
                    agent_name="user",
                    agent_human_input_mode="ALWAYS" if user_input else "NEVER",
                ) as executor,
            ):
                try:
                    if msg_to == "agent":
                        chat_result = executor.initiate_chat(
                            self,
                            message=message,
                            clear_history=clear_history,
                            max_turns=max_turns,
                            summary_method=summary_method,
                        )
                    else:
                        chat_result = self.initiate_chat(
                            executor,
                            message=message,
                            clear_history=clear_history,
                            max_turns=max_turns,
                            summary_method=summary_method,
                        )

                    IOStream.get_default().send(
                        RunCompletionEvent(
                            history=chat_result.chat_history,
                            summary=chat_result.summary,
                            cost=chat_result.cost,
                            last_speaker=self.name,
                        )
                    )
                except Exception as e:
                    response.iostream.send(ErrorEvent(error=e))

    else:

        def initiate_chat(
            self=self,
            iostream: ThreadIOStream = iostream,
            response: RunResponse = response,
        ) -> None:
            with IOStream.set_default(iostream):  # type: ignore[arg-type]
                try:
                    chat_result = self.initiate_chat(
                        recipient,
                        clear_history=clear_history,
                        silent=silent,
                        cache=cache,
                        max_turns=max_turns,
                        summary_method=summary_method,
                        summary_args=summary_args,
                        message=message,
                        **kwargs,
                    )

                    response._summary = chat_result.summary
                    response._messages = chat_result.chat_history

                    _last_speaker = recipient if chat_result.chat_history[-1]["name"] == recipient.name else self
                    if hasattr(recipient, "last_speaker"):
                        _last_speaker = recipient.last_speaker

                    IOStream.get_default().send(
                        RunCompletionEvent(
                            history=chat_result.chat_history,
                            summary=chat_result.summary,
                            cost=chat_result.cost,
                            last_speaker=_last_speaker.name,
                        )
                    )
                except Exception as e:
                    response.iostream.send(ErrorEvent(error=e))

    threading.Thread(
        target=initiate_chat,
    ).start()

    return response