Add decorator for function calling

[davorrunje]

Why are these changes needed?

Inspired by modern Python frameworks, an alternative method of registering functions using typing annotations and a function decorator could be added to the framework.

The principle can be illustrated in the following modified example in agentchat_function_call.ipynb notebook:

llm_config = {
   "config_list": config_list,
   "timeout": 120,
}
chatbot = autogen.AssistantAgent(
   name="chatbot",
   system_message="For coding tasks, only use the functions you have been provided with. Reply TERMINATE when the task is done.",
   llm_config=llm_config,
)

user_proxy = autogen.UserProxyAgent(
   name="user_proxy",
   is_termination_msg=lambda x: x.get("content", "") and x.get("content", "").rstrip().endswith("TERMINATE"),
   human_input_mode="NEVER",
   max_consecutive_auto_reply=10,
   code_execution_config={"work_dir": "coding"},
)

from typing import Annotated
from IPython import get_ipython

@user_proxy.register_for_execution()
@chatbot.register_for_llm(name="python", description="run cell in ipython and return the execution result.")
def exec_python(cell: Annotated[str, "Valid Python cell to execute."]):
   ...

@user_proxy.register_for_execution()
@chatbot.register_for_llm(name="sh", description="run a shell script and return the execution result.")
def exec_sh(script: Annotated[str, "Valid shell script to execute."]):
   return user_proxy.execute_code_blocks([("sh", script)])

user_proxy.initiate_chat(
   chatbot,
   message="Draw two agents chatting with each other with an example dialog. Don't add plt.show().",
)

The @agent.register_for_llm(...) function decorator reads the signature of the function and generates the function dictionary and calls ​​agent.update_function_signature(). The @agent.register_for_execution(...) function decorator wraps the function so it uses Pydantic.BaseModel.model_dump_json() to serialize output to string if needed and then calls agent.register_function() with the wrapped function.

The main advantage of this approach is the automatic generation of JSON schema from type hints in the signature of a decorated function. It is easy to use and results in much shorter and more understandable code. Alternatively, manually written JSON schemas are prone to errors and difficult to debug. If there is an error in the JSON schema, OpenAI API will silently ignore it and potentially produce incorrect parameters. Such mistakes are easy to make, a developer must remember to use 'string', 'integer', 'number', 'null' instead of appropriate Python base types. Encoding more complex JSON schemas involving tuples, lists, unions etc. is even more difficult. On the other hand, proposed decorators immediately raise an exception with an explanation of why the generation of the JSON schema failed.

Developers today are well versed in using decorators and type hints because of FastAPI and similar frameworks. Moreover, there is a strong preference for such a style as evidenced by the rising popularity of FastAPI and the decline of older Flask. Implementing decorators in the framework requires a somewhat deeper knowledge of Python, but using them feels natural and has proven easy to adopt by a wide range of developers.

Related issue number

Checks

• I've included any doc changes needed for https://microsoft.github.io/autogen/. See https://microsoft.github.io/autogen/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.

[davorrunje]

@microsoft-github-policy-service agree company="AIRT Technologies"

[davorrunje]

@microsoft-github-policy-service agree company="AIRT Technologies"

[rickyloynd-microsoft]

@davorrunje In the "Why are these changes needed?" section, can you add a description of the expected benefits of this PR? Will it make certain code more readable or easier to write? Also, how much do you anticipate this will increase the learning curve for repo users unfamiliar with python decorators?

[davorrunje]

@rickyloynd-microsoft I tried to summarize the discussion we had on Discord (https://discord.com/channels/1153072414184452236/1185807538801873016) in the "Why are these changes needed?" section. Please let me know if more info is needed.

[qingyun-wu]

This decorator addition is very appealing and the documentation looks good to me now. Thanks @davorrunje!

[davorrunje]

This decorator addition is very appealing and the documentation looks good to me now. Thanks @davorrunje!

Thank you :) This is one of my favorite projects and I am glad if I can help.

I am not happy with the documentation, i will try to write a standalone page with more examples in a separate PR.

[ekzhu]

@davorrunje thank you so much for your contribution!

[lestan]

Is this feature in 0.2.2 or in the next version? I tried the example in the notebook and it's not working. I am on 0.2.2.

Error I'm getting is:
@user_proxy.register_for_execution() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ AttributeError: 'UserProxyAgent' object has no attribute 'register_for_execution'. Did you mean: 'register_function'?

Any suggestions? Thanks!

[rickyloynd-microsoft]

Is this feature in 0.2.2 or in the next version? I tried the example in the notebook and it's not working. I am on 0.2.2.

Error I'm getting is: @user_proxy.register_for_execution() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ AttributeError: 'UserProxyAgent' object has no attribute 'register_for_execution'. Did you mean: 'register_function'?

Any suggestions? Thanks!

It will be in the next pip version, not 0.2.2.

[davorrunje]

@davorrunje thank you so much for your contribution!

@ekzhu it was a pleasure :)