UserProxyAgent

``autogen.UserProxyAgent #

UserProxyAgent(name, is_termination_msg=None, max_consecutive_auto_reply=None, human_input_mode='ALWAYS', function_map=None, code_execution_config={}, default_auto_reply='', llm_config=False, system_message='', description=None, **kwargs)

Bases: ConversableAgent

(In preview) A proxy agent for the user, that can execute code and provide feedback to the other agents.

UserProxyAgent is a subclass of ConversableAgent configured with human_input_mode to ALWAYS and llm_config to False. By default, the agent will prompt for human input every time a message is received. Code execution is enabled by default. LLM-based auto reply is disabled by default. To modify auto reply, register a method with register_reply. To modify the way to get human input, override get_human_input method. To modify the way to execute code blocks, single code block, or function call, override execute_code_blocks, run_code, and execute_function methods respectively.

Args: name (str): name of the agent. is_termination_msg (function): a function that takes a message in the form of a dictionary and returns a boolean value indicating if this received message is a termination message. The dict can contain the following keys: "content", "role", "name", "function_call". max_consecutive_auto_reply (int): the maximum number of consecutive auto replies. default to None (no limit provided, class attribute MAX_CONSECUTIVE_AUTO_REPLY will be used as the limit in this case). The limit only plays a role when human_input_mode is not "ALWAYS". human_input_mode (str): whether to ask for human inputs every time a message is received. Possible values are "ALWAYS", "TERMINATE", "NEVER". (1) When "ALWAYS", the agent prompts for human input every time a message is received. Under this mode, the conversation stops when the human input is "exit", or when is_termination_msg is True and there is no human input. (2) When "TERMINATE", the agent only prompts for human input only when a termination message is received or the number of auto reply reaches the max_consecutive_auto_reply. (3) When "NEVER", the agent will never prompt for human input. Under this mode, the conversation stops when the number of auto reply reaches the max_consecutive_auto_reply or when is_termination_msg is True. function_map (dict[str, callable]): Mapping function names (passed to openai) to callable functions. code_execution_config (dict or False): config for the code execution. To disable code execution, set to False. Otherwise, set to a dictionary with the following keys: - work_dir (Optional, str): The working directory for the code execution. If None, a default working directory will be used. The default working directory is the "extensions" directory under "path_to_autogen". - use_docker (Optional, list, str or bool): The docker image to use for code execution. Default is True, which means the code will be executed in a docker container. A default list of images will be used. If a list or a str of image name(s) is provided, the code will be executed in a docker container with the first image successfully pulled. If False, the code will be executed in the current environment. We strongly recommend using docker for code execution. - timeout (Optional, int): The maximum execution time in seconds. - last_n_messages (Experimental, Optional, int): The number of messages to look back for code execution. Default to 1. default_auto_reply (str or dict or None): the default auto reply message when no code execution or llm based reply is generated. llm_config (LLMConfig or dict or False or None): llm inference configuration. Please refer to OpenAIWrapper.create for available options. Default to False, which disables llm-based auto reply. When set to None, will use self.DEFAULT_CONFIG, which defaults to False. system_message (str or List): system message for ChatCompletion inference. Only used when llm_config is not False. Use it to reprogram the agent. description (str): a short description of the agent. This description is used by other agents (e.g. the GroupChatManager) to decide when to call upon this agent. (Default: system_message) **kwargs (dict): Please refer to other kwargs in ConversableAgent.

Source code in autogen/agentchat/user_proxy_agent.py

``nameproperty#

name

Get the name of the agent.

description`propertywritable`#

description

Get the description of the agent.

``system_messageproperty#

system_message

Return the system message.

DEFAULT\_CONFIG`class-attributeinstance-attribute`#

DEFAULT_CONFIG = False

MAX\_CONSECUTIVE\_AUTO\_REPLY`class-attributeinstance-attribute`#

MAX_CONSECUTIVE_AUTO_REPLY = 100

DEFAULT\_SUMMARY\_PROMPT`class-attributeinstance-attribute`#

DEFAULT_SUMMARY_PROMPT = 'Summarize the takeaway from the conversation. Do not add any introductory phrases.'

DEFAULT\_SUMMARY\_METHOD`class-attributeinstance-attribute`#

DEFAULT_SUMMARY_METHOD = 'last_msg'

``llm_configinstance-attribute#

llm_config = _validate_llm_config(llm_config)

``handoffsinstance-attribute#

handoffs = handoffs if handoffs is not None else Handoffs()

``silentinstance-attribute#

silent = silent

``run_executorinstance-attribute#

run_executor = None

``clientinstance-attribute#

client = _create_client(llm_config)

``client_cacheinstance-attribute#

client_cache = None

``human_input_modeinstance-attribute#

human_input_mode = human_input_mode

``reply_at_receiveinstance-attribute#

reply_at_receive = defaultdict(bool)

``context_variablesinstance-attribute#

context_variables = context_variables if context_variables is not None else ContextVariables()

``hook_listsinstance-attribute#

hook_lists = {'process_last_received_message': [], 'process_all_messages_before_reply': [], 'process_message_before_send': [], 'update_agent_state': []}

``code_executorproperty#

code_executor

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

``chat_messagesproperty#

chat_messages

A dictionary of conversations from agent to list of messages.

``use_dockerproperty#

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.

``toolsproperty#

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.

``function_mapproperty#

function_map

Return the function map.

DEFAULT\_USER\_PROXY\_AGENT\_DESCRIPTIONS`class-attributeinstance-attribute`#

DEFAULT_USER_PROXY_AGENT_DESCRIPTIONS = {'ALWAYS': 'An attentive HUMAN user who can answer questions about the task, and can perform tasks such as running Python code or inputting command line commands at a Linux terminal and reporting back the execution results.', 'TERMINATE': 'A user that can run Python code or input command line commands at a Linux terminal and report back the execution results.', 'NEVER': 'A computer terminal that performs no other action than running Python scripts (provided to it quoted in ```python code blocks), or sh shell scripts (provided to it quoted in ```sh code blocks).'}

``send #

send(message, recipient, request_reply=None, silent=False)

Send a message to another agent.

{
    "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.

Source code in autogen/agentchat/conversable_agent.py

``a_sendasync#

a_send(message, recipient, request_reply=None, silent=False)

(async) Send a message to another agent.

{
    "content": lambda context: context["use_tool_msg"],
    "context": {"use_tool_msg": "Use tool X if they are relevant."},
}

Source code in autogen/agentchat/conversable_agent.py

``receive #

receive(message, sender, request_reply=None, silent=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.

Source code in autogen/agentchat/conversable_agent.py

``a_receiveasync#

a_receive(message, sender, request_reply=None, silent=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.

Source code in autogen/agentchat/conversable_agent.py

``generate_reply #

generate_reply(messages=None, sender=None, **kwargs)

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.

Source code in autogen/agentchat/conversable_agent.py

``a_generate_replyasync#

a_generate_reply(messages=None, sender=None, **kwargs)

(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.

Source code in autogen/agentchat/conversable_agent.py

``set_ui_tools #

set_ui_tools(tools)

Set the UI tools for the agent.

Source code in autogen/agentchat/conversable_agent.py

``unset_ui_tools #

unset_ui_tools(tools)

Unset the UI tools for the agent.

Source code in autogen/agentchat/conversable_agent.py

``update_system_message #

update_system_message(system_message)

Update the system message.

Source code in autogen/agentchat/conversable_agent.py

``register_reply #

register_reply(trigger, reply_func, position=0, config=None, reset_config=None, *, ignore_async_in_sync_chat=False, remove_other_reply_funcs=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.

Source code in autogen/agentchat/conversable_agent.py

``replace_reply_func #

replace_reply_func(old_reply_func, new_reply_func)

Replace a registered reply function with a new one.

Source code in autogen/agentchat/conversable_agent.py

``register_nested_chats #

register_nested_chats(chat_queue, trigger, reply_func_from_nested_chats='summary_from_nested_chats', position=2, use_async=None, **kwargs)

Register a nested chat reply function.

Source code in autogen/agentchat/conversable_agent.py

``update_max_consecutive_auto_reply #

update_max_consecutive_auto_reply(value, sender=None)

Update the maximum number of consecutive auto replies.

Source code in autogen/agentchat/conversable_agent.py

``max_consecutive_auto_reply #

max_consecutive_auto_reply(sender=None)

The maximum number of consecutive auto replies.

Source code in autogen/agentchat/conversable_agent.py

``chat_messages_for_summary #

chat_messages_for_summary(agent)

A list of messages as a conversation to summarize.

Source code in autogen/agentchat/conversable_agent.py

``last_message #

last_message(agent=None)

The last message exchanged with the agent.

Source code in autogen/agentchat/conversable_agent.py

``initiate_chat #

initiate_chat(recipient, clear_history=True, silent=False, cache=None, max_turns=None, summary_method=DEFAULT_SUMMARY_METHOD, summary_args={}, message=None, **kwargs)

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.

Source code in autogen/agentchat/conversable_agent.py

``run #

run(recipient=None, clear_history=True, silent=False, cache=None, max_turns=None, summary_method=DEFAULT_SUMMARY_METHOD, summary_args={}, message=None, executor_kwargs=None, tools=None, user_input=False, msg_to='agent', **kwargs)

Source code in autogen/agentchat/conversable_agent.py

``a_initiate_chatasync#

a_initiate_chat(recipient, clear_history=True, silent=False, cache=None, max_turns=None, summary_method=DEFAULT_SUMMARY_METHOD, summary_args={}, message=None, **kwargs)

(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.

Args: Please refer to initiate_chat.

Source code in autogen/agentchat/conversable_agent.py

``a_runasync#

a_run(recipient=None, clear_history=True, silent=False, cache=None, max_turns=None, summary_method=DEFAULT_SUMMARY_METHOD, summary_args={}, message=None, executor_kwargs=None, tools=None, user_input=False, msg_to='agent', **kwargs)

Source code in autogen/agentchat/conversable_agent.py

``initiate_chats #

initiate_chats(chat_queue)

(Experimental) Initiate chats with multiple agents.

Returns: a list of ChatResult objects corresponding to the finished chats in the chat_queue.

Source code in autogen/agentchat/conversable_agent.py

``sequential_run #

sequential_run(chat_queue)

(Experimental) Initiate chats with multiple agents sequentially.

Returns: a list of ChatResult objects corresponding to the finished chats in the chat_queue.

Source code in autogen/agentchat/conversable_agent.py

``a_initiate_chatsasync#

a_initiate_chats(chat_queue)

Source code in autogen/agentchat/conversable_agent.py

``a_sequential_runasync#

a_sequential_run(chat_queue)

(Experimental) Initiate chats with multiple agents sequentially.

Returns: a list of ChatResult objects corresponding to the finished chats in the chat_queue.

Source code in autogen/agentchat/conversable_agent.py

``get_chat_results #

get_chat_results(chat_index=None)

A summary from the finished chats of particular agents.

Source code in autogen/agentchat/conversable_agent.py

``reset #

reset()

Reset the agent.

Source code in autogen/agentchat/conversable_agent.py

``stop_reply_at_receive #

stop_reply_at_receive(sender=None)

Reset the reply_at_receive of the sender.

Source code in autogen/agentchat/conversable_agent.py

``reset_consecutive_auto_reply_counter #

reset_consecutive_auto_reply_counter(sender=None)

Reset the consecutive_auto_reply_counter of the sender.

Source code in autogen/agentchat/conversable_agent.py

``clear_history #

clear_history(recipient=None, nr_messages_to_preserve=None)

Clear the chat history of the agent.

Source code in autogen/agentchat/conversable_agent.py

``generate_oai_reply #

generate_oai_reply(messages=None, sender=None, config=None)

Generate a reply using autogen.oai.

Source code in autogen/agentchat/conversable_agent.py

``a_generate_oai_replyasync#

a_generate_oai_reply(messages=None, sender=None, config=None)

Generate a reply using autogen.oai asynchronously.

Source code in autogen/agentchat/conversable_agent.py

``generate_code_execution_reply #

generate_code_execution_reply(messages=None, sender=None, config=None)

Generate a reply using code execution.

Source code in autogen/agentchat/conversable_agent.py

``generate_function_call_reply #

generate_function_call_reply(messages=None, sender=None, config=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

Source code in autogen/agentchat/conversable_agent.py

``a_generate_function_call_replyasync#

a_generate_function_call_reply(messages=None, sender=None, config=None)

Generate a reply using async function call.

Source code in autogen/agentchat/conversable_agent.py

``generate_tool_calls_reply #

generate_tool_calls_reply(messages=None, sender=None, config=None)

Generate a reply using tool call.

Source code in autogen/agentchat/conversable_agent.py

``a_generate_tool_calls_replyasync#

a_generate_tool_calls_reply(messages=None, sender=None, config=None)

Generate a reply using async function call.

Source code in autogen/agentchat/conversable_agent.py

``check_termination_and_human_reply #

check_termination_and_human_reply(messages=None, sender=None, config=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.

Source code in autogen/agentchat/conversable_agent.py

``a_check_termination_and_human_replyasync#

a_check_termination_and_human_reply(messages=None, sender=None, config=None)

(async) Check if the conversation should be terminated, and if human reply is provided.

Source code in autogen/agentchat/conversable_agent.py

``get_human_input #

get_human_input(prompt)

Get human input.

Override this method to customize the way to get human input.

Source code in autogen/agentchat/conversable_agent.py

``a_get_human_inputasync#

a_get_human_input(prompt)

(Async) Get human input.

Override this method to customize the way to get human input.

Source code in autogen/agentchat/conversable_agent.py

``run_code #

run_code(code, **kwargs)

Run the code and return the result.

Override this function to modify the way to run the code.

Source code in autogen/agentchat/conversable_agent.py

``execute_code_blocks #

execute_code_blocks(code_blocks)

Execute the code blocks and return the result.

Source code in autogen/agentchat/conversable_agent.py

``execute_function #

execute_function(func_call, call_id=None, verbose=False)

Execute a function call and return the result.

Override this function to modify the way to execute function and tool calls.

"function_call" deprecated as of OpenAI API v1.1.0 See https://platform.openai.com/docs/api-reference/chat/create#chat-create-function\_call

Source code in autogen/agentchat/conversable_agent.py

``a_execute_functionasync#

a_execute_function(func_call, call_id=None, verbose=False)

Execute an async function call and return the result.

Override this function to modify the way async functions and tools are executed.

Source code in autogen/agentchat/conversable_agent.py

``generate_init_message #

generate_init_message(message, **kwargs)

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

Source code in autogen/agentchat/conversable_agent.py

``a_generate_init_messageasync#

a_generate_init_message(message, **kwargs)

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

Source code in autogen/agentchat/conversable_agent.py

``remove_tool_for_llm #

remove_tool_for_llm(tool)

Remove a tool (register for LLM tool)

Source code in autogen/agentchat/conversable_agent.py

``register_function #

register_function(function_map, silent_override=False)

Register functions to the agent.

Source code in autogen/agentchat/conversable_agent.py

``update_function_signature #

update_function_signature(func_sig, is_remove, silent_override=False)

Update a function_signature in the LLM configuration for function_call.

Deprecated as of OpenAI API v1.1.0 See https://platform.openai.com/docs/api-reference/chat/create#chat-create-function\_call

Source code in autogen/agentchat/conversable_agent.py

``update_tool_signature #

update_tool_signature(tool_sig, is_remove, silent_override=False)

Update a tool_signature in the LLM configuration for tool_call.

Source code in autogen/agentchat/conversable_agent.py

``can_execute_function #

can_execute_function(name)

Whether the agent can execute the function.

Source code in autogen/agentchat/conversable_agent.py

``register_for_llm #

register_for_llm(*, name=None, description=None, api_style='tool', silent_override=False)

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.

Examples:

@user_proxy.register_for_execution()
@agent2.register_for_llm()
@agent1.register_for_llm(description="This is a very useful function")
def my_function(a: Annotated[str, "description of a parameter"] = "a", b: int, c=3.14) -> str:
     return a + str(b * c)

For Azure OpenAI versions prior to 2023-12-01-preview, set api_style to "function" if "tool" doesn't work:

@agent2.register_for_llm(api_style="function")
def my_function(a: Annotated[str, "description of a parameter"] = "a", b: int, c=3.14) -> str:
     return a + str(b * c)

Source code in autogen/agentchat/conversable_agent.py

``register_for_execution #

register_for_execution(name=None, description=None, *, serialize=True, silent_override=False)

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.

Examples:

@user_proxy.register_for_execution()
@agent2.register_for_llm()
@agent1.register_for_llm(description="This is a very useful function")
def my_function(a: Annotated[str, "description of a parameter"] = "a", b: int, c=3.14):
     return a + str(b * c)

Source code in autogen/agentchat/conversable_agent.py

``register_model_client #

register_model_client(model_client_cls, **kwargs)

Register a model client.

Source code in autogen/agentchat/conversable_agent.py

``register_hook #

register_hook(hookable_method, hook)

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.

Source code in autogen/agentchat/conversable_agent.py

``update_agent_state_before_reply #

update_agent_state_before_reply(messages)

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

Source code in autogen/agentchat/conversable_agent.py

``process_all_messages_before_reply #

process_all_messages_before_reply(messages)

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

Source code in autogen/agentchat/conversable_agent.py

``process_last_received_message #

process_last_received_message(messages)

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.

Source code in autogen/agentchat/conversable_agent.py

``print_usage_summary #

print_usage_summary(mode=['actual', 'total'])

Print the usage summary.

Source code in autogen/agentchat/conversable_agent.py

``get_actual_usage #

get_actual_usage()

Get the actual usage summary.

Source code in autogen/agentchat/conversable_agent.py

``get_total_usage #

get_total_usage()

Get the total usage summary.

Source code in autogen/agentchat/conversable_agent.py

``register_handoff #

register_handoff(condition)

Register a single handoff condition (OnContextCondition or OnCondition).

Source code in autogen/agentchat/conversable_agent.py

``register_handoffs #

register_handoffs(conditions)

Register multiple handoff conditions (OnContextCondition or OnCondition).

Source code in autogen/agentchat/conversable_agent.py

Back to top