autogen.AssistantAgent

AssistantAgent

AssistantAgent(
    name: str,
    system_message: str | None = &#x27;You are a helpful AI assistant.\nSolve tasks using your coding and language skills.\nIn the following cases, suggest python code (in a python coding block) or shell script (in a sh coding block) for the user to execute.\n    1. When you need to collect info, use the code to output the info you need, for example, browse or search the web, download/read a file, print the content of a webpage or a file, get the current date/time, check the operating system. After sufficient info is printed and the task is ready to be solved based on your language skill, you can solve the task by yourself.\n    2. When you need to perform some task with code, use the code to perform the task and output the result. Finish the task smartly.\nSolve the task step by step if you need to. If a plan is not provided, explain your plan first. Be clear which step uses code, and which step uses your language skill.\nWhen using code, you must indicate the script type in the code block. The user cannot provide any other feedback or perform any other action beyond executing the code you suggest. The user can\&#x27;t modify your code. So do not suggest incomplete code which requires users to modify. Don\&#x27;t use a code block if it\&#x27;s not intended to be executed by the user.\nIf you want the user to save the code in a file before executing it, put # filename: &lt;filename&gt; inside the code block as the first line. Don\&#x27;t include multiple code blocks in one response. Do not ask users to copy and paste the result. Instead, use \&#x27;print\&#x27; function for the output when relevant. Check the execution result returned by the user.\nIf the result indicates there is an error, fix the error and output the code again. Suggest the full code instead of partial code or code changes. If the error can\&#x27;t be fixed or if the task is not solved even after the code is executed successfully, analyze the problem, revisit your assumption, collect additional info you need, and think of a different approach to try.\nWhen you find an answer, verify the answer carefully. Include verifiable evidence in your response if possible.\nReply &quot;TERMINATE&quot; in the end when everything is done.\n    &#x27;,
    llm_config: LLMConfig | dict[str, Any] | Literal[False] | None = None,
    is_termination_msg: Callable[[dict[str, Any]], bool] | None = None,
    max_consecutive_auto_reply: int | None = None,
    human_input_mode: Literal['ALWAYS', 'NEVER', 'TERMINATE'] = 'NEVER',
    description: str | None = None,
    **kwargs: Any
)

(In preview) Assistant agent, designed to solve a task with LLM.
AssistantAgent is a subclass of ConversableAgent configured with a default system message.
The default system message is designed to solve a task with LLM, including suggesting python code blocks and debugging.
human_input_mode is default to “NEVER” and code_execution_config is default to False.
This agent doesn’t execute code by default, and expects the user to execute the code.
Parameters:

Name	Description
`name`	Type: str
`system_message`	Type: str \| None Default: ‘You are a helpful AI assistant.\nSolve tasks using your coding and language skills.\nIn the following cases, suggest python code (in a python coding block) or shell script (in a sh coding block) for the user to execute.\n 1. When you need to collect info, use the code to output the info you need, for example, browse or search the web, download/read a file, print the content of a webpage or a file, get the current date/time, check the operating system. After sufficient info is printed and the task is ready to be solved based on your language skill, you can solve the task by yourself.\n 2. When you need to perform some task with code, use the code to perform the task and output the result. Finish the task smartly.\nSolve the task step by step if you need to. If a plan is not provided, explain your plan first. Be clear which step uses code, and which step uses your language skill.\nWhen using code, you must indicate the script type in the code block. The user cannot provide any other feedback or perform any other action beyond executing the code you suggest. The user can't modify your code. So do not suggest incomplete code which requires users to modify. Don't use a code block if it's not intended to be executed by the user.\nIf you want the user to save the code in a file before executing it, put # filename
`llm_config`	Type: LLMConfig \| dict[str, typing.Any] \| Literal[False] \| None Default: None
`is_termination_msg`	Type: Callable[[dict[str, Any]], bool] \| None Default: None
`max_consecutive_auto_reply`	Type: int \| None Default: None
`human_input_mode`	Type: Literal[‘ALWAYS’, ‘NEVER’, ‘TERMINATE’] Default: ‘NEVER’
`description`	Type: str \| None Default: None
`**kwargs`	Type: Any

Class Attributes

DEFAULT_DESCRIPTION

DEFAULT_SYSTEM_MESSAGE

Instance Attributes

chat_messages

A dictionary of conversations from agent to list of messages.

code_executor

The code executor used by this agent. Returns None if code execution is disabled.

description

Get the description of the agent.

function_map

Return the function map.

name

Get the name of the agent.

system_message

Return the system message.

tools

Get the agent’s tools (registered for LLM) Note this is a copy of the tools list, use add_tool and remove_tool to modify the tools list.

use_docker

Bool value of whether to use docker to execute the code, or str value of the docker image name to use, or None when code execution is disabled.

Instance Methods

a_check_termination_and_human_reply

a_check_termination_and_human_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, str | None]

(async) Check if the conversation should be terminated, and if human reply is provided.
This method checks for conditions that require the conversation to be terminated, such as reaching a maximum number of consecutive auto-replies or encountering a termination message. Additionally, it prompts for and processes human input based on the configured human input mode, which can be ‘ALWAYS’, ‘NEVER’, or ‘TERMINATE’. The method also manages the consecutive auto-reply counter for the conversation and prints relevant messages based on the human input received.
Parameters:

Name	Description
`messages`	A list of message dictionaries, representing the conversation history. Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	The agent object representing the sender of the message. Type: Agent \| None Default: None
`config`	Configuration object, defaults to the current instance if not provided. Type: Any \| None Default: None

Returns:

Type	Description
tuple[bool, str \| None]	Tuple[bool, Union[str, Dict, None]]: A tuple containing a boolean indicating if the conversation should be terminated, and a human reply which can be a string, a dictionary, or None.

a_execute_function

a_execute_function(
    self,
    func_call: dict[str, Any],
    call_id: str | None = None,
    verbose: bool = False
) -> tuple[bool, dict[str, Any]]

Execute an async function call and return the result.
Override this function to modify the way async functions and tools are executed.
Parameters:

Name	Description
`func_call`	a dictionary extracted from openai message at key “function_call” or “tool_calls” with keys “name” and “arguments”. Type: dict[str, typing.Any]
`call_id`	a string to identify the tool call. Type: str \| None Default: None
`verbose`	Whether to send messages about the execution details to the output stream. When True, both the function call arguments and the execution result will be displayed. Defaults to False. Type: bool Default: False

Returns:

Type	Description
tuple[bool, dict[str, typing.Any]]	A tuple of (is_exec_success, result_dict). is_exec_success (boolean): whether the execution is successful. result_dict: a dictionary with keys “name”, “role”, and “content”. Value of “role” is “function”. “function_call” deprecated as of OpenAI API v1.1.0 See https://platform.openai.com/docs/api-reference/chat/create#chat-create-function_call

a_generate_function_call_reply

a_generate_function_call_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, dict[str, Any] | None]

Generate a reply using async function call.
”function_call” replaced by “tool_calls” as of OpenAI API v1.1.0 See https://platform.openai.com/docs/api-reference/chat/create#chat-create-functions Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: Any \| None Default: None

a_generate_init_message

a_generate_init_message(
    self,
    message: str | dict[str, Any] | None,
    **kwargs: Any
) -> dict[str, Any] | str

Generate the initial message for the agent.
If message is None, input() will be called to get the initial message.
Parameters:

Name	Description
`message`	the message to be processed. Type: str \| dict[str, typing.Any] \| None
`**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. It can be a string or a list of string. If provided, we will combine this carryover with the “message” content when generating the initial chat message. Type: Any

Returns:

Type	Description
dict[str, typing.Any] \| str	str or dict: the processed message.

a_generate_oai_reply

a_generate_oai_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, str | dict[str, Any] | None]

Generate a reply using autogen.oai asynchronously. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: Any \| None Default: None

a_generate_reply

a_generate_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: ForwardRef('Agent') | None = None,
    **kwargs: Any
) -> 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.
Parameters:

Name	Description
`messages`	a list of messages in the conversation history. Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	sender of an Agent instance. Type: ForwardRef(‘Agent’) \| None Default: None
`**kwargs`	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. Type: Any

Returns:

Type	Description
str \| dict[str, typing.Any] \| None	str or dict or None: reply. None if no reply is generated.

a_generate_tool_calls_reply

a_generate_tool_calls_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, dict[str, Any] | None]

Generate a reply using async function call. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: Any \| None Default: None

a_get_human_input

a_get_human_input(self, prompt: str) -> str

(Async) Get human input.
Override this method to customize the way to get human input.
Parameters:

Name	Description
`prompt`	prompt for the human input. Type: str

Returns:

Type	Description
str	str: human input.

a_initiate_chat

a_initiate_chat(
    self,
    recipient: ConversableAgent,
    clear_history: bool = True,
    silent: bool | None = False,
    cache: AbstractCache | None = None,
    max_turns: int | None = None,
    summary_method: str | Callable[..., Any] | None = 'last_msg',
    summary_args: dict[str, Any] | None = {},
    message: str | Callable[..., Any] | None = None,
    **kwargs: Any
) -> ChatResult

(async) 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.
a_generate_init_message is called to generate the initial message for the agent.
Parameters:

Name	Description
`recipient`	Type: ConversableAgent
`clear_history`	Type: bool Default: True
`silent`	Type: bool \| None Default: False
`cache`	Type: AbstractCache \| None Default: None
`max_turns`	Type: int \| None Default: None
`summary_method`	Type: str \| Callable[…, Any] \| None Default: ‘last_msg’
`summary_args`	Type: dict[str, typing.Any] \| None Default: {}
`message`	Type: str \| Callable[…, Any] \| None Default: None
`**kwargs`	Type: Any

Returns:

Type	Description
ChatResult	ChatResult: an ChatResult object.

a_receive

a_receive(
    self,
    message: dict[str, Any] | str,
    sender: Agent,
    request_reply: bool | None = None,
    silent: bool | None = 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.
Parameters:

Name	Description
`message`	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. Type: dict[str, typing.Any] \| str
`sender`	sender of an Agent instance. Type: Agent
`request_reply`	whether a reply is requested from the sender. If None, the value is determined by `self.reply_at_receive[sender]`. Type: bool \| None Default: None
`silent`	(Experimental) whether to print the message received. Type: bool \| None Default: False

a_send

a_send(
    self,
    message: dict[str, Any] | str,
    recipient: Agent,
    request_reply: bool | None = None,
    silent: bool | None = False
) ->

(async) Send a message to another agent.
Parameters:

Name	Description
`message`	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. For example, one agent can send a message A as: Type: dict[str, typing.Any] \| str
`recipient`	the recipient of the message. Type: Agent
`request_reply`	whether to request a reply from the recipient. Type: bool \| None Default: None
`silent`	(Experimental) whether to print the message sent. Type: bool \| None Default: False

a_sequential_run

a_sequential_run(self, chat_queue: list[dict[str, Any]]) -> list[AsyncRunResponseProtocol]

(Experimental) Initiate chats with multiple agents sequentially.
Parameters:

Name	Description
`chat_queue`	a list of dictionaries containing the information of the chats. Each dictionary should contain the input arguments for `initiate_chat` Type: list[dict[str, typing.Any]]

Returns:

Type	Description
list[AsyncRunResponseProtocol]	a list of ChatResult objects corresponding to the finished chats in the chat_queue.

can_execute_function

can_execute_function(self, name: list[str] | str) -> bool

Whether the agent can execute the function. Parameters:

Name	Description
`name`	Type: list[str] \| str

chat_messages_for_summary

chat_messages_for_summary(self, agent: Agent) -> list[dict[str, Any]]

A list of messages as a conversation to summarize. Parameters:

Name	Description
`agent`	Type: Agent

check_termination_and_human_reply

check_termination_and_human_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, str | None]

Check if the conversation should be terminated, and if human reply is provided.
This method checks for conditions that require the conversation to be terminated, such as reaching a maximum number of consecutive auto-replies or encountering a termination message. Additionally, it prompts for and processes human input based on the configured human input mode, which can be ‘ALWAYS’, ‘NEVER’, or ‘TERMINATE’. The method also manages the consecutive auto-reply counter for the conversation and prints relevant messages based on the human input received.
Parameters:

Name	Description
`messages`	A list of message dictionaries, representing the conversation history. Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	The agent object representing the sender of the message. Type: Agent \| None Default: None
`config`	Configuration object, defaults to the current instance if not provided. Type: Any \| None Default: None

Returns:

Type	Description
tuple[bool, str \| None]	A tuple containing a boolean indicating if the conversation should be terminated, and a human reply which can be a string, a dictionary, or None.

clear_history

clear_history(
    self,
    recipient: Agent | None = None,
    nr_messages_to_preserve: int | None = None
) ->

Clear the chat history of the agent.
Parameters:

Name	Description
`recipient`	the agent with whom the chat history to clear. If None, clear the chat history with all agents. Type: Agent \| None Default: None
`nr_messages_to_preserve`	the number of newest messages to preserve in the chat history. Type: int \| None Default: None

execute_code_blocks

execute_code_blocks(self, code_blocks) ->

Execute the code blocks and return the result. Parameters:

Name	Description
`code_blocks`

execute_function

execute_function(
    self,
    func_call: dict[str, Any],
    call_id: str | None = None,
    verbose: bool = False
) -> tuple[bool, dict[str, Any]]

Execute a function call and return the result.
Override this function to modify the way to execute function and tool calls.
Parameters:

Name	Description
`func_call`	a dictionary extracted from openai message at “function_call” or “tool_calls” with keys “name” and “arguments”. Type: dict[str, typing.Any]
`call_id`	a string to identify the tool call. Type: str \| None Default: None
`verbose`	Whether to send messages about the execution details to the output stream. When True, both the function call arguments and the execution result will be displayed. Defaults to False. Type: bool Default: False

Returns:

Type	Description
tuple[bool, dict[str, typing.Any]]	A tuple of (is_exec_success, result_dict). is_exec_success (boolean): whether the execution is successful. result_dict: a dictionary with keys “name”, “role”, and “content”. Value of “role” is “function”. “function_call” deprecated as of OpenAI API v1.1.0 See https://platform.openai.com/docs/api-reference/chat/create#chat-create-function_call

generate_code_execution_reply

generate_code_execution_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: dict[str, Any] | Literal[False] | None = None
) ->

Generate a reply using code execution. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: dict[str, typing.Any] \| Literal[False] \| None Default: None

generate_function_call_reply

generate_function_call_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, dict[str, Any] | None]

Generate a reply using function call.
”function_call” replaced by “tool_calls” as of OpenAI API v1.1.0 See https://platform.openai.com/docs/api-reference/chat/create#chat-create-functions Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: Any \| None Default: None

generate_init_message

generate_init_message(
    self,
    message: str | dict[str, Any] | None,
    **kwargs: Any
) -> dict[str, Any] | str

Generate the initial message for the agent.
If message is None, input() will be called to get the initial message.
Parameters:

Name	Description
`message`	the message to be processed. Type: str \| dict[str, typing.Any] \| None
`**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. It can be a string or a list of string. If provided, we will combine this carryover with the “message” content when generating the initial chat message. Type: Any

Returns:

Type	Description
dict[str, typing.Any] \| str	str or dict: the processed message.

generate_oai_reply

generate_oai_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: OpenAIWrapper | None = None
) -> tuple[bool, str | dict[str, Any] | None]

Generate a reply using autogen.oai. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: OpenAIWrapper \| None Default: None

generate_reply

generate_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: ForwardRef('Agent') | None = None,
    **kwargs: Any
) -> str | dict[str, Any] | None

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.
Parameters:

Name	Description
`messages`	a list of messages in the conversation history. Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	sender of an Agent instance. Type: ForwardRef(‘Agent’) \| None Default: None
`**kwargs`	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. Type: Any

Returns:

Type	Description
str \| dict[str, typing.Any] \| None	str or dict or None: reply. None if no reply is generated.

generate_tool_calls_reply

generate_tool_calls_reply(
    self,
    messages: list[dict[str, Any]] | None = None,
    sender: Agent | None = None,
    config: Any | None = None
) -> tuple[bool, dict[str, Any] | None]

Generate a reply using tool call. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]] \| None Default: None
`sender`	Type: Agent \| None Default: None
`config`	Type: Any \| None Default: None

get_actual_usage

get_actual_usage(self) -> dict[str, int] | None

Get the actual usage summary.

get_chat_results

get_chat_results(self, chat_index: int | None = None) -> list[ChatResult] | ChatResult

A summary from the finished chats of particular agents. Parameters:

Name	Description
`chat_index`	Type: int \| None Default: None

get_human_input

get_human_input(self, prompt: str) -> str

Get human input.
Override this method to customize the way to get human input.
Parameters:

Name	Description
`prompt`	prompt for the human input. Type: str

Returns:

Type	Description
str	str: human input.

get_total_usage

get_total_usage(self) -> dict[str, int] | None

Get the total usage summary.

initiate_chat

initiate_chat(
    self,
    recipient: ConversableAgent,
    clear_history: bool = True,
    silent: bool | None = False,
    cache: AbstractCache | None = None,
    max_turns: int | None = None,
    summary_method: str | Callable[..., Any] | None = 'last_msg',
    summary_args: dict[str, Any] | None = {},
    message: dict[str, Any] | str | Callable[..., Any] | None = 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.
Parameters:

Name	Description
`recipient`	the recipient agent. Type: ConversableAgent
`clear_history`	whether to clear the chat history with the agent. Default is True. Type: bool Default: True
`silent`	(Experimental) whether to print the messages for this conversation. Default is False. Type: bool \| None Default: False
`cache`	the cache client to be used for this conversation. Default is None. Type: AbstractCache \| None Default: None
`max_turns`	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. Type: int \| None Default: None
`summary_method`	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., `def my_summary_method( sender: ConversableAgent, recipient: ConversableAgent, summary_args: dict, ): return recipient.last_message(sender)["content"]` Type: str \| Callable[…, Any] \| None Default: ‘last_msg’
`summary_args`	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”. Type: dict[str, typing.Any] \| None Default: {}
`message`	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): `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): `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` Type: dict[str, typing.Any] \| str \| Callable[…, Any] \| None Default: None
`**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. Type: Any

Returns:

Type	Description
ChatResult	ChatResult: an ChatResult object.

initiate_chats

initiate_chats(self, chat_queue: list[dict[str, Any]]) -> list[ChatResult]

(Experimental) Initiate chats with multiple agents.
Parameters:

Name	Description
`chat_queue`	a list of dictionaries containing the information of the chats. Each dictionary should contain the input arguments for `initiate_chat` Type: list[dict[str, typing.Any]]

Returns:

Type	Description
list[ChatResult]	a list of ChatResult objects corresponding to the finished chats in the chat_queue.

last_message

last_message(self, agent: Agent | None = None) -> dict[str, Any] | None

The last message exchanged with the agent.
Parameters:

Name	Description
`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. Type: Agent \| None Default: None

Returns:

Type	Description
dict[str, typing.Any] \| None	The last message exchanged with the agent.

max_consecutive_auto_reply

max_consecutive_auto_reply(self, sender: Agent | None = None) -> int

The maximum number of consecutive auto replies. Parameters:

Name	Description
`sender`	Type: Agent \| None Default: None

print_usage_summary

print_usage_summary(self, mode: list[str] | str = ['actual', 'total']) -> None

Print the usage summary. Parameters:

Name	Description
`mode`	Type: list[str] \| str Default: [‘actual’, ‘total’]

process_all_messages_before_reply

process_all_messages_before_reply(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]

Calls any registered capability hooks to process all messages, potentially modifying the messages. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]]

process_last_received_message

process_last_received_message(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]

Calls any registered capability hooks to use and potentially modify the text of the last message, as long as the last message is not a function call or exit command. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]]

receive

receive(
    self,
    message: dict[str, Any] | str,
    sender: Agent,
    request_reply: bool | None = None,
    silent: bool | None = 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.
Parameters:

Name	Description
`message`	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. Type: dict[str, typing.Any] \| str
`sender`	sender of an Agent instance. Type: Agent
`request_reply`	whether a reply is requested from the sender. If None, the value is determined by `self.reply_at_receive[sender]`. Type: bool \| None Default: None
`silent`	(Experimental) whether to print the message received. Type: bool \| None Default: False

register_for_execution

register_for_execution(
    self,
    name: str | None = None,
    description: str | None = None,
    *,
    serialize: bool = True,
    silent_override: bool = False
) -> Callable[[~F | Tool], Tool]

Decorator factory for registering a function to be executed by an agent.
It’s return value is used to decorate a function to be registered to the agent.
Parameters:

Name	Description
`name`	name of the function. If None, the function name will be used (default: None). Type: str \| None Default: None
`description`	description of the function (default: None). Type: str \| None Default: None
`serialize`	whether to serialize the return value Type: bool Default: True
`silent_override`	whether to suppress any override warning messages Type: bool Default: False

Returns:

Type	Description
Callable[[~F \| Tool], Tool]	The decorator for registering a function to be used by an agent.

register_for_llm

register_for_llm(
    self,
    *,
    name: str | None = None,
    description: str | None = None,
    api_style: Literal['function', 'tool'] = 'tool',
    silent_override: bool = False
) -> Callable[[~F | Tool], Tool]

Decorator factory for registering a function to be used by an agent.
It’s return value is used to decorate a function to be registered to the agent. The function uses type hints to specify the arguments and return type. The function name is used as the default name for the function, but a custom name can be provided. The function description is used to describe the function in the agent’s configuration.
Parameters:

Name	Description
`name`	name of the function. If None, the function name will be used (default: None). Type: str \| None Default: None
`description`	description of the function (default: None). It is mandatory for the initial decorator, but the following ones can omit it. Type: str \| None Default: None
`api_style`	(literal): the API style for function call. For Azure OpenAI API, use version 2023-12-01-preview or later. `"function"` style will be deprecated. For earlier version use `"function"` if `"tool"` doesn’t work. See Azure OpenAI documentation for details. Type: Literal[‘function’, ‘tool’] Default: ‘tool’
`silent_override`	whether to suppress any override warning messages. Type: bool Default: False

Returns:

Type	Description
Callable[[~F \| Tool], Tool]	The decorator for registering a function to be used by an agent.

register_function

register_function(
    self,
    function_map: dict[str, Callable[..., Any]],
    silent_override: bool = False
) ->

Name	Description
`function_map`	a dictionary mapping function names to functions. if function_map[name] is None, the function will be removed from the function_map. Type: dict[str, typing.Callable[…, typing.Any]]
`silent_override`	whether to print warnings when overriding functions. Type: bool Default: False

register_handoff

register_handoff(self, condition: ForwardRef('OnContextCondition') | ForwardRef('OnCondition')) ->

Name	Description
`condition`	The condition to add (OnContextCondition, OnCondition) Type: ForwardRef(‘OnContextCondition’) \| ForwardRef(‘OnCondition’)

register_handoffs

register_handoffs(self, conditions: list[ForwardRef('OnContextCondition') | ForwardRef('OnCondition')]) ->

Name	Description
`conditions`	List of conditions to add Type: list[ForwardRef(‘OnContextCondition’) \| ForwardRef(‘OnCondition’)]

register_hook

register_hook(
    self,
    hookable_method: str,
    hook: Callable
) ->

Registers a hook to be called by a hookable method, in order to add a capability to the agent.
Registered hooks are kept in lists (one per hookable method), and are called in their order of registration.
Parameters:

Name	Description
`hookable_method`	A hookable method name implemented by ConversableAgent. Type: str
`hook`	A method implemented by a subclass of AgentCapability. Type: Callable

register_model_client

register_model_client(
    self,
    model_client_cls: ModelClient,
    **kwargs: Any
) ->

Name	Description
`model_client_cls`	A custom client class that follows the Client interface Type: ModelClient
`**kwargs`	The kwargs for the custom client class to be initialized with Type: Any

register_nested_chats

register_nested_chats(
    self,
    chat_queue: list[dict[str, Any]],
    trigger: type[Agent] | str | Agent | Callable[[Agent], bool] | list,
    reply_func_from_nested_chats: str | Callable[..., Any] = 'summary_from_nested_chats',
    position: int = 2,
    use_async: bool | None = None,
    **kwargs: Any
) -> None

Name	Description
`chat_queue`	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. Type: list[dict[str, typing.Any]]
`trigger`	refer to `register_reply` for details. Type: type[Agent] \| str \| Agent \| Callable[[Agent], bool] \| list
`reply_func_from_nested_chats`	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. `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]]:` Type: str \| Callable[…, Any] Default: ‘summary_from_nested_chats’
`position`	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. Type: int Default: 2
`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. Type: bool \| None Default: None
`**kwargs`	Type: Any

register_reply

register_reply(
    self,
    trigger: type[Agent] | str | Agent | Callable[[Agent], bool] | list,
    reply_func: Callable,
    position: int = 0,
    config: Any | None = None,
    reset_config: Callable[..., Any] | None = 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.
Parameters:

Name	Description
`trigger`	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`. Type: type[Agent] \| str \| Agent \| Callable[[Agent], bool] \| list
`reply_func`	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. `def reply_func( recipient: ConversableAgent, messages: Optional[List[Dict]] = None, sender: Optional[Agent] = None, config: Optional[Any] = None, ) -> Tuple[bool, Union[str, Dict, None]]:` Type: Callable
`position`	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. Type: int Default: 0
`config`	the config to be passed to the reply function. When an agent is reset, the config will be reset to the original value. Type: Any \| None Default: None
`reset_config`	the function to reset the config. The function returns None. Signature: `def reset_config(config: Any)` Type: Callable[…, Any] \| None Default: None
`ignore_async_in_sync_chat`	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. Type: bool Default: False
`remove_other_reply_funcs`	whether to remove other reply functions when registering this reply function. Type: bool Default: False

remove_tool_for_llm

remove_tool_for_llm(self, tool: Tool) -> None

Remove a tool (register for LLM tool) Parameters:

Name	Description
`tool`	Type: Tool

replace_reply_func

replace_reply_func(
    self,
    old_reply_func: Callable,
    new_reply_func: Callable
) ->

Replace a registered reply function with a new one.
Parameters:

Name	Description
`old_reply_func`	the old reply function to be replaced. Type: Callable
`new_reply_func`	the new reply function to replace the old one. Type: Callable

reset

reset(self) -> None

Reset the agent.

reset_consecutive_auto_reply_counter

reset_consecutive_auto_reply_counter(self, sender: Agent | None = None) ->

Reset the consecutive_auto_reply_counter of the sender. Parameters:

Name	Description
`sender`	Type: Agent \| None Default: None

run_code

run_code(
    self,
    code: str,
    **kwargs: Any
) -> tuple[int, str, str | None]

Run the code and return the result.
Override this function to modify the way to run the code.
Parameters:

Name	Description
`code`	the code to be executed. Type: str
`**kwargs`	other keyword arguments. Type: Any

Returns:

Type	Description
tuple[int, str, str \| None]	A tuple of (exitcode, logs, image). exitcode (int): the exit code of the code execution. logs (str): the logs of the code execution. image (str or None): the docker image used for the code execution.

send

send(
    self,
    message: dict[str, Any] | str,
    recipient: Agent,
    request_reply: bool | None = None,
    silent: bool | None = False
) ->

Send a message to another agent.
Parameters:

Name	Description
`message`	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. For example, one agent can send a message A as: Type: dict[str, typing.Any] \| str
`recipient`	the recipient of the message. Type: Agent
`request_reply`	whether to request a reply from the recipient. Type: bool \| None Default: None
`silent`	(Experimental) whether to print the message sent. Type: bool \| None Default: False

sequential_run

sequential_run(self, chat_queue: list[dict[str, Any]]) -> list[RunResponseProtocol]

(Experimental) Initiate chats with multiple agents sequentially.
Parameters:

Name	Description
`chat_queue`	a list of dictionaries containing the information of the chats. Each dictionary should contain the input arguments for `initiate_chat` Type: list[dict[str, typing.Any]]

Returns:

Type	Description
list[RunResponseProtocol]	a list of ChatResult objects corresponding to the finished chats in the chat_queue.

set_ui_tools

set_ui_tools(self, tools: list[Tool]) -> None

Set the UI tools for the agent.
Parameters:

Name	Description
`tools`	a list of tools to be set. Type: list[Tool]

stop_reply_at_receive

stop_reply_at_receive(self, sender: Agent | None = None) ->

Reset the reply_at_receive of the sender. Parameters:

Name	Description
`sender`	Type: Agent \| None Default: None

unset_ui_tools

unset_ui_tools(self, tools: list[Tool]) -> None

Unset the UI tools for the agent.
Parameters:

Name	Description
`tools`	a list of tools to be unset. Type: list[Tool]

update_agent_state_before_reply

update_agent_state_before_reply(self, messages: list[dict[str, Any]]) -> None

Calls any registered capability hooks to update the agent’s state.
Primarily used to update context variables.
Will, potentially, modify the messages. Parameters:

Name	Description
`messages`	Type: list[dict[str, typing.Any]]

update_function_signature

update_function_signature(
    self,
    func_sig: dict[str, Any] | str,
    is_remove: None,
    silent_override: bool = False
) ->

Update a function_signature in the LLM configuration for function_call.
Parameters:

Name	Description
`func_sig`	description/name of the function to update/remove to the model. See: https://platform.openai.com/docs/api-reference/chat/create#chat/create-functions Type: dict[str, typing.Any] \| str
`is_remove`	whether removing the function from llm_config with name ‘func_sig’ Type: None
`silent_override`	whether to print warnings when overriding functions. Type: bool Default: False

update_max_consecutive_auto_reply

update_max_consecutive_auto_reply(
    self,
    value: int,
    sender: Agent | None = None
) ->

Update the maximum number of consecutive auto replies.
Parameters:

Name	Description
`value`	the maximum number of consecutive auto replies. Type: int
`sender`	when the sender is provided, only update the max_consecutive_auto_reply for that sender. Type: Agent \| None Default: None

update_system_message

update_system_message(self, system_message: str) -> None

Update the system message.
Parameters:

Name	Description
`system_message`	system message for the ChatCompletion inference. Type: str

update_tool_signature

update_tool_signature(
    self,
    tool_sig: dict[str, Any] | str,
    is_remove: bool,
    silent_override: bool = False
) ->

Update a tool_signature in the LLM configuration for tool_call.
Parameters:

Name	Description
`tool_sig`	description/name of the tool to update/remove to the model. See: https://platform.openai.com/docs/api-reference/chat/create#chat-create-tools Type: dict[str, typing.Any] \| str
`is_remove`	whether removing the tool from llm_config with name ‘tool_sig’ Type: bool
`silent_override`	whether to print warnings when overriding functions. Type: bool Default: False

API Reference

​AssistantAgent

​Class Attributes

​DEFAULT_DESCRIPTION

​DEFAULT_SYSTEM_MESSAGE

​Instance Attributes

​chat_messages

​code_executor

​description

​function_map

​name

​system_message

​tools

​use_docker

​Instance Methods

​a_check_termination_and_human_reply

​a_execute_function

​a_generate_function_call_reply

​a_generate_init_message

​a_generate_oai_reply

​a_generate_reply

​a_generate_tool_calls_reply

​a_get_human_input

​a_initiate_chat

​a_receive

​a_send

​a_sequential_run

​can_execute_function

​chat_messages_for_summary

​check_termination_and_human_reply

​clear_history

​execute_code_blocks

​execute_function

​generate_code_execution_reply

​generate_function_call_reply

​generate_init_message

​generate_oai_reply

​generate_reply

​generate_tool_calls_reply

​get_actual_usage

​get_chat_results

​get_human_input

​get_total_usage

​initiate_chat

​initiate_chats

​last_message

​max_consecutive_auto_reply

​print_usage_summary

​process_all_messages_before_reply

​process_last_received_message

​receive

​register_for_execution

​register_for_llm

​register_function

​register_handoff

​register_handoffs

​register_hook

​register_model_client

​register_nested_chats

​register_reply

​remove_tool_for_llm

​replace_reply_func

​reset

​reset_consecutive_auto_reply_counter

​run_code

​send

​sequential_run

​set_ui_tools

​stop_reply_at_receive

​unset_ui_tools

​update_agent_state_before_reply

​update_function_signature

​update_max_consecutive_auto_reply

​update_system_message

​update_tool_signature

AssistantAgent

Class Attributes

DEFAULT_DESCRIPTION

DEFAULT_SYSTEM_MESSAGE

Instance Attributes

chat_messages

code_executor

description

function_map

name

system_message

tools

use_docker

Instance Methods

a_check_termination_and_human_reply

a_execute_function

a_generate_function_call_reply

a_generate_init_message

a_generate_oai_reply

a_generate_reply

a_generate_tool_calls_reply

a_get_human_input

a_initiate_chat

a_receive

a_send

a_sequential_run

can_execute_function

chat_messages_for_summary

check_termination_and_human_reply

clear_history

execute_code_blocks

execute_function

generate_code_execution_reply

generate_function_call_reply

generate_init_message

generate_oai_reply

generate_reply

generate_tool_calls_reply

get_actual_usage

get_chat_results

get_human_input

get_total_usage

initiate_chat

initiate_chats

last_message

max_consecutive_auto_reply

print_usage_summary

process_all_messages_before_reply

process_last_received_message

receive

register_for_execution

register_for_llm

register_function

register_handoff

register_handoffs

register_hook

register_model_client

register_nested_chats

register_reply

remove_tool_for_llm

replace_reply_func

reset

reset_consecutive_auto_reply_counter

run_code

send

sequential_run

set_ui_tools

stop_reply_at_receive

unset_ui_tools

update_agent_state_before_reply

update_function_signature

update_max_consecutive_auto_reply

update_system_message

update_tool_signature