[Feature Request]: new high-level programming interface

[sonichi]

Is your feature request related to a problem? Please describe.

Offer a simpler high-level programming interface for common orchestration patterns such as Swarm-style handsoff.
Extend it to incorporate group chat, nested chat and sequential chats.
Offer builtin tools that an agent can register for these common chat patterns.
Enable self-execution for swarm-style agents.

Describe the solution you'd like

from autogen import ConversableAgent, autobuild_groupchat, initiate_chat, OnCondition, AfterWork, register_handoff

captain = ConversableAgent("captain", llm_config=..., human_input_mode="NEVER")
user_proxy = ConversableAgent("user_proxy")
planner = ConversableAgent("planner", llm_config=..., human_input_mode="NEVER")
team_creator = ConversableAgent("team_creator", llm_config=..., human_input_mode="NEVER", tools=[autobuild_groupchat])

register_handoff(from=user_proxy, hand_to=captain)  # always hand off to captain after human input
register_handoff(
    from=captain,
    hand_to=[
        OnCondition(nested_chat=[chat_with_planner, chat_with_team_creator, ...], condition="You need help from a planner. The user does not need to be involved in the planning."),
        OnCondition(agent=planner, condition="You need help from a planner. The user would like to be involved in the planning"),
        OnCondition(agent=team_creator, condition="The plan has been generated. A team is needed to execute the next step in the plan.")
        AfterWork(user_proxy),  # After work, choose user proxy
    ]
register_handoff(
    from=planner,
    hand_to=[
        AfterWork(AfterWorkOption.SWARM_MANAGER, next_agent_selection_msg="If the user would like to be involved in the planning and has't approved the latest plan, hand off to user proxy. Otherwise handoff to captain."),
    ]
)
register_handoff(from=team_creator, hand_to=[AfterWork(captain)])

# what's swarm orchestration? auto-created group chat, execution agent, user proxy agent, transition tools etc.
initiate_chat(sender=captain, message="How can I help you?", mode="swarm")
# or
initiate_chat(sender=user_proxy, recipient=captain, message="Solve a puzzle", mode="swarm")

the list of other modes are subject to discussion.

Benefits:

1. Simplify user's code in tool use, group chat, nested chat etc. They are handled by the library automatically.
2. Offer built-in tools like autobuild_groupchat.
3. Can still leverage all the conversation patterns we support and expand the ways to use them.
4. Compatible with swarm-style handsoff.

Note:
Only one AfterWork is allowed. Multiple OnCondition is allowed.
OnCondition corresponds to tool-based handoff.
AfterWork corresponds to speaker selection after the work of the agent is done and no other agent is selected by a tool call. It can be both NL-based selection or PL-based.

Additional context

Currently, SwarmAgent and initiate_swarm_chat are offered and there's some mismatch with the API proposed here. Can we avoid subclassing and make initiate_chat support swarm orchestration?

[marklysze]

With Nested Chat, #107, complete and merged. Will close this. Swarm will continue to develop with additional features and these can be created in a new Issue.