Swarm: Allow functions to update agent's state, including system message, before replying

[marklysze]

Why are these changes needed?

To provide more control over the SwarmAgent's state, just before they reply, this PR provides the ability to define functions to update state when they are selected in the swarm.

A list of functions can be set when creating an agent through the update_agent_state_before_reply parameter. These will be executed once selected and before creating their reply.

UPDATE_SYSTEM_MESSAGE
A special function called UPDATE_SYSTEM_MESSAGE can be passed in here and this function allows an easy way to update the agent's system message using a Callable or an f-string. The Callable must return a string. The f-string will automatically merge in context_variable values into the string.

IMPORTANT NOTE: context variables have been moved from the SwarmAgent to ConversableAgent (in this PR but it will be done in #137 and aim to merge that before this). The following functions are available on a ConversableAgent to access state:

• my_agent.get_context - gets a value based on a key (allowing a default to be used)
• my_agent.set_context - updates a key with a value
• my_agent.update_context - updates with a dictionary
• my_agent.pop_context - removes a key from the context variables

context_variables = {
    "passport_number": "ABC1234C",
    "test_number": 50,
}

# Function associated with UPDATE_SYSTEM_MESSAGE, returns a string - the new system message
def customer_service_sys_msg(agent: ConversableAgent, messages) -> str:
    passport = agent.get_context("passport_number")
    return "You are a customer service representative. We already have the passport number: " + passport

# Function used to update state
def do_some_state_update_here(agent: ConversableAgent, messages) -> None:
    # Single context key update / add
    agent.set_context("test_other", agent.get_context_value("test_other") + 1)

    # Batch update/add context
    context_updates = {
        "passport_number": "123456789",
        "another_key": "another_value",
        "another_key2": "another_value2"
    }
    agent.update_context(context_updates)

customer_service = SwarmAgent(
    name="CustomerServiceRep",
    system_message="",
    update_agent_state_before_reply=[
                            UPDATE_SYSTEM_MESSAGE("You are a customer service representative. Always respond with the current passport number, which is currently '{passport_number}'"),
                            UPDATE_SYSTEM_MESSAGE(customer_service_sys_msg),
                            do_some_state_update_here]
)

Note: No additional documentation has been added. Once the code looks good, I'll add to or update existing documentation.

Related issue number

#77

Checks

• I've included any doc changes needed for https://ag2ai.github.io/ag2/. See https://ag2ai.github.io/ag2/docs/Contribute#documentation to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

[linmou]

Thanks your implement about SwarmAgent.update_state! It also matches my thoughts. How about building a more general interface like register_update_function ? So that users can register their own functions to modify other attributes besides sys_msg. In this version we can simply add a new key in hook_lists.

[linmou]

Thanks your implement about SwarmAgent.update_state! It also matches my thoughts. How about building a more general interface like register_update_function ? So that users can register their own functions to modify other attributes besides sys_msg. In this version we can simply add a new key in hook_lists.

I have added a new commit 22189f1 as a demo for you to discuss. In this implementation, I created a new hook update_states_once_selected to let users pass in a function to update the agent state.
Btw, if we use the context_variable field to store variables in the future version, this hook may be merged with 'process_all_messages_before_reply'

[marklysze]

All tests passed except Dall-e 3 image generation, unrelated to the changes. Will merge and address that test separately.

Thanks all!