Why are these changes needed?

In line with Issue #357, adding further control of the next agent through the return of the SwarmResult in a tool call, would allow you to terminate, return to the user agent, use auto speaker selection next, or stay with the current agent after a tool call.

So you can now return an AfterWorkOption in the agent parameter of a SwarmResult, e.g.:

def publish_results(context_variables:dict) -> SwarmResult:
  ### take something from context_variables and turn it into a final string ###
  return SwarmResult(agent=AfterWorkOption.TERMINATE, context_variables=context_variables, values=final_string)

All AfterWorkOption's are supported.

Related issue number

Closes #357

Checks

• I've included any doc changes needed for https://docs.ag2.ai/. See https://docs.ag2.ai/docs/contributor-guide/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.